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, 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.

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. Wiki Markup
   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 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
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. Under hver <Action> tag tilføjes derefter et <DecouplingModel> tag med værdien 'synchronous_timeout' og 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.
<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">
<DecouplingModel>synchronous_timeout</DecouplingModel>
<Timeout>30000</Timeout>
</Action>
<!-- flere actions -->
<Action Name="2011/01/01#CreatePrescriptionMedicationWithoutCPR">
<DecouplingModel>synchronous_timeout</DecouplingModel>
<Timeout>30000</Timeout>
</Action>
</Endpoint>

Anchor
_Toc325203597 _Toc325203597

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

1. Anchor
   _Ref260054066 _Ref260054066

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

1. Anchor
   _Ref260054115 _Ref260054115

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

2. Anchor
   _Ref260054172 _Ref260054172

   Identificér URL'en for en eventuel (SOSI-GW) proxy på den pågældende installation.
3. 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

  Anchor
  _Hlt260053990 _Hlt260053990

  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

1. 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:
<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>

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').
<Endpoint ActionPrefix="http://www.example.org#" URL="http://foobar.com/example/*">
<Action Name="doIt">
<DecouplingModel>synchronous_timeout</DecouplingModel>
<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:
<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