Indholdsfortegnelse. Version Serviceplatformen - opsætningsguide (Eksterne testmiljø) Indledning... 2

Transkript

1 Indholdsfortegnelse 1 Serviceplatformen - opsætningsguide (Eksterne testmiljø) Indledning Forberedelse til anvendelse Serviceplatformen Medarbejdercertifikat (MOCES) Virksomhedscertifikat/ Funktionscertifikat Opsætning af Serviceplatformen Oprettelse af leverandør Oprettelse af leverandør som kommune Anmod om serviceaftale Udfyldelse af invocationcontext Opsætning af klient Opsætning af SoapUI klient Opsætning af keystore Hent WSDL fil Opret projekt Ændre endpoint Opsætning af SOAP og GCTP kald Udførsel af SOAP og GCTP kald Eksempler ADRSOG1 - CPR Opslag (lokal) Version ADRSOG1 - CPR Opslag (lokal) Version CPR Kommunekode Service CPR SERVICE - Version søgning på myndigheder Søgning på en fødselsdato i en bestemt kommune (hér: Aalborg) Søgning på forældre til et givent CPR nummer Familie - CPR Opslag (lokal) Version Familie - CPR Opslag (lokal) Version Familie+ - CPR Opslag (lokal) Version Familie+ - CPR Opslag (lokal) Version navne3 - CPR Opslag (lokal) Version

2 navne3 - CPR Opslag (lokal) Version Person stamdata (lokal) STAM - CPR Opslag (lokal) Version STAM - CPR Opslag (lokal) Version STAM+ - CPR Opslag (lokal) Version STAM+ - CPR Opslag (lokal) Version CVR Online OIS Service CPR documentation Fejlsøgning ServiceUUID er forkert i forhold til den kaldte service Forkert syntaks for det angivne serviceuuid eller manglende ServiceUUID Fejlsøgning CPR Serviceplatformen - opsætningsguide (Eksterne testmiljø) 1.1 Indledning Denne opsætningsguide skal hjælpe med at komme i gang med at kalde services på Serviceplatformen. Guiden består af følgende sektioner: 1. Forberedelse til anvendelse af Serviceplatformen 2. Opsætning af Serviceplatformen 3. Opsætning af klient 4. Eksempler på kald til Serviceplatformen. 1.2 Forberedelse til anvendelse Serviceplatformen Inden et it-system fra en kommune eller UDK/ATP kan kalde Serviceplatformen er der en række forudsætninger, som skal være på plads. Disse forudsætninger gælder for anvendelse af Serviceplatformens eksterne testmiljø og produktionsmiljøet. Sikkerheden på Serviceplatforment er baseret på certifikater, hvorfor der kræves følgende opsætning. Disse forudsætninger beskrives i de nedenstående afsnit Medarbejdercertifikat (MOCES) Man skal have installeret et Medarbejdercertifikat (MOCES) på sin lokale pc. Dette bruges til at logge på Serviceplatformens selvbetjening. Certifikatet kan bestilles via DanID. 2

3 1.2.2 Virksomhedscertifikat/ Funktionscertifikat For at kalde en webservice på Serviceplatforment, skal man have et virksomhedscertifikat (VOCES) eller et funktionscertifikat (FOCES). Hvert registreret itsystem på Serviceplatformen, kræver et særskilt certifikat, som skal bruges for at kunne kalde webservices på Serviceplatformen. Dette certifikat skal være produktionscertifikat, hvilket gælder for både Serviceplatformens eksterne test og produktionsmiljø. Certifikatet kan bestilles via DanID. Dette certifikat kommer indpakket i en p12 fil, og skal eksporteres til filtypen.cer. Certifikatet der skal bestilles er som udgangspunkt for leverandøren. Hvis kommunen agerer både som kommune og leverandør, skal kommunens certifikat bruges. 1.3 Opsætning af Serviceplatformen Når brugeren har både et MOCES og et VOCES/FOCES certifikat, kan denne påbegynde sin opsætning af Serviceplatformen Oprettelse af leverandør For at kunne kalde webservices på Serviceplatformen, skal ens organisation være oprettet som leverandørorganisation på Serviceplatformen. Dette gøres ved at kontakte Helpdesk eller helpdesk@serviceplatformen.dk, og bede om en oprettelsesformular for en leverandør I denne blanket vil ansøgeren blive bedt om at udfylde sit RID ID, som er det ID som findes i ansøgerens medarbejdercertifikat (MOCES). Denne blanket udfyldes og sendes til Helpdesk. Når denne oprettelse er blevet godkendt, oprettes organisationen. Samtidig oprettes den første administrator for organisationen. Denne kan efterfølgende selv kan oprette brugere i egen organisation Oprettelse af leverandør som kommune Hvis kommunen selv drifter egne it-systemer, der driftes internt i kommunen og ønsker at tilslutte dem til Serviceplatformen skal kommunen ved siden af oprettelse som kommune også oprettes som leverandør med leverandørroller. Dette gøres ved at kontakte Helpdesk eller helpdesk@serviceplatformen.dk og bede om en oprettelsesformular for en leverandør 8jf. ovenstående proces).registrér it-system Brugerne kan nu logge på Serviceplatformens selvbetjening og vælge rollen Bruger for at kunne registrere et nyt it-system. Ved registrering af nyt it-system (Figur 1), skal brugeren angive VOCES/FOCES certifikat. Afhængigt af om it-systemet registreres i eksternt testmiljø eller produktionsmiljøet skal der angives et testcertifikat eller et produktionscertifikat. Dette certifikat benyttes efterfølgende at kalde services på Serviceplatformen. I forbindelse med registrering af it-systemet accepteres også vilkår for it-systemets tilslutning til Serviceplatformen. 3

4 Det er muligt at oprette flere it-systemer for en organisation, med unikt certifikat.. Figur Anmod om serviceaftale Når leverandøren har registreret et it-system, skal der angives, hvilke services it-systemet ønsker at kalde. Der kan angives en eller flere services. Det gøres ved at tilføre de services til en anmodning om en serviceaftale (Figur 2). Dernæst vælges hvilken kommune/udk/atp aftalen skal gælde for. I ekstern testmiljø kan der kun vælges support, da denne aftale godkendes automatisk. I produktionsmiljøet skal aftalen godkendes af de relevante kommuner/atp/udk, som er angivet under kommuner. Det er først når aftalen er godkendt at der muligt at kalde services. Bemærk at en aftale, der godkendes af flere myndigheder resulterer i flere underliggende serviceaftaler med unikke UUID er. Figur 2 4

5 1.4 Udfyldelse af invocationcontext Ved et webservicekald imod Serviceplatformen, er det krævet at man sender en række informationer med i XML kaldet, for at identificerer sig selv, og blive godkendt adgang til at kalde webservicen. Figur 10 fra Serviceplatformen, viser hvor man kan læse værdierne for ServiceAgreementUUID, UserSystemUUID, UserUUID, ServiceUUID. Udfyld følgende informationer i invocationcontext i xml en (eksempler på dette ses under afsnittet eksempler): Feltnavn ServiceAgreementUUID UserSystemUUID UserUUID ServiceUUID OnBehalfOfUser CallersServiceCallIdentifier Værdi Aftale UUID fra Serviceplatformen under Serviceaftaler System UUID fra Serviceplatformen under Serviceaftaler Kommune UUID fra Serviceplatformen under Serviceaftaler Service UUID fra Serviceplatformen under Find service eller Serviceaftaler Eget navn og firma (valgfrit felt) F.eks. SoapUI eller systemnavn (valgfrit felt) 5

6 Figur Opsætning af klient En god start til at teste kald mod Serviceplatformen, er at opsætte SoapUI. Via SoapUI, kan der hurtigt testes, om eksempelvis udfyldelse af invocationcontext er korrekt og strukturen af svaret. 6

7 1.5.1 Opsætning af SoapUI klient Opsætning af keystore SoapUI skal bruge et funktionscertifikatet pakket ind i Javas keystore-format for at kunne læse indholdet. Dette oprettes ved at læse virksomheds (VOCES) / funktionscertifikatet (FOCES) ud i en JKS fil via Javaværktøjet keytool. Dette køres i en kommandolinje (i windows: cmd.exe) Kaldet der skal udføres ser således ud: keytool -v -importkeystore -srckeystore "<filnavn>.p12" -srcstoretype PKCS12 -destkeystore funkcert.jks Den fil der dannes, skal beskyttes af et password, som ikke behøver at være det samme password som til certifikatet. Nogle værktøjer (fx Visual Studio) kræver dog at de to passwords er ens. Herefter åbnes SoapUI på følgende måde (Figur 3): 1. Vælg File Preferences 2. Vælg fanebladet SSL Settings og udfyld stien til KeyStore og KeyStore Password 3. Tryk ok. VOCES/FOCES Certifikat er nu klar til at blive brugt med kaldet mod Serviceplatformen. Figur 3 Viser hvilket certifikat der bruges af SoapUI 7

