AtlasMap User Guide

To use AtlasMap standalone, the main steps are:

What can you do with an AtlasMap .adm file?

The Syndesis open-source integration platform embeds AtlasMap. In a Syndesis integration, you add connections to applications that provide the data of interest to you. With connections in place, Syndesis offers an AtlasMap data mapper step. When you add a data mapper step, Syndesis displays the data mapper canvas with:

In other words, you do not import source and target data as you would in standalone AtlasMap. Likewise, when data mappings are complete, instead of exporting the mappings, you just click a button to indicate that you are done.

When Syndesis embeds AtlasMap, it does not display the icons for importing and exporting data.

The AtlasMap user interface displays source fields and target fields and you define the field-to-field mappings that you need.

An understanding of the different kinds of AtlasMap fields makes it easier for you to define the mappings you need. For the purposes of mapping, there are three field types:

For example, consider this sample XML instance document:

When you define a mapping that uses this XML instance document as the source data, you cannot know how many items will be in an order. However, the same mapping definition works for each transaction, regardless of the number of items in the order.

AtlasMap supports the following general types of mappings:

In a data mapping, you can apply a transformation to one or more fields. A transformation is a function that AtlasMap performs on the selected field. For example, suppose you select a source field and specify the Uppercase transformation. At runtime, AtlasMap converts the source field value to uppercase and inserts the uppercase value in the target field.

To apply a transformation, select a source or target terminal field, click Add Transformation in the Mapping Details panel on the right, and select the transformation.

You can apply different transformations to different fields in the same mapping.

In a one-to-one mapping, which maps one source field to one target field, it does not matter whether you apply the transformation to the source field or the target field. In a one-to-many or many-to-one mapping, consider what the target field value needs to be when you specify a transformation. For example, consider a many-to-one mapping that combines source fields for number, street, city, and state into one target address field. If you want the strings in the target address field to all be uppercase, select the target address field and apply the uppercase transformation. If only the state needs to be uppercase, select the source state field, and apply the uppercase transformation.

You can think of a source field transformation as performing pre-processing, while a target field transformation performs post-processing.

When you are mapping fields, you might find that a source data shape does not provide a value that a target data shape requires. In these situations, AtlasMap provides two alternatives for specifying source values that you can map to target fields:

For example, suppose that a target data shape defines a Layout field whose value must be HORIZONTAL or VERTICAL. The source data shape does not provide this field. You can create a constant. Specify HORIZONTAL or VERTICAL as the value and accept String as the data type. After you save the new constant, you can map it to the Layout target field.

The following table describes some of the AtlasMap icons:

There are also several toolbar buttons that allow you to choose what should be displayed, such as data types, sample data previews, and mapped or unmapped fields.

You can import a JSON schema file or a JSON instance file into AtlasMap. The procedure for importing each kind of file is the same. For example, the following JSON schema file, JSONSchema.json, defines properties for an Order object:

To import this file into the AtlasMap Source panel:

AtlasMap displays the fields in the Source panel:

.

You can import an XML schema file or an XML instance file into AtlasMap. The procedure for importing each kind of file is the same. For example, the following XML schema file, XMLSchema.xml, defines a schema for transactions related to pets:

To import this file into the AtlasMap Target panel:

AtlasMap displays the fields in the Target panel. In the following image, the fields are expanded to show more detail.

AtlasMap can import a Java archive file and display mappable fields in either the source or target panel. In the data mapper, each class-wide public entity in a class file that is in the imported JAR file becomes a mappable field.

Arrays and data types are more discretely defined.

Consider the following two files:

To import these files:

In a relatively simple integration, mapping data fields is easy and intuitive. In more complex integrations or in integrations that handle large sets of data fields, mapping from source to target is easier when you have some background about how to use the data mapper.

The data mapper displays two columns of data fields:

To quickly find the data field that you want to map, you can do any of the following:

The default mapping behavior maps one source field to one target field. For example, map the Name field to the CustomerName field.

In a data mapping, you might need to identify missing or unwanted data when a source or target field contains compound data. For example, consider a long_address field that has this format:

number street apartment city state zip zip+4 country

Suppose that you want to separate the long_address field into discrete fields for number, street, city, state, and zip. To do this, you select long_address as the source field and then select the target fields. You then add padding fields at the locations for the parts of the source field that you do not want. In this example, the unwanted parts are apartment, zip+4, and country.

