Determining mapping candidates

For each item in the target structure, the mapping table automatically presents a list of valid mapping candidates.

To determine the candidates to display in the mapping candidate list and to determine which candidate to use for the Auto Map option, the mapping algorithm uses the following process:

Create a list that contains all of the valid mapping candidates. Valid candidates are unambiguous.
Select only the candidates that meet the specified level of conversion accuracy. By default, the level for conversion accuracy is lossy; candidates must have a data type that can be converted to the target data type without creating a possible runtime error.
Evaluate the similarity of the name and of the data type of the source and target items. Assign a score to each candidate, based on the similarity of the names and data types.
Select the highest scoring candidate to use for the Auto map option.
Select the highest scoring candidates to present on the mapping candidate list, which displays when you press the down-arrow on the source item in the mapping table. By default, the mapping candidate list displays the top 5 candidates.

To change the level of conversion accuracy and the number of mapping candidates to present on the candidate list, choose Administration > Mapping Configuration.

Mapping example

To understand why certain mapping candidates are valid or invalid, review this example. The following figure shows the step Input. The step Input contains the following items that are peers of each other:

An item named documentID.
A list named mySourceList, which contains an item named sourceChildField and a list item named sourceChildList, which contains an item named sourceDescendentField.
A list named Peer-List, which contains an item named peerField.

The following figure shows the instance data that the step receives and transforms to the target structure:

The following is the XML data that this example uses. As you read about valid and invalid mapping candidates, refer to this data so that you can understand how the data values are determined:

<SourceDoc>>
 <documentID>ID001</documentID>
 <mySourceList>
  <sourceChildField>A1</sourceChildField>
  </sourceChildList>
   <sourceDescendentField>A11</sourceDescendentField>
  </sourceChildList>
  <sourceChildList>
   <sourceDescendentField>A12</sourceDescendentField>
  </mySourceList>
  <mySourceList>
   <sourceChildField>A2</sourceChildField>
   </sourceChildList>
    <sourceDescendentField>A21</sourceDescendentField>
   </sourceChildList>
   <sourceChildList>
    <sourceDescendentField>A22</sourceDescendentField>
   </mySourceList>
   <Peer-List>
    <peerField>peer1</peerField>
   </Peer-List>
   <Peer-List>
    <peerField>peer2</peerField>
   </Peer-List>
</SourceDoc>

The following figure of the mapping table shows that list item mySourceList is mapped to list item myTargetList, and all of the child items of myTargetList are correctly mapped.

Valid mappings

List mapping determines how the items of a target list are created. During item creation, the source list is iterated; and for each item in the source list, a new item is created in the target list. A child list is similarly iterated in a nested loop. Content mappings are evaluated in the context of the iteration. In other words, the target value of an item depends on the source list item that is currently being iterated and on the mapping .

The following mappings are valid for the example:

List mapping: For each item in mySourceList, one item in myTargetList is created. Therefore, two myTargetList items are created for the two mySourceList items that are in the input data.
Simple content mapping: To create the first myTargetList item, the mapping top/result/SourceDoc/mySourceList/sourceChildField evaluates to A1. Therefore, the value of targetField is A1. To create the second myTargetList item, the mapping top/result/SourceDoc/mySourceList/sourceChildField evaluates to A2. Therefore, the value of targetField is A2.
Ancestor content mapping: To create the first myTargetList item, the mapping top/result/SourceDoc/documentID evaluates to ID001. When looking for the value of documentID, the containment relationship is taken into account. Because mySourceList is contained within a single document that has only a single documentID value, the mapping is unambiguous; and the value of targetDocumentID is ID001. The second myTargetList item has the same containment relationship. Therefore, the mapping top/result/SourceDoc/documentID valuates to ID001. Consequently, both target items have the same documentID value.
Child list mapping: Valid mappings always preserve containment relationships. Therefore, targetChildList must be mapped to a descendent list of mySourceList. Each child list has two items because the sourceChildList has two items in the input data.; To modify or create a containment relationship, add a transformation step, such as an HJoin step or a Union step, before the step that contains the mapping table.

Invalid mappings

The mapping table prevents you from creating ambiguous, invalid mappings. An ambiguous mapping occurs when you map an item that, when evaluated, returns multiple values. The following mappings are invalid:

Mapping the content child of a peer list to a child content item: When iterating on the first mySourceList and trying to evaluate the mapping top/result/SourceDoc/Peer-List/peerField, the two values peer1 and peer2 are returned. The containment relationship for the mySourceList item does not help to resolve which value should be returned. Therefore, the mapping is ambiguous and is not allowed.
Mapping content child of a descendent list to a child content item: When iterating on the first mySourceList and trying to evaluate the mapping top/result/SourceDoc/sourceChildList/sourceDescendentField, the two values A11 and A12 are returned. The containment relationship for the mySourceList item does not help to solve which value to return because both values are contained in the mySourceList. Therefore, this mapping is ambiguous and it not allowed.
Mapping peer list to a child list: List mapping can be ambiguous. When iterating on the first mySourceList and trying to evaluate the mapping top/result/SourceDoc/Peer-List, the mapping cannot determine whether to return the first or the second Peer-List item. Without a containment relationship between the items of Peer-List and mySourceList, the ambiguity cannot be resolved. Therefore, this mapping is invalid.

The following figures show the valid choices: