...

...

Nærværende dokument beskriver hvordan routing af beskeder konfigureres i SOSI-DCC. Der forventes at læseren har indgående kendskab til såvel SOSI-DCC som SOSI-Gateway.
Denne konfigurationsvejledning er alene gældende for SOSI-DCC version 2.4.x.

...

DCC'en udstiller de enkle operationer for en service med hver deres default afkoblingsmodel og timeout-grænse. Eksempelvis kunne FMK operationen 'hent medicinkort' udstilles synkront med en timeoutgrænse på 20 sekunder, hvorimod 'suspender medicinkort' kunne udstilles som kø efter timeout med en 10 sekunders timeoutgrænse. 
\\
For at DCC'en kan skelne mellem de forskellige operationer for en service foregår routing og valg af default afkoblingsmodel på baggrund af HTTP headeren 'SOAPAction' i kaldet, som altid skal angives i kaldet for HTTP bundne SOAP web-services \[SOAP\].
\\
I NSP sammenhæng har der indtil nu ikke været understøttelse for de to asynkrone afkoblingsmodeller og i praksis har alle en services operationer som default derfor været udstillet som synkrone operationer med en fast timeoutgrænse.

...

Routing af beskeder i DCC'en kan konfigureres på to måder – enten som filbaseret statisk konfiguration eller som databasebaseret dynamisk konfiguration.

...

For at udstille en service gennem DCC'en skal følgende skridt gennemføres når den filbaserede statiske tilgang benyttes:

...

Notér 'soapAction' attributten for hver operation i servicens WSDL  – bemærk at 'soapAction' attributten er mandatory for HTTP-bundne webservices jf. WSDL specifikationen \[WSDL\]

...

1. 'ActionPrefix' sættes til den identificerede fælles prefix
2. 'URL' sættes til URL'en for servicen
3. 'ProxyURL' (optionel) sættes til URL'en for SOSI-Gateways 'proxy' snitflade såfremt servicen skal tilgås gennem denne
4. 'IdcardMaxAgeMinutes' (optionel) – se afsnittet 'IdcardMaxAgeMinutes instruktionen' længere ned
5. 'DoNotVerifySSLHostname' (optionel) – se afsnittet 'SSL/TLS håndtering' længere ned
6. 'WSA_Headers_Processing' (optionel) – se afsnittet 'WS-Addressing processering' længere ned

...

1. Installation

DCC anvender NSP's Continuous Integration og Continuous Deployment miljøer til byg og leverance af komponenten.

Jenkins

DCC bygges med NSP's Jenkins server via følgende jobs:

• DCC_build - Bygger koden (sker automatisk ved commits)
• DCC_push_snapshot - Pusher det nyeste snapshot image til NSP Docker Registry

NSP er selv ansvarlige for at pushe release versioner af DCC til NSP Docker Registry gennem Jenkins.

Docker

DCC består af et Docker images som pushes til NSP Docker Registry under navnet:

Docker Compose

DCC leveres samtidig som et sæt af Docker Compose filer i folderen https://svn.nspop.dk/svn/components/dcc/trunk/compose.

For release x.y.z af DCC findes Docker Compose filerne i folderen https://svn.nspop.dk/svn/components/dcc/tags/release-x.y.z/compose

Compose folderen indeholder 5 underfoldere:

Konfiguration

I folderen https://svn.nspop.dk/svn/components/dcc/trunk/compose/configuration findes følgende konfigurationsfiler:

Begge filer skal tilrettes til de forskellige miljøer hvorpå de installeres. Filerne indeholder en konfiguration der passer i en standalone test konfiguration.

Afvikling

DCC startes og stoppes med Docker Compose kommandoer.

Standalone test

For en standalone test af DCC hentes "compose" folderen for den ønskede version med Subversion og kommandoen "docker-compose up" køres i folderen "test".

NSP Miljø

På et NSP miljø hentes "compose" folderen for den ønskede version med Subversion og kommandoen "docker-compose up" køres i folderen "release".

2. SOSI-DCC Konfigurationsvejledning

Indledning
Baggrund
Routingskonfiguration
Filbaseret routingskonfiguration
Databasebaseret routingskonfiguration
Generel routingsfunktionalitet
Test af konfiguration
Referencer

Anchor
_Toc325203593 _Toc325203593

Indledning

Nærværende dokument beskriver hvordan routing af beskeder konfigureres i SOSI-DCC. Der forventes at læseren har indgående kendskab til såvel SOSI-DCC som SOSI-Gateway.
Denne konfigurationsvejledning er alene gældende for SOSI-DCC version 2.4.x.

