Difference between revisions of "XIS maintenance"

(added: Configuring query parameters)
Line 97: Line 97:
 
For this purpose a messageFilter can be configured in: /hl7/<HL7 material set>/message-templates/messageFilter_manifest.xml
 
For this purpose a messageFilter can be configured in: /hl7/<HL7 material set>/message-templates/messageFilter_manifest.xml
 
An example filter configuration:
 
An example filter configuration:
<messageFilters>
 
 
<syntaxhighlight lang="xml" heading="Example fragment" enclose="div">
 
<syntaxhighlight lang="xml" heading="Example fragment" enclose="div">
 
<messageFilters>
 
<messageFilters>
Line 137: Line 136:
 
     </messageFilter>
 
     </messageFilter>
 
</messageFilters>
 
</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>
 
</syntaxhighlight>

Revision as of 11:59, 3 March 2015

Introduction to XIS

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.

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

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.

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>

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