ART maintenance manual

This is documentation for ART-DECOR Release 2 and tends to be out-dated. Please visit our new documentation site at


For development of ART-DECOR, see also ART developers manual

ART users

Create users

This section describes how to create users. In order to create users, the following actions should be performed:

  • log in as exist-db administrator
  • Go to application -> users

Example screenshot:

En create user 01.jpg

  • Select: Add user

Example screenshot:

En create user 02.jpg

  • Fill in a username, password and other information for this user
  • Select user roles by adding groups to this user

Example screenshot:

En create user 03.jpg

  • Click: Save to create the user

Deactivate users

This section describes how to deactivate users. In order to deactivate users, the following actions should be performed:

  • log in as exist-db administrator
  • Go to application -> users
  • Select the user you want to deactivate
  • Under Account Active: Click no
  • Click: Save to deactivate the user

Note that the useraccount is not deleted, but rather deactivated. The user can no longer log in to ART-DECOR. Of the user was a author or had others roles in DECOR-projects, the authorship is still present for historical reasons, but the user can no longer edits projects, since the useraccount is deactivated.

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. (default group = decor).
  • Project admin - 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. (default group = decor).
  • Issue editor - Groups: decor, issues. Besides these groups the user should also be listed as author in the project section in the decor file. (default group = decor).
  • Refset editor - Groups: terminology, editor. Besides these groups the user should also be listed as author in the project section in the refset file. (default group = terminology).
  • Interaction tester - Groups: decor, xis. Besides these groups the user should also be listed in a testaccount. (default group = xis)
  • 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.
  • decor-admin - This group enables extra tabs in the project tab.
  • 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.
  • terminology - Creating and editing of terminology objects, code systems / ref sets
  • 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 configuration

In the menu application/configuration the following tabs can be found:

  • Installed packages
  • Functions

Installed packages

A list of all installed xar packages with their version and the collection in which they are installed.

Example screenshot:

Error creating thumbnail: Unable to save thumbnail to destination


This menu contains the following functions:

  • Refresh menu
  • Update codesystem index
  • Fix ART permissions
  • Refresh External Repository Cache

Refresh menu

Normally the topmenu should automatically refresh when new ART-DECOR projects are added. These projects should appear under the DECOR menu. Use this function to refresh the top menu when ART failed to refresh the list of ART-DECOR projects automatically.

Update codesystem index

Normally the topmenu should automatically refresh when new claml terminology files are added. These should appear under the Terminology menu. Use this function to refresh the top menu when ART failed to refresh the list of claml terminology files automatically.

Fix ART permissions

Call this function to set permissions for ART-DECOR software, DECOR projects files and xis messages and reports.

Refresh External Repository Cache

Use this function to refresh the repository cache that this local server keeps of repositories from remote servers. After each refresh it lists:

  • the number of cached repository DECOR-projects.
  • the number of unreachable repositories
  • last date and time of refresh
  • for each repository: the DECOR project prefix and the URL for the external server where the repository is hosted.

Example screenshot:

Error creating thumbnail: Unable to save thumbnail to destination

ART Server Settings


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.


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.


ART services prefix


When certain routines need to know where to find the DECOR/OID 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.


FHIR endpoint prefix


When certain routines need to know where to find the FHIR endpoint for this server, this is the setting they'll consult. Must end in fhir/. This setting will result in a decor/@deeplinkprefixfhirendpoint attribute in compiled projects. Note that the listing after "Installed packages" are links to the index.html of that version of the FHIR server


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.


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

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

Server IDs


