br40815_.htm |
Last updated Friday, 21 July 2017From WebSphere® Message Broker Version 8 onwards, you transform data graphically by using a message map. These maps are managed through the Graphical Data Mapping editor. You define your transformation logic by using XPath 2.0 expressions. You can also call Java methods, ESQL procedures, or complex XPath expressions by using specialized transforms such as the Custom Java, Custom XPath, or Custom ESQL transforms.
When you convert a legacy message map that includes handling for nilled elements, check how a message map handles NULL values. For more information, see Handling nulls in message maps.
In ESQL, a special NULL value is defined, and is distinct from empty. When you assign NULL to a named element, or set the element from the returned NULL value of a called ESQL function, you delete the element from the tree.
In a message map, the ESQL NULL produces an empty element, or an empty element with the xsi:nil attribute set when the element is defined as nillable in the model. Consequently, in some cases the output of the map might include unexpected empty elements that can cause processing problems, including XML schema validation violations. Such problems typically occur when an ESQL user-defined function that returns ESQL NULL in some conditions is called. To avoid these problems, add a condition to the Custom Transform to prevent it from being invoked if it would return NULL.
In an ESQL-based legacy message map, writing a NULL to an output element does not create the element. However, in the converted message map, this action can produce an empty element.
If the esql:coalesce call is in a valid form, and is converted without error, you must review and test the converted transform to ensure that it results in equivalent function.
If you convert a legacy message map that contains an eqsl:coalesce call that is not in a valid form, for example, esql:coalesce(esql:func($source/path/item1,$source/path/item2)) a Task transform is created with details of the error, and you must manually convert the eqsl:coalesce call to provide the equivalent function. For more information, see Managing conversion errors on converted legacy message maps.
Use the Assign transform to set literal values in output elements. The Assign transform uses a string representation, which is assigned to the relevant output element and so must be formatted according to its type. The property value does not need to be in quotation marks, as any quotation marks would be passed as part of the string value. To provide an explicitly typed value, use the xs:<type> Cast transform with no input wiring.
You could build expressions in the legacy message mapping editor that implied a type cast and used the underlying string value representation.
The Graphical Data Mapping editor uses XPath expression syntax and enforces strict typing. For example, testing a Boolean-typed element for the string literal value true would cause a type exception.
You can use the xs:<type> functions in your expressions to avoid these incorrect typing issues.
A legacy message map allows the use of Java methods with MbElement parameters types. The Graphical Data Mapping editor uses standard XPath expression execution and can only support Java methods with standard Java parameter types; see Defining a Java conditional expression for a transform.
A legacy message map does not require the user to be explicit when accessing mixed content text values from a complex type element in a condition expression.
The Graphical Data Mapping editor is based on standard XPath syntax, and requires the explicit use of /text() to signify that the mixed content text value is to be used. As a result, a converted map with a conditional expression that referenced mixed content text values might fail until the path expression is extended to add the missing /text().
The legacy message map editor did not correctly validate the typing of submap inputs. Users could edit the normal element path value of a submap input, and instead provide an untyped literal value.
The Graphical Data Mapping editor requires that all submap inputs are wired to an appropriately typed input element.
Some transformations require the use of the "For each index" counter value. The WebSphere Message Broker Version 6.1 and WebSphere Message Broker Version 7 message map provided the msgmap:occurrence function to obtain the current loop count. The Graphical Data Mapping editor provides a For loop counter variable which can be used to provide equivalent function. The name of this variable is fixed format $<For each primary input element name>-index can be obtained using content assist ctrl-space in the relevant "ForEach transform" Filter properties expression panel, or in the content assist in any nested transforms.
If your message is modeled in a message set, the message map requires the message set schema (.xsdzip file) to be deployed to run your message map. If your existing message set is used for text and binary formats only, you can deploy your message map with only a .dictionary file in the integration node archive (BAR). In this case, you must modify the message set to additionally set the XMLNSC domain support option, so it is added to a BAR with both a .dictionary file and .xsdzip file. If this option is not set, a warning is displayed in the Problems view, along with a quick fix action.
A submap can be invoked only from a top level message map, that is, a map consumed by a Mapping node.
If you use a Mapping node that includes XPath datetime, or Assign transforms to set the value of output elements that are defined as xs:date, xs:dateTime, or xs:time and you want the timezone included, you must set the environment variable MQSI_USE_TIMEZONE to any value.
Last updated Friday, 21 July 2017