Eksterne Integrationer > Integrationsspecifikation

Vejledning til opsætning og anvendelse af LIFA EjdExplorer integrationskobling

Denne vejledning indeholder instruktioner i brugen af LIFA EjdExplorer kobling.

Koblingen giver en bruger mulighed for at starte LIFA EjdExplorer fra enten en applikation eller Webapplikation. Integrationen er enkel og fungerer som en én-vejs integration. Det betyder at det er muligt for en web- eller dekstop klient applikation, at starte EjdExplorer, samt medgive parametre som instruktion for hvilke kommandoer, der ønskes udført. Denne vejledning angiver parametrene til samtlige kommandoer og argumenter der kan sendes til EjdExplorer og er understøttet i denne version.

For at opnå 2-vejs integration mellem EjdExplorer og en klient applikation kræver dette en tættere integration, som eksempelvis er udviklet til desktop GIS platformene: MapInfo, ArcGIS og QGIS.

BEMÆRK: Ved alle forespørgsler til WebService (LIFAExternalIntegrationService) anvendes en negativ buffer på 10 cm. for alle geometrier.

Forudsætninger

EjdExplorer er en computer applikation der afvikles lokalt på computeren. Selvom EjdExplorer er aktiveret af en Internet baseret Webapplikation, forudsætter anvendelse af EjdExplorer stadig en lokal installation og aktivering med et serienummer udstedt af LIFA.

EjdExplorer koblingen fungerer med aktivering af separat licens – til dette udstedes serienummer af LIFA.

EjdExplorer fungerer under alle konfigurationer af licens (flydende-, site- og demolicens), samt øvrige installerede desktop GIS koblinger og datakilder (LOIS og OIS WebService).

I praksis kan alle typer af programmer anvende koblingen. Det er en forudsætning at applikationen kan forsyne EjdExplorer med mindst en eller flere af følgende kombinationer til identifikation af en eller flere ejendomme:

•Kommunenummer, vejkode og husnummer

•Ejerlavskode og matrikelnummer

•Ejendomsnummer

De generelle forudsætninger for installation af EjdExplorer er beskrevet separat i EjdExplorer installationsmanualen.

Det forudsættes at sikkerheden i de applikationer der anvender integrationen, har justeret sikkerhedsindstillinger til et passende niveau, der giver adgang til at starte EjdExplorer.

I den resterende del af vejledningen tages udgangspunkt i at EjdExplorer integreres til en Webapplikation. Det er også muligt at anvende samme parametre som input til at starte EjdExplorer fra en almindelig desktop applikation. For at starte EjdExplorer som en desktop applikation anvendes følgende kommando i en kommando prompt eller lignende:

Start EjdExplorer_Program_Path\LIFA.EjdExplorer.GUI.exe “Parameter_Streng”

Med fed skrift er angivet de parametre der skal tilpasses:

•EjdExplorer_Program_Path: installationskataloget hvor EjdExplorer er installeret. Kan læses i registreringsdatabasen under værdien ’INSTALLDIRECTORY’ der befinder sig under nøglen ’HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\lifa\EjdExplorer’

•Parameter_Streng: input parametre til at styre opstarten af EjdExplorer. Strengen indeholder samme formatering som hvis applikationen var startet via en Webapplikation

Opsætning og installation af kobling til EjdExplorer