To identify the unwanted parts, you need to know the order of the parts. The order indicates an index for each part of the content in the compound field. For example, the long_address field has 8 ordered parts. Starting at 1, the index of each part is:

In the data mapper, to identify apartment, zip+4, and country as missing, you add padding fields at indexes 3, 7, and 8. See Separating one source field into multiple target fields.

Now suppose that you want to combine source fields for number, street, city, state, and zip into a long_address target field. Further suppose that there are no source fields to provide content for apartment, zip+4, and country. In the data mapper, you need to identify these fields as missing. Again, you add padding fields at indexes 3, 7, and 8. See Combining multiple source fields into one target field.

In a data mapping, you can combine multiple source fields into one compound target field. For example, you can map the FirstName and LastName fields to the CustomerName field.

For the target field, you must know what type of content is in each part of this compound field, the order and index of each part of the content, and the separator between parts, such as a space or comma. See Example of missing or unwanted data when combining or separating fields.

In a data mapping, you can separate a compound source field into multiple target fields. For example, map the Name field to the FirstName and LastName fields.

For the source field, you must know what type of content is in each part of this compound field, the order and index of each part of the content, and the separator between parts, such as a space or comma. See Example of missing or unwanted data when combining or separating fields.

In the data mapper Source and Target panels:

To toggle the display of data types, such as (COMPLEX), STRING, INTEGER, click in the toolbar.

The following table shows the default behavior when mapping between collection fields and non-collection fields.

When you map from a collection field to a non-collection field, the default behavior is that the target field gets its value from the last element in the source collection. You can change this default behavior in the following ways:

When you map from a non-collection field to a collection field, the default behavior is that the target collection contains one element, which contains the non-collection, source field value. You can change the default behavior when the source field contains a series of values that are separated by the same delimiter. For example, consider a non-collection, source cities field that contains:

Boston Paris Tokyo

You would map this to a target collection or to a target field that is in a collection. On the source cities field, add the Split transformation. During execution, the data mapper splits the value of the cities field at the space delimiter. The result is a collection that contains three elements. In the first element, the value of the city field is Boston. In the second element, the value of the city field is Paris. In the third element, the value of the city field is Tokyo.

In the data mapper, after you define a mapping, you can transform any field in the mapping. Transforming a data field defines how you want to store the data. For example, you could specify the Capitalize transformation to ensure that the first letter of a data value is uppercase.

Descriptions of available transformations

In some integrations, it is helpful to add conditional processing to a mapping. For example, suppose that you are mapping a source zip code field to a target zip code field. If the source zip code field is empty, you might want to fill the target field with 99999. To do this, you would specify an expression that tests the zip code source field to determine if it is empty, and if it is empty, inserts 99999 into the zip code target field.

The data mapper supports expressions that are similar to a Microsoft Excel expressions, but does not support all Microsoft Excel expression syntax.

You can define zero or one condition for each mapping.

The following procedure gets you started with applying conditions to mappings. As you work with mappings and conditions, you can perform the required steps in the order that is most convenient for you.

During execution, if the data mapper determines that the lastName field is empty, it maps only the firstName field to the target customerName field. If the lastName field contains a value, that is, it is not empty, the data mapper concatenates the values in the source orderId and phone fields, and inserts the result in the customerName field. (This example shows how the logic works, but it is probably not a useful example because when there is a value in the lastName field, you most likely want the data mapper to simply perform the mapping and not map some other value into the target.)

+ For this example, after you complete entering the expression, the data mapping is:

+

+ In the conditional expression, if you remove a field name that is in the mapping that the expression applies to, the data mapper removes that field from the mapping. In other words, every field name in the mapping must be in the conditional expression.

While you are using the data mapper UI, you can view the mappings that are already defined. This lets you check whether the correct mappings are in place.

The data mapper canvas is visible.

The following table describes the available transformations. The date and number types refer generically to any of the various forms of these concepts. That is, number includes, for example, integer, long, double. Date includes, for example, date, Time, ZonedDateTime.

In addition to the built-in transformations, you can define custom field action transformations. Write custom field actions in Java and then import them into the AtlasMap data mapper. After it is established in a source or target panel, the transformation appears in the list of transformations that are available for any field.