Anchor
_Toc325203594 _Toc325203594

Baggrund

DCC'en udstiller de enkle operationer for en service med hver deres default afkoblingsmodel og timeout-grænse. Eksempelvis kunne FMK operationen 'hent medicinkort' udstilles synkront med en timeoutgrænse på 20 sekunder.

For at DCC'en kan skelne mellem de forskellige operationer for en service foregår routing og valg af default afkoblingsmodel på baggrund af HTTP headeren 'SOAPAction', og evt. 'ServiceIdentifier'-parameteren angivet i url'en. Bemærk at SOAPAction altid skal angives i kaldet for HTTP bundne SOAP web-services \[SOAP\].

Anchor
_Toc325203595 _Toc325203595

Routingskonfiguration

Routing af beskeder i DCC'en kan konfigureres på to måder – enten som filbaseret statisk konfiguration eller som databasebaseret dynamisk konfiguration.

Anchor
_Toc325203596 _Toc325203596

Filbaseret routingskonfiguration

For at udstille en service gennem DCC'en skal følgende skridt gennemføres når den filbaserede statiske tilgang benyttes:

1. Identificér endpoint URL'en for servicen
2. Find servicens WSDL
3. Find ud af hvorvidt servicen skal kaldes gennem SOSI-Gateway

4. Notér 'soapAction' attributten for hver operation i servicens WSDL – bemærk at 'soapAction' attributten er mandatory for HTTP-bundne webservices jf. WSDL specifikationen \[WSDL\]

5. Identificér en fælles prefix for alle de noterede 'soapActions'
6. Definér en timeoutgrænse for hver operation
7. Tilføj nu et <Endpoint> tag til DCC'en konfigurationsfil med følgende attributter:
   1. 'ActionPrefix' sættes til den identificerede fælles prefix
   2. 'URL' sættes til URL'en for servicen
   3. 'ProxyURL' (optionel) sættes til URL'en for SOSI-Gateways 'proxy' snitflade såfremt servicen skal tilgås gennem denne
   4. 'IdcardMaxAgeMinutes' (optionel) – se afsnittet 'IdcardMaxAgeMinutes instruktionen' længere nede
   5. 'DoNotVerifySSLHostname' (optionel) – se afsnittet 'SSL/TLS håndtering' længere nede
   6. 'WSA_Headers_Processing' (optionel) – se afsnittet 'WS-Addressing processering' længere nede
8. Tilføj nu et <Action> tag under <Endpoint> tagget for hver af de identificerede 'soapActions' og sæt 'Name' attributten på <Action> tagget til 'soapActions' navn - uden den identificerede fælles prefix. Hvis operationen skal udstilles under en bestemt ServiceIdentifier, angives dette med en 'ServiceIdentifier'-attribut. Under hver <Action> tag tilføjes derefter et <Timeout> tag med det definerede timeout for operationen som angives i millisekunder.
9. SOSI-DCC genstartes for at få konfigurationsændringen til at slå i gennem

Nedenstående eksempel illustrerer konfigurationen for en service der udstilles gennem DCC, her FMK.

<?xml version="1.0" encoding="UTF-8"?>
<Endpoint ActionPrefix="http://www.dkma.dk/medicinecard/xml.schema/"URL="http://triforkprodtest.lms.trifork.com/fmk12/ws/MedicineCard"ProxyURL="http://localhost:8080/sosigw/proxy/soap-request"IdcardMaxAgeMinutes="560">
  <Action Name="2009/01/01#GetMedicineCard">
    <Timeout>30000</Timeout>
  </Action>
  <!-- flere actions -->
  <Action Name="2011/01/01#CreatePrescriptionMedicationWithoutCPR" ServiceIdentifier="fmk-1">
    <Timeout>30000</Timeout>
  </Action>
</Endpoint>

Konfigurationen kan genindlæses ved kald til ReloadConfiguration baggrundsjobbet, således at konfigurationen kan opdateres uden genstart af komponenten. Se driftsvejledning.

Anchor
_Toc325203597 _Toc325203597

Databasebaseret routingskonfiguration

I den databasebaserede routingskonfiguration læser DCC'en routings konfiguration fra en database. Konfigurationen kan genindlæses ved kald til ReloadConfiguration baggrundsjobbet, således at konfigurationen kan opdateres uden genstart af komponenten - se driftsvejledning. DCC'en forholder sig ikke til hvordan data i database vedligeholdes og kræver udelukkende læseadgang til databasen. 
For at anvende den databasebaserede routingskonfiguration skal følgende skridt gennemføres for en given installation:

