• Access the Translator Editor
• Create a Script
• Edit a Script
• Code Navigation
• The Importance of queue.push{}
• Execute a Script
• Script Error Messages
• Exporting/Importing Projects
• Editing files other than Lua
• Create database tables from a VMD file

Access the Translator Editor

The following channel components use scripts:

• From Translator: Mandatory script
• To Translator: Mandatory script
• Filter: Optional script when Filter type = Translator
• From HTTPS: Mandatory script
• LLP Listener: Optional script to generate ACK  message when ACK = Translator

There are two ways to access the Iguana Translator script editor:

• Click on the Edit Script link in the properties of a scripting component:
  
• Click on an Edit Script link in a script component tooltip in the Dashboard:
  

Create a Script [top]

The first time time that you edit a script (by clicking on an Edit Script link), you will need to create the script.

The import project dialog will open:

• Choose one of the options:
  • Use a blank project: Create an empty script template
  • Import From Existing Projects: Copy another project script, select from the listbox
  • Import project from zip file: Select a project zip file to import from
• Click Import
  
  

Edit a Script [top]

To edit a script simply type your Lua  script code into the Translator Editor window:

• Code is written in the Lua scripting language, see Lua Basics
  Note: It is very easy to write useful mapping code in Lua
• The Translator provides handy built-in API functions to perform basic scripting operations such as:
  • Parsing a VMD file, creating database tables
  • Merging database tables with an existing database
  • For help with built-in functions, see The Iguana API Reference
• As you enter code auto-completion guesses your intention and offers hints, support, and scripting help, see Auto-Completion
• The Translator displays annotations that show you exactly what your code is doing, see Annotations

Code Navigation [top]

The Translator allows you not to just navigate through functions, but also navigate through the calls.

To see what I mean take a glance at this dummy code:

In this dummy code the function foo() is called in two places. Once directly from the main() function and once from the bar() function. Code navigation allows us to easily see these two calls. By hovering the mouse over the purple foo in the annotation block on line two you’ll see something like this:

By clicking on the purple foo annotation the editor will highlight where the foo() function is defined and if need be switch the editor over to the module file where the function is defined. A small green highlight will appear and fade away rather like this:

Now by clicking on the second call of foo on line 11 the editor will again highlight line seven but notice how the iteration it is showing is now 2 of 2. The editor is actually showing the actual iteration of when foo() is called by bar():

Now what’s even more fun is that the navigation is bidirectional. We can navigate back the other way by clicking on foo in the annotation window, we go different places depending on whether we are on annotation 1 of 2 or 2 of 2.

Back to main() from call one:

Back to bar() from call two:

You can also navigate back from the last line of of a function. This is very helpful with long functions (that you you cannot see on a single screen), because it means you do not have to scroll back up to the start of the function:

All this makes it very easy to navigate through finding out the source of those calls that produce those odd boundary cases and so on.

This is also nicely complemented by the Error Stack Trace window for exceptions.

The Importance of queue.push{} [top]

The queue.push{} function is pivotal to your use of Iguana.

You will be using queue.push{} in most of your channels, it allows you to push text data to Iguana queue/log. This function is the the primary mechanism used to transfer data from a Source component to a Filter component, and from a Filter to a Destination component.

The usage is deceptively simple:

queue.push{data=Out}

Out is a string argument (for example, an HL7 message, an XML document, or simply a database row ID). Out will be pushed into Iguana’s queue, to be processed by the channel’s destination(s). The queue.push{} function can be called multiple times, so you can queue multiple output messages for each input message. If queue.push{} is never called, the input message will be “ignored”.

Execute a Script [top]

Scripts in the Editor can be executed automatically, or manually.

Scripts are run automatically when the editor is in the default “auto-execute mode”, and manually when this is turned off.

The Toggle auto-execution button on the toolbar is used to turn auto-execution on and off:

When the editor is not in auto-execute mode you can use the Execute button to run the script:

Script Error Messages [top]

Errors are immediately displayed when you finish editing a line of code. When you correct an error, the error message disappears as soon as you finish editing the line. This makes debugging quick and easy!

Errors messages are displayed in red, with an additional error link at the bottom of the screen:

Exporting/Importing Projects [top]

Use project zip files to transfer component code and sample data between Translator instances. Simply export from your source component and import into your target component.

You can export all the associated Lua, vmd files etc. for a Translator instance into a project zip file to share between Iguana instances. You can optionally include the channel’s sample message data.

Create a project zip file

1. Open the desired component  in the Translator’s Editor.
2. Hover the mouse over the triangle to the right of main.lua in the Project Files panel:
   
3. Select Export Project from the menu:
   
4. Optionally include the component sample messages:
   
5. Save the project zip file to disk.

Import a project zip file into another Iguana instance

There are two ways to import a project zip file and access its contents:

• Import a project zip file when creating a new channel
• Import a project zip files from the Project Files panel in the Iguana Editor

Importing a project zip file when creating a new channel

1. When you create a script the Import Project dialog opens
2. Use the Browse button to select a project file to import:
   

Import a project zip file within the Editor

1. Open the desired component  in the Translator’s Editor.
2. Hover the mouse over the triangle to the right of main.lua in the Project Files panel:
   
3. Select Export Project from the menu:
   

Editing files other than Lua [top]

As well editing Lua files the Translator Editor works as a colorized programmer’s editor for other file types, like CSS, javascript and HTML.

Note: Annotations are only available when editing Lua files.

Here are CSS, javascript, HTML files opened in the Editor:

Create database tables from a VMD file [top]

You can create table(s) “manually” from the VMD files menu (in the left pane of the Translator screen), hover over the small triangle next to your VMD file, and choose Create DB Tables:
Note: This method of creating tables will work with all databases supported by Iguana.