Formål

Som led i den løbende modernisering af CPR-systemet konverteres CPR Services til en Java-platform, hvilket medfører tilpasninger og ændringer. Moderniserede versioner af services vil blive frigivet løbende. I en overgangsperiode vil både den 'gamle' service og den 'nye' service blive udstillet.

Denne side beskriver, hvad der er nyt ved de moderniserede services, og hvordan disse services kan testes.

Scope

Denne side henvender sig specifikt til private kunder af CPR's opdateringsservices og deres behov. Derfor vil siden indeholde mindre information, end hvad der er relevant for offentlige kunder, som i stedet henvises til https://cprservicedesk.atlassian.net/wiki/spaces/EXMYN/pages/2292514823 .

Hvad er nyt?

De moderniserede services indeholder få, mindre ændringer i den overordnede GCTP-protokol og i de enkelte services.

I hovedsagen ændres følgende i GCTP-protokollen:

1. GCTP behandles som XML, og derfor skal både GCTP-forespørgsler og -svar være velformede XML-dokumenter jf.  https://www.w3.org/TR/xml/#sec-well-formed .

2. GCTP-forespørgsler valideres for at sikre, at forespørgselsindholdet er gyldigt jf. GCTP XSD-skemaet.

Formålet med ændringerne er at sikre, at både CPR's egne systemer samt andre fagsystemer kan benytte standardiserede XML-værktøjer og tredjepartsbiblioteker, når de integreres med CPR Services. XML fordrer ikke, at elementerne i XML-dokumenterne er i en bestemt rækkefølge, så rækkefølgen på elementerne kan afvige fra den rækkefølge, som elementerne havde i de nuværende services.

Lokale tilpasninger og forberedelse

Anvendertest og anvenders risikomitigering

Anvendere af CPR’s services er selv ansvarlige for at vurdere risikoen for egen virksomhed, bl.a. risikoen for, at forespørgsler ikke bliver accepteret grundet ugyldig XML eller GCTP, samt at der indrapporteres forkerte data i tilfælde, hvor manuel indtastning nu er påkrævet, osv. Det anbefales, at der foretages en grundig test af de anvendte services fra anvenderside.

GCTP ajourførende services konverteres som udgangspunkt 1:1 i forhold til eksisterende natural services, dog med en række undtagelser.

1. GCTP Ajourførende services snitflade er XML baseret

   1. Da XML ikke fordrer nogen specifik rækkefølge af elementer, vil elementerne i den nye snitflade ikke nødvendigvis forefindes i samme rækkefølge i requests og responses

   2. Tabeller i GCTP skal identificeres med nøgler, igen fordi XML ikke fordrer en rækkefølge

   3. Attributter, der tidligere har været behandlet som tomme (f.eks. a=””), vil blive opfattet som nullværdier. I XML vil attributter med nullværdier ikke være til stede

   4. Elementer, der indeholder koder (f.eks. myndighedskode), vil altid have de samme attributter med ud på elementet, f.eks. t og tl

2. Der anvendes et simplificeret tegnsætsregelsæt som beskrevet i dokumentationen

3. Services kører udelukkende med ISO-8859-1 som tegnsæt

4. Der kan forekomme små afvigelser i forretningslogikken som følge af ændringer i den enkelte service

XML-parser

Den klare forventning er, at anvendere, som bruger tidssvarende og standardiserede XML-parsere, ikke vil have behov for at foretage lokale tilpasninger.

Anvendere, der bruger en selvudviklet XML-parser, bør foretage en grundig test.

Dokumentation af services

Dokumentation af de relevante services findes i https://cprservicedesk.atlassian.net/wiki/spaces/CPR/pages/2237661187 . Hvis I anvender en service, som ikke findes på listen, skal I kontakte CPRs servicedesk om den manglende servicebeskrivelse for opdateringsservices, der henvender sig til private.

Endvidere henvises der til servicehåndbogen for en generel beskrivelse af integration med GCTP-services.

Overgang til moderniserede CPR Services

Overgangen til moderniserede services foretages med fokus på risikomitigering.

Moderniserede services vil benytte en ny GCTP-protokolversion - version 2.0.

Kald, der i dag modtages med version 1.0 eller uden versionsnummer i <Gctp> -tagget, vil fortsat blive betjent af den 'gamle' service i servicens overgangsperiode.

Når overgangsperioden er udløbet, vil den gamle serviceversion blive lukket, og alle kald til den pågældende service vil herefter blive betjent af en moderniseret service - uanset versionsnummer i <Gctp> -tagget.

Default service

1. Før overgangsperioden (før release): Standard servicen er den gamle service. Det er ikke muligt at benytte version 2.0 service.

2. Under overgangsperioden: Standard servicen er stadig den gamle service. Det er muligt at benytte version 2.0 service.

3. Under udfasningsperioden: Standard servicen er den nye 2.0 service. Det er ikke muligt at benytte den gamle service. CPR forbeholder sig retten til uden varsel at rulle tilbage til "overgangsperioden", hvor den gamle service er standard.

4. Efter udfasningsperioden: Standard servicen er den nye 2.0 service. Det er ikke muligt at benytte den gamle service, og der kan ikke rulles tilbage til den gamle service.

Bemærk: Efter overgangsfasen kan og vil CPR uden varsel og kommunikation ændre den standard service, der betjener servicekald uden versionsnummer i tagget.

Anvenders lokale tilpasninger skal derfor tage højde for, at standard servicen kan ændres uden varsel efter overgangsperioden.

Anvendertest

I overgangsperioden vil anvendere have mulighed for at teste integrationen med de moderniserede services. Se mere i afsnittet 'Værktøjer til test af ændringer i CPR Services'.

