Symphonia Mapper

Getting Started Guide

This page intentionally left blank

iii

Table of Contents
BACKGROUND AND INSTALLATION
Introduction ......................................................................................................................................1 What is Mapping?............................................................................................................................2 Installation ........................................................................................................................................3

USING THE SYMPHONIA MAPPER

Launching the Mapper....................................................................................................................5 The Symphonia Mapper .................................................................................................................7 The Message Definitions .................................................................................................................8 Using the Mapper ............................................................................................................................9 Main Maps ......................................................................................................................................12 Submaps ..........................................................................................................................................12 Mapping Repeating Items ............................................................................................................18 External Functions .........................................................................................................................19 Other Basic Operations .................................................................................................................22 Compiling Mappings ....................................................................................................................26

iv

This page intentionally left blank

Background and Installation

Introduction
This document introduces the concepts of mapping and shows how to use the Symphonia Mapper to perform some basic mapping tasks. A basic knowledge of EDI and XML is assumed. If you are at all unsure about these topics, we strongly recommend that you familiarize yourself with them prior to commencing this mapping. The Symphonia web pages have introductions to these topics. Go to http://www.symphonia3.com/ and follow the link to Having difficulty with messaging. If you are unclear about the use of any of the technical terms in this section, please consult the glossary at the end of the full Symphonia Mapper manual.

What is Mapping?
Mapping
Mapping is about reformatting structured information. Lets say that I want to communicate two pieces of information: A name and a date of birth. The name will consist of a first name, a space and a surname. At the end of the name, there will be a comma and a space. There will also be a / character to separate the day, month and year of the date. At the end of the communication, there will be a new line character. Firstname Surname, Date of Birth Fyodor Dostoevsky, 06/07/1821 When we are working with computers, the information about how this data is presented is important, as the program must process this information in the correct way. What happens when someone else might need the same information formatted differently? For instance, someone else might accept the surname and then the first name. We would need to map the information from the original format to the recipients format. Mapping is about changing the way structured data is formatted.

Installation

Installation
Installation
Installation is very straightforward. Note that in order to install successfully, you will need to have administrative privileges on the target machine. If you havent been given a development key (Serial Number), leave DEMO in the serial number field. You will be able to use the product for sixty days before needing to register it.

If you have trouble installing

The number one cause of problems in this area is the installer not having administrative rights to the target machine. Also, ensure that all other applications have been shut down before beginning installation. If you dont have administrative rights or if you are unsure what this means, you will need to talk to your system administrator.

This page intentionally left blank

Launching the Mapper

Using the Symphonia Mapper

Launching the Mapper
The Mapper is very straightforward to use. This document is designed to help you over the initial learning curve. More advanced training is available upon request.

The First Screen

When the mapper is first run, the following dialog appears:

Continued on next page

Launching the Mapper, Continued

Project Creation
In the previous dialog, the mapper is asking you to create a project where mapping information can be stored. The default setting is the Projects directory under the main mapper program directory. This can easily be changed in the application settings. For now, it is probably easiest to view one of the sample projects that we have created for you. Access these by moving to the Recent tab and select the SimpleADTSample project. This sample is a common mapping that is often used in real life. It follows the common HL7 version 2.3 standard but also accepts an HL7 2.1 ADT message and outputs it in the later version.

The Symphonia Mapper

The Symphonia Mapper

The Mapper Screen
The image below shows the Symphonia Mapper with a partially completed mapping project: Map Window Input Definition Output Definition Tree Tree

Map Workspace

Output Pane

Code Editor

Continued on next page

The Symphonia Mapper, Continued

Screen Areas
There are four important parts of the Symphonia Mapper Application. Map Workspace Window contains all of the available maps and submaps in this project Input Definition Tree the structure we are mapping from Output Definition Tree the structure we are mapping to Code Editor Window where the mapping code will be written that defines the rules to map from the HL7 2.1 message to the Hl7 2.3 message

The Message Definitions

The mapper needs definitions for the two objects in the Input and output trees. The Mapper can map both XML and EDI messages. An XML Schema or DTD may be used for the XML Definitions but for EDI messages the mapper needs either a Symphonia PCF file or a Composer DLL. Users of Symphonia will be familiar with Composer and the Direct ActiveX objects that it produces. Composer is Symphonias Message definition GUI. It is a tool that allows the customisation of message definitions. There is a Composer for EDI message definitions and a Composer for XML document definitions; both of these are included with the Mapper. A PCF file is a Parser Control File. It is generated by Composer for use in the Symphonia Parsing Engine. It contains information about the structure of a set of EDI messages. Composer can also generate an ActiveX DLL for a message definition. If you have generated a DLL from Composer, the mapper will be able to use it without you having to change anything. If you need to map messages from a commonly used EDI standard such as X12, EDIFACT or HL7, it is likely that the messages you are using will be included in the Composer Library. Use the Composer wizard to import these messages and generate a PCF.

