• Working with Annotations
• Viewing Annotation data
• Showing/Hiding Annotations
• Strings
• Functions
• Loops
• Node Trees
• Showing/Hiding Empty Nodes
• Docking Annotation Dialogs

Working with Annotations

The Iguana Translator displays annotations that show you exactly what your code is doing. An annotation block appears to the right of each function that is executed. If you have imported sample data for your script, it will also be shown in the annotations.

Annotations and data dialogs are synchronized with script and data changes, if you edit the script or navigate through sample data the annotations and data dialogs will be updated in real time.

Each element of an annotation corresponds to the line of code that it is adjacent to:

An annotation element is created for each line of code that is executed.

In this example, the call to ProcessLab() is not executed, so it does not have an annotation element:

Annotations contain click-able “dialog links” so you can inspect data in more detail.

In this case we clicked the Warnings link:

Viewing Annotation data [top]

Annotations contain click-able links that open dialogs so you can inspect data in more detail.

For example you can view a sample HL7 message as text or as a parsed node tree:

The dialogs are synchronized with script and data changes, if you edit the script or navigate through sample data the dialogs will be updated in real time.

Showing/Hiding Annotations [top]

When you are using the Translator editor, you can hide the annotations by disabling auto-execution.

Simply click the Toggle auto-execution button on the toolbar to hide annotations:

You can show annotations again in one of two ways:

• Use the Toggle auto-execution button to turn auto-execution back on
• Use the Execute button to run the script once

Pressing Execute will run the script once and show annotations (while auto-execute is turned off):

At this point any action that renders the annotations out-of-date (editing the script, change of sample data, etc) will hide them again. Clicking the Toggle auto-execution button twice will also hide annotations.

Strings [top]

Integration work often requires getting under the hood and looking exactly what is going over the wire, just what invisible formatting character is it that is screwing up the presentation of reports in the end system? That information is just a mouse click away with the annotation dialogs for strings.

You can view strings as Plain Text, Escaped Text (Lua string format), and Hexadecimal

Here is an example of a file name showing the differences displaying the ” character:

• Plain Text
  
• Escaped Text
  
• Hexadecimal
  

And a more complex string with invisible newline characters ‘n”

 

• Plain Text
  
• Escaped Text
  
• Hexadecimal
  

Functions [top]

The annotations show exactly how the code is working and include click-able links to inspect data and to navigate to/from called functions.

Annotation blocks

An annotation block appears to the right of each function that is executed.

In this case ProcessLab() is not called so it has no annotation block:

Parameters and Returns

If a line of code contains a function call, the associated annotation element displays the parameters passed to the function call, and the return values if any are defined. Both parameters and return values are click-able links that open dialogs to inspect the data.

For example, consider the call to the ProcessADT() function:

Function execution

When a function is executed more than once during the processing of the sample message, the annotation displays a count of the number of times that it was called:

Initially the annotation displays the data for the first time the function was called, just hover over the count indicator and use the arrows to navigate through the function calls:

Code navigation to and from functions

The function names in annotations are links that enable you to step into or out of any called function. Simply click on the name where a function is called to step into it, or click on the name in the function declaration to step out. The pictures below will make this clearer.

To step into the ProcessAdt() function simply click the name:

The function you step into will be highlighted for a few moments:

To step out simply click the function name in the declaration, or the return statement:

Loops [top]

Our loop navigation controls are very clear, and they are great for nested loops:

For nested loops, brilliant!

If you get a feeling of déjà vu, it is probably because they look similar to function call repeats:

Node Trees [top]

The Translator uses Node Trees to store parsed hierarchical data like HL7 and XML messages, and database query results. These are displayed in dialogs using a simple hierarchy, that can be expanded/contracted to show more or less detail as needed.

For example an HL7 message is received as plain text and then parsed into a node tree:

The node tree is much simpler to understand and work with than the original text format. Simply click on a little “horizontal arrow” to expand a node.

Here we have expanded the MSH segment:

By default only nodes with data are shown, but the node tree is “smart” it knows the structure of the HL7 message, which it derives from the supplied VMD file. If you check Show Empty Nodes, it will also display the empty HL7 message fields (this can be very useful when you are mapping data for “partial” messages).

Here are some of the empty fields in this MSH segment:

Database query results and XML use node trees, but with different icons:

Finally a word about Lua tables and JSON trees, these are not node trees, but they are displayed are displayed hierarchically.

This is what a Lua table or a JSON tree looks like:

Showing/Hiding Empty Nodes [top]

In Iguana Translator, when you use hl7.parse() to parse an incoming message, or db.tables() to create database tables, the result is stored in a “node tree” (an internal tree-based format). Each component of this “node tree” is known as a node. Nodes that do not contain a value are called empty nodes.

By default, empty nodes are not displayed in annotations. However you can show them if you wish, simply check the Show empty nodes option at the top right of the annotation window:

To hide empty nodes again, just uncheck Show empty nodes.

Examples:

Here is an ADT message, with hidden nodes. Notice that field 8 of the MSH segment is not displayed.

When you check Show empty nodes, fields 8, other empty fields appear in the dialog:

Here is an example using a db.tables() node tree:

This can be useful a visual check that your database tables are what you expect.

Docking Annotation Dialogs [top]

Ever have too many dialogs open at once in the Translator and wished a better way of organizing them?

And here is what it looks like when you dock all those dialogs:

To dock a dialog simply click the Down Arrow at the top right on the toolbar:

Un-docking is very similar just click the Up Arrow on a docked annotation tab:

You can also reorder the docked tabs by dragging them, very similar to moving tabs in a (Chrome or Firefox) browser: