Changes in behavior in message maps converted from legacy message maps

In IBM® App Connect Enterprise, 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.

Behavior changes during the development phase

Nulls behavior

When you convert a legacy message map (.msgmap) 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.

Mapping from missing inputs

In ESQL-based legacy message maps, writing a NULL to an output element did not create the element. However, in the converted message map, this action can produce an empty element.

When a legacy message map ran certain transforms, and the input data was missing, the input was set as NULL; therefore, no output element was created. In the converted message map, these cases can produce an empty output element:
  • For transforms that are completely self-defined (such as Move), and if the input and output elements are defined as optional (minOccurs=0), the converted message map handles the missing input element, and no output element is created.
  • If the output element is defined as mandatory, the element is created in order to conform to the schema model.
  • For transforms that are internally defined to produce some output value even if the input element is missing (such as Custom ESQL, Custom Java, or Submap), the converted message map cannot automatically handle the missing input element. In this situation, you can add a condition such as fn:exists($input) to prevent these transforms producing the empty output element.
Some transforms, such as the XPath fn:concat() function, require exactly one data value for each parameter. When you are using these types of function, be aware that the legacy .msgmap might have provided an empty string for a NULL or missing input; however, the new XPath based .map provides an empty sequence, which results in an XPath runtime error because a single data value has not been provided. To solve this problem, you can modify the parameter so that it is wrapped in an XPath coalesce expression, in the following form:
(( $input, '' )[1])
This coalesce expression causes the parameter to be set to one of the following values:
  • The first value from the "$input" element, if it exists
  • The empty string ", if the "$input" element is missing.

Limitations on the conversion of esql:coalesce calls

Because there is no XPath equivalent for ESQL NULL, you can convert esql:coalesce calls (that have multiple arguments) in a legacy message map only if all of the arguments of the call (except for the final argument) have one of the following three forms:
  • A simple source reference; for example, $source/path/item.
  • An expression without any source reference. For example, the following are valid arguments: 123, 'myString', esql:current-time(), or fn:string-length("some-text").
  • A function (other than esql:coalesce), whose arguments also have one of these three forms, and where no more than one argument includes a simple source reference. For example, the following are valid arguments: fn:current-date(), esql:func1(esql:func2($source/path/item)), orxs:int(fn:substring($source/path/item, 3, 5)).
Note: There is no limitation on the conversion of esql:coalesce calls that have a single argument, or on the final argument of an esql:coalesce call that has multiple arguments.

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.

Assigning literal values to output elements

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.

Literals in conditional expressions

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.

Java methods in conditional expressions

Legacy message maps allowed the use of Java methods with MbElement parameters types. The Graphical Data Mapping editor uses standard XPath expression execution and can support only Java methods with standard Java parameter types. For more information, see Defining a Java conditional expression for a transform.

Complex type text values in condition expression

A legacy message map did not require you 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().

Literals in submap calls

The legacy message map editor did not correctly validate the typing of submap inputs. You 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.

"For each index" counter variables

Some transformations require the use of the "For each index" counter value. The 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.

Explicit casting of variables in conditional expression

While using conditional expressions like the If transform, for complex expressions or when a return value from ESQL function was being compared with a variable, you could add explicit type casting in expressions using xs:<type>( $<var> ). An example of an If transform for checking the variable of DATE datatype: function:
isStartdate() =xs:date($test)

Behavior changes during the deployment phase

In IBM App Connect Enterprise, message maps can be deployed only as source. You must provide any of the following resources before deploying your solution:
  • For text and binary messages, you must provide the DFDL schema file or the message set that defines your input and output messages.
  • For XML messages, you must provide the XML schema files that define your input and output messages.

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 BAR file. In this case, you must modify the message set to additionally set the XMLNSC domain support option, so it is added to a BAR file 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.

Behavior changes at run time

  • In IBM App Connect Enterprise, the Graphical Data Mapping editor has a dedicated Java based run time. As a result, map execution benefits from full support for XPath 2.0 and Java JIT optimization, which offers increased reliability.
  • A message map can be invoked only from a Mapping node.

  • A submap can be invoked only from a top level message map, that is, a map consumed by a Mapping node.

  • The message map runs in the Java virtual machine of the integration node. You must ensure that the integration node is configured correctly. For more information, see Setting the JVM heap size.

Timezone handling

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.