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
driven by the data models that define the input and the output message
structures of a map. At run time, the Graphical Data Mapping engine must account for
all possible states of the data when executing the transformations
you have defined in the map against the data models. You may have
control or not over the data models in your solution. If you can influence
the data model, these are some of the key points to consider:
- 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.
- Define an element as nillable when you know that the
application will need to handle out of bound value in the data.
- Enable schema validation when
you are developing a map. Disable validation in your test and production
systems unless the solution requires validation enabled.
Validation
is the process of checking a message’s structure, 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 only
leave validation on if your solution requires it because of the extra
processing involved.
For more information, see Validating messages.
- Identify the type of message map.
- 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.
- 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:
- 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.
- 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 the nested mapping is used only if the parent
folders are present at run time
- 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.
- 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.
- Custom XPath
- Custom Java
- Custom ESQL
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.