Format of the synonym file

The Auto map (automap) facility allows you to create mappings between specific inputs and outputs by putting the names of the inputs and outputs in a file called the synonym file.

Synonyms, in the context of the synonym file, are groups of words that represent mappings that you want to create.

File type

A synonym file can reside anywhere in your file system, only if the encoding used in the synonym file is the same as that used by the Eclipse Toolkit system.

However, if the synonym file uses a specific encoding that is, or might be, different from the encoding of the Eclipse Toolkit, the file must reside in a project in the IBM® App Connect Enterprise Toolkit.

If the synonym file is created outside the IBM App Connect Enterprise Toolkit, and uses a specific encoding, save the file under an IBM App Connect Enterprise Toolkit project and click Refresh to make the file visible in the navigator.

The synonym file uses Tab-separated or comma-separated files only. If you have written your mapping requirement in any external application, for example, Microsoft Word or Microsoft Excel, you must export the relevant data in a format that the synonym file supports.

Item names in the file

A synonym file contains the names of items to be mapped, without the path to the item or the namespace of the item.

For example, if you want to map partNum to partNumber in the following XML, you must put partNum in the synonym file, not item/partNum, items/item/partNum, or purchaseOrder/items/item/partNum. 
<po:purchaseOrder xmlns:po="http://www.ibm.com">
 <items> 
    <item>
         <partnum>100-abc</partnum>
         <productName>Acme Integrator</productName>
         <quantity>22</quantity>
         <USPrice>100.99</USPrice>
         <po:comment>Acme Integrator</po:comment>
         <shipDate>2008-12-01</shipDate>
    </item>
 </items> 
</po:purchaseOrder>
Synonyms in the file can:
  • Be case sensitive or not case sensitive
  • Contain the entire mapping item name
  • Have non-alphanumeric characters removed

Rows in the synonym file

In the synonym file, each row represents one group of names to be mapped between each other and each row must contain at least two names. Names within a row are separated by commas in .csv files, and by Tab characters in .txt files.

A synonym file can contain an optional special row at the top. This top row contains key words Input, Output, or Input_Output, separated by the same delimiter used in the remainder of the file. The top row is used to indicate whether the synonyms are to be used to match names in mapping the input or the output:
  • If the first word in the top row is Output, the first name only, in each subsequent row is searched in the mapping output for name matching.
  • If the second word in the top row is Input, the second name only, in each subsequent row is searched in the mapping input for name matching.
  • If the third word in the top row is Input_Output, the third name only, in each subsequent row is searched in both the mapping input and mapping output for name matching.
The top row must not contain fewer key words than the maximum number of names in any row in the file.

If the top row contains any word other than Input, Output, or Input_Output, the top row is ignored and it is assumed that the top row is missing. If you omit the optional top row, every name in the synonym file is considered to be Input_Output; that is, any name found either in the mapping input or in the mapping output is matched.

If a synonym file contains two rows:

car               automobile
automobile        vehicle

car and vehicle are not considered to be synonyms.

In order to make all three words synonyms, your synonym file can have either of the following structures:
  • One row with all three words -
    car          automobile          vehicle
  • Three rows - 
    car          autombile
automobile   vehicle
car          vehicle

Special characters

You can write synonym files manually, or export them from another application; for example, Microsoft Excel.

Item names in synonym files reflect the application domain and do not have to match exactly the names in the XML schema or the relational database column.

For example, a synonym file might contain the row:
         summer	      l'été
As l'été does not conform to the XML NCName format, you could name the element l_été. If all the alphanumeric characters in the synonym file match those in the schema, you can use the file with the option Alphanumeric characters (Letters and digits only).

Many mapping requirements are written in Microsoft Excel, and cells in a Microsoft Excel file might contain specific characters like double quotation marks, space, new line, comma, and so on. When such a Microsoft Excel file is saved as a Tab-separated or comma-separated file, they contain additional double quotation marks.

Two groups of synonyms in a synonym file are delimited either by a Line Feed (LF) character, or Line Feed followed by a Carriage Return (LFCR). A Carriage Return (CR) character by itself does not end a group of synonyms.

Leading and trailing space characters adjacent to the delimiter (comma or Tab character) are ignored. Blank rows, or rows that contain only space characters, are permitted and ignored in a synonym file.

Different editors might inject different space characters into a synonym file; spaces are not used to delimit synonyms, and spaces are ignored unless they are inside double quotation marks.

If a synonym contains a comma, a double quotation mark, a carriage return, or a leading or trailing space that is significant, the synonym must be enclosed in double quotation marks. A double quotation mark within a synonym is escaped with another double quotation mark. For example:
       "comma,separated"
       "double""quote"
         "with<CR>
          newline"
         "  spaces   "
When the synonym file is read by the Graphical Data Mapping editor, the double quotation marks at the beginning and end of the synonym are removed and the following data is stored in the synonym table:
       comma,separated
       double"quote
         with<CR>newline
           spaces

The Graphical Data Mapping editor reads a synonym file containing these special characters correctly, and you should select the Alphanumeric characters (Letters and digits only) option when using the synonym file.