Using the Mapper

Using the Mapper

Assigning Simple Values
The mapper has very powerful features to help you define your mapping code. The simplest mapping operation is to copy the contents of a field in an input definition to a corresponding field in an output definition. To instruct the mapper to create this statement, click on the field you wish to map and drag it across to the field on the output side that you wish to map it to.

Continued on next page

10

Using the Mapper, Continued

When you drag an input field (a field does not have any children) across to an output field, the mapper adds a new line in the code area at the bottom. For the operation on the previous page, the line of code is shown here:
Out.FieldSeparator = In.FieldSeparator;

This line of code is called an assignment statement because the value of In.FieldSeparator is assigned to the field Out.FieldSeparator. Only fields from the output pane can appear on the left hand side of assignment statements. The mapper behaves slightly differently when records (i.e. items with children) are mapped. Records must be mapped using submaps which will be described later in this manual. The mapper adds its code at the current location; if this line is not empty the mapper will use the following line. You can also drag and drop in reverse. In other words, if you start from the output window and drag to the input window, the mapper will add exactly the same line of code.

Assigning Fixed Values

Another common task is to assign fixed values into an output field. HL7 2.3 messages have a version code that must contain the value 2.3. We clearly do not want the HL7 2.1 value 2.1 assigned to this field, so we need to assign the constant value 2.3. Point the mouse to the version field and drag it down to the start of a line in the code editor, type the assignment operator = and then the value 2.3. Finally, all statements must be finished with a semicolon ; character. This process is shown in the image on the following page: Continued on next page

Using the Mapper

11

Using the Mapper, Continued

Entering Constant Values

The process of dragging and dropping items can be used for most mapping exercises. Knowing these techniques is enough to map most of HL7 2.1 messages to the more complex HL7 2.3. It is a good idea to do your maps in the order that they are found in the output definition. Mapping in this order makes your code easier to read and understand.

12

Main Maps
Main Maps
A main map is a top-level function that maps between two top-level objects. A top-level object is either an EDI message or an XML document. Main maps can only have two parameters an input parameter by default called In, and an output parameter called Out also by default. Each message or document in the Input definition can only appear in a main map once. No such restriction applies to the messages in the output definition.

Submaps
Submaps
One way of solving a difficult problem is to break it down into smaller tasks that are easier to manage. Submaps allow us to map individual components of the messages and documents as if they were top-level objects. For example, if an EDI message is mapped to another EDI message, the task can be broken down by looking at the individual segments of each message. Mapping XML documents is often best accomplished by mapping individual elements. Both EDI segments and XML elements can be broken down still further until we reach the simple data types. Submaps work in a similar way to main maps but there are no restrictions on the type and number of parameters that they are able to take. The idea of a submap is still the same as that of a main map: take Input objects and produce Output objects. Most commonly, a submap will take one input parameter and produce one output parameter. Whenever you map two records, you must use a submap. The reason for this is that the Mapper does not know how to assign the child items of the two complex objects. Continued on next page

Submaps

13

Submaps, Continued
ACK Message Code
Here is the complete code for the main map of the ACK message:
map mainACK( <- Input::ACK in, -> Output::ACK out ) { MapMSHToMSH(in.MSH, out.MSH); MapMSAToMSA( in.MSA,out.MSA ); MapERRToERR( in.ERR,out.ERR ); }

The code in this map is quite different to the code that was created for the mapping of fields. The main difference is that there are no assignment statements.

Submap Reuse

The mapper cannot assign records so the following syntax would be illegal:
In.MSH = Out.MSH;

This code for the mainACK map was created with exactly the same drag and drop process. Note that if the same segment is ever found in another message, the submap created above can be reused.

Mapping a Record

When you first map a record, you will see this dialog box:

Continued on next page

14

Submaps, Continued
Mapping a Record
continued Once OK has been clicked, we are presented with the submap creation dialog. Most of the time, the default parameters will be fine, but occasionally you may want a submap that takes different parameters. Change the parameters using the Add Parameter and Delete Parameter buttons. The column on the left contains Combo Boxes of all of the available data types.