8 Hent WSDL fil I dette eksempel bruges CPR Service version 1.0 og benyttes WSDL-filen fra denne service. En WSDL fil beskriver hvilken struktur webservicen forventer at modtage fra klienten og hvilken struktur webservicen returnerer. Denne WSDL bruges af SoapUI til at opbygge xml strukturen af webservicekaldet. WSDL-filer findes for hver version af en service under menupunktet Find service. Vælg den service, du ønsker at kalde, Klik på Service WSDL (Figur 4), og download filen som en CprService.wsdl fil. Figur 4 Viser hvor bruger kan finde Service WSDL en Opret projekt Dernæst opret et nyt projekt i SoapUI (Figur 5), for opsætte kaldet mod en given webservice på Serviceplatformen Projektet oprettes således: 1. Angiv et projektnavn. 2. Indsæt stien til den downloaded WSDL fil. 3. Klik på OK. 8

9 Figur 5 Oprettelse af SoapUI projekt SoapUI opretter et projekt med et tomt request/kald ud fra WSDL filen. Klik ind på projektet og kontroller at alt er oprettet korrekt for callgctpservice som figuren nedenfor (Figur 6). Dette vil at SoapUI har oprettet en xml struktur, som nu kan modificeres, med bl.a. værdier i invocationcontext. 9