1. Anchor
   _Ref260053972 _Ref260053972

   Opsæt og deploy en standard data-source på JBoss applikationsserveren med læsadgang til den database der indeholder routingsinformationen. Det er en forudsætning af de i data-source definitionen refererede Java klasser er tilgængelige på classpath'en for applikationsserveren.

Ikke-normativ eksempel på en data-source definition:

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
  <xa-datasource>
    <jndi-name>crkDS</jndi-name>
    <xa-datasource-property name="URL">jdbc:mysql://:3306/crk</xa-datasource-property>
    <user-name>XXXXX</user-name>
    <password>YYYYYYYYYY</password>
    <xa-datasource-class>com.mysql.jdbc.jdbc2.optional.MysqlXADataSource</xa-datasource-class>
    <driver-class>com.mysql.jdbc.Driver</driver-class>
    <min-pool-size>2</min-pool-size>
    <max-pool-size>20</max-pool-size>
    <idle-timeout-minutes>5</idle-timeout-minutes>
    <track-connection-by-tx>true</track-connection-by-tx>
    <exception-sorter-class-name>com.mysql.jdbc.integration.jboss.ExtendedMysqlExceptionSorter</exception-sorter-class-name>
    <valid-connection-checker-class-name>com.mysql.jdbc.integration.jboss.MysqlValidConnectionChecker</valid-connection-checker-class-name>
  </xa-datasource>
</datasources>

2. 

3. 

4. Opdatér DCC'ens konfigurationsfil ved at slette alle <Endpoint> definitioner og indsætte følgende <EndpointDatabase> struktur i stedet:

<EndpointDatabase>
   <DataSourceName>DATASOURCE</DataSourceName>
   <ActionsSelectStatement>ACTION_SELECT</ActionsSelectStatement>
   <GatewayProxyURL>PROXY_URL</GatewayProxyURL>
</EndpointDatabase>

Hvor der gælder at

• DATASOURCE er navnet på datasourcen deployet under

  Anchor
  _Hlt260053990 _Hlt260053990

  1) præfikset med java:/
• ACTION_SELECT er det i 2) definerede statement
• PROXY_URL er den i 3) eventuel identificerede proxy eller tomt hvis der ikke benyttes nogen proxy

6. Genstart derefter komponenten og verificer at der ikke optræder nogen 'ERROR' log-indgange i komponentens log-fil.

Bemærk: DCC'en fejler under opstart hvis det angivne 'select' statement kaster en exception, men starter korrekt selvom 'select' statement måtte returnere tomme result-sets. 
Ikke-normativ eksempel på en endpoint-database definition:

<?xml version="1.0" encoding="UTF-8"?>
<EndpointDatabase>
  <DataSourceName>java:/crkDS</DataSourceName>
  <ActionsSelectStatement>select SOAP_ACTION, SERVICE_URL, TIMEOUT_MILLIS, IDCARD_MAXAGE_MINS, USE_PROXY, DO_NOT_VERIFY_SSL_HOSTNAME, WSA_HEADERS_PROCESSING from DCC_ACTIONS</ActionsSelectStatement>
  <GatewayProxyURL>http://127.0.0.2:8080/sosigw/proxy/soap-request</GatewayProxyURL>
</EndpointDatabase>

Anchor
_Toc325203598 _Toc325203598

Generel routingsfunktionalitet

Vigtigt: Bemærk at der kun kan kaldes operationer som er blevet konfigureret, dette betyder, at når en serviceudbyder tilføjer operationer til en eksisterende service skal disse ligeledes tilføjes til DCC'ens konfiguration før de kan kaldes gennem DCC'en. I øvrigt anbefales der, at der i takt med at en serviceudbyder fjerner operationer fra en service at disse ligeledes fjernes fra DCC'ens konfiguration.

Bevarelse af URL suffiks
Det er muligt at konfigurere såvel URL som ProxyURL attributterne til at bevare URL suffikset i kaldet, dvs. alt i klienternes kald efter http://HOST:PORT/decoupling tilføjes til hhv. URL og/eller ProxyURL. Bevarelse af URL suffiks konfigureres ved at lade URL/ProxyURL attributten ende på '/*'.
Med f.eks. nedenstående konfiguration vil kald til http://HOST:PORT/decoupling/foo blive viderestillet til http://foobar.com/example/foo (for kald med SOAPAction 'http://www.example.org#doIt'):

<?xml version="1.0" encoding="UTF-8"?>
<Endpoint ActionPrefix="http://www.example.org#" URL="http://foobar.com/example/*">
  <Action Name="doIt">
    <Timeout>10000</Timeout>
  </Action>