The image above shows the submap screen for the creation of an MSH to MSH submap. Continued on next page

Submaps

15

Submaps, Continued
Definition Tree Structure
Once we have passed the submap dialog, the definition trees will contain the structures of the parameters we selected.

This pane allows us to concentrate on the MSH segments only. Had we not used a submap, all the code written here would have had to go inside the main map. When you have finished the mapping the fields inside this segment, return to the main message map. Inside the main map, the mapper will have added the line that we saw before. MapMSHToMSH(in.MSH, out.MSH); Continued on next page

16

Submaps, Continued
Reusing a Submap
Once this submap has been defined, we can use it anywhere that the same two input and output components occur. If we are mapping many messages with similar elements, submaps can save a great deal of time and effort. For instance, the MSH also occurs at the top of the ADTA01 message. When the submap has been defined, the next time that we drag an MSH onto another MSH, the mapper will detect that it already has an appropriate submap:

If we select OK, the mapper will add the same code as before. We can also drag the submap name from the workspace window into the code editor in the same way that we entered 2.3 into the VersionId field. The mapper will add a call to the submap as shown on the following page: Continued on next page

Submaps

17

Submaps, Continued

We can now drag the items that we need from the definition trees onto the question marks to give the code the mapper added before.

18

Mapping Repeating Items

Repeating Items
Repeating items can occur more than once in a message or document and are very common in both EDI messages and XML documents. It is essential that you understand how the Symphonia Mapper handles these items. Repeating items are also called collections or arrays. Repeating items show up in the definition pane with a pair of square brackets [ ] at the end of the name and a red R on the bottom left of its icon. This NK1 segment shows what repeating items look like.

Mapping Repeating Items

Whenever a single element is mapped out of a repeating item, the index of the element you wish to work with must be specified. For instance, if you are only interested in the first repeat of the NK1 segment above, you must type: NK1[0] Note that the first item has a reference of 0. If we are using a submap, we can specify that we want to call the submap for every element in the repeating collection. SubMap(In.repeatingElement[*], Out.repeatingElement[*]); This means that every time repeatingElement occurs in a message, the submap will be called. Whenever this syntax is used, you MUST have two repeating components, one for input and one for output. Note: This syntax can only occur in a call to a submap; we cannot use the following, (Wrong) Out.repeatingElement[*] = In.RepeatingElement[*]; This syntax will NOT work.

External Functions

19

External Functions
External Functions are similar to submaps and are used to perform tasks that we either dont wish to do or cannot do with Submaps. The Mapper is provided with a default set of External Functions which are described in the full Symphonia Mapper manual. A common task is to map a portion of one string into another. For instance we might only want the first three characters of an input field to be entered into the output field. The standard Symphonia Mapper functions are able to perform most common mapping operations. At least one of these functions is displayed at all times and it is possible to get a list of all available functions by clicking on the arrow next to it. The list of external functions is also available from the workspace window by clicking the External Functions tab (next to the Map tab at the bottom of the workspace). Functions can be dragged from here into the code window in the same way as dragging maps.

The External Functions button

Continued on next page

20

External Functions, Continued

The external functions are defined in three parts: the return type; in the case of StrLeft, the value returned from the function will be a string the functions name the list of the parameters expected by the function Most of the functions are straightforward to use. For instance, if we want to get the first three characters, we need to use the StrLeft Function to return the Leftmost characters in a string. Out.text = StrLeft(In.A_String, 3); Another common task is the mapping of one field to another field that is of a different type. Every field in the Symphonia mapper is one of four basic data types. These can easily be recognized by their icons. String Integer Boolean Double

When the assignment statement is used, the type of the field on the left must be the same as the type of the field on the right. If you try and assign two simple fields of different types by dragging one to the other, the mapper will automatically add a type conversion function. This type conversion function is another External function. Continued on next page

External Functions

21

External Functions, Continued

In the MapDG1toDG1 submap, there is an example of automatic conversion.
//This is an Example of an Automatic Function call. //When a field is mapped to another field of a //Different Type, the Mapper will automatically add the //function call to perform the conversion

if (exists(In.OutlierDays)) Out.OutlierDays = IntToDbl(In.OutlierDays); In HL7 2.3 the OutlierDays field in the DG1 segment is a double. In HL7 2.1, this same field is an integer. When we mapped this field, the Mapper added the conversion function IntToDbl to make sure that we assign the correct type. Note: In both XML and EDI it is possible to have empty fields, i.e. fields that do not contain any data. If an empty field is passed into a conversion function, the mapper will substitute a default value of zero if the field is numeric (integer or double). This can have the unfortunate side effect of mapping an empty field to a zero in the output. The next section shows how to avoid this problem.

