This topic applies only to the IBM Business Automation Workflow Advanced configuration.

Format of the synonym file

Edit online
Draft comment:
This topic only applies to BAW, and is located in the BAW repository. Last updated on 2025-03-13 12:15
Auto map allows you to create mappings between specific sources and targets by putting the names of the sources and targets 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.

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 Source, Target, or Source_Target, 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 source or the target:
  • If the first word in the top row is Target, the first name only, in each subsequent row is searched in the mapping target for name matching.
  • If the second word in the top row is Source, the second name only, in each subsequent row is searched in the mapping source for name matching.
  • If the third word in the top row is Source_Target, the third name only, in each subsequent row is searched in both the mapping source and mapping target 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 Source, Target, or Source_Target, 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 Source_Target; that is, any name found either in the mapping source or in the mapping target 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 one of the following:
  • One row with all three words 
    car, automobile, vehicle
    or
  • Three rows 
    car, automobile
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.

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é. As long as all the alphanumeric characters in the synonym file match those in the schema, you can use the file with the option Letters and digits only, ignore non-alphanumeric characters.

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 ended by another double quotation mark. For example:
       "comma,separated"
       "double""quote"
         "with<CR>
          newline"
         "  spaces   "