Modernisering af CPR Services

Introduktion

Som led i den løbende modernisering af CPR-systemet konverteres CPR Services til en Java platform, hvilket medfører mindre tilpasninger og ændringer for opslags-, søge- og læseservices.

For CPR’s Ajourføringsservices (indberetning-/skriveservices) henvises specifikt til https://cprservicedesk.atlassian.net/wiki/spaces/EXMYN Adgang til siden gives til eksterne anvendere efter anmodning via CPRs servicedesk https://cpr.dk/kunder/support/link-til-cpr-servicedesk

Moderniserede versioner af services vil releases løbende.

I en overgangsperiode vil både den “gamle” service og den “nye” service være tilgængelige.

1 Introduktion
2 Hvad er nyt?
3 Udrulningsplan
4 Scope
5 Lokale tilpasninger og forberedelse
- 5.1 Anvendertest og anvenders risikomitigering
- 5.2 XML-parser
- 5.3 Hvilke services anvender I?
6 Overgang til moderniserede CPR Services
- 6.1 Default service
  - 6.1.1 Særlige bemærkninger vedr. flere GCTP services i et request
- 6.2 Anvendertest
- 6.3 CPR’s test
7 Værktøjer til test af ændringer i CPR Services
- 7.1 GCTP 2.0 XSD skema
- 7.2 Request validering i DEMO-miljøet (CPR’s kundevendte testmiljø)
8 Ændringer i version 2.0 services
- 8.1 Opbygning af restart (REST) nøgleværdier og SEARCH_ID feltværdier

Hvad er nyt?

De moderniserede opslags-, søge- og læseservices indeholder få mindre ændringer i den overordnede GCTP protokol og i de enkelte services.

I hovedsagen ændres følgende i GCTP protokollen:

GCTP behandles som XML, og derfor skal både GCTP requests og responses være velformet XML dokumenter jvf. https://www.w3.org/TR/xml/#sec-well-formed.
GCTP requests valideres for at sikre, at request indholdet er gyldigt jvf. 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 der integreres med CPR Services.

Læs eventuelt også afsnittet Ændringer i version 2.0 services.

Udrulningsplan

Datoer for ændringer i de enkelte services fremgår af Udrulningsplan for moderniserede CPR Services.

Scope

Kun CPR’s opslags-, søge- og læseservices er i scope.

For CPR’s Ajourføringsservices (indberetning-/skriveservices) henvises specifikt til https://cprservicedesk.atlassian.net/wiki/spaces/EXMYN . Adgang til siden gives til eksterne anvendere efter anmodning via CPRs servicedesk https://cpr.dk/kunder/support/link-til-cpr-servicedesk .

Lokale tilpasninger og forberedelse

Anvendertest og anvenders risikomitigering

Anvendere af CPR’s opslags-, søge- og læseservices er selv ansvarlig for at vurdere risikoen for egen myndighed eller virksomhed.

CPR’s test og udrulning er baseret på, at services funktionelt releases 1:1 i forhold til “gamle” services.

CPR’s vurdering af risikoen for anvenderne er således for nuværende, at risikoen for anvendere er meget lav. Det er imidlertid også baseret på en forventning om, at anvendernes integration til CPR’s services er baseret på tidssvarende rammeværk.

XML-parser

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

Anvendere, som anvender en egen udviklet XML-parser, bør foretage en grundig test. Ved modtagelse af ikke valid XML vil GCTP services svar tilbage med følgende struktur i responsen:

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<root xmlns="http://www.cpr.dk">
    <Gctp v="2.0" env="">
        <Kvit r="Fejl" t="GCTP Request er ikke valid XML" v="5400"/>
    </Gctp>
</root>

Hvilke services anvender I?

Anvendere af CPR’s GCTP services bør undersøge præcist, hvilke services som anvendes.

Derved kan du som anvender hurtigt identificere, hvornår en service ændres og hvornår overgangsperioden slutter, og således vinduet for lokale test, jf. Udrulningsplan for moderniserede CPR Services

Overgang til moderniserede CPR Services

Transitionen 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 betjenes 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 betjenes af en moderniseret service - uanset versionnummer i <Gctp> tagget.

Default service

Før overgangsperiode (før release): Default service er gamle service. Det er ikke muligt at benytte version 2.0 service.
Overgangsperioden: Default service er gamle service. Det er muligt at benytte version 2.0 service.
Udfasningsperiode: Default service er ny 2.0 service. Det er ikke muligt at benytte gamle service. CPR forbeholder sig ret til uden varsel rulle tilbage til “overgangsperioden”, hvor gamle service er default.
Efter udfasningsperioden: Default service er ny 2.0 service. Det er ikke muligt at benytte gamle service, og der kan ikke rulles tilbage til gamle service.

