The Message Libraries installed for the Message Library for HL7 are located in the Project window in the CAPS Components Library > Message Library > HL7 tree. These Message Libraries are protected and cannot be checked out or modified. This assures that the original Message Libraries are always available in their original form.
If you copy and paste an HL7 Message Library to a Project, version control is available for that Message Library. To check in or check out a Message Library, right-click the Message Library from the Project Explorer tree, and select Version Control > Check Out or Check In from the shortcut menu. When a Message Library has been checked in, the Message Library file icon appears in the Projects window as locked (the icon includes a red padlock).
HL7 Message Libraries are made up of various segment Message Libraries that correspond to the HL7 message segments. The main HL7 Message Libraries contain references to the segment Message Libraries, which are located in the same HL7 directory.
The following example uses the HL7_25_ADT_A02 Message Library segment to illustrate removing a segment Message Library and replacing it with a different segment. For example, if you are working with a V2.6 library and want to use the V2.5 version for one or more segments, you can replace those segments in your Message Library. It is important to retain the original Message Library structure. If you will be doing any cutting, pasting, or deleting of segments, make a note of the Message Library segment order in the Editor’s Object Type Definition pane.
The following steps illustrate deleting a Message Library segment from this list, so it is important to make a note of the original segment location so that you can relocate the edited segment to it’s original position in the Message Library structure as illustrated in the figure.
On the Projects window, copy the Message Library you want to use for your Project from CAPS Components Library > Message Library > HL7 and paste it into the Project.
To copy the Message Library segment, use the copy command from the Tools menu.
Repeat the above step for any Message Libraries that contain segments you want to use in the above Message Library.
Double-click the pasted Message Library from step 1 above to display it in the Message Library Editor.
Make note of the Message Library segment order so you can maintain the structure.
The figure below shows the structure of the HL7_26_ADT_A02 segment.
Click the Internal tab in the Reference pane, right-click the segment you want to replace, and then click Delete.
In the Internal tab, select the top-level node to display all segments in the Object Type Definition pane.
In the Object Type Definition pane, right-click the same segment you deleted above, and click Delete again.
In the Reference pane, click External, right-click any of the references to the segment you just removed, and then click Delete.
This removes all other references to the segment Message Library.
On the Message Library Editor toolbar, click Import OTD From External Template.
The Import dialog box appears.
In the Look In field, navigate to the location of the Message Library that contains the segment that will replace the one you just deleted.
This is one of the Message Libraries you pasted into a Project in step 2 above.
Locate and select the Message Library you want to import to your Project file.
Click Add to add the Message Library to the Select OTD(s) to Import section. Click Import.
The Message Library is added to the External tab of the Reference pane.
Drag the imported segment reference from the External tab and drop it onto the root node of the Object Type Definition pane.
The segment is added to the Object Type Definition tree.
Right-click the segment and click Level Up to move the segment up the tree from the Object Type Definition tree.
Repeat this step until the new segment is in the same position as that of the segment being replaced.
Repeat this procedure for any additional segments you want to replace.
Save the changes to the Repository.
You can now open the segment Message Library and edit the properties.
You can also modify a Message Library by adding additional segment Message Libraries to your Message Library’s external template.
On the Projects window, copy the Message Library you want to use for your Project from CAPS Components Library > Message Library > HL7 and paste it into the Project.
To copy the Message Library segment, use the copy command from the Tools menu.
Repeat the above step to copy any segment Message Libraries you want to import to your Project.
This opens the Message Library in the Message Library Editor.
Double-click the Message Library to which you want to add the segment.
The Message Library Editor appears.
On the Message Library Editor toolbar, click Import OTD From External Template.
The Import dialog box appears.
In the Look In field, navigate to the location of the Message Library that contains the segment that will replace the one you just deleted.
This is one of the Message Libraries you pasted into a Project in step 2 above.
Locate and select the Message Library you want to import to your Project file.
Click Add button to add the Message Library to the Select OTD(s) to Import section.
Click Import.
The Message Library is added to the External tab of the Reference pane.
Drag the imported segment reference from the External tab and drop it onto the root node of the Object Type Definition pane.
The segment is added to the Object Type Definition tree.
Right-click the segment and click Level Up to move the segment up the tree from the Object Type Definition tree.
Repeat this step until the new segment is in the location you want it.
Save the changes to the Repository.
The HL7 Message Library copied to your Project can only be edited from the root node. Each of the Message Library’s segments are write protected. The Message Library segments are visible from the Reference pane of the Message Library Editor. This Reference pane contains internal and external templates for the Message Library file. To edit specific segments of a Message Library, see Editing the Message Library Delimiters. For more information regarding Message Library properties, see Message Library Properties.
The Message Library Editor allows you to add and delete nodes, elements, and fields in a Message Library. You can also prune nodes, which deletes only the children associated with the node while the node itself is preserved. Pruning can only be performed on nodes. When you delete a node, all associated children are deleted. When you delete an element, all associated fields are deleted.
To add a node, element, or field to the Message Library structure, right-click the
Right-click the node to which you want to add the node, element, or field.
Click Add, and then select the type of object to add.
In the Properties pane, customize the properties for your data requirements.
See Message Library Propertiesfor more information about properties.
To remove a node, element, or field, right-click the object to remove and then click Delete.
To prune a node, right-click the node and then click Prune.
The Object Type Definition pane of the Message Library Editor displays the nodes, elements, and fields of the Message Library. When any of these are selected, the item’s properties are displayed in the Properties pane.
The following topics list and describe each property:
When an HL7 Message Library is opened in the Message Library Editor, the properties of the root node are displayed in the Properties pane. The configurable node properties are shown in the following figure and described in the table below.
Property |
Description |
---|---|
name |
The node display name. This can be any string. |
javaName |
The property accessor basename. This is normally derived from the display name, modified to suit the restrictions on Java identifiers, and supplied automatically by the Sun Enterprise Service Bus. Do not modify this property. |
javaType |
The Java type. This is automatically assigned, and not is editable. |
comment |
Free-form text (no runtime effect). |
delim |
The specified delimiter. See Specifying Delimiters. |
nodeType |
Governs the marshal/unmarshal format. See Specifying the Node Type. |
antecoding |
The input data coding. See Changing HL7 Standard Encoding Characters. If this property is not specified, the value specified for the decoding property will be used for the input data. This property is displayed only when the top property is set to true. |
decoding |
The unmarshal coding. See Changing HL7 Standard Encoding Characters. It is recommended to use UTF-8 for DBCS data, since the hex value of some ASCII delimiter may coincide with a hex value contained within a double-byte character. This property is displayed only when the top property is set to true. |
encoding |
The marshal coding. This property is displayed only when the top property is set to true. |
order |
Specifies the ordering of the root node’s children:
|
postcoding |
Specifies the output data coding (see Specifying Data Encoding on page 219). If this property is not specified, the value specified for the encoding property will be used for the output data. This property is displayed only when the top property is set to true. |
public |
Reserved for future development |
rootClassName |
The Java class name corresponding to the root node. |
top |
An indicator of whether the root node supports marshal/unmarshal (T/F). |
The set of properties associated with the element level is shown in the following figure and is described in the table below.
Property |
Descriptions |
---|---|
name |
The element display name. |
javaName |
Property accessor basename. Do not modify this property; it is assigned by the Sun Enterprise Service Bus. |
javaType |
The Java type. This is automatically assigned, and is not editable. |
comment |
Free-form text (no runtime effect). |
access |
The access specification. |
optional |
An indicator of whether the element is required or optional. Specify true if the element is optional; otherwise specify false. This is not applicable to the root or to a child of a choice node. |
repeat |
An indicator of whether the element can have multiple instances. Specify true if the element can appear multiple times; otherwise specify false. This is not applicable to the root or to a child of a choice node. |
maxOccurs |
The maximum number of occurrences of the node if the node is repeating. This property has no effect if node is non-repeating, but might show an error during validation if set to a value greater than 1. |
delim |
The delimiter specification (see Specifying Delimiters). |
nodeType |
Governs the marshal/unmarshal format. See Specifying the Node Type. |
showDelim |
If the nodeType property is delimited, the delimiter appears here. This field is not editable. |
public |
For future use, not currently active. |
top |
An indicator or whether marshal/unmarshal is supported. Specify true if it is supported; otherwise specify false. |
The set of properties associated with the field level is shown in the following figure and is described in the table below.
Property |
Descriptions |
---|---|
name |
The field display name. |
javaName |
The property accessor basename. Do not modify this property; it is assigned by the Sun Enterprise Service Bus. |
javaType |
The Java type. This can be either java.lang.String or byte array (byte[]). |
comment |
Free-form text (no runtime effect). |
access |
The access specification. |
optional |
An indicator of whether the field can be absent from an instance. Clicking the Value field toggles between true and false. Not applicable if the field is the child of a choice element node. |
repeat |
Specifies whether or not the node can appear multiple times. Specify true is the node is options; specify false if it is required. Click in the field to toggle between true and false. This is not applicable if the field is the child of a choice element node. |
maxOccurs |
The maximum number of occurrences of the node if the node is repeating. This property has no effect if the node is non-repeating, but it might show an error during validation if set to a value greater than 1. |
delim |
The delimiter specification (see Specifying Delimiters). |
initial |
The initial field value, which is set when the parent node is created or reset. When provided, it is assigned to the node before the node is populated with any data. |
match |
If nodeType is delimited, performs an exact match to the data. |
nodeType |
Governs the marshal/unmarshal format. See Specifying the Node Type. |
align |
Specifies the byte alignment criteria for the match property. |
decoding |
The unmarshal coding. This is displayed only if the nodeType property is set to fixed. It is recommended to use UTF-8 for DBCS data, since the hex value of some ASCII delimiter may coincide with a hex value contained within a doublebyte character. |
encoding |
The marshal coding. This property is displayed only if the nodeType property is set to fixed. |
length |
The length of the field. This property is displayed only if the nodeType property is set to fixed. |
If you move a Message Library node, you must reset the nodeType for that node.
In the Message Library Editor, expand the Message Library until the field you want to edit appears in the Object Type Definition pane.
Select the field to edit.
Click in the nodeType field, and then click the arrow to display the options.
Select the option you want, and then save the Message Library.
The following table describes the nodeType options.
Option |
Description |
Element |
Field |
Internal |
---|---|---|---|---|
array |
Array is a delimited structure. If repeated, occurrences are separated by the repeat delimiter. The last occurrence may be terminated by a normal delimiter. |
Yes |
Yes |
simple or group |
delim |
Delim (delimited) structure. If repeated, occurrences are separated by a normal delimiter. |
Yes |
Yes |
simple or group |
fixed |
Fixed indicates a fixed length, which is specified by non-negative integer (or zero to indicate end of parent node data). |
Yes |
Yes |
simple or group |
group |
Group provides organizational grouping for purposes such as repetition. Applies only to elements. |
Yes |
No |
group |
trans |
Trans (transient) appears only in an internal tree as a scratch pad field. It does not appear in external data representation, and can only have trans nodeTypes as children. |
Yes |
Yes |
choice, simple, or group |
Delimiters for all node levels are set and modified from the root node. Be aware that the default level 1 delimiter character is a non-ASCII character. Once it has been changed it cannot be typed back in as a character, but it can be pasted. For information about editing a specific segment of the Message Library, see Managing Message Library Nodes, Elements, and Fields.
Select the root node in the Object Type Definition pane of the Message Library Editor.
Double-click the delim properties field in the Properties pane.
An ellipsis (...) button appears in the field.
Click the ellipsis button.
The Delimiter List Editor appears.
Double-click any field in the Delimiter List Editor on any level to make the field editable or to display a list of options.
For Level 3, do the following:
Double-click the Delimiter Bytes field for level 3.
Change the current delimiter character to a pound sign (#), Tab to the next field, and then click OK.
The delimiter for all level 3 nodes in the Message Library is now a pound sign (#), unless it is specified differently for a specific segment. The figure displays an example of various levels in the Object Type Definition tree, from the Root node.
All HL7 Message Libraries have a predefined list of delimiters, per the definition in the HL7 Standard. If you elect to change the delimiter encoding characters in your HL7 messages, you must change the delimiter in the Message Library from the root node using the Message Library Editor to match the delimiters used in the HL7 message.
The delimiter encoding character field is a fixed-length field of four encoding characters plus the field separator. The fifth (extra) character is necessary for the segment field separator.
If you wish to validate against the encoding characters, modify the prebuilt Collaboration rules as follows:
// first unmarshal the HL7 OTD payload // then get the encoding character field: String encodingChars = otdHL7_GENERIC_EVT_1.getMSH().getMsh2EncodingCharacters(); if (!encodingChars.equals(“<customer_encoding_characters>”)) { validated = false; ErrorMessage = "Validation Failure: Receiving Facility"; log( LOG_LEVEL_ERROR, "Validate HL7 Message failed: Encoding character field" ); } |
A node defines a set of delimiters to be used in the external data representation for itself and its descendents in the hierarchical data structure. If a node defines a delimiter list, this negates any effect of any ancestor’s delimiter list on itself and its descendents. The delimiter list is typically specified on the Root node.
For example, if you want to parse the following data:
a^b|c^d|e |
you might define a Message Library as follows:
The delimiter list for this Message Library will be specified on the demo-otd element, so that it applies to the entire Message Library, and will have two levels:
Level 1
Delimiter |
Level 2
Delimiter ^
The Level 1 delimiter applies to the two elements and field 5, and the Level 2 delimiter applies to fields 1 through 4.
Delimiter lists can be much more complex than this very simple example. For instance, you can create multiple delimiters of different types at any given level, and you can specify a delimiter list on any node within the Message Library—not only the Root node as shown in the example. See Modifying a Message Library Using the Message Library Editor for a description of the procedure for creating a Delimiter List.
Delimiter Properties
Delimiters are defined using the Delimiter List Editor. The Delimiter properties and values are displayed in the following.
Table 1 Delimiter Properties
Delimiter Properties and Value Options |
||
---|---|---|
Property |
Option |
Description |
Level |
Child level beneath defining node. |
|
Type |
escape |
Escape sequence. |
repeat |
Array delimiter/separator. |
|
normal |
Terminator. |
|
Delimiter Bytes |
Delimiter (single or multiple characters). |
|
Precedence |
See Precedence. |
|
Optional Mode |
never |
Do not allow on input, do not emit on output (empty field between delimiters implies zero length data field). |
allow |
Skip empty field if present; if absent, do not delimit on output. |
|
cheer |
Skip empty field if present; if absent, do delimit on output. |
|
force |
Require empty, delimited field on input; always delimit on output. |
|
Terminator Mode |
never |
Do not allow on input, do not emit on output (pure separator). |
allow |
Allow on input, do not emit on output. |
|
cheer |
Allow on input, always emit on output. |
|
force |
Require on input, always emit on output (pure terminator). |
Type Property - Escape Option
An escape delimiter is simply a sequence that will be recognized and ignored during parsing. Its purpose is to allow the use of escape sequences to embed byte sequences in data that would otherwise be seen as delimiter occurrences.
For example, if there is a normal delimiter “+” at a given level, and we define an escape delimiter “\+”, then aaa+b\+c+ddd will parse as three fields: aaa, b\+c, and ddd. If the escape delimiter were not defined, the sequence would then parse as four fields: aaa, b\, c, and ddd.
If there is only an escape delimiter on a given level, however, it presents a no delimiter defined situation for delim and array nodes.
Delimiter Bytes
There is essentially no limitation on what characters you can use as delimiters; however, you obviously want to avoid characters that can be confused with data or interfere with escape sequences. The backslash (\) is normally used as an escape character. The HL7 protocol uses a double backslash as part of an escape sequence that provides special text formatting instructions.
You should avoid using a colon (:) as a delimiter character, since it is used as a literal in system-generated time strings. This can interfere with recovery procedures, for example following a Domain shutdown.
Terminator Mode Property
Consider the tree structure shown in the previous example, where the node a has a pipe (|) as its delimiter, the sub-node b has a tilde (~) as its delimiter, and sub-node c has an asterisk (*) as its delimiter.
Option |
Input |
Output |
---|---|---|
never |
c| |
c| |
allow |
c| or c*| |
c| |
cheer |
c| or c*| |
c*| |
force |
c*| |
c*| |
Optional Mode Property
Consider the tree structures shown in the figures, where the node a has a pipe (|) as its delimiter, and the sub-nodes b, c, and d all have asterisks (*) as their delimiters.
Example 1: Sub-node c is optional. Sub-node c and sub-node d must have different values for the match parameter.
Option |
Input |
Output |
---|---|---|
never |
b*d| |
b*d| |
allow |
b**d| |
b*d| |
cheer |
b**d| |
b**d| |
force |
b**d| |
b**d| |
Example 2: Both sub-node c and sub-node d are optional.
Option |
Input |
Output |
---|---|---|
never |
b| |
b| |
allow |
b|, b*|, or b**| |
b| |
cheer |
b|, b*|, or b**| |
b**| |
force |
b**| |
b**| |
Precedence
Precedence indicates the priority of a certain delimiter, relative to the other delimiters. By default, all delimiters are at precedence 10, which means they are all considered the same; fixed fields are hard-coded at precedence 10. Delimiters on parent nodes are not considered when parsing the child fields; only the child’s delimiter (or if it is a fixed field, its length).
Changing the precedence of a delimiter will cause them to be applied to the input data-stream in different ways. For example:
Root node
element (type delim, delimiter = “^”, repeat)
field1 (type fixed, length = 5)
field2 (type fixed, length = 8, optional)
Although this will parse ”abcde12345678^zyxvuABCDEFGH’, it will not parse the text ”abcde^zyxvuABCDEFGH’ even though the second fixed field is optional. The reason is that the element’s delimiter is ignored within the fixed field because they have the same precedence. If you want the element’s delimiter to be examined within the fixed field data, you must change its precedence, for example: