RetrieveTransaction

Revision as of 15:43, 12 December 2014 by Ahenket (talk | contribs) (The dataset element)

The Retrieve Transaction Service

Retrieve Transaction is conceived as a single view on the data in datasets, transactions, valuesets and (a little) templates, gathered together with the transaction as a starting point. This enables developers to have a single view on all - or most of - the data necessary to implement a transaction. Retrieve Transaction comes with both an HTML and a XML view. Here we'll focus on the XML view (the HTML view is nothing more than the data in the XML view, rendered as HTML).

Error creating thumbnail: Unable to save thumbnail to destination

Since Retrieve Transaction XML collects all the data from the various DECOR views, it can be a good starting point for code generation.

The query parameters

Retrieve Transaction will accept the following query parameters:

  • id (of either a transaction or a dataset)
  • language (optional, default is the project's default language)
  • format ('xml' or 'html')
  • version (to retrieve a frozen release)
  • hidecolumns (to influence the HTML display)
  • unfiltered (to influence the HTML display)

The dataset element

This element contains the following attributes:

Attribute Example Description
@id 2.16.840.1.113883.3.1937.99.62.3.1.1 The id of the dataset which was filtered.
@effectiveDate 2012-05-30T11:32:36 The effectiveDate of the dataset which was filtered.
@statusCode draft The statusCode of the dataset which was filtered.
@versionLabel v2014.07 The versionLabel of the dataset which was filtered.
@transactionId 2.16.840.1.113883.3.1937.99.62.3.4.2 The id of the transaction which was used to filter the dataset.
@transactionEffectiveDate 2012-09-05T16:59:35 The effectiveDate of the transaction which was used to filter the dataset.
@shortName measurement_message A machine-processable name which can be used as an XML element name or SQL column name. Basically, the transaction (or dataset) name in lowercase, spaces to underscores, and odd characters removed.

If a dataset id is provided as query parameter, the dataset will not be filtered for a particular transaction. If a transaction id is provided, only those concepts will occur in the original dataset which are in this transaction as well.

The dataset element will contain name and desc elements from the original transaction or dataset. Below this will come concept children.

The concept element

This element contains the following attributes and elements. They are all taken from the concept as it occurs in the dataset, from the attributes which are added in the transaction or from elsewhere where indicated below. If a concept is inherited, all the attributes are completed from the inherited-from concept. History of concepts is omitted. Multi-lingual artefacts (name, desc) are filtered for one language (so there will be only one name child element).

Child From Description
@id dataset The id of the concept.
@effectiveDate dataset
@type dataset
@statusCode dataset
@isMandatory transaction
@conformance transaction
@minimumMultiplicity transaction
@maximumMultiplicity transaction
inherit dataset If the original concept was inherited, the inherit element from the original concept.
name dataset
desc dataset
implementation N.A. See below
valueDomain dataset
valueSet N.A. See below

The implementation element

This element contains the following attributes and elements.

Child Description
@shortName A machine-processable name which can be used as an XML element name or SQL column name. Basically, the concept name in lowercase, spaces to underscores, and odd characters removed. There is no 100% uniqueness guarantee (i.e. 'My name' and 'My [name]' will generate the same shortName. In most cases however, the name should be unique on a given level in the hierarchy.
@xpath An Xpath expression which indicates where the concept will occur the message in wire format. An Xpath is generated whenever a matching elementId for this concept is found in a template which is called in the chain of templates for this transaction. Xpaths are calculated on a best effort basis. The should be considered a starting point for application logic, not an endpoint. Xpaths may be missing. If the hierarchy of the transaction does not completely resemble the hierarchy of the templates (i.e. concepts which are children in a transaction are siblings in the wire format etc.), the Xpaths may not completely match. Xpaths are only shown for frozen DECOR releases, not for the current version (due to performance).
@hl7Type The HL7 datatype of the element in the template that this concept matches onto, if any.
templateLocation The attributes (id, effectiveDate etc.) of the template that this concept matches onto, if any.

The valueSet element

Concepts of valueDomain type 'code' will have a valueSet element if a valueSet is associated. The valueSet element will contain all the attributes of the valueSet, and as children the terminologyAssociation used to find the valueSet, and the conceptList.

The conceptList will contain the child concepts from the valueSet, with the following additional information:

Child Description
@localId A unique sequential number. Thew number is not (and cannot be) maintained between releases. However, since code + codeSystem is cumbersome to in for instance an option/@value in an HTML select tag, localId is generated for such purposes. Only use there; in a database localId should never be used, use code and codeSystem there instead.
name If this concept in the valueSet conceptList is mapped onto a concept in the valueDomain conceptList with a translation for the language under scope, a name child is generated with this name and an @language attribute. If no name is found, a name child is generated with the displayName and no @language attribute.