Tilgængelighed og modernisering

Der er fokus på at fastholde systemets tilgængelighed i hele forløbet.

Strategien herfor er følgende:

1:1 konvertering af en service

Hvor det er muligt og hensigtsmæssigt, foretages der ikke ændringer til servicens requests og responses. Dette vil gælde for de fleste services. Derfor forventes det også, at de fleste ajourføringsservices konverteres på en sådan måde, at der i hovedsagen ikke foretages ændringer, der påvirker servicens requests og responses.

Imidlertid anvendes CPR’s ajourføringsservices ikke helt identisk på tværs af private og offentlige kunder. Det må derfor forventes, at nogle anvendere vil opfatte dette som en ændring.

Services, der konverteres 1:1, vil i en periode være i drift samtidigt med både en Java (ny) version og en Natural (gammel) version.

Afvigelser til ajourførende services

I forbindelse med konverteringen af services er der foretaget en række mindre afvigelser for at ensarte og simplificere anvendelsen. Hver af disse afvigelser er beskrevet herunder.

Tabeller

En række GCTP-services understøtter indberetning af data i tabeller, hvor der således kan være flere rækker. I den gamle version af GCTP er der ikke et krav om, at hver række skal være identificeret med en nøgle, men dette er et krav ved anvendelse af tabeller i de moderniserede GCTP-services. Nøgler skal altid udfyldes, og de nøgler, som en GCTP-service eventuelt har udstedt under initiering, skal anvendes.

Nøglerne skal være unikke.

En række i GCTP før modernisering kunne eksempelvis fremstå som vist herunder, hvor det ønskes at foretage en ny registrering af notatlinje 1 i de kommunale notater.

I den moderniserede GCTP skal k attributten være udfyldt med en unik nøgle, herunder med værdien k="NOTAT1_NOEGLE"

Character Encoding

Der understøttes kun ISO-8859-1-kodning.

Ensartet anvendelse af xml attributter i GCTP

I de nuværende services kunne enkelte elementer i GCTP-strukturen blive behandlet forskelligt, men dette er ensrettet i den nye GCTP-protokol, således at attributter på det enkelte XML-element opfører sig ens. For eksempel kan man i services opleve, at en attribut har en tom værdi: tl=””. I den nye protokol vil denne attribut blive betragtet som null og derfor slet ikke være til stede på elementet. Elementer, som indeholder koder, for eksempel myndighedskoder, vil altid have de samme tekstattributter medfølgende. For eksempel t=”København”.

Endvidere er der nu krav til felter, som er markeret som obligatoriske, at disse skal sendes ind i forbindelse med servicekald for at sikre, at en anvender af servicen forholder sig til indholdet i feltet. Tidligere har nogle services accepteret, at disse ikke indsendes, og i stedet anvendt den værdi, der var fremkommet under initiering. Nu er det påkrævet.

Værktøjer til test af ændringer i CPR Services

Følgende værktøjer kan anvendes til at understøtte overgangen til de moderniserede services (version 2.0 eller nyere).

GCTP 2.0 XSD skema

Skemaer for GCTP version 2.0 kan anvendes til at validere GCTP-forespørgsler.

Filer sidst opdateret 29. februar 2024 kl. 14.32

Request validering i DEMO-miljøet (CPR’s kundevendte testmiljø)

Kunder kan med fordel kalde GCTP-valideringsendpointet i DEMO-miljøet for at teste egen integration med de moderniserede services. URL'en til endpointet er https://gctp-demo.cpr.dk/cpr-online-gctp/validate. Endpointet kan tilgås uden session (login) og kræver, at forespørgslen indsendes via POST-metoden.

Eksempel gyldigt request/respons

De fleste værdier i forespørgslen, som fx System og Service, har ingen betydning i forbindelse med validering alene. Forespørgslen skal blot overholde GCTP-skemaet.

GCTP-forespørgslen er gyldig, og der returneres et <Kvit>-element i svaret:

Eksempel på ugyldig request/respons

Eksempel hvor forespørgslen ikke overholder XML-standarden:  </ CprServiceHeader> i stedet for </CprServiceHeader>

GCTP-forespørgslen er ugyldig, og der returneres <Kvit>-elementet i responsen, hvor attributten v har værdien 999, og attributten t har en værdi, der beskriver valideringsfejlen.

Serviceoversigt

Dette afsnit giver et overblik over de CPR-opdateringsservices, der anvendes af private brugere, samt deres moderniserede ændringer og vigtige datoer for overgangsperioden og udfasningsperioden.

Generelle ændringer

Herunder findes en liste med en opsummering af de generelle ændringer, der er foretaget i forbindelse med konverteringen af GCTP-ajourføringsservices. Disse ændringer er beskrevet i detaljer i de tidligere afsnit. Nøgleordene anvendes som referencer i konverteringsplanens tabel.

Specifikke ændringer

Såfremt en service har specifikke ændringer, vil de fremgå af dette afsnit.

Konverteringsplan

Planen angiver blandt andet:

• Hvornår en service kan testes i demo

• Hvornår en service releases til produktion

• Hvornår overgangsperioden for en service afsluttes

• Hvornår udfasningsperioden for en service afsluttes

Eventuelle problemer med de moderniserede CPR-services kan indrapporteres til CPR Servicedesk.

Dato Demo: Hvornår servicen er blevet lagt i Demo-miljøet og er klar til at blive testet af eksterne anvendere

Dato Produktion: Hvornår servicen er lagt i Produktion

Overgangsperiode slut: Angiver datoen, hvorefter alle kald til servicen vil blive betjent af den moderniserede (version 2.0) service, og udfasningsperioden starter

Udfasningsperioden slut: Angiver datoen for udfasningsperiodens afslutning