EjdExplorer koblingen styres ved at registrere en applikation til en URL protokol (teknisk information: http://msdn.microsoft.com/en-us/library/aa767914(v=vs.85).aspx)

Opsætningen skal registreres lokalt på computeren og understøttes i følgende browsertyper

•Internet Explorer version 9

•Mozilla Firefox version 13.01

•Safari version 5.1.7

•Google Chrome version 20.0 (se bemærkninger i nedenstående afsnit)

For at registrere EjdExplorer til en URL protokol, skal følgende script afvikles:

Windows Registry Editor Version 5.00

[HKEY_CLASSES_ROOT\ejdexpl]

@="URL:ejdexpl"

"URL Protocol"=""

"EditFlags"=dword:00000002

[HKEY_CLASSES_ROOT\ejdexpl\DefaultIcon]

@="C:\\Program Files (x86)\\LIFA\\EjdExplorer\\LIFA.EjdExplorer.GUI.exe"

[HKEY_CLASSES_ROOT\ejdexpl\Shell]

[HKEY_CLASSES_ROOT\ejdexpl\Shell\Open]

[HKEY_CLASSES_ROOT\ejdexpl\Shell\Open\Command]

@="C:\\Program Files (x86)\\LIFA\\EjdExplorer\\LIFA.EjdExplorer.GUI.exe \"%1\""

Med fed skrift er angivet den parameter der kan tilpasses i scriptet:

•C:\\Program Files (x86)\\LIFA\\EjdExplorer\\LIFA.EjdExplorer.GUI.exe: Reference til installationsmappen og opstartsfilen til EjdExplorer

Efter registrering vil EjdExplorer kunne startes som program fra en Internet browsers adresselinje med følgende url: ’ejdexpl://’

Håndtering af EjdExplorer i Google Chrome browser

For at håndtere EjdExplorer i Google Chrome browser, skal applikationen tillige registreres i webapplikationen. Følgende html kodeeksempel viser hvorledes EjdExplorer startes fra en Google Chrome browser

<html>

<body>

navigator.registerProtocolHandler('web+ejdexpl', 'http://www.lifa.dk?q=%s', 'EjdExplorer');

window.open("ejdexpl://", null);

</script>

</body>

</html>

Teknisk manual for integration af EjdExplorer

Integrationsmanualen er en hjælp til opsætning af klient programmet der skal kunne starte EjdExplorer med de forventede parametre.

Ideen er at EjdExplorer kan startes fra en URL med argumenter – som om det var en almindelig hjemmeside. Windows operativsystemet vil efter registrering af ’ejdexpl’ som en URL protokol automatisk genkende applikationen ’EjdExplorer’ og starte denne. Specielt henledes opmærksomheden på anvendelse af Google Chrome til integration, som medfører at der evt. skal laves en særlig tilpasning i applikationen der integrerer EjdExplorer.

Hvis der ikke angives parametre, startes EjdExplorer i normal tilstand, som hvis programmet var startet på traditionel vis fra computeren.

Hvis der er fejl i parametre startes EjdExplorer, men den valgte operation (’mode’) udføres ikke.

Såfremt EjdExplorer startes med de korrekte parametre, går programmet straks i gang med at udføre operationen. Programstart og præsentation kan under disse omstændigheder vare længere end normalt pga. informationssøgningen.

Integration ved hjælp af WebService

I forbindelse med understøttelse af koblingen i Internet Explorer miljø, har det vist sig at der er begrænsninger. Det drejer sig om at Internet Explorer ikke kan håndtere lange URL strenge og derfor korter dem ned. Det betyder at EjdExplorer ikke kan fortolke parametrene og starter op uden at der sker noget i applikationen. Såfremt lange url strenge ikke anvendes, er det ikke nødvendigt at tage disse forbehold (eks. hvis der kun skal foretages enkeltopslag på en udpeget ejendom).

For at kompensere for begrænsningen er der udviklet en WebService (LIFAExternalIntegrationService), der midlertidigt holder tekststrengen og leverer denne til EjdExplorer på dennes forlangende. Tekststrengen der holdes i WebService svarer til den querystring der skal sendes til EjdExplorer, som anført i den videre dokumentation, uden parameteren ’MODE’.

Der findes to versioner af denne WebService: En SOAP baseret og en REST/JSON baseret. Begge services håndterer samme parametre og anvender samme programlogik for at bestemme de underliggende parametre for EjdExplorer.

•Endpoint til den SOAP baserede WebService: http://www.kortviser.dk/UsersPublic/Webservices/LIFAExternalIntegrationService.asmx

•Endpoint til den REST baserede WebService: http://kortviser.dk/UsersPublic/Handlers/LIFAExternalIntegrationServiceREST.ashx

Eksempel på integration med den SOAP baserede WebService

1.EjdExplorer integrationsfunktionen i WebGIS aktiveres og parametre til identifikation af ejendommen bestemmes (se afsnit: Parametre til identifikation af ejendom)

2.Ejerlavskoder og matrikelnumre ’postes’ til webservice vha ’Put’ metoden – Endpoint til WebService er: http://www.kortviser.dk/UsersPublic/Webservices/LIFAExternalIntegrationService.asmx

3.WebServicen kvitterer med en nøgle, som bruges som parameter til opstart af EjdExplorer

4.EjdExplorer startes med URL: ejdexpl://?mode=<MODE>&LIFAExternalIntegrationServiceID=<nøgle>, hvor mode angiver tilstanden af søgning (se afsnit: Generelle parametre) og LIFAExternalIntegrationServiceID angiver nøgles værdi, som hentes fra samme service med ’Get’ metoden

5.EjdExplorer starter og anmoder om parameterstrengen, givet ved nøglens værdi og foretager de anmodede operationer i hht. parameterstrengen

Herunder vises et HTML kodeeksempel på anvendelse af integrations WebService:

<form action='http://www.kortviser.dk/UsersPublic/WebServices/LIFAExternalIntegrationService.asmx/Put'

method="post" target="_blank">

<table>

<tr>

<td>Indsæt ID:</td>

</tr>

<tr>

</tr>

</table>

</form>

Den efterfølgende dokumentation angiver syntaks og eksempler på de værdier der kan sendes til EjdExplorer enten direkte eller gennem ’LIFAExternalIntegrationService’.

Følgende tre funktioner kan anvendes:

•’ConvertToAdresses’ (Adresser)

•’ConvertToRealProperties’ (Ejendomme)

•’ConvertToCadastralDistrictsAndLandparcels’ (Matrikler)

Eksempel på GET metoden med JSONP på integration mod REST Service:

function CallLifaExternalIntegrationServiceTest(sender, e) {

//Eksempel på data bærende objekt ved GET forespørgsel.

var data = {

'function': 'ConvertToRealProperties',

wkt: 'POLYGON ((453498.8 6180106.6, 452737.2 6180081, 452167.6 6179684.2, 451681.2 6178186.6, 452321.2 6176535.4, 455751.6 6176701.8, 455950 6178295.4, 455457.2 6179735.4, 454894 6180145, 453498.8 6180106.6))',

ticket: 'c4fdb7f0d671e4785ae835f7dfd7a9ff',

parameters: ['parametereksempel1', 'parametereksempel2', 'ejdexpl://?mode=single']

//Hvis denne parameterliste tilføjes data objektet kaldes callback funktionen med de ekstra parametrer angivet. Id fra integrationsservicen sættes automatisk som den sidste parameter.

}

var url = 'http://www.kortviser.dk/UsersPublic/Handlers/LIFAExternalIntegrationServiceREST.ashx';

var data = encodeURI(JSON.stringify(data));

$.ajax({

type: "GET",

url: url,

data: { data: data },

dataType: "jsonp",

jsonpCallback: 'CallApplication',

success: function (result) {

//Her kan tilføjes afsluttende funktionalitet ved gemmeført kald.

error: function (xhr, status, error) {

//Her kan tilføjes afsluttende funktionalitet ved fejlet kald.

}

});

}

function CallApplication(parametereksempel1, parametereksempel2, mode, integrationsserviceid) {

//Her returneres data objekt bærende parameterliste med tilføjet id fra integrationsservicen til sidste parameter som querystring, hvis parameterliste er inkluderet.

//Ved fejl returneres json objekt bærende 'error' attribut. Indholdstekseten vil være den pågældende exception types fejlmeddelelse - det er ikke muligt at hente en stacktrace.

}

Eksempel på POST metoden med JSONP på integration mod REST Service:

function CallLifaExternalIntegrationServiceTest(sender, e) {

//Eksempel på data bærende objekt ved POST forespørgsel.

var data = {

'function': 'ConvertToRealProperties',

ticket: 'c4fdb7f0d671e4785ae835f7dfd7a9ff',

parameters: ['parametereksempel1', 'parametereksempel2', 'ejdexpl://?mode=single']

//Hvis denne parameterliste tilføjes data objektet returneres json objekt med parameterliste og id fra integrationsservicen sættes automatisk som den sidste parameter.

//Uden denne parameterliste på data objektet returneres json objekt med 'lifaexternalintegrationserviceid' parameter indeholdende id fra integrationsservicen.

}

var url = 'http://www.kortviser.dk/UsersPublic/Handlers/LIFAExternalIntegrationServiceREST.ashx';

var data = JSON.stringify(data);

$.ajax({

type: "POST",

url: url,

data: { data: data },

dataType: "json",

success: CallApplication,

error: function (xhr, status, error) {

//Her kan tilføjes afsluttende funktionalitet ved fejlet kald.

}

});

}

function CallApplication(data) {

// Eks. data = { "lifaexternalintegrationserviceid" : "352298" }

// Eks. ejdexpl://?mode=merge&LIFAExternalIntegrationServiceID=352298

//Her returneres data objekt bærende parameterliste med tilføjet id fra integrationsservicen til sidste parameter som querystring, hvis parameterliste er inkluderet i data objekt postet i forespørgslen.

//Er parameterlisten ikke inkluderet i data objekt postet i forespørgslen, returneres objekt med 'lifaexternalintegrationserviceid' parameter indeholdende id fra integrationsservicen.

//Ved fejl returneres json objekt bærende 'error' attribut. Indholdstekseten vil være den pågældende exception types fejlmeddelelse - det er ikke muligt at hente en stacktrace.

}

Special parametre til WebService integration

LIFAExternalIntegration webservicen er indrettet med yderligere parametre til at omsætte en geometri, der eksempelvis er indtegnet i WebGIS til en række af ejerlavskoder og matrikelnumre. Der medfører nemmere integration af EjdExplorer fra en GIS applikation, hvor brugerens indtegnede geometri automatisk omsættes til parametre der direkte indlæses i EjdExplorer.

samme WebService metode 'put' som øvrige parametre anvendes. I stedet for at der anvendes parametre som beskrevet i afsnittet 'Parametre til identifikation af ejendom', angives i stedet en Well Known Text 'WKT' tekststreng, sammen med brugernavn og adgangskode til GST kortforsyningen.

Bemærk: Adgangskode og brugernavn der anvendes til GST kortforsyningen skal have brugerrettigheder til at foresprøge tjenesten 'mat_gml2'. Få liste over tjenester, som du har adgang til vha. følgende link: http://www.kortforsyningen.dk/content/list-tjenester-getservices

Følgende parametre definerer den digitaliserede geometri og angiver brugernavn og adgangskode til GST kortforsyningen:

WKT	Geometri angivet ved Well Known Text 'WKT' tekststreng
ticket	ticket leveret af GST kortforsyningen på baggrund af brugernavn og adgangskode

Generelle parametre

EjdExplorer kan startes i en tilstand, hvor enkeltopslag foretages, med følgende parameter:

ejdexpl://?mode=<MODE>

Parameter	Betydning	Valgmuligheder
mode	Tilstanden af EjdExplorer	mode=single: starter enkeltopslag og foretager enkeltopslag på de specificerede ejendomme, angivet ved de efterfølgende parametre til EjdExplorer
		mode=bulk: Starter EjdExplorer, skifter automatisk til ’Forespørgselbyggeren’ fanebladet og importerer en tabel med felterne, angivet ved de efterfølgende parametre til EjdExplorer
		mode= merge: Starter EjdExplorer, skifter automatisk til ’Adresseudtræk’ fanebladet og udfører automatisk brevflet med de specificerede ejendomme, angivet ved de efterfølgende parametre til EjdExplorer.

For at EjdExplorer skal foretage noget aktivt i den specificerede ’mode’, skal der angives nøgleværdier til identifikation af ejendomme.

I de efterfølgende afsnit er gennemgået de parametre der kan anvendes til at angive nøgler.

Parametre til identifikation af ejendom

I de tre forskellige modes der er understøttet, kan anføres parametre der identificerer ejendommen for EjdExplorer. En ejendom kan bestemmes ud fra følgende:

•Kommunenummer, vejkode og husnummer

•Ejerlavskode og matrikelnummer

•Ejendomsnummer

•Gælder kun ved WebService integration: En geometri udtrykt vha. OGC WKT (http://en.wikipedia.org/wiki/Well-known_text) - se afsnit 'Special parametre til WebService integration'

Kommunenummer, vejkode og husnummer

EjdExplorer kan anvende adressen som nøgle til fremsøgning af ejendommen, med følgende parametre:

ejdexpl://?mode=<MODE>& municipalitycode=<municipalitycode>&streetcode=<streetcode>&housecode=<housecode>

Bemærk: alle 3 parametre skal angives for at give en éntydig nøgle til identifikation af ejendommen.

Følgende parametre angiver ejendommen:

municipalitycode	kommunekode
streetcode	vejkode
housecode	husnummer

Det er muligt at håndtere flere ejendomme samtidigt, ved at kommaseparere adresserne – eksempel:

ejdexpl://?mode=single&municipalitycode=450,450,461&streetcode=834,837,91&housecode=1,14,4

Resultatet er at EjdExplorer starter med en automatisk søgning på følgende adresser: Skalkendrupvej 1 Nyborg, Skellerup byvej 14 Nyborg og Abildhøj 4 Odense.

Ejerlavskode og matrikelnummer

EjdExplorer kan anvende ejerlavskode og matrikelnummer som nøgle til fremsøgning af ejendommen, med følgende parametre:

ejdexpl://?mode=<MODE>&CadastralDistrictIdentifier=<CadastralDistrictIdentifier>&RealPropertyKey=<RealPropertyKey>

Bemærk: Begge parametre skal angives for at give en éntydig nøgle til identifikation af ejendommen.

Følgende parametre angiver ejendommen:

CadastralDistrictIdentifier	Landsejerlavskode
RealPropertyKey	Matrikelnummer

Det er muligt at håndtere flere ejendomme samtidigt, ved at kommaseparere landsejerlavskoden og matrikelnumrene – eksempel:

ejdexpl://?mode=single&CadastralDistrictIdentifier=411355,411355,331751&RealPropertyKey=9b,12d,6u

Resultatet er at EjdExplorer starter med en automatisk søgning på følgende adresser: Skalkendrupvej 1 Nyborg, Skellerup byvej 14 Nyborg og Abildhøj 4 Odense.

Ejendomsnummer

EjdExplorer kan anvende ejendomsnummer som nøgle til fremsøgning af ejendommen, med følgende parametre:

ejdexpl://?mode=<MODE>& municipalitycode=<municipalitycode>&LandParcelMunicipalNumber=<LandParcelMunicipalNumber>

Følgende parametre angiver ejendommen:

municipalitycode	kommunekode
LandParcelMunicipalNumber	ESR ejendomsnummer

Det er muligt at håndtere flere ejendomme samtidigt, ved at kommaseparere kommunekode og ejendomsnummeret - eksempel:

ejdexpl://?mode=single&municipalitycode=461,461,461&landparcelmunicipalnumber=10,29,209750

Resultatet er at EjdExplorer starter med en automatisk søgning på adressen: A. P. Rasmussens Allé 3 Odense, A. P. Rasmussens Allé 4 Odense, Kochsgade 112C Odense.