</Endpoint>

Bemærk at det stadig er muligt at bevare URL suffiks, når der angives en ServiceIdentifier. 

...

I den databasebaserede routingskonfiguration genindlæser DCC'en routings konfiguration fra en database med jævne mellemrum, således at konfigurationen kan opdateres uden genstart af komponenten. DCC'en forholder sig ikke til hvordan data i database vedligeholdes og kræver udelukkende læseadgang til databasen.
For at anvende den databasebaserede routingskonfiguration skal følgende skridt gennemføres for en given installation:

...

1. Et 'LastUpdateSelectStatement' som returnerer én og kun én række med én og kun én værdi af typen 'Datetime' eller null. Værdien skal afspejle hvornår routingsinformation sidst er blevet opdateret. DCC genindlæser hele konfigurationen hvis denne værdi er større end den komponenten sidst har læst (komponenten benytter 1/1/1970 som initiel dato).
2. Et 'ActionSelectStatement' som returner et antal rækker som indeholder følgende navngivne værdier med følgende egenskaber:

...

Navn

...

Datatype

...

Nullable

...

Betydning

...

SOAP_ACTION

...

String

...

Nej

...

Routingsnøglen - skal være unik

...

SERVICE_URL

...

String

...

Nej

...

Endpointet hvortil beskeder for den givne soap action skal routes til

...

TIMEOUT_MILLIS

...

int

...

Nej

...

Grænseværdien for hvornår det (synkrone) kald afbrydes

...

USE_PROXY

...

boolean

...

Ja

...

Hvorvidt beskeder skal sendes gennem proxy hvis en sådan er defineret i DCC'ens statiske konfiguration

...

IDCARD_MAXAGE_MINS

...

int

...

Ja

...

DO_NOT_VERIFY_SSL_HOSTNAME

...

boolean

...

Ja

...

WSA_HEADERS_PROCESSING

...

String

...

Ja

...

1. Genstart derefter komponenten og verificer at der ikke optræder nogen 'ERROR' log-indgange i komponentens log-fil.

...

Vigtigt: Bemærk at der kun kan kaldes operationer som er blevet konfigureret, dette betyder, at når en serviceudbyder tilføjer operationer til en eksisterende service skal disse ligeledes tilføjes til DCC'ens konfiguration før de kan kaldes gennem DCC'en. I øvrigt anbefales der, at der i takt med at en serviceudbyder fjerner operationer fra en service at disse ligeledes fjernes fra DCC'ens konfiguration.
Bevarelse af URL suffiks
Det er muligt at konfigurere såvel URL som ProxyURL attributterne til at bevare URL suffikset i kaldet, dvs. alt i klienternes kald efter http://HOST:PORT/decoupling tilføjes til hhv. URL og/eller ProxyURL. Bevarelse af URL suffiks konfigureres ved at lade URL/ProxyURL attributten ende på '/*'.

Med f.eks. nedenstående konfiguration vil kald til http://HOST:PORT/decoupling/service/bar/foo blive viderestillet til http://foobar.com/example/foo (for kald med SOAPAction 'http://www.example.org#doIt').
<Endpoint :

<?xml version="1.0" encoding="UTF-8"?>
<Endpoint ActionPrefix="http://www.example.org#" URL="http://foobar.com/example/*">

...

  <Action Name="doIt" ServiceIdentifier="

...

bar">

...

    <Timeout>10000</Timeout>

...

  </Action>

...

</Endpoint>

IdcardMaxAgeMinutes instruktionen
For en service der kaldes gennem SOSI-Gateway kan der angives en IdcardMaxAgeMinutes konfigurationsparameter som sættes til den alder i minutter et idkort højst må have for at servicen vil acceptere den. Hvis denne parameter sættes tilføjer DCC'en en SOSI-GW specifik soap header til kaldet med parameterværdien. Når SOSI-GW modtager kaldet vil den afvise den med en standard 'no valid idcard in cache' hvis idkortet i dens cache er ældre en angivet i parameteren.
Fordelen ved at sætte denne parameter er at klienter spares for et kald i de tilfælde hvor der er et idkort i SOSI-GW som er gyldigt, men for gammel i forhold til den service der bliver kaldt: Fremfor at de får en fejlbesked fra servicen om at idkortet er for gammel og derefter skal foretage et eksplicit login til SOSI-GW (som består af to kald), får de i stedet et fejlsvar fra SOSI-GW med en implicit login header og kan derefter foretage et eksplicit login til SOSI-GW med et enkelt kald.
Ulempen ved at benytte parameteren er at værdien skal afstemmes med serviceudbyderen.
SSL/TLS håndtering
For udgående HTTPS kald validerer DCC'en som udgangspunkt 'trust' af det kaldte endpoint's SSL/TLS-server-certifikat mod Java's egen truststore.
Det er muligt at udvide 'trust' til at omfatte certifikater (også udstedende rod-/kryds-certifikater) fra et lokalt truststore.
Det lokale truststore skal være et standard Java KeyStore fil, som indeholder de trustede (almindelige eller udstedende) certifikater. KeyStoren filen placeres i $JBOSS_HOME/standalone/configuration/ og konfigureres i DCC'ens konfigurationsfil (dcc-config.xml) med filnavn og password, feks som:
<TrustStore> <JKS_File>dcc-test-truststore.jks</JKS_File> <Password>Test1234</Password> </TrustStore>
Som default foretages hostname verifikation af server-certifikatet (wildcards er understøttet) – dette er dog muligt at slå fra på endpoint/action niveau ved at sætte 'DoNotVerifySSLHostname' (for XML baseret endpoint konfiguration) eller 'DO_NOT_VERIFY_SSL_HOSTNAME' (for database baseret konfiguration) til 'true'.
WS-Addressing processering:
Der kan konfigureres hvordan WS-Addressing headere i routede kald skal håndteres af DCC. Følgende tre modeller understøttes:

• WSA_OVERWRITE (default): Eventuel eksisterende WS-Addressing headere fjernes, og der indsættes to nye WS-Addressing headere med hhv. SoapAction ('wsa:Action') og endpoint URL'en (wsa:To).
• WSA_REMOVE: Eventuel eksisterende WS-Addressing headere fjernes og der indsættes ingen nye.
• WSA_PASSTHROUGH: Eventuel eksisterende WS-Addressing headere bevares og der indsættes ingen nye.

...

(som består af to kald), får de i stedet et fejlsvar fra SOSI-GW med en implicit login header og kan derefter foretage et login til SOSI-GW med et enkelt kald.
Ulempen ved at benytte parameteren er at værdien skal afstemmes med serviceudbyderen.

SSL/TLS håndtering
For udgående HTTPS kald validerer DCC'en som udgangspunkt 'trust' af det kaldte endpoint's SSL/TLS-server-certifikat mod Java's egen truststore.
Det er muligt at udvide 'trust' til at omfatte certifikater (også udstedende rod-/kryds-certifikater) fra et lokalt truststore.
Det lokale truststore skal være et standard Java KeyStore fil, som indeholder de trustede (almindelige eller udstedende) certifikater. KeyStoren filen placeres i $JBOSS_HOME/standalone/configuration/ og konfigureres i DCC'ens konfigurationsfil (dcc-config.xml) med filnavn og password, feks som:

<?xml version="1.0" encoding="UTF-8"?>
<TrustStore>
  <JKS_File>dcc-test-truststore.jks</JKS_File>
  <Password>Test1234</Password>
</TrustStore>

Som default foretages hostname verifikation af server-certifikatet (wildcards er understøttet) – dette er dog muligt at slå fra på endpoint/action niveau ved at sætte 'DoNotVerifySSLHostname' (for XML baseret endpoint konfiguration) eller 'DO_NOT_VERIFY_SSL_HOSTNAME' (for database baseret konfiguration) til 'true'.

WS-Addressing processering:
Der kan konfigureres hvordan WS-Addressing headere i routede kald skal håndteres af DCC. Følgende tre modeller understøttes:

• WSA_OVERWRITE (default): Eventuel eksisterende WS-Addressing headere fjernes, og der indsættes to nye WS-Addressing headere med hhv. SoapAction ('wsa:Action') og endpoint URL'en (wsa:To).
• WSA_REMOVE: Eventuel eksisterende WS-Addressing headere fjernes og der indsættes ingen nye.
• WSA_PASSTHROUGH: Eventuel eksisterende WS-Addressing headere bevares og der indsættes ingen nye.

Bemærk at hvis kaldet routes i gennem SOSI-GW indsættes altid nye WS-Addressing headere (svarende til WSA_OVERWRITE).

Anchor
_Toc325203599 _Toc325203599

Test af konfiguration

Der anbefales at der udformes en testklient for hver service der udstilles for at kunne verificere at servicen kan kaldes i gennem DCC'en.

Anchor
_Toc325203600 _Toc325203600

Referencer

...

Der anbefales at der udformes en testklient for hver service der udstilles for at kunne verificere at servicen kan kaldes i gennem DCC'en.

...