Bemærk: CPR kan og vil efter overgangsfasen uden varsel og kommunikation ændre på den default service, som betjener servicekald uden versionsnummer i tagget.

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

Særlige bemærkninger vedr. flere GCTP services i et request

Hvis et <Gctp v="2.0"> request indeholder kald til flere GCTP services skal samtlige services i requestet være tilgængelige som version 2.0 services (jvf. Udrulningsplan for moderniserede CPR Services) for at version 2.0 services bliver kaldt. Der kaldes aldrig både version 1.0 og 2.0 services for at fuldføre et request. Hvis en service i requestet er kun tilgængelig som version 1.0 service vil samtlige services i requestet blive håndteret af version 1.0 services. Denne regel gælder også selvom overgangsperioden/udfasningsperioden for en eller flere services i requestet er afsluttet.

Anvendertest

I overgangsperioden vil anvendere have mulighed for at teste integrationen mod moderniserede services.

CPR’s test

Inden en moderniseret service bliver releaset, er der afviklet en maskinel sammenligningstest mellem gamle og moderniserede services, der identificerer eventuelle forskel i responsen.

CPR’s klient CPRWeb ændres løbende til at benytte moderniserede services. Hvis der mod forventning er fejl i servicens forretningslogik eller tilsvarende, vil det således med høj sandsynlighed blive konstateret gennem anvendelsen af CPRWeb.

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

Følgende værktøjer kan anvendes til at hjælpe med overgangen til moderniserede services (version >= 2.0).

GCTP 2.0 XSD skema

Skemaer for GCTP version 2.0 kan anvendes til at validere GCTP requests.

Filer sidst opdateret 25. januar 2024 kl. 14.48

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 til endpointet er https://gctp-demo.cpr.dk/cpr-online-gctp/validate. Endpointet kan kaldes uden session (login).

Eksempel gyldigt request/respons

De fleste værdier i requestet som fx. System og Service har ingen betydning, hvor det alene angår validering. Requestet skal blot overholde GCTP skemaet.

curl -i https://gctp-demo.cpr.dk/cpr-online-gctp/validate -d '
<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<root xmlns="http://www.cpr.dk">
  <Gctp v="2.0">
    <System r="CprSoeg">
      <Service r="STAMP">
        <CprServiceHeader r="STAMP">
          <Key>
            <Field r="PNR" v="..."/>
          </Key>
        </CprServiceHeader>
      </Service>
    </System>
  </Gctp>
</root>
'

GCTP requestet er gyldigt, og der returneres et <Kvit> element i svaret:

HTTP/1.1 200 
Content-Type: text/xml;charset=ISO-8859-1
Content-Length: 447

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<root xmlns="http://www.cpr.dk">
    <Gctp v="2.0">
        <System r="CprSoeg">
            <Service r="STAMP">
                <CprServiceHeader r="STAMP">
                    <Key>
                        <Field r="PNR" v="..."/>
                    </Key>
                </CprServiceHeader>
            </Service>
        </System>
        <Kvit r="Ok" v="0"/>
    </Gctp>
</root>

Eksempel på ugyldig request/respons

Eksempel hvor requestet ikke overholder XML-standarden: </ CprServiceHeader> i stedet for </CprServiceHeader>.

GCTP request er ugyldig, og der returneres <Kvit> elementet i response, hvor attributten v har værdi 999 og attributten t 's værdi er en beskrivelse af valideringsfejlen.

Ændringer i version 2.0 services

Opbygning af restart (REST) nøgleværdier og SEARCH_ID feltværdier

Restartnøgler benyttes i de søgeservices, der understøtter paginering af responsdata. Restartnøgler bruges i efterfølgende forespørgsler for at hente den næste side data.

SEARCH_ID feltværdier benyttes i visse søgeservices for at indikere, at resultatet af en søgning er blevet gemt. Efterfølgende kald til servicen med en restartnøgle, der indeholder SEARCH_ID feltværdien, vil hente data fra den gemte søgning.

Opbygning af REST nøgleværdier i de version 2.0 GCTP services, der indeholder SEARCH_ID feltværdier, kan afvige fra opbygningenaf REST nøgleværdier i version 1.0 services.

Version 1.0 service eksempel:

Version 2.0 service eksempel:

De CPR Services integrationer, der overfører REST nøgleværdien uændret fra responsdata til et efterfølgende forespørgsler forventes ikke at blive påvirket af denne ændring.