Professional Documents
Culture Documents
Symphonia Mapper: Getting Started Guide
Symphonia Mapper: Getting Started Guide
Symphonia Mapper: Getting Started Guide
iii
Table of Contents
BACKGROUND AND INSTALLATION
Introduction ......................................................................................................................................1 What is Mapping?............................................................................................................................2 Installation ........................................................................................................................................3
iv
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.
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.
Map Workspace
Output Pane
Code Editor
10
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.
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
11
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:
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
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.
20
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
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
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 { }
23
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
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
25
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
When the above error was fixed, the output window displayed the following text: