[Deprecated] HL7 Conformance profiles and HL7 tables management

Warning: This documentation is out-dated, newest version of the documentation is available at https://gazelle.ihe.net/gazelle-documentation 

This part of the documentation is dedicated to the manager/administrator of the GazelleHL7Validator tool.

The validation of HL7v2 messages within the Gazelle platform is based on

  • HL7 conformance profiles : XML files which describe the structure of the HL7 messages, they are constrainable. For each segment, field, component and subcomponent, the usage (required, optional, not allowed...), the cardinality and the datatypes are defined.

  • HL7 resources : XML files which declare a set of HL7 tables (kind of value sets). HL7 conformance profiles may reference HL7 table for a field, component or subcomponent, in order to constrain the set of allowed values for this element of the message

Both HL7 conformance profiles and HL7 resources are stored in the database of the tool along with an OID as well as the links between the conformance profiles and the resources. Note that the conformance profile file only reference the number of the the HL7 table, that means that, for a given conformance profile, the tool must be able to know in which HL7 resources looking for the table.

For each HL7 conformance profile, we need to know to which part of the technical framework, which message it applies. That's why, the HL7 conformance profiles are actually referenced in Gazelle Master Model. This enables us to link a conformance profile to a tuple (Domain, Actor, Transaction, HL7 version, message type [, order control code]). GazelleHL7v2Validator and Gazelle Master Model are two tools which have independent databases; as a consequence, the OID is used as a foreign key and two web services offered by Gazelle Master Model allow us to exchange data between those two applications:

  • IHEConcepts: This web service lists the different concepts (domain, actor, transaction) based on other parameters. For instance, you can get the list of all domains, the list of actors involved in a given domain and so on.
  • Hl7MessageProfile: This web service offers methods to retrieve the complete list of conformance profiles registered in GMM, a subset of these profiles which match certain parameters (actor, message type, HL7 version...). This web service also offers a method to add a new conformance profile reference into the database of GMM.

The URL of the Gazelle Master Model web services are configurable within the application preferences part of GazelleHL7v2Validator. Make sure to reference the correct instance of Gazelle Master Model.

The following sections detail the different actions you may need to perform to maintain the set of conformance profiles available in your instance of GazelleHL7v2Validator. In order to keep a consistency between the references in Gazelle Master Model and the conformance profiles actually available in GazelleHL7v2Validator, only one instance of GazelleHL7v2Validator must be used per instance of Gazelle Master Model.

OID assignments

HL7 conformance profiles and HL7 tables are assigned OIDs. Remember that an OID must be unique through the world; that means that, the first thing to do when you install a new instance of GazelleHL7v2Validator is to update the root of the OIDs which will be generated by the application. Three OIDs are used which are defined in oid_generator table:

  • One for the conformance profiles
  • One for the HL7 resources
  • One for the validation results (messages)

Currently, no user interface is available to perform this update, you will need to modify those values, manually, in the database.

Add a new conformance profile

Adding a new conformance profile consists in two things:

  1. Creating a new reference in Gazelle Master Model
  2. Importing the XML file representing the conformance profile to the database of GazelleHL7v2Validator

When you have just developing a new conformance profile, make sure that the transaction for which it is defined is registered into your instance of Gazelle Master Model (also check the actor and domain). Then, in GazelleHL7v2Validator, go to Administration --> Register new profiles (you must be logged on as an administrator).

A form is displayed (see screenshot below). Fill out this form with the information that match the conformance profile you are working with. Note that, first, only the domain drop-down list is displayed, then the list of actors is computed depending on the domain you have selected and finally the transactions will be available depending on the actor/domain pair previously selected.

add a new profile

As you can notice it on the screenshot, a button is available on the right of the "Profile OID" field. Clicking on this button will ask the application to automatically assign an OID to this conformance profile.

GazelleHL7Validator uses HAPI as validation engine. At validation time, message to validate is converted to a java object. Although all the message structures defined by HL7 are available in HAPI, in some cases, you will need to generate your own java class describing the message and tell the application in which java package it will find it. That is the case when IHE defines a new segment or change the structure of a message. 

A project called gazelle-hl7-messagestructures available on Gazelle's forge and based on HAPI libraries is available to generate the java classes from the conformance profiles.

Finally, upload the XML file representing the conformance profile. As soon as the form is filled and the file is uploaded a "Submit" button is available. Hit this button, the file will be stored in database and the reference to the profile will be sent to Gazelle Master Model.

In order to facilitate the management of the registered profiles, we recommand to rename the XML file (on your file system) with the OID assigned to the conformance profile.

Add a new resource

