XIS maintenance

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:

En xis testaccount configure.png

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:

Loading a HL7 material set

Use the eXist-db dashboard as explained in the 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.

En xis service location configure.png

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: 

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

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: duration and date-picture-string (date-time-examples).

Variables typically used in message payload

See also Variables typically used in message wrappers for reponse templates for elements such as id, creationTime, targetMessage.

  • Current date
{format-date(current-date(),'[Y0001][M01][D01]')}

20150821

<author>
<time value="{format-date(current-date(),'[Y0001][M01][D01]')}"/>
</author>
  • Current date minus/plus x number of days

Use P500D to add/subtract 500 days from the current date. 

{format-date(current-date()-xs:dayTimeDuration('P500D'),'[Y0001][M01][D01]')}

20140408

<phase>
<center value="{format-date(current-date()-xs:dayTimeDuration('P31D'),'[Y0001][M01][D01]')}"/></phase>

With time appended (hardcoded in the template as a fixed time): 

<phase>
<center value="{format-date(current-date()-xs:dayTimeDuration('P31D'),'[Y0001][M01][D01]')}0800"/>
</phase>
  • Query id/@extension attribute from the incoming message
{$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@extension}

179a1709-636d-4bbf-be27-43de86f84e20

<queryAck>
<queryId extension="{$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@extension}" root="{$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@root}"/>
</queryAck>
  • Query id/@root attribute from the incoming message
{$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@root}

2.16.528.1.1007.3.3.999.1.10

<queryAck>
<queryId extension="{$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@extension}" root="{$message/hl7:ControlActProcess/hl7:queryByParameter/hl7:queryId/@root}"/>
</queryAck>

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. 

{util:uuid()}

179a1709-636d-4bbf-be27-43de86f84e20

<id extension="{util:uuid()}" root="{$messageIdRoot}"/>
  • 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 

{$messageIdRoot}

2.16.840.1.113883.2.4.6.6.1

<id extension="{util:uuid()}" root="{$messageIdRoot}"/>
  • current date and time, for instance used in /creationTime/@value

Returns the current date and time. 

{datetime:format-dateTime(current-dateTime(),'yyyyMMddHHmmssZ')}

20150821163649+0200

<creationTime value="{datetime:format-dateTime(current-dateTime(),'yyyyMMddHHmmssZ')}"/>
  • current date and time, for instance used in /creationTime/@value

Returns the current date and time. 

{datetime:format-dateTime(current-dateTime(),'yyyyMMddHHmmssZ')}

20150821163649+0200

<creationTime value="{datetime:format-dateTime(current-dateTime(),'yyyyMMddHHmmssZ')}"/>
  • 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. 

{$message/id}

<id root="2.16.528.1.1007.3.3.999.1.11" extension="555555112"/>

<targetTransmission> {$message/id} </targetTransmission>
  • 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. 

{$message/hl7:sender/hl7:device/hl7:id/@extension}

85

<receiver>
   <device>
      <id extension="{$message/hl7:sender/hl7:device/hl7:id/@extension}" root="{$message/hl7:sender/hl7:device/hl7:id/@root}"/>
   </device>
</receiver>
  • incoming message device id @root

Returns the device/id/@root from the incoming message. 

{$message/hl7:sender/hl7:device/hl7:id/@root}

2.16.528.1.1007.3.3.999.1.11

<receiver>
   <device>
      <id extension="{$message/hl7:sender/hl7:device/hl7:id/@extension}" root="{$message/hl7:sender/hl7:device/hl7:id/@root}"/>
   </device>
</receiver>
  • Returns our own sender id/@extension attribute as configured in the testaccount as XIS HL7 configuration / Application Id
{$applicationId}

1

<sender>
   <device>
      <id extension="{$applicationId}" root="2.16.840.1.113883.2.4.6.6"/>
   </device>
</sender>

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: 

<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 -&gt; RTEDEST --&gt;
                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>

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

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

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

Retrieved from "https://wiki.art-decor.org/index.php?title=XIS_maintenance&oldid=7499"