DCC anvender NSP's Continuous Integration og Continuous Deployment miljøer til byg og leverance af komponenten.
DCC bygges med NSP's Jenkins server via følgende jobs:
NSP er selv ansvarlige for at pushe release versioner af DCC til NSP Docker Registry gennem Jenkins.
DCC består af et Docker images som pushes til NSP Docker Registry under navnet:
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:
Folder | Indhold |
---|---|
configuration | Her ligger alle de konfigurationsfiler som det forventes af driften tilretter til det anvendte miljø. |
development | Her ligger en Docker Compose fil til brug for udvikling. Se Guide til Udviklere. |
test | Her ligger en Docker Compose fil der kan starte DCC i en standalone test konfiguration. |
release | Her ligger den Docker Compose fil som det forventes driften anvender på både test og produktionsmiljøerne. |
I folderen https://svn.nspop.dk/svn/components/dcc/trunk/compose/configuration findes følgende konfigurationsfiler:
Fil | Indhold |
---|---|
dcc-config.xml | Konfiguration af dcc servicen |
dcc-service.xml | Konfiguration af dcc servicen |
log4j-dcc.properties | Log opsætning af dcc servicen |
log4j-nspslalog.properties | Opsætning af NSP SLA log |
Begge filer skal tilrettes til de forskellige miljøer hvorpå de installeres. Filerne indeholder en konfiguration der passer i en standalone test konfiguration.
DCC startes og stoppes med Docker Compose kommandoer.
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".
På et NSP miljø hentes "compose" folderen for den ønskede version med Subversion og kommandoen "docker-compose up" køres i folderen "release".
Indledning
Baggrund
Routingskonfiguration
Filbaseret routingskonfiguration
Databasebaseret routingskonfiguration
Generel routingsfunktionalitet
Test af konfiguration
Referencer
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.
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\].
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\]
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.
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:
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 'select' statement,'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 | Den action der ønskes kaldt. |
SERVICE_IDENTIFIER | String | Ja | Logisk navn på den service der ønskes kaldt. Parret <SOAP_ACTION, SERVICE_IDENTIFIER> skal være unikt. Bemærk at SERVICE_IDENTIFIER kan være NULL af hensyn til bagudkompatibilitet. |
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 | Instruktion til en evt. SOSI-Gateway. |
DO_NOT_VERIFY_SSL_HOSTNAME | boolean | Ja | Hvorvidt hostname verifikation af SSL-servercertifikatet skal foretages. |
WSA_HEADERS_PROCESSING | String | Ja | Hvordan WS-Addressing headere skal processeres, se afsnittet 'WS-Addressing processering' længere nede for tilladte værdier. |
3. Identificér URL'en for en eventuel (SOSI-GW) proxy på den pågældende installation.
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
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> |
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:
Bemærk at hvis kaldet routes i gennem SOSI-GW indsættes altid nye WS-Addressing headere (svarende til WSA_OVERWRITE).
Der anbefales at der udformes en testklient for hver service der udstilles for at kunne verificere at servicen kan kaldes i gennem DCC'en.
[SOAP] | Simple Object Access Protocol (SOAP) 1.1 | http://www.w3.org/TR/2000/NOTE-SOAP-20000508/ |
[WSDL] | Web Services Description Language (WSDL) 1.1 | http://www.w3.org/TR/wsdl |