Modifying a Message Library Using the Message Library Editor

• Message Library Check Out and Check In

• Adding and Replacing Message Library Segments

• Managing Message Library Nodes, Elements, and Fields

• Message Library Properties

• Specifying the Node Type

• Editing the Message Library Delimiters

• Changing HL7 Standard Encoding Characters

• Specifying Delimiters

Message Library Check Out and Check In

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

Adding and Replacing Message Library Segments

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.

To Replace a Message Library Segment

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.

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

   ---

   Tip –

   To copy the Message Library segment, use the copy command from the Tools menu.

   ---

2. Repeat the above step for any Message Libraries that contain segments you want to use in the above Message Library.

3. Double-click the pasted Message Library from step 1 above to display it in the Message Library Editor.

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

   

5. Click the Internal tab in the Reference pane, right-click the segment you want to replace, and then click Delete.

6. In the Internal tab, select the top-level node to display all segments in the Object Type Definition pane.

7. In the Object Type Definition pane, right-click the same segment you deleted above, and click Delete again.

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

9. On the Message Library Editor toolbar, click Import OTD From External Template.

   The Import dialog box appears.

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

11. Locate and select the Message Library you want to import to your Project file.

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

    

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

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

15. Repeat this procedure for any additional segments you want to replace.

16. Save the changes to the Repository.

    You can now open the segment Message Library and edit the properties.

To Add a Segment Message Library to a Message Library

You can also modify a Message Library by adding additional segment Message Libraries to your Message Library’s external template.

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

   ---

   Tip –

   To copy the Message Library segment, use the copy command from the Tools menu.

   ---

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

3. Double-click the Message Library to which you want to add the segment.

   The Message Library Editor appears.

4. On the Message Library Editor toolbar, click Import OTD From External Template.

   The Import dialog box appears.

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

6. Locate and select the Message Library you want to import to your Project file.

7. Click Add button to add the Message Library to the Select OTD(s) to Import section.

8. Click Import.

   The Message Library is added to the External tab of the Reference pane.

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

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

11. Save the changes to the Repository.

Managing Message Library Nodes, Elements, and Fields

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 Manage Message Library Nodes, Elements, and Fields

1. To add a node, element, or field to the Message Library structure, right-click the

   1. Right-click the node to which you want to add the node, element, or field.

   2. Click Add, and then select the type of object to add.

   3. In the Properties pane, customize the properties for your data requirements.

      See Message Library Propertiesfor more information about properties.

2. To remove a node, element, or field, right-click the object to remove and then click Delete.

3. To prune a node, right-click the node and then click Prune.

Message Library Properties

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:

• Node Properties

• Element Properties

• Field Properties

Node Properties

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.

Element Properties

The set of properties associated with the element level is shown in the following figure and is described in the table below.

Figure 1 Message Library Editor - Message Library Element Properties

Field Properties

The set of properties associated with the field level is shown in the following figure and is described in the table below.

Figure 2 Message Library Editor - Message Library Field Properties

Specifying the Node Type

If you move a Message Library node, you must reset the nodeType for that node.

To Specify a Node Type

1. In the Message Library Editor, expand the Message Library until the field you want to edit appears in the Object Type Definition pane.

2. Select the field to edit.

3. Click in the nodeType field, and then click the arrow to display the options.

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

Editing the Message Library Delimiters

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.

To Edit the Delimiters From the Root Node

1. Select the root node in the Object Type Definition pane of the Message Library Editor.

2. Double-click the delim properties field in the Properties pane.

   An ellipsis (...) button appears in the field.

3. Click the ellipsis button.

   The Delimiter List Editor appears.

   

4. Double-click any field in the Delimiter List Editor on any level to make the field editable or to display a list of options.

5. For Level 3, do the following:

   1. Double-click the Delimiter Bytes field for level 3.

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

      

Changing HL7 Standard Encoding Characters

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" );

}

Specifying Delimiters

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:

• demo-otd

  • element1

    • field1

    • field2

  • element2

    • field3

    • field4

  • field5

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.

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.

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.

• Example 2: Both sub-node c and sub-node d are optional.

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:

• Root node

  • element (type delim, delimiter = “^”, repeat, precedence = 11)

    • field1 (type fixed, length = 5)

    • field2 (type fixed, length = 8, optional)

      This will successfully parse the text ”abcde^zyxvuABCDEFGH’.