Designing a message map

You can use a message map to graphically transform, route, or update an external system. For best performance and capability, you must design it to include the most appropriate transforms.

Procedure

Consider the following guidance to design a message map:

Design the data model of your input and output message per the solution requirements.

The function of a message map is completely dependent on the data models that define the input and the output message structures of a map. At run time, the Graphical Data Mapping engine accesses the input message with the assumption that it conforms exactly to the provided input schema model. Additionally, it must account for all possible states of the data when executing the transformations that you have defined in the map against the data models. You might or might not have control over the data models in your solution. If you can influence the data model, these are some of the key points to consider:
1. If you are working with XML schema models, you must always enable schema validation when you are developing a message map. The schema validation ensures that the input message to the map matches the model that has been used to define the map, and prevents invalid mapping due to any mismatch.
  
  Validation is the process of checking the structure of a message, and optionally the values within, based on a description called a schema. The Mapping node relies on schema definitions, but it does not enforce them. If the input message does not conform to the schema being used, the output you expect to see might not be produced. During the development of your integration solutions, it is recommended that you enable validation. However, for other environments such as test or production, you should leave validation on only if your solution requires it, because of the extra processing involved. For more information, see Validating messages.
  
  If you are working with DFDL schema models, and the message has been received by an input node, the input to the map is validated by the DFDL parser. If the DFDL tree is constructed by other means, ensure that it is valid by running test serialize, which you can do by using a trace node.
  
  If you are working with JSON models, there is currently no internal support for JSON schema validation. Ensure that your message is valid by using an external tool.
2. Set the cardinality of each element in a data model to specific values whenever possible.
  
  When you define a logical model, you can configure the cardinality of each element by setting the minoccurs and the maxoccurs properties.
  
  Avoid, whenever possible, configuring maximum flexibility unless actually required. Only set minoccurs to 0, when an element needs to be optional. Only set maxoccurs above 1 if the element will actually repeat.
3. Define an element as nillable when you know that the application will need to handle out of bound value in the data.
Identify the type of message map.
1. Use a message map to graphically transform, route, and enrich a message. You can use a message map to modify data in a database system.
  
  For more information, see Message maps.
2. Use a submap to define a set of mapping functions that you can reuse in multiple message maps.
  
  For more information, see Submaps.
For example, the Mapping node invokes a map that deals with a message assembly. You can put the mapping for common parts of the message data into a submap to enable reuse.
Identify the input and output components to a message map.
- You can select an XML schema, DFDL schema, or message set to define the message body.
- You can choose any of the following message assembly components: the Properties tree, the local environment tree, or the environment tree.
- You can add database tables.
You should only include a component when you need to read data or write data:
- To read elements of an input component, add the component to the input message assembly only. The Graphical Data Mapping editor passes to the output the input component unchanged.
- To modify elements of an input component, add the component to the input message assembly and to the output message assembly. Then, define transforms between its elements.
- To initialize an input component, that is, to create a new component in your output message, add the component only to the output message assembly.
- To add an input component, add the component to the output message assembly and populate at least one field. The Graphical Data Mapping editor creates a new output structure containing the results of your transformations.
- To delete an input component from the input message, add the component to the output message assembly and do not set any field.
For more information, see Choosing a mapping action.
For each output element, identify the transform and the input elements required to calculate its value.

When the transformation of an element from input to output becomes more than just a simple Move, or type conversion (xs:type), you can call on the full set of standard XPath 2.0 operators and functions to manipulate the data as required.

The Graphical Data Map editor offers the XPath functions as transform types in the pick list as well as in the content assist (Ctrl-space) when you edit expressions and conditions.
Define a conditional expression for each transform to determine at run time whether the transform is applied or not.

For more information, see Defining an XPath conditional expression for a transform.
Use structural transforms to enhance the readability and maintenance of your map and, in some situations, reduce the runtime overheads of your map. Use the transforms If, Local Map or Submap, and For each to group transforms.
Using structural transforms has the following advantages:
1. You can define a conditional expression that determines whether a nested map is applied at run time. For example, if a set of child fields should only be mapped dependent on some attribute of the folder, place all the child elements inside an If transform. The nested mappings are executed only when the condition evaluates to true.
2. You can use a Local Map transform between the parent folders that are defined as optional (<code>minOccurs=0</code>) instead of mapping directly between child elements in the folders. By using a Local Map, you create a more efficient transformation because, by default, the nested mapping is executed only if the primary input is optional (minOccurs=0) and is available at run time. Alternatively, you can add your own condition, which can also use additional supplemental inputs.
3. When you use a Local Map transform, you can convert the map to a submap if the need for reuse comes at a later stage. You can use an action in the Graphical Data Mapping editor to re-factor the Local Map into a Submap.
4. You can use the Auto map wizard (automap) to create Move transforms to create mappings from input to output elements within structural transforms that are based on some correlation of the names of the input and output elements. By using the structural transform, the scope of the automap is reduced, which enables a better match to be achieved.
For more information, see Using nested maps.
When you need to process data, rather than just move it from source to target, use custom transforms to define specialized transformations.
From a performance point of view, it is recommended that you use XPath transforms or the Custom XPath transform as your first choice, then Custom Java. You can also use Custom ESQL.