ART maintenance manual

This article or section is in the middle of an expansion or major restructuring and is not yet ready for use. You are welcome to assist in its construction by editing it as well.

ART user roles

This section describes the user roles that are used in ART, with the corresponding groups the user should have permission for.

The roles in ART and corresponding group permissions:

• Project editor - Groups: decor, editor, issues. Besides these groups the user should also be listed as author in the project section in the decor file.
• Project author - Groups: decor-admin (the rest is the same as 'Project editor'). This role enables extra tabs in the project tab: Ids, Status, Compilations and MyCommunity.
• Issue editor - Groups: decor, issues. Besides these groups the user should also be listed as author in the project section in the decor file.
• Refset editor - Groups: terminology, editor. Besides these groups the user should also be listed as author in the project section in the refset file.
• Testing/SOAP interaction tester - Groups: decor, xis. Besides these groups the user should also be listed in a testaccount.
• Read-only view - No groups necessary.
• Database admin - dba.

In order to give permissions you must be logged in as database admin, and choose the menu 'Application' -> tab 'Users'.

The following groups are available for users:

• dba - Creating users, DECOR projects, etc.
• debug - Show the Orbeon forms debug information. Do not use, except for ART-developers.
• decor - General permission to write to DECOR projects.
• editor - Creating, editing, deleting of DECOR objects (dataset, scenario's, valuesets).
• guest - Read-only access to data in a DECOR project.
• issues - Creating and editing of issues in DECOR projects.
• tools - Creating and editing in the OID-registry.
• xis - Access to the tab 'testing' and the underlying functionality such as uploading message instances.

How to add a user to a DECOR project: Open the DECOR project, choose the tab 'Project' -> 'Authors'. In order to perform this action you must be either in the groups: decor and editor and be named as an author in the DECOR project or have database admin permissions.

ART Server Settings

The ART-DECOR has a number of settings. The exact features that you as dba member may or may not want to adjust will continue to expand as ART-DECOR evolves. ART sports a complete UI to control them through the menu item Application > Server settings. If you do not see that menu item: you are not a DBA. The settings you can control are as follows.

All changes are saved immediately in art-data/server-info.xml in the database, which means they are instantly effective!

ART server language

The language that the server will present itself in, if there is no user setting available. Default is en-US (US English). Note: user settings can be set by administrators through the user management, or by the user from the home page.

<defaultLanguage>en-US</defaultLanguage>

ART server prefix

When certain routines need to know what the server is, this is the setting they'll consult. In publications for example, this setting is used to build links back to project issues. Must end in art-decor/. This setting will result in a decor/@deeplinkprefix attribute in compiled projects.

<url-art-decor-deeplinkprefix>http://art-decor.org/art-decor/</url-art-decor-deeplinkprefix>

ART services prefix

When certain routines need to know where to find the services for this server, this is the setting they'll consult. Must end in services/. This setting will result in a decor/@deeplinkprefixservices attribute in compiled projects.

<url-art-decor-services>http://art-decor.org/decor/services/</url-art-decor-services>

ART server stylesheet

All ART UI has some kind of menu structure, and logo at the top of the page. This is governed by an XSL file. A few different skins come predefined to make ART appear like a special purpose server. The XSL must live in art/resources/stylesheets. All xsls in this database location are presented in the drop down list. TODO: create more info on skinning ART

<xformStylesheet>apply-rules.xsl</xformStylesheet>

External repository server

Your server may host one or more DECOR building block repositories (BBR), but you may also want to use externally hosted BBRs. To retrieve these you need the services URL for that server as an External repository server. This services url is like the ART services prefix setting for your own server. The services url for art-decor.org comes predefined, but you change it or add more. When you click the Select button you get a dialog that allows you to select the repositories that this server hosts and add them as External building block repository (see below).

<buildingBlockServer url="http://art-decor.org/decor/services/">

External building block repositories

If you want to offer projects the option to add external building block repositories (BBR) to their project, you need to have one or more preconfigured here. You can delete them here, but they will remain active in any project that already uses them, so deleting only affects what project can select from from that point on. If you want you can override the name supplied for the repository by the external server.

<buildingBlockRepository url="http://art-decor.org/decor/services/" ident="ad1bbr-">
   <name language="en-US">CDA Release 2</name>
   <name language="nl-NL">CDA Release 2</name>
   <name language="de-DE">CDA Release 2</name>
</buildingBlockRepository>

Creating a project

The following actions are needed to create a project:

• Prerequisite: you are logged in as role: 'dba'
• Click 'Application'
• Click 'DECOR Administration'
• Click 'New DECOR Project'

Example screenshot: Fill in the following fields:

• Package: select a location where the project will be created.

Project:

• Name: required. See: name
• Prefix: required. See: @prefix
• Repository: See @repository
• Language: required. See: @defaultLanguage
• Id: required. See: @id
• Private: See @private

Authors:

• Select users from the database that are authors for the project.
  • Email: optional. Enter an Email-address for the user.
  • Notifier: optional. Default value is 'off'. Set to 'on' if the user should receive project notifications.

Dataset:

• Name: required. Enter a name for the dataset.
• Description: optional. Enter a description for the dataset.

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:

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

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

Customization

Language

(Parts based on ART >= 1.1.38)

ART-DECOR supports a number of languages out of the box. As ART-DECOR super user (dba group) you may edit terms in a language, and you may add languages as needed by your community. Especially when you add a new language you might want to consider offering it for merge into the ART-DECOR source.

When you update/add terms, these will be written in a special collection resource art-data/form-resources.xml. The default copy is in the corresponding package under resources/form-resources.xml. The resources is organized as follows:

   <artXformResourcesBundle>
       <artXformResource packageRoot="art">
           <resources xml:lang="en-US" displayName="English (en-US)">
               <key>value</key>
    ...
           </resources>
           <resources xml:lang="nl-NL" displayName="Nederlands (nl-NL)">
               <key>value</key>
    ...
           </resources>
    ...
       </artXformResource>
   </artXformResourcesBundle>

The local file in art-data is updated whenever new versions of the packages are installed. The way the update works is:

• Add any new language from the new package version into the local copy
• Add any new <key/> from the new package version into the local copy
• Overwrite any <key/> in the local copy with the corresponding <key/> from the new package version unless the local <key/> carries the attribute @updated indicating that this <key/> was explicitly updated on this server.
• Remove any <key/> in the local copy that has no corresponding <key/> in the new package version

If you add a language and you update the base package then you may be missing new keys from that package. Check Languages from the Configuration menu to find if this is the case.

Menus and generic UI

TODO. At present when you need different menu structures, alternate css, and more then ART support this when you change art/resources/stylesheets. However: when you update the ART package you loose all your changes (!)

Running ART-DECOR in a production environment

See: Production environment