10 Figur 6 Oprettet xml struktur fra WSDL Ændre endpoint I WSDL-filen er endpointet (stien til kald af servicen) ikke sat korrekt, så først skal man klikke på dropdown-pilen (Figur 7) ud for endpointet (der starter med og vælge [add new endpoint ]. Indsæt et nyt endpoint med adressen: 10

11 Figur 7 Ændring af endpoint / Url til servicekald Alle endpoints kan findes under Find service på konkrete service, ved klik på Læs mere (Figur 8). Informationerne kan tilgåes fra følgende links: Miljø Ekstern test Produktion Link

12 Figur Opsætning af SOAP og GCTP kald XML kaldet skal opdateres, så alle oplysningerne passer (Se venligst nedenstående xml). Dette betyder at værdier i invocationcontext skal indsættes med de UUID er som findes for jeres respektive serviceaftaler Udfyld InvocationContext. Værdierne der skal indsættes i Invocationcontext, der beskrevet i afsnittet Udfyldelse af InvocationContext. xmlns:kom=" <kom:forwardtocprservicerequest> <invctx:usersystemuuid>usersystemuuid </invctx:usersystemuuid> <invctx:useruuid>useruuid </invctx:useruuid> 12

13 <invctx:serviceuuid>8ee213c7-25a9-11e d4bed98c63db</invctx:serviceuuid> <invctx:accountinginfo> </invctx:accountinginfo> <kom:gctpmessage><![cdata[ <Gctp v="1.0" > <Service r="adresse3"> <CprServiceHeader r="adresse3"> <Field r="pnr" v="xxxxxxxxxx"/> <Field r="akx" v="x"/> </kom:forwardtocprservicerequest> Udførsel af SOAP og GCTP kald Når XML en er sat op, trykkes på Play -knappen og kaldet udføres. I det returnerede svar, er også CDATA-indpakket og uden linjeskift. Eksempel: <env:envelope xmlns:env=" <env:header/> <env:body> <ns2:forwardtocprserviceresponse xmlns=" xmlns:ns2=" <ns2:result><![cdata[... GCTP-XML...</ns2:result> </ns2:forwardtocprserviceresponse> </env:body> </env:envelope> For nemmere at læse svaret fra eksempelvis CPR, kan man vælge at fjerne alt andet end GCTP-XML en fra tekstboksen, og derefter trykke på Alt+F for at vise XML en pænt formateret med linieskift (Figur 9). 13

14 Figur 9 Viser formateret xml, med linieskift 1.6 Eksempler Ved kald af nedenstående eksempler husk at ændre sti til den specifikke service, og henholdsvis miljø (test/produktion). I testmiljøet er det muligt at kalde alle service, såfremt disse indgår i den aftale der er automatisk godkendt. I produktionsmiljøet skal aftalen først være godkendt af de relevante kommuner/atp/udk inden servicen kan kaldes. Bemærk at der i produktionsmiljøet altid skal angives det korrekte UUID for aftale og myndighed man ønsker at kalde på vegne af ADRSOG1 - CPR Opslag (lokal) Version 1.0 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>d e3-9ed6-e376a4d43aa6</invctx:serviceuuid> 14

15 <kom:gctpmessage> <![CDATA[ <Service r="adrsog1"> <CprServiceHeader r="adrsog1"> <Field r="komk" v="1111"/> <Field r="vejk" v="1111"/> </kom:callgctpcheckservicerequest> ADRSOG1 - CPR Opslag (lokal) Version 1.1 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>6538f113-b1e6-4b21-8fe1-28b7bf78a1bd</invctx:serviceuuid> <kom:gctpmessage> <![CDATA[ <Service r="adrsog1"> <CprServiceHeader r="adrsog1"> <Field r="komk" v="1111"/> <Field r="vejk" v="1111"/> </kom:callgctpcheckservicerequest> CPR Kommunekode Service xmlns:ns=" xmlns:invctx=" xmlns:ns2=" <ns:getmunicipalitycoderequest> 15

16 <invctx:serviceuuid>cdf2d790-63ed-11e3-96c7-000c f</invctx:serviceuuid> <ns2:pnr> </ns2:pnr> </ns:getmunicipalitycoderequest> CPR SERVICE - Version 1.0 Bemærk at denne service hare en særlig omkostningsstruktur og anbefales kun benyttet for de it-systemer, med forretningsbehov for direkte opslag I CPR-registeret. xmlns:kom=" <kom:forwardtocprservicerequest> <invctx:serviceuuid>8ee213c7-25a9-11e d4bed98c63db</invctx:serviceuuid> <kom:gctpmessage><![cdata[ <Gctp v="1.0" > <Service r="adresse3"> <CprServiceHeader r="adresse3"> <Field r="pnr" v="xxxxxxxxxx"/> <Field r="akx" v="x"/> </kom:forwardtocprservicerequest> CPR service er et forward kald mod CPR registreret. Det kan bruges til at modtage forskellige information fra CPR, afhængig af Gctp xml en i kaldet. Nedenstående viser flere specifikke eksempler på kald af CPR Service. Bemærk at nedenstående dog skal pakkes ind i Serviceplatformens soap xml søgning på myndigheder <Service r="myn2"> <CprServiceHeader r="myn2"> <Field r="myte" v="farum"/> <Field r="aia" v="x"/> <Field r="maxa" v="15"/> 16

17 Søgning på en fødselsdato i en bestemt kommune (hér: Aalborg) <Service r="fodsog2"> <CprServiceHeader r="fodsog2"> <Field r="aia" v="x"/> <Field r="fodt" v=" "/> <Field r="komk" v="0851"/> Søgning på forældre til et givent CPR nummer <Service r="morfar"> <CprServiceHeader r="morfar"> <Field r="pnr" v=" "/> Familie - CPR Opslag (lokal) Version 1.0 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>dc3706bd e3-9ed6-e376a4d43aa6</invctx:serviceuuid> <kom:gctpmessage><![cdata[ <Service r="familie"> <CprServiceHeader r="familie"> <Field r="pnr" v=" "/> </kom:callgctpcheckservicerequest> 17

18 1.6.6 Familie - CPR Opslag (lokal) Version 1.1 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>2419e94b fc5-935c-2419ac956e79</invctx:serviceuuid> <kom:gctpmessage><![cdata[ <Service r="familie"> <CprServiceHeader r="familie"> <Field r="pnr" v=" "/> </kom:callgctpcheckservicerequest> Familie+ - CPR Opslag (lokal) Version 1.0 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>d55c9d e3-9ed6-e376a4d43aa6</invctx:serviceuuid> <kom:gctpmessage><![cdata[ <Service r="familie+"> <CprServiceHeader r="familie+"> <Field r="pnr" v=" "/> </kom:callgctpcheckservicerequest> 18

19 1.6.8 Familie+ - CPR Opslag (lokal) Version 1.1 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>a34cf599-26e bfbd-2490d3d1c3ab</invctx:serviceuuid> <kom:gctpmessage><![cdata[ <Service r="familie+"> <CprServiceHeader r="familie+"> <Field r="pnr" v=" "/> </kom:callgctpcheckservicerequest> navne3 - CPR Opslag (lokal) Version 1.0 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>e1f24e e3-9ed6-e376a4d43aa6</invctx:serviceuuid> <kom:gctpmessage><![cdata[ <Service r="navne3"> <CprServiceHeader r="navne3"> <Field r="pnr" v=" "/> </kom:callgctpcheckservicerequest> 19

20 navne3 - CPR Opslag (lokal) Version 1.1 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>e3f e-4b8f-8a15-674a4f8abaad</invctx:serviceuuid> <kom:gctpmessage><![cdata[ <Service r="navne3"> <CprServiceHeader r="navne3"> <Field r="pnr" v=" "/> </kom:callgctpcheckservicerequest> Person stamdata (lokal) xmlns:ns=" xmlns:invctx=" xmlns:ns2=" <ns:callcprbasicinformationrequest> <invctx:serviceuuid>d84f1ac8-76ca-11e3-abab bdf</invctx:serviceuuid> <ns2:pnr> </ns2:pnr> </ns:callcprbasicinformationrequest> STAM - CPR Opslag (lokal) Version 1.0 xmlns:kom=" <kom:callgctpcheckservicerequest> 20

21 <invctx:serviceuuid>ed3a77cd e3-9ed6-e376a4d43aa6</invctx:serviceuuid> <kom:gctpmessage><![cdata[ <Service r="stam"> <CprServiceHeader r="stam"> <Field r="pnr" v=" "/> </kom:callgctpcheckservicerequest> STAM - CPR Opslag (lokal) Version 1.1 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>7ae c-4b0a e97b12197</invctx:serviceuuid> <kom:gctpmessage><![cdata[ <Service r="stam"> <CprServiceHeader r="stam"> <Field r="pnr" v=" "/> </kom:callgctpcheckservicerequest> STAM+ - CPR Opslag (lokal) Version 1.0 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>e6ff0b e3-9ed6-e376a4d43aa6</invctx:serviceuuid> 21

22 <kom:gctpmessage><![cdata[ <Service r="stam+"> <CprServiceHeader r="stam+"> <Field r="pnr" v=" "/> </kom:callgctpcheckservicerequest> STAM+ - CPR Opslag (lokal) Version 1.1 xmlns:kom=" <kom:callgctpcheckservicerequest> <invctx:serviceuuid>7baec3a5-26a fd-37f3bad3dfcb</invctx:serviceuuid> <kom:gctpmessage><![cdata[ <Service r="stam+"> <CprServiceHeader r="stam+"> <Field r="pnr" v=" "/> </kom:callgctpcheckservicerequest> CVR Online 3.0 xmlns:x.=" xmlns:ns=" xmlns:x.1=" <x.:getlegalunitrequest level="1"> <ns:invocationcontext> <ns:serviceagreementuuid>serviceagreementuuid</ns:serviceagreementuuid> <ns:usersystemuuid>usersystemuuid</ns:usersystemuuid> <ns:useruuid>useruuid</ns:useruuid> 22

23 <ns:serviceuuid>93a48b e d4bed98c63db</ns:serviceuuid> <ns:accountinginfo></ns:accountinginfo> </ns:invocationcontext> <x.1:legalunitidentifier>xxxxxxxx</x.1:legalunitidentifier> </x.:getlegalunitrequest> OIS Service xmlns:ois=" xmlns:ns=" <ois:execproc> <ns:invocationcontext> <ns:serviceagreementuuid>serviceagreementuuid</ns:serviceagreementuuid> <ns:usersystemuuid>usersystemuuid</ns:usersystemuuid> <ns:useruuid>useruuid</ns:useruuid> <ns:serviceuuid>a02ebddc-389d-11e2-8d27-5c260a88aed0</ns:serviceuuid> <ns:accountinginfo></ns:accountinginfo> </ns:invocationcontext> <!--Optional:--> <ois:proc>sel_adressevalg</ois:proc> <!--Optional:--> <ois:par>421,1510</ois:par> </ois:execproc> 1.7 CPR dokumentation Følgende Excel-dokument, beskriver feltbetegnelser, koder osv. Dette dokument er ment som supplement til cpr dokumentation. Titel Supplerende CPR dokumentation Url viceplatform/hjemmesidematerialer/supplerende%20dokumentation% 20af%20CPR_april2015.xls 1.8 Fejlsøgning I nedenstående findes de typiske fejlbeskeder og løsninger ServiceUUID er forkert i forhold til den kaldte service Hvis Serviceplatformen returnerer en fejl kontrollér den modtagne fejlbesked. Der gives typisk en konkret fejlbeskrivelse hvis f.eks. ServiceUUID er forkert i forhold til den kaldte service. Dette giver fejlen: com.systematic.kombit.common.exception.messagekombitexception: Service called with wrong service = Kaldt ServiceUUID Forkert syntaks for det angivne serviceuuid eller manglende ServiceUUID Dette kan skyldes at der er tastet et mellemrum eller tabulering foran eller bagved UUID et. Dette giver fejlen: 23

24 com.systematic.kombit.common.exception.messagekombitexception: Service uuid = XXXXXXXXXXX-XXXXX-XXXXX must be an UUID Fejlsøgning CPR Hvis CPR ikke finder nogle data, så returneres en tom GCTP besked med en enkelt tom række. Hvis GCTP kaldet er forkert, gives blot beskeden: Exception message: com.systematic.kombit.common.exception.messagekombitexception: Gctp error in request 24