Graphical Mapping overview

Graphical data maps offer the ability to achieve the transformation of a message without the need to write code. You can use a message map, a submap, or a local map. To define the input and output messages to a map, you can use an XML, JSON, or DFDL schema message model, which defines the structure of the data and provides information about the data type, or you can define it dynamically in the map by using the Add user defined function.

Message maps

A message map is the IBM® App Connect Enterprise implementation of a graphical data map. It is based on XML schema and XPath 2.0 standards, with additional support for JSON schema draft 4 and Swagger 2.0.

A message map offers the ability to achieve the transformation of a message without the need to write code. It provides a visual image of the transformation, and simplifies its implementation and ongoing maintenance.

You can 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. You can use drag actions to make connections, select transforms, and build logic to transform your message data without programming.

For more information, see Message maps.

Defining a map input and output

To enable graphical transformation, you must provide a model of the data so that the Graphical Data Mapping editor can display it. You can use an XML, JSON, or DFDL schema message model, or you can define a model dynamically in the map by using the Add User-Defined function. Predefined models are also provided for SOAP and BLOB message types. You can also transform data from other parts of the IBM App Connect Enterprise message assembly, including the Properties folder, the Environment, the Local Environment, and transport headers, such as HTTP or MQMD.

For more information, see Message maps.

Submaps

A submap is a reusable form of message map.

You use a submap to reuse common data transformations. You define in the submap the mapping functions that transform a set of elements from the input object to the output object.

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

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

For more information, see Submaps.

Local maps

A local map is a subset of data transformations between input elements and output elements that are part of a message map. You define a local map by creating a Local map transform in a message map.

A local map is not an independent resource. There is no physical file that is associated with a local map.

The scope of a local map is the message map. A local map is processed with the message map.

Local maps provide a way of breaking up a large message map into nested groups of mapping elements.

You can use local maps to simplify the overall message map presentation. You can structure complex data transformations into nested groups that are easier to manage and implement.

For more information, see Local map.

Legacy message maps

A legacy message map is a message map that was created as a .msgmap file in earlier versions of WebSphere® Message Broker (for example, in WebSphere Message Broker Version 7).

IBM App Connect Enterprise uses graphical data maps in .map format, which were introduced in WebSphere Message Broker Version 8. These message maps replace the previous message maps that were in .msgmap format.

Before you can use a legacy message map in IBM App Connect Enterprise, you must convert it into a message map, as described in Using or converting legacy resources into message maps.

Choosing a type of graphical data map

Use the following table to identify the type of map that you must create when you transform data graphically in the Graphical Data Mapping editor:

Table 1. Types of map based on design requirements
  Recommended use Type of resource Supported in IBM App Connect Enterprise
Message map Graphical data mapping .map file Yes
Submap (See notes below.) Reuse of common data transformations .map file Yes
Local map Reduce complexity when you read and manage a message map No file. It is embedded within a Message map Yes
Legacy message map Reuse of maps that are developed in earlier versions of IBM App Connect Enterprise .msgmap file These files must be converted into .map files before they can be used in IBM App Connect Enterprise. (See notes below.)
Notes:
  1. Legacy message maps must be converted into .map message map format before they can be deployed or modified by IBM App Connect Enterprise.
  2. Submaps are not supported for use with JSON schema models.
Note:

Editing a graphical data map

You edit a message map or a submap in the Graphical Data Mapping editor.

The Graphical Data Mapping editor saves message maps as .map files.

For more information, see Graphical Data Mapping editor and Editing message maps.

Mapping operations

You can use transforms to map graphically your data in the Graphical Data Mapping editor.

For more information, see Transforms (Mapping operations).

XPath

In the Graphical Data Mapping editor, you can use XPath functions in any of the following ways:
  • You can define an XPath function to transform data by using a built-in XPath transform. For more information, see Built-in XPath transforms.
  • You can define complex XPath expressions that combine multiple XPath functions to transform data by using the Custom XPath transform. For more information, see Custom XPath.
  • You can define XPath expressions to set a condition on a transform or to filter an element in a repeating element. For more information, see Defining an XPath conditional expression for a transform.
  • You can use XPath inline when you specify an argument to an XPath function. For more information, see Built-in XPath transforms.

Built-in IBM App Connect Enterprise functions

You can use built-in IBM App Connect Enterprise functions to retrieve Integration Bus data and perform data-type conversion and formatting. The iib: functions are available through content assist in the Custom XPath transform. For more information, see Transform types in the Graphical Data Mapping editor