22

Other Basic Operations

Notice that in the OutlierDays example above, the first line of code was:
if (exists(In.OutlierDays))

The mapper language includes features that can be used for processing more than just simple assignments. Most options are available on the Code Toolbar above the code window where the External Functions button was found.

A complete list and explanation of all of these functions may be found in the Symphonia Mapper manual. Those items that have been used in this sample have been presented here. Clicking any one of these buttons will insert code into the code window leaving question marks where the syntax is incomplete and needing information from the user. With the OutlierDays, we want to make sure that the field in the input message is not empty before we copy the value to the output message. If we do not, the mapper will insert the default value 0 (zero) into the conversion function and there will be data in the output message where there was none in the input message. First, we press the if button following code.
if (???) { } else { }

to insert an if statement. This inserts the

Continued on next page

Other Basic Operations

23

Other Basic Operations, Continued

The question marks after the if statement expect either true or false (or a statement that evaluates to true or false). The if statement allows us to perform tasks when a particular condition is met, if the condition is not met we can perform some other statements. We only want to copy the value of OutlierDays to the output message if the outlier days field is present (ie not empty) in the message. We dont need to do anything if the OutlierDays field is not present so we can remove everything after the else, leaving:
if (???) { }

Highlight the question marks and press the exists button. replace the question marks with the code:
exists(

. This will

The exists operator tests whether elements are present in the message. If a field is empty, it not considered to exist. Next, drag the OutlierDays from the input pane to the right of exists( and type a close bracket ). Finally, place the cursor in the middle of the parentheses { and } and do the normal mapping for outlier days. Continued on next page

24

Other Basic Operations, Continued

The other function that was used extensively is found in the sample in the MapPV1toPV1 submap.
//This requires a for loop. for(int i=0;i<sizeof(In.FinancialClass); i=i+1 ) { Out.FinancialClass[i].FinancialClass = In.FinancialClass[i]; }

This code accomplishes the mapping of a repeating item without using the [*] syntax. It means: Every time the In.FinancialClass field repeats, copy (assign) the value in that field to the Out.FinancialClass.FinancialClass field.

For Loops

A for loop performs the same task a specified number of times. When the for loop button is clicked, the following text is inserted into the code.
for(int i=0;i<???; i=i+1 ) { }

All that is needed is to specify the number of times the loop is to be performed. The variable i will take all of the values between 0 and the value that you put in the question marks. Most commonly, this value will be calculated using the sizeof( operation. In the financial class example, we only want to loop as many times as there are elements in the FinancialClass field. Continued on next page

Other Basic Operations

25

Other Basic Operations, Continued

Highlight the question marks and press the sizeof button. insert the text:
sizeof(

This will

Drag the FinancialClass field from the input definition pane to the right of the sizeof( and type a bracket ). Place the cursor in the middle of the parentheses { and } and do the normal mapping for FinancialClass. The mapper will insert the following text.
Out.FinancialClass[???].FinancialClass = In.FinancialClass[???];

Replace the question marks with i. This tells the mapper to use the value of i for the index to the repeating items. Since i will go from 0 to the sizeof financial class, all of the items in the repeating collection will be mapped. For detailed information on the for loop and the other available functions you will need to consult the manual.

26

Compiling Mappings
The Symphonia mapper works in two distinct phases: define the rules that describe how the input messages are mapped to the output message. Once the definition is complete, you need to compile the map. The Mapping compiler writes out a compiled mapping file which has the extension .ecc. Use the mapping engine to load this file and perform the task of changing input messages to output messages. When the mapping is complete, click the compile button on the toolbar. The mapper will then check that all of your mapping code is well formed. If it contains errors, the compiler will display an error message in the output window.

Common Errors

Some common causes of errors are: Leaving some question marks when you have dragged in a map from the workspace window. Not specifying the index of a repeating item If you have typed any text, spelling mistakes can often occur. You can click on the errors in the output window and the mapper will take you to the line of code where the problem is. In the image on the following page, an e has been removed from LicenseNumber to simulate a spelling error. The compilers error message is that the variable LicensNumber is not defined. This commonly means that something has been misspelled. Double clicking the error will move the cursor to the exact line where the problem can be fixed. Continued on next page

Compiling Mappings

27

Compiling Mappings, Continued

When the above error was fixed, the output window displayed the following text: