Using Context in Message Mapping

A message mapping queue consists of all the values of a field in the data flow editor. This applies to source field, target fields, and any fields created by mapping steps. These queues are important tools for testing because you can display the source field values, target field values, and any other field values that the mapping step created in the message mapping as soon as test data is available.

You can perform message mapping at runtime using queues. A queue contains all the values that relate to a field in the message mapping. There is a queue for each XML hierarchy level. If you create an XML instance in the test environment editor, you can display the various queues in the data flow editor.

By using queues, you can process large XML messages quickly.

A Document Object Model (DOM) parser builds the entire XML tree for an XML file and uses excessive memory and CPU time. A queue uses a Simple API for XML (SAX) parser that only builds the values of a hierarchy level, resulting in faster processing.

If a source structure contains more than one instance of the same elements (occurrence > 1), the context of a queue can contain multiple values. As long as the input queues have the same number of values for each context, the way the values are processed is clear cut, as shown in the figure, Queues with Same Contexts.

In the figure, Queues with Different Contexts, the input queues for the concat function have a different number of values in the related contexts. If, for this reason, an input value from a queue is missing for a function, the mapping runtime simply uses the last value read from the queue.

The rule that applies to queues with different contexts also applies to generating functions, such as constants, which only generate one value when they are linked to a function. If an additional input queue has more than one value in a context, the mapping runtime reuses the last value that the generating function returned.

The context of a field is a description of the structure in which the field occurs. A field can contain multiple contexts if the field exists in a series of structure levels in a hierarchical manner. If a field is part of a structure that can have multiple occurrences (occurrences > 1), this is referred to as a context change for the field.

If a field occurs more than once (occurrence > 1) within one structure, this does not constitute a context change because the field occurs more than once within the same structure (context).

A context change within a hierarchy is shown in the relevant queue. For example, in the figure, Context Changes in XML Files, the field item occurs in the context of three nodes with the name A. This results in two context changes for the queue on the hierarchy level of the field item.

Complex Context Change – Example

The figure, Complex Context Change – Example, illustrates the concept of context change in more detail for a field person that uses the following contexts:

• flat

  In the context of the first flat, Fix and Foxy are the people who live there. There are four flats in total and therefore, three context changes.

• street

  In the context of the first street, Fix, Foxy, Jolly Jumper, and Lucky Luke are the residents. There are three streets in total and, therefore, two context changes.

• city

  In the context of the first city, Asterix and Obelix are also residents. There are two cities in total and, therefore, one context change.

• root

  In the context of the root element root, Valerian is also a resident. There is no context change in this context.

You can create and delete context changes with both standard functions and user-defined functions. This enables a direct influence on the hierarchy levels in the source message.

The figure, Impact of RemoveContexts() on Message Mapping, shows how the RemoveContexts() works in the following ways:

• Example 1

  In this example, only the values for the source field item of the first node header are used. The mapping program creates the corresponding item target fields, and the contents of the source fields are copied. In this case, the mapping stops for the item field at the first context change because node A can only occur once in this example.

• Example 2

  In this example, the context change is deleted by RemoveContexts(), which means the contents of all the item source fields are transferred to the queue without a context change. As a result, the transferred fields are all created as item target fields and their values transferred accordingly.

The figure, Impact of SplitByValue() on Message Mapping, shows how the function SplitByValue() works in the following ways:

• Example 1

  In this example, the SplitByValue() function is not used and therefore, four context changes are generated, as required. However, after the first context change, all four item source fields are saved as item target fields and then populated with the relevant strings.

• Example 2

  In this example, the SplitByValue(Each Value) function is used and the function results in a context change after each source field item. Every target field item appears in an individual context new_context.

You can set the context of source fields explicitly in the data flow editor by using the context menu.

The figure, Impact of Explicit Context Selection on the Message Mapping, shows the effect of explicit context selection on the sample message type TestContext. Depending on whether you select segment, parent, or TestContext as the context for the item source field, the queue has either 4, 1, or no context changes. Selecting a higher context level deletes the context changes located under this level. You can use this method to simplify the task of context selection for source fields and avoid multiple use of the standard function RemoveContexts() in the message mapping.

You can use the function RemoveContexts() in target field mappings that consist of function chains.

You can use the standard function exists() to determine whether a specific source field exists in the XML instance being processed. If it does, exists() returns true; otherwise, it returns false. This is useful, for example, if you want to map an optional source field to an obligatory target field. You can check whether the field (not the contents) actually exists and if necessary, transfer a constant instead.

For a field with an occurrence greater than zero (occurrence > 0), you can use the standard function copyvalue() to copy the individual values separately to multiple target fields.

If a source structure contains a field with the name addrDat and the field has three values, you can map these three values to the street, city, and zipcode target fields by using copyValue() and specifying an index, as follows:

• /ns0:MT_B/street=CopyValue(/ns0:MT_A/addrDat, nnumber=0)
• /ns0:MT_B/city=CopyValue(/ns0:MT_A/addrDat, nnumber=1)
• /ns0:MT_B/zipcode=CopyValue(/ns0:MT_A/addrDat, nnumber=2)

You can use the mapping editor to assign the fields of two XML structures to each other. Target structures do not exist at runtime. The mapping program creates target structures only during the execution of the mapping.

Whether the mapping program creates a particular field in the target structure depends on the number of occurrences of the field in the target structure and whether a target field mapping has been defined for this field.

The target field mappings required for fields in the target structure are as follows:

Target Structure Creation: A Simple Mapping Example

The figure, Target Structure Creation: A Simple Mapping Example, shows the mapping between source and target structures.

Target Structure Creation: Source Message

In the figure, Target Structure Creation: Source Message, an actual message from a sender system is used as the basis for creating target fields.

Target Structure Creation: minOccurs = maxOccurs = 1

In the figure, Target Structure Creation: minOccurs = MaxOccurs = 1, even though the MT_TargetMessage node has no target field mapping, the mapping program creates this node exactly once to match the number of occurrences specified.

Target Structure Creation: minOccurs = 0

In the figure, Target Structure Creation: minOccurs = 0, the number of occurrences of node B is between minOccurs = 0 and maxOccurs = unbounded. However, because a target field mapping is defined for node B, the mapping program creates it in the target structure as often as required, according to the source structure and target field mapping (in this case, three times).

Note

The attribute setting minOccurs > 0 for a field does not necessarily mean that the field will exist in the target message. Assuming that the field is part of a structure node with minOccurs = 0, and if no mapping is assigned to that structure, neither the structure nor the subordinate fields are created. In the example, this applies to node B and the field item.

Target Structure Creation: 0 < minOccurs < maxOccurs

In the figure, Target Structure Creation: 0 < minOccurs < maxOccurs, the number of occurrences for the target field item is between 1 and unbounded. In practice, however, this field cannot be created an infinite number of times. How often the mapping program creates this field depends on the corresponding source fields, how often they occur, and the relevant target field mapping.

You can use the mapping editor to debug all the steps in a message mapping by displaying the contents of the relevant queue. For each element in the data flow editor (both fields and functions), you can display the contents of the queue by choosing Display Queue from the context menu.

The message mapping in the figure, Message Mapping for the Target Field Description, shows an example of a more complex message mapping for the target field Description.

In this example, the source field LANGKEY is first compared with the constant EN. If this comparison is successful, the contents of the source field TEXT are copied to the target field Description. Based on the contents of the queue equalsS, the value [true] is only determined in the second case. This means that the content toothpaste is copied from the middle field TEXT to the target field Description. This result is represented in the queue for the IfWithoutElse element.

Debugging View for the Description Target Field Mapping

To debug message mappings, you need to display the queue. The result from each step of the message mapping is represented in such a way that you can examine the transformation from the source fields to the target fields in a step by step manner.

The displayed queue contains the following entries:

• Initial context change

  The first gray entry represents the initial change that is not part of the contents of the queue.

• Final context change

  The last black entry represents final context changes that are not part of the contents of the queue.

• Suppressed entries

  The two turquoise entries are the suppressed entries; they result from the [false] entries of the if part of the IfWithoutElse standard function.