Basically, one HL7 resource is registered for each version of HL7. In some cases, you will need to customize a table for a given conformance profile or for a set of conformance profiles. In that case, you may need to register a new resource.

Go to Administration --> Register new resources. A new form is displayed (see screenshot below).

register new resource

As for the conformance profile, you can ask the application to generate an OID. Once the form is filled out and the XML file is uploaded, hit the "Submit" button and the HL7 resource will be stored in database.

Tip for filling out the weight attribute

 When the tool initializes a validation, it retrieves all the HL7 resources linked to the selected conformance profile. Then, at validation time, for each reference to an HL7 table, it browses the selected resources to extract the set of allowed values. We have defined a mechanism of weight which allow us to tell the application in which order it must browse the resources. Actually, it may happen that you have overriden a table defined in several of the selected resources. The resource is the higher weight will be processed first. HL7 resources defined by HL7 have usually a weight equals to 1.

In order to facilitate the management of the registered resources, we recommand to rename the XML file (on your file system) with the OID assigned to the resource.

Link conformance profiles to resources

Go to Administration --> Link profiles to resources.

This page is composed of four parts:

  • he list of available HL7 resources
  • The list of selected HL7 resources
  • A panel to select a set of conformance profile or a profile knowing its OID
  • A panel which lists the selected conformance profiles

To link HL7 resources to conformance profiles, process as follows:

  1. First select the HL7 resource(s) you want to link to a set of profiles. Click on the blue plus icon of each row.
  2. Then, select a set of conformance profile (use filters)
  3. Finally hit the button "Link the profiles displayed below to the selected profiles"

Update conformance profiles and resources

This section assumes that you have renamed your XML files according to the previous advices; that means that on your file system, you have a set of files named [profile_oid|resource_oid].xml. Maintenance will be easier if you store the profiles and resources in two different directories.

To update the content of a conformance profile or a resource, go to Administration --> Configure application.

In this page, a section is entitled "HL7 message profiles and tables import".

To update the conformance profiles, configure the "Path to HL7 message profiles" and hit the Import/Update profiles. The path must point to a directory on the server.

To update the conformance profiles, configure the "Path to HL7 tables" and hit the Import/Update tables. The path must point to a directory on the server.

In both cases, the application browses the given folder and lists all the XML files. For each file, it tries to retrieve the relative conformance profile / resource and compare the date of the file with the date of the last changed. If the file on disk is newer than the last changed, then, the file will be imported into the database to replace the old content.

How conformance profiles and resources are organized on Gazelle's forge

This section describes how we have chosen to organize the conformance profiles and resources on Gazelle's forge and how they are maintained and managed.

Currently, both IHE Europe development team and the NIST contribute to maintain profiles.

A project is called Data and is available at https://gforge.inria.fr/scm/viewvc.php/Data/?root=gazelle. This project is made of two main folders: 

  • HL7MessageProfiles: In this folder, conformance profiles are organized by firstly actor keyword then transaction keyword and finally message type (messageType_triggerEvent). For instance, you will find the conformance profile for validating the ADT^A28^ADT_A05 message issued by the Patient Demographic Supplier actor in the context of the ITI-30 transaction at the following location: PDS/ITI-30/ADT_A28/profile/ADT_A28.xml. A sub-directory of HL7MessageProfiles is named ProfilesPerOid and contains a symbolic link to each profile. Name of the link is the OID assigned to the targeted message profile. In this way, when you want to update a profile you do not have to know its OID and in the same way, when updating the message profiles in the database of the tool, the mapping is correctly performed thanks to the symbolic links.
  • HL7Tables contains the HL7 resources all with a meaningful name and a child directory named TablesPerOid which contains a symbolic link to each resource. Name of the link is the OID assigned to the targeted resource.

Finally, this project has been checked out on the server hosting GazelleHL7v2Validator application and is periodically updated; which allows us to easily perform the update of the profiles and resources in the application.

Manage HL7v3 Constraints file

The list of HL7v3 constraints is available under the administration tab, by going to the “Manage HL7v3 constraints file” menu. From there, it’s possible to delete individually each HL7v3 constraint by clicking on the trash icon. It’s also possible to import an XML file with the constraints written inside. This file must be generated with “Topcased” software from the OCL constraints. Be careful when using the “Delete and Generate” button, because all the existing HL7v3 constraints are first deleted before the new ones are imported.

 

Manage users' accesses

You can restrict the messages an user is allowed to see in the logs page by editing the user preferences from the Administration -> Manage users’ accesses page. By adding an user, you can restrict the allowed IP addresses to constraint this user to see only the messages coming from this IP address. You can add many IP addresses for a single user.