Submaps

You can use a submap to use the same mapping transformation in multiple message maps.

You use submaps to define a set of mapping functions that you can reuse in multiple message maps.

A submap transform references another map. It calls or invokes a map from a separate file, which can be stored in a library, an application, an integration service, or an Integration project.

A submap can contain components of the message body only, such as global elements and global types. A submap does not contain Properties, message headers, or the Local Environment tree. The elements or types that define the input and outputs of a submap must be defined as globals in an XML or DFDL message model. You cannot use user-defined elements as a submap input or output unless it is defined using a global type in an XML or DFDL schema. You cannot use a JSON data element defined from a JSON schema, or REST API swagger document, as a submap input or output.

For more information, see Creating a submap.

When you use submaps, you must consider the following behavior:
  • You can only use a submap to define transformations between DFDL or XML global elements or global types.
  • A submap cannot be used to transform local anonymous complex types, that is, xs:any elements.
  • A submap can be placed in any project that is visible to the main map that calls the submap.

Editing a submap

You edit a submap transform in the Graphical Data Mapping editor.

The Graphical Data Mapping editor saves submaps as .map files.

For more information, see Graphical Data Mapping editor.

Input and output data to a submap

To configure the inputs and the output to a submap transform, you connect one or more inputs, and a single output.

The input and output message data for a submap must be defined by a user-provided message model in a schema file.
Note: You cannot use submap transforms with input or output from the following places:
  • A user-defined element, unless its type is set to a global type in a DFDL or XML schema.
  • A JSON data type defined in JSON schema or a REST API swagger document.

You must have message models for any messages that you want to include in a mapping. You can select the message model from your existing message models in your application, integration service, or library when you create a message map. The mapping facility supports message models that are provided in DFDL schema and XML schema files, REST API swagger 2.0 documents, JSON schema draft 4, or MRM message sets.

In a message map, input and output objects are defined by reference to message models. They provide a definition of the message structure and type through the following components:
  • Simple elements and attributes, which define the type, range, and default values
  • Complex elements, which build the structure of the message
  • Repeating simple or complex elements
  • Other (embedded) messages

If your message model includes wildcards (xsd:any), you can use a Cast function to redefine these data elements to a global type or element from any message schema in your application. For more information, see Casting elements in a message map. You can also define dynamically a wildcard by adding user-defined elements.

Mapping operations

You can use any of the following transforms to map graphically your data in the Graphical Data Mapping editor:
  • Core mapping transforms: You can use built-in structural and functional mapping operations to graphically construct the required message transformations to build the output message.
  • Custom transforms: You can use custom transformations to define specialized transformations in XPath 2.0, Java™, or ESQL functions.
  • XPath functions (fn:functionName): You can use XPath 1.0 and XPath 2.0 functions to transform data in a message map.
  • Database transforms:
    • You can use the Select transform to query one or more database tables, and retrieve data that you can use in the message map. You can use the data to set output element values, define conditions, or use it as input to build other transforms conditions. Database tables can be set as extra outputs of a message map.
    • You can use a database routine transform to call a stored procedure from a database, and retrieve data. You can use the data to set output element values, define conditions, or use as input to build other transforms conditions.
      Note: For information about the support for stored procedures, see Support for stored procedures.
    • You can use the Insert transform to add one new row of data, or multiple rows of data, into a database table.
    • You can use the Update transform to modify a row of data, or multiple rows of data, in a database table.
    • You can use the Delete transform to delete a row of data, or multiple rows of data, in a database table.
  • Cast function: You can use the Cast function to cast schema types.

For more information, see Transforms (Mapping operations).

Creating a submap

A submap can be referenced from other message maps.

When you construct your transformation map, you create a submap to group part of the message transformation. The submap must be in a project visible to the main map that they are called from.

To create a submap, you define a Submap transform between the input object and the output object in your message map. The submap can then be used to enable reuse of common transformations for sections of, or the whole of, the message.

You can also refactor existing transform logic into a submap from a local transform, by using the context menu action.

For more information, see Calling a submap.

Reusing a submap

You can use a submap to reuse common data transformations.

You can reuse submaps in other solutions, and in other products that support graphical data maps.

Note: If you plan to reuse a submap across different products, read Guidelines for developing reusable graphical data mapping assets.