|
|
| Line 1: |
Line 1: |
| − | == Introduction to XIS ==
| |
| − | Documentation on using XIS is detailed in [[ART_Tests]].
| |
| | | | |
| − | XIS functions as a testserver which can be used to test remote applications: validate messages/documents or uploaded files.
| |
| − | Depending on the testscript the following situations are possible:
| |
| − | * The remote application initiates an interaction to the XIS-server
| |
| − | ** The remote application sends a message or does a query
| |
| − | ** The XIS-server returns content or (n)ack to the remote application
| |
| − | * XIS-server initiates an interaction to the remote application
| |
| − | ** The XIS-server sends a message or does a query to the remote application
| |
| − | ** The remote application returns content or (n)ack to the XIS-server
| |
| − | * The messages are manually uploaded with XIS
| |
| − |
| |
| − | == Setting up a testaccount ==
| |
| − | Before starting a test, a testaccount should be configured:
| |
| − | * Log in on the XIS-server (ART-DECOR)
| |
| − | * Go to: 'Testing', 'Test Accounts'
| |
| − | * Check if there is a testaccount already present for this vendor/application, if not:
| |
| − | * Create a testaccount by clicking on the +: 'Add test account'
| |
| − | When adding a testaccount the following information can be entered:
| |
| − | * Account name: short name for the testaccount. Use <HL7 set>-<vendor>-<application name>
| |
| − | * Display Name: Display name for the testaccount. This name is used as display name for the testaccount.
| |
| − | * Organization: for which vendor is this testaccount configured. Enter a vendor/organization name.
| |
| − | * Concact: Who is the primary technical contact person for this testaccount within the remote organization.
| |
| − | * Email: The email-address of the technical contact person.
| |
| − | For each application, add with +:
| |
| − | * Application Id of the remote application
| |
| − | * Name of the remote application
| |
| − | * URL of the remote application (only required for scripts when the XIS-server initiates interactions). The URL should contain: http:// or https://
| |
| − | * (optional) Organization Register Id (can be used in response templates in payload)
| |
| − | XIS HL7 configuration: here the configuration for the XIS-server can be changed. This will modify the information passed to response templates.
| |
| − | ** Application Id: which Application Id to use for the XIS-server.
| |
| − | ** HL7 resources: which HL7 materials are used. Displays a dropdown-box from which the HL7-material set can be selected.
| |
| − | Permissions for this testaccount:
| |
| − | * Users: add users who have permission to view/edit this testaccount
| |
| − | Store the configuration:
| |
| − | * save: saves the testaccount configuration
| |
| − | Screenshot for the configuration of a testaccount:
| |
| − |
| |
| − | [[Image:En_xis_testaccount_configure.png|800px]]
| |
| − |
| |
| − | == Connectivity description ==
| |
| − | The following content is handled by the XIS-server:
| |
| − | * SOAP-messages, optionally including a SOAP-header
| |
| − | * HTTP (no certificates) or HTTPS (with certificates)
| |
| − | * With or without SOAP security tokens
| |
| − | XIS will store the entire SOAP message, but only displays the payload of messages.
| |
| − | == Creating an HL7 material set ==
| |
| − | HL7 material sets contain schema and/or schematron (SVRL) to validate message instances in XIS. The same HL7 material set can contain templates for sending out XML instances or responding to XML instances.
| |
| − | To create a HL7 materials, the following is needed:
| |
| − | * Create a xar package, see [[ART_developers_manual#Creating_new_.xar_packages|Creating new .xar_packages]]
| |
| − | * Create the following layout and content in the xar package, see [[HL7 material set]]
| |
| − |
| |
| − | == Loading a HL7 material set ==
| |
| − | Use the eXist-db dashboard as explained in the [[Download#Software|installation manual]] to add a HL7 materials xar package to the XIS-server.
| |
| − | == Service location ==
| |
| − | To configure the XIS-server to listen for incoming interactions, the service location (typically found in the WSDL) should be activated:
| |
| − | * Go to: 'Testing', 'XIS Configuration'
| |
| − | * Available Services: select the HL7-material set from the dropdown box. The messageTypes and service locations which can be selected are shown
| |
| − | * Click +: to activate this service location.
| |
| − | [[Image:En_xis_service_location_configure.png|800px]]
| |
| − | == Query templates ==
| |
| − | Query templates are templates that are used by XIS when querying other applications.
| |
| − | <TODO>
| |
| − | == Send templates ==
| |
| − | Send templates are templates that are used by XIS when sending out message instances.
| |
| − | <TODO>
| |
| − | == Response templates ==
| |
| − | When the XIS-server should receive interactions (not through upload), response templates should be present in /hl7/<HL7 material set>/message-templates
| |
| − | Typically they will contain the response in XML which (based on the WSDL) should be returned to the remote application as a reply.
| |
| − | See also the next sections which describe the variables that can be used in these templates.
| |
| − |
| |
| − | Here is an example for an HL7-ack:
| |
| − | <syntaxhighlight lang="xml" heading="Example fragment">
| |
| − | <MCCI_IN000002 xmlns="urn:hl7-org:v3" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
| |
| − | <id extension="{util:uuid()}" root="{$messageIdRoot}"/>
| |
| − | <creationTime value="{datetime:format-dateTime(current-dateTime(),'yyyyMMddHHmmssZ')}"/>
| |
| − | <versionCode code="NICTIZEd2005-Okt"/>
| |
| − | <interactionId extension="MCCI_IN000002" root="2.16.840.1.113883.1.6"/>
| |
| − | <profileId root="2.16.840.1.113883.2.4.3.11.1" extension="810"/>
| |
| − | <processingCode code="P"/>
| |
| − | <processingModeCode code="T"/>
| |
| − | <acceptAckCode code="NE"/>
| |
| − | <acknowledgement typeCode="CA">
| |
| − | <targetMessage>
| |
| − | {$message/id}
| |
| − | </targetMessage>
| |
| − | </acknowledgement>
| |
| − | <receiver>
| |
| − | <device>
| |
| − | <id extension="{$message/hl7:sender/hl7:device/hl7:id/@extension}"
| |
| − | root="{$message/hl7:sender/hl7:device/hl7:id/@root}"/>
| |
| − | </device>
| |
| − | </receiver>
| |
| − | <sender>
| |
| − | <device>
| |
| − | <id extension="{$applicationId}" root="2.16.840.1.113883.2.4.6.6"/>
| |
| − | </device>
| |
| − | </sender>
| |
| − | </MCCI_IN000002>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | == Using variables in templates ==
| |
| − | The following variables are used in message templates.
| |
| − |
| |
| − | Note: the way to format xs:dayTimeDuration and picture-strings are part of the W3C standards. See: [http://www.w3.org/TR/xmlschema-2/#duration duration] and [http://www.w3.org/TR/xslt20/#date-picture-string date-picture-string] ([http://www.w3.org/TR/xslt20/#date-time-examples date-time-examples]).
| |
| − |
| |
| − | ===Variables typically used in message payload===
| |
| − | See also [[XIS_maintenance#Variables_typically_used_in_message_wrappers_for_reponse_templates|Variables typically used in message wrappers for reponse templates]] for elements such as id, creationTime, targetMessage.
| |
| − | * Current date
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {format-date(current-date(),'[Y0001][M01][D01]')}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 20150821
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <author>
| |
| − | <time value="{format-date(current-date(),'[Y0001][M01][D01]')}"/>
| |
| − | </author>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | * Current date minus/plus x number of days
| |
| − | Use P500D to add/subtract 500 days from the current date.
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {format-date(current-date()-xs:dayTimeDuration('P500D'),'[Y0001][M01][D01]')}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 20140408
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <phase>
| |
| − | <center value="{format-date(current-date()-xs:dayTimeDuration('P31D'),'[Y0001][M01][D01]')}"/></phase>
| |
| − | </syntaxhighlight>
| |
| − | With time appended (hardcoded in the template as a fixed time):
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <phase>
| |
| − | <center value="{format-date(current-date()-xs:dayTimeDuration('P31D'),'[Y0001][M01][D01]')}0800"/>
| |
| − | </phase>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | * Query id/@extension attribute from the incoming message
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@extension}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 179a1709-636d-4bbf-be27-43de86f84e20
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <queryAck>
| |
| − | <queryId extension="{$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@extension}" root="{$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@root}"/>
| |
| − | </queryAck>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | * Query id/@root attribute from the incoming message
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@root}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 2.16.528.1.1007.3.3.999.1.10
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <queryAck>
| |
| − | <queryId extension="{$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@extension}" root="{$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@root}"/>
| |
| − | </queryAck>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | ===Variables typically used in message wrappers for reponse templates===
| |
| − | * uuid, for instance for /id/@extension
| |
| − | Returns a universally unique identifier (UUID) which can be used as a message (or payload) identifier.
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {util:uuid()}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 179a1709-636d-4bbf-be27-43de86f84e20
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <id extension="{util:uuid()}" root="{$messageIdRoot}"/>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | * messageIdRoot, for instance for /id/@root
| |
| − | Returns the root OID which is used for message identification for the responding application (our own ART-DECOR server).
| |
| − | Note that this variable is hardcoded in /db/apps/xis/modules/retrieve-SOAP-response.xquery
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {$messageIdRoot}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 2.16.840.1.113883.2.4.6.6.1
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <id extension="{util:uuid()}" root="{$messageIdRoot}"/>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | * current date and time, for instance used in /creationTime/@value
| |
| − | Returns the current date and time.
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {datetime:format-dateTime(current-dateTime(),'yyyyMMddHHmmssZ')}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 20150821163649+0200
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <creationTime value="{datetime:format-dateTime(current-dateTime(),'yyyyMMddHHmmssZ')}"/>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | * current date and time, for instance used in /creationTime/@value
| |
| − | Returns the current date and time.
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {datetime:format-dateTime(current-dateTime(),'yyyyMMddHHmmssZ')}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 20150821163649+0200
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <creationTime value="{datetime:format-dateTime(current-dateTime(),'yyyyMMddHHmmssZ')}"/>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | * incoming message id element
| |
| − | Returns the message id element from the incoming message.
| |
| − | Note that {$message} contains the incoming message, and xpath can be used to return specific XML elements and attributes.
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {$message/id}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | <id root="2.16.528.1.1007.3.3.999.1.11" extension="555555112"/>
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <targetTransmission> {$message/id} </targetTransmission>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | * incoming message device id @extension
| |
| − | Returns the device/id/@extension from the incoming message.
| |
| − | Note that for message filtering to work correctly this device id should be configured through the ART webinterface at testing/test accounts/Application/Application Id
| |
| − | Note that device/id corresponds to the identification of the sending application.
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {$message/hl7:sender/hl7:device/hl7:id/@extension}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 85
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <receiver>
| |
| − | <device>
| |
| − | <id extension="{$message/hl7:sender/hl7:device/hl7:id/@extension}" root="{$message/hl7:sender/hl7:device/hl7:id/@root}"/>
| |
| − | </device>
| |
| − | </receiver>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | * incoming message device id @root
| |
| − | Returns the device/id/@root from the incoming message.
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {$message/hl7:sender/hl7:device/hl7:id/@root}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 2.16.528.1.1007.3.3.999.1.11
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <receiver>
| |
| − | <device>
| |
| − | <id extension="{$message/hl7:sender/hl7:device/hl7:id/@extension}" root="{$message/hl7:sender/hl7:device/hl7:id/@root}"/>
| |
| − | </device>
| |
| − | </receiver>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | * Returns our own sender id/@extension attribute as configured in the testaccount as XIS HL7 configuration / Application Id
| |
| − | <syntaxhighlight lang="xml" heading="Usage">
| |
| − | {$applicationId}
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="Output example">
| |
| − | 1
| |
| − | </syntaxhighlight>
| |
| − | <syntaxhighlight lang="xml" heading="In an example fragment" enclose="div">
| |
| − | <sender>
| |
| − | <device>
| |
| − | <id extension="{$applicationId}" root="2.16.840.1.113883.2.4.6.6"/>
| |
| − | </device>
| |
| − | </sender>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | == Message handling ==
| |
| − | Incoming/sent/uploaded messages/documents are stored in the messagelog.
| |
| − | For incoming messages the following logic is used:
| |
| − | * Does the incoming /sender/device/@id match a Application Id for one of the testaccounts. If so: store the message in this testaccount messagelog.
| |
| − | * Is this service location active on the XIS-server?
| |
| − | * Can a WSDL be found?
| |
| − | * What are the valid output messages for this service based on SOAPAction?
| |
| − | * Is there an optional message filter configured for this content?
| |
| − | * Send out a reply
| |
| − | == Configuring response filters ==
| |
| − | In some testscripts, depending on the incoming content different replies should be sent out, for example based on:
| |
| − | * message type
| |
| − | * patient identifier
| |
| − | For this purpose a messageFilter can be configured in: /hl7/<HL7 material set>/message-templates/messageFilter_manifest.xml
| |
| − | An example filter configuration:
| |
| − | <syntaxhighlight lang="xml" heading="Example fragment" enclose="div">
| |
| − | <messageFilters>
| |
| − | <messageFilter>
| |
| − | <message active="true" interactionId="REPC_IN000023NL">
| |
| − | <desc language="en-US">query potential contraindications</desc>
| |
| − | <queryParameters>
| |
| − | <parameter name="patientId"
| |
| − | value="999999011">//*:queryByParameter/*:patientID/*:value
| |
| − | [@root='2.16.840.1.113883.2.4.6.3']/@extension</parameter>
| |
| − | </queryParameters>
| |
| − | <responseTemplateFile value="MCCI_IN200101_REPC_EX000024NL_01_999999011.xml"/>
| |
| − | </message>
| |
| − | </messageFilter>
| |
| − | <messageFilter>
| |
| − | <message active="false" interactionId="REPC_IN990003NL">
| |
| − | <desc language="en-US">
| |
| − | initial setting: false -> RTEDEST -->
| |
| − | for ACK use: true (then this messageFilter will match and respond with ACK)
| |
| − | for RTEDEST use: false (then the next messageFilter will match
| |
| − | and respond with RTEDEST)</desc>
| |
| − | <queryParameters>
| |
| − | <parameter name="patientId"
| |
| − | value="999999072">//*:subject/*:PrimaryCareProvision/*:subject/*:Patient/*:id
| |
| − | [@root='2.16.840.1.113883.2.4.6.3']/@extension</parameter>
| |
| − | </queryParameters>
| |
| − | <responseTemplateFile value="MCCI_IN000002.xml"/>
| |
| − | </message>
| |
| − | </messageFilter>
| |
| − | <messageFilter>
| |
| − | <message active="true" interactionId="REPC_IN990003NL">
| |
| − | <queryParameters>
| |
| − | <parameter name="patientId"
| |
| − | value="999999072">//*:subject/*:PrimaryCareProvision/*:subject/*:Patient/*:id
| |
| − | [@root='2.16.840.1.113883.2.4.6.3']/@extension</parameter>
| |
| − | </queryParameters>
| |
| − | <responseTemplateFile value="MCCI_IN000002_RTEDEST.xml"/>
| |
| − | </message>
| |
| − | </messageFilter>
| |
| − | </messageFilters>
| |
| − | </syntaxhighlight>
| |
| − |
| |
| − | == Configuring query parameters ==
| |
| − | In some testscripts, depending on the message templates, specific query parameters can be configured per query type. To configure these query parameters, create a file in the HL7-materials package as /hl7/<HL7 material set>/message-templates/query_manifest.xml
| |
| − |
| |
| − | Every HL7V3 query message in the package SHALL have an entry in this file in an element <query>.
| |
| − | This element has an attribute @id containing the interactionId including version of the interaction, but without namespace prefix.
| |
| − | The first child element is <name language="..."> containing the query name in the appropriate language(s).
| |
| − | The next element is <patientId> containing Dutch patient id, which is used as patientId/value[@root="2.16.840.1.113883.2.4.6.3"]/@extension
| |
| − |
| |
| − | The next element is <parameters> containing the parameters exactly as you would like them to be in the resulting query including the right namespace.
| |
| − |
| |
| − | If a query parameter itself is marked with @atp:repeats='true', or if the contained hl7:value element is marked as such, this will trigger the form to offer 'add' and 'delete' options to add/remove queryparameters (AND logic) or add/remove value items (OR logic).
| |
| − | <syntaxhighlight lang="xml" heading="Example fragment" enclose="div">
| |
| − | <queryManifest xmlns:atp="urn:nictiz.atp">
| |
| − | <version date="2014-09-10T15:00:00" by="username">
| |
| − | <desc language="en-US">message filters for qualification and test purposes</desc>
| |
| − | </version>
| |
| − | <query id="QURX_IN990011NL">
| |
| − | <name language="nl-NL">Opvragen verstrekkingen</name>
| |
| − | <patientId>789123459</patientId>
| |
| − | <parameters>
| |
| − | <administrationRequestEffectiveTimeInterval xmlns="urn:hl7-org:v3">
| |
| − | <value>
| |
| − | <low value="20111101"/>
| |
| − | </value>
| |
| − | </administrationRequestEffectiveTimeInterval>
| |
| − | </parameters>
| |
| − | </query>
| |
| − | </queryManifest>
| |
| − | </syntaxhighlight>
| |
| − | ==Testsuite schematron to check payload==
| |
| − | Testsuite schematron can be used to check whether message payload conforms to a specific testcase.
| |
| − | See: [[Specifying_Tests_with_DECOR]]
| |