In various places you need ids. ART-DECOR allows you to set a base for them. You can set a base for the server, DECOR projects in general, experimental projects, building block repositories (specially marked projects, and governance groups.

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: Project create 01.png Fill in the following fields:

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



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


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

Terminology maintenance

Terminology update process

The update schedules for various terminology systems is documented at: TerminologyUpdateProcess.

During the release of a terminology system, the next release will also be scheduled as an action.

Creating a ClaML codesystem

Create a xar package

To create a ClaML codesystem, the following is needed:

Loading a package

Use the eXist-db dashboard as explained in the installation manual to add the package to the ART-DECOR server.

Update codesystem index

See: Update codesystem index

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="">
    <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." extension="810"/>
    <processingCode code="P"/>
    <processingModeCode code="T"/>
    <acceptAckCode code="NE"/>
    <acknowledgement typeCode="CA">
            <id extension="{$message/hl7:sender/hl7:device/hl7:id/@extension}"
            <id extension="{$applicationId}" root="2.16.840.1.113883."/>

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

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

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

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

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

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.

<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

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

Returns the current date and time.

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

Returns the current date and time.

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

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

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

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

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

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:

        <message active="true" interactionId="REPC_IN000023NL">
            <desc language="en-US">query potential contraindications</desc>
                <parameter name="patientId" 
            <responseTemplateFile value="MCCI_IN200101_REPC_EX000024NL_01_999999011.xml"/>
        <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>
                <parameter name="patientId"       
            <responseTemplateFile value="MCCI_IN000002.xml"/>
        <message active="true" interactionId="REPC_IN990003NL">
                <parameter name="patientId" 
            <responseTemplateFile value="MCCI_IN000002_RTEDEST.xml"/>

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."]/@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>
    <query id="QURX_IN990011NL">
        <name language="nl-NL">Opvragen verstrekkingen</name>
            <administrationRequestEffectiveTimeInterval xmlns="urn:hl7-org:v3">
                    <low value="20111101"/>

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



(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/resources/form-resources.xml. The default copy is in the corresponding package under resources/form-resources.xml. The resource is organized as follows:

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

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

(Parts based on ART >= 1.1.44)

All forms/screens in ART-DECOR are called through get-forms.xq which in turn runs gets the requested xform and runs it through a stylesheet (art/resources/stylesheets/apply-rules.xsl) to get to the form that ART-DECOR shows a user.

There are a number of things that a system administrator may configure:

  • Menu structure. By default art-menu-template.xml is loaded. If you have an ART-DECOR server geared towards testing or terminology you may want a different menu structure
  • Logo and its URL. By default the ART-DECOR logo and URL are shown top right hand, but you may wish to provide your own.
  • Scripting/CSS. For installations that need specific scripting or css overrides you can add that in art-data/resources/local-header-resources.xml

En art settings left part.png

Adding your own menu

There's no ART support currently for building a new menu structure. The easiest thing to do is:

  • Start from a copy of any of the menu files in art-data/resources
  • When you add new @labels, add the appropriate language labels through ART language-settings (under the application menu
  • Attach the new menu in ART art-settings

The menu file has a top level element <menu/> and 0..* child elements <section/> | <application/>. Both have an @id attribute to tell ART what it is and a @label attribute to get the display name in the right language from form-resources.xml. Any section many have section | application up to 2 layers deep. Section optionally have a link, applications are expected to link somewhere. The link may be a part of ART-DECOR, but may also go somewhere else like your publication environment.

Part of the art-menu-template.xml:

    <!-- menu section visible for decor projects -->
    <!-- decor menu will be filled dynamically -->
    <section id="decor" link="/home" label="menu_decor"/>
    <!-- Decor project sections -->
    <section id="project" link="/decor-project--" label="menu_project"/>
    <section id="decor-terminology" link="/decor-valuesets--" label="menu_terminology">
        <application id="valuesets" link="/decor-valuesets--" label="menu_valuesets"/>
        <application id="codesystems" link="/decor-codesystems--" label="menu_codesystems"/>
        <application id="associations" link="/decor-terminology--" label="menu_terminologyassociations"/>
        <application id="valueset-ids" link="/decor-valueset-ids--" label="menu_valuesetids"/>
        <application id="codesystem-ids" link="/decor-codesystem-ids--" label="menu_codesystemids"/>

A number of special menu parts exist:

  • @id=decor. This section is built from projects on the server
  • @id=terminology. This section can host several applications, e.g. SNOMED CT, but also contains a dynamic part where the installed terminology data packages, e.g. ICD-10-DE are added
  • @id=refsets. This section is built from ref sets available on the server

The other special thing is that when you are in the context of a DECOR-project, certain menus are displayed while others aren't and vice versa.

  • DECOR context: ('home','decor','project','project-overview','datasets','scenarios','decor-terminology','decor-templates','issues')
    • DECOR menu items have special @link attributes as the project prefix is attached to the value of it. Hence "/decor-terminology--" will be "/decor-terminology--demo1-" in practice.
  • Other context: ('home','decor','demo','refsets','terminology','testing','tools','application')

This means you cannot invent your own menu ids but you need to use any of the ids above.

Adding your own logo and URL

In ART settings (available from the Application menu you may configure any logo. This logo must be present in the art-decor/WEB-INF/resources/img folder in your Tomcat installation to be displayed. Additionally you can add a URL onto the logo. This URL usually goes to your organization.

Adding your own scripting/css

In the database under art-data/resources/local-header-recources.xml you may add your own own custom code that will injected into the header of any ART-DECOR form the users will get. Any headerExtras/xhtml:script and xhtml:style is copied as-is.

Example for Google Analytics:

<headerExtras xmlns:xhtml="">
    <!-- Add Google analytics hook -->
    <xhtml:script type="text/javascript">
        var _gaq = _gaq || [];
        _gaq.push(['_setAccount', 'MyAnalyticsAccount']);
        (function() {
        var ga = document.createElement("script");
        ga.type = "text/javascript";
        ga.async = true;
        ga.src = ("https:" == document.location.protocol ? "https://ssl" : "http://www") + "";
        (document.getElementsByTagName("head")[0] || document.getElementsByTagName("body")[0]).appendChild(ga);

Running ART-DECOR in a production environment

See: Production environment

Database maintenance

Create a backup