| Skip Navigation Links | |
| Exit Print View | |
|
Oracle Java CAPS Message Library for HL7 User's Guide Java CAPS Documentation |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Oracle Java CAPS Message Library for HL7 User's Guide Java CAPS Documentation |
Working With the Message Library for HL7
Overview of HL7 and the Message Library for HL7
Medical Records/Information Management
Working With HL7 Message Libraries
Viewing a Message Library Using the Message Library Editor
Copying a Message Library to a Project
To Copy a Message Library to the Project
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
Editing the Message Library Delimiters
Changing HL7 Standard Encoding Characters
Using the Message Library Tester
To Use the Message Library Tester
HL7 Version 3 Message Library Structure
HL7 Version 2.6 Message Library Structure
HL7 Version 2.5.1 Message Library Structure
HL7 Version 2.5 Message Library Structure
HL7 Version 2.4 Message Library Structure
HL7 Version 2.3.1 Message Library Structure
HL7 Version 2.3 Message Library Structure
The Message Library Editor displays the structure of a selected Message Library and allows you to verify its operation with a built-in tester. You can also use the editor to create and modify Message Libraries.
The following topics provide information specific to using Message Libraries with the Message Library Editor. These Message Libraries are templates that correspond to message types used by industry-specific data exchange systems and open-source standards. The templates are predefined and can be used as-is.
Note - Only the base and generic 2.6 libraries are installed by default. You need to install the Message Libraries for the versions of HL7 you are using separately. For more information, see Installing Additional Repository-Based Java CAPS Components in Installing Additional Components for Oracle Java CAPS 6.3.
The Message Library Editor displays the structure of a selected Message Library and allows you to verify its operation with a built-in tester. You can also use the editor to create and modify User-Defined Message Libraries.
Note - The Message Libraries available under Message Library in the Projects window are protected (read-only).
You can copy and paste a Message Library to your Project to view the Message Library in an editable mode.
The Message Library is added to your Project on the Projects window.
The editable Message Library appears in the Message Library Editor. Notice that for the Message Libraries, the Message Library segments are still write protected. The Message Libraries properties can only be modified from the Root node at this point.
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 CAPS Components Library 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.
Tip - To copy the Message Library segment, use the copy command from the Tools menu.
The figure below shows the structure of the HL7_26_ADT_A02 segment.
This removes all other references to the segment Message Library.
The Import dialog box appears.
This is one of the Message Libraries you pasted into a Project in step 2 above.
The Message Library is added to the External tab of the Reference pane.
The segment is added to the Object Type Definition tree.
Repeat this step until the new segment is in the same position as that of the segment being replaced.
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.
Tip - To copy the Message Library segment, use the copy command from the Tools menu.
This opens the Message Library in the Message Library Editor.
The Message Library Editor appears.
The Import dialog box appears.
This is one of the Message Libraries you pasted into a Project in step 2 above.
The Message Library is added to the External tab of the Reference pane.
The segment is added to the Object Type Definition tree.
Repeat this step until the new segment is in the location you want it.
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.
See Message Library Properties for more information about 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:
The OTD is added to your Project in the Projects window tree.
The Root properties and displayed in the editor’s Properties pane.
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.
|
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
|
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
|
Note - If you move a Message Library node, you must reset the nodeType for that node.
The following table describes the nodeType options.
|
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.
An ellipsis (...) button appears in the field.
The Delimiter List Editor appears.
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:
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.
Table 1 Delimiter Properties
| ||||||||||||||||||||||||||||||||||||||||||||||||
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.
Note - 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’.
The Message Library Tester allows you to simulate the operation of a Collaboration containing a specific Message Library, thereby checking the correctness of the library during the design phase. You can enter input data values, perform the unmarshal and marshal operations, and also manipulate the tree structure as a Collaboration might do by using the Add Instance and Delete Instance functions. By using these latter features, you can prepare an output data file that can then be used as an input data file for testing purposes.
Note - For selected Message Libraries, the Verbose option provides a trace of parsing actions during the unmarshal process to aid in debugging the library structure. Selecting the Verbose check box causes parsing information to appear on the Verbose panel. The format and content of the data display are library-specific.
This saves the currently displayed Message Library to the Repository and displays the Message Library Tester at the bottom of the Message Library Editor. The data display panel offers four different data display modes. The Input mode is selected by default.
The unmarshal options are:
Unmarshal
Unmarshal from Bytes
Unmarshal from String
Use the Add/Delete Instance (+/-) buttons to add or remove instances where needed.
The output is displayed in the Output panel
The marshal options are:
Marshal
Marshal to Bytes
Marshal to String
|