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

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.

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\].

Routingskonfiguration

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

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>

Databasebaseret routingskonfiguration

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. 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. Definér to 'select' statements:

a. 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).

b. Et 'ActionSelectStatement' som returner et antal rækker som indeholder følgende navngivne værdier med følgende egenskaber:

3. Fastlæg hvor tit DCC'en skal genindlæse konfigurationen fra databasen, målt i minutter.

4. Identificér URL'en for en eventuel (SOSI-GW) proxy på den pågældende installation.

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

<EndpointDatabase>
   <DataSourceName>DATASOURCE</DataSourceName>
   <LastUpdateSelectStatement>LAST_UPDATE_SELECT</LastUpdateSelectStatement>
   <ActionsSelectStatement>ACTION_SELECT</ActionsSelectStatement>
   <RefreshIntervalMinutes>INTERVAL</RefreshIntervalMinutes>
   <GatewayProxyURL>PROXY_URL</GatewayProxyURL>
</EndpointDatabase>

Hvor der gælder at

• DATASOURCE er navnet på datasourcen deployet under 1) præfikset med java:/
• LAST_UPDATE_SELECT og ACTION_SELECT er de i 2) definerede statements
• INTERVAL er det i 3) fastlagte interval
• PROXY_URL er den i 4) 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 et af de to 'select' statements kaster en exception, men starter korrekt selvom de to 'select' statements måtte returnere tomme result-sets.
Når der foreligger en opdateret konfiguration i databasen erstatter denne den tidligere indlæste konfiguration uden at DCC'en forholder sig til forskellene mellem de to konfigurationer. Hvis der er fejl i den nye konfiguration logges dette og den tidligere korrekt indlæste bibeholdes.
Ikke-normativ eksempel på en endpoint-database definition:

<?xml version="1.0" encoding="UTF-8"?>
<EndpointDatabase>
  <DataSourceName>java:/crkDS</DataSourceName>
  <LastUpdateSelectStatement>select LAST_UPDATE from DCC_LASTUPDATE</LastUpdateSelectStatement>
  <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>
  <RefreshIntervalMinutes>60</RefreshIntervalMinutes>
  <GatewayProxyURL>http://127.0.0.2:8080/sosigw/proxy/soap-request</GatewayProxyURL>
</EndpointDatabase>

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. 

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'):

<?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 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).

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.

Referencer