Mapping Headers and Payloads (Beta)

You can map header and payload values between your source and target systems when you create or edit a Micro-Integration. Mapping allows you to define the relationships between the data fields in your source system and the data fields in your target system.

If you don't map any source headers, their values are not propagated to the target headers. If you don't map any payload fields, the payload is passed through to the target unchanged.

The Mappings step is laid out with source constants, headers, and payload on the left, and target Smart Routing, headers, and payload on the right. This step allows you to: 

• map header fields, including custom headers, from your source directly to your target. For more information, see Mappings and Custom Headers.

• import JSON files to map fields between the payloads of your two systems, or to map fields between headers and payloads. For details, see Payloads.

• define constants so that you can use string, boolean, or numeric values in your mappings. For more information, see Constants.

• add transformation functions to your mappings to modify the source header or payload data so that it conforms to your target format. For more information, see Transformations.

• define a Smart Topic Destination using simple mappings or mappings with transformation functions. For more information, see Smart Topic Destinations.

For information about the headings that are available to map for each Micro-Integration, see the Message Header Reference.

Mappings

In the Mappings step, you can drag and drop fields from your source system to your target system to create associations between the two. You can map any of the following:

• Constants—You must have created the constant beforehand. For more information, see Mapping Headers and Payloads (Beta).

• Message headers—The header fields that are available depend on the external system you are using and whether your Micro-Integration is a source or a target type. For more information, see Custom Headers and the Message Header Reference.

• Payloads—These fields are available for mapping if you have imported a JSON sample of your payload. For more information, see Payloads.

You can:

• create a new mapping

• delete a mapping

If you want to change an existing mapping, delete it and recreate it.

Creating a Mapping

Perform the following steps to create a new mapping for either a source or target Micro-Integration:

1. If you haven't already, open your Micro-Integration and select the Mappings step.

2. In the Source or Target panel, hover over the required field until you see an arrow appear beside it.

3. Click and drag the arrow to the field that you want to map to in the other panel. A line appears between the fields as show below:

   

4. (Optional) Click Add Transformation to transform the data between the source and the target. For more information about adding a function, see Transformations. When you've finished adding a transformation, click Apply.

If you want to change the source or target fields for an existing mapping, delete it and recreate it.

Deleting a Mapping

When you delete a mapping, its transformation functions (if any exist) and any related mappings are also deleted.

Perform the following steps to delete an existing mapping:

1. If you haven't already, open your Micro-Integration and select the Mappings step.

2. In the mappings area, click the mapping you want to delete to select it.

3. Click Delete .

   

4. If your mapping has transformations, a confirmation dialog appears that lists the affected functions and mappings. Click Delete to confirm.

Custom Headers

You can optionally add custom header fields to map headers in your source data that are not detected automatically.

To add a custom header, perform the following steps:

1. If you haven't already, open your Micro-Integration and select the Mappings step.

2. In the Source panel, click Add Header.

3. In the Header Name field, type the name of header.

4. In the Data Type list, select one of the following data types:

   • String—A alphanumeric value that can be up to 255 characters in length.

   • Boolean—A value of True for False.

   • Integer—A numeric value.

5. Click Add.

To edit or delete an existing custom header, click the custom header to select it, then click either Edit to make changes, or Delete to delete the header.

Constants

Optionally, you can create static values called constants. Constants allow you to include unchanging values in the mappings between fields, which may be useful for testing or for including as part of a transformation on an incoming value.

Perform the following steps to create a constant:

1. If you haven't already, open your Micro-Integration and select the Mappings step.

2. In the Source panel, click Add Constant.

3. In the Data Type list, select one of the following data types:

   • String—A alphanumeric value that can be up to 255 characters in length.

   • Boolean—A value of True for False.

   • Integer—A numeric value.

4. In the Constant Value field, enter the value for the constant.

5. Click Add.

To edit or delete an existing constant, click the constant to select it, then click either Edit to make changes, or Delete to delete the constant.

Payloads

You can import a sample of your message payload to allow you to map payload fields. If you don't map any payload fields, the payload passes through unchanged from source to target. If you map payload fields, any unmapped fields are dropped.

Your sample payload must be well-formed JSON comprising a single record; an example is shown below:

{
    "orderId": "DC-78901",
    "orderDate": "2024-10-30T13:35:00Z",
    "status": "Ready for Pickup",
    "items": [
        {
            "sku": "WH-001",
            "name": "Wireless Headphones",
            "quantity": 2,
            "location": "A3-B12"
        },
        {
            "sku": "PC-002",
            "name": "Phone Case",
            "quantity": 5,
            "location": "B2-C07"
        }
    ],
    "shippingAddress": {
        "name": "Jane Smith",
        "street": "789 Pine Lane",
        "city": "Warehouse City",
        "state": "WH",
        "zip": "54321"
    },
    "shippingMethod": "Ground",
    "priority": "Standard",
    "estimatedShipDate": "2024-10-31",
    "notes": "Fragile items. Handle with care."
}

You can import payloads for your source system, target system, or both:

Perform the following steps to import a sample of your payload: 

1. If you haven't already, open your Micro-Integration and select the Mappings step.

2. In the source or target Payload panel, click Import From File. The Import Source Payload dialog opens:

   

3. In the Import Source Payload dialog, either drag and drop a file or click Upload File to select a file from your computer.

4. Click Import. The payload fields appear in the Payload panel.

   

5. If required, repeat these steps in the other (Source or Target) panel.

To make changes or to import a different file, in the source or target Payload panel, click Re-Import.

Transformations

Transformations allow you to modify the message headers and payloads as they flow through your Micro-Integration. You can use transformations to make simple changes such as converting a string value to uppercase, or to perform more complex operations, such as combining several values together, or extensively altering the incoming payload to conform to a target schema.

For more information about the functions that are available to use in transformations, see the Transformation Function Reference.

Adding a Transformation

Perform the following steps to add a transformation:

1. If you haven't already, open your Micro-Integration and select the Mappings step.

2. Create a new mapping or select an existing one.

3. Click Add Transformation.

4. In the Transformation Details dialog, in the Transformation list, select the function you want to use.

5. Verify that the fields you want to use are shown correctly, and make any changes you need to.

6. Click Apply. The mapping now shows that there is a transformation associated with it:

   

To edit a transformation, click its mapping to select it, then click Edit Transformation.

To delete a transformation, you must delete the mapping and recreate it.

Smart Topic Destinations

A Smart Topic is a destination (queue, topic, or other third-party specific destination) that is dynamically determined based on data coming from your source. You can map any constant, header, or payload field to a Smart Topic Destination. You can also use transformations to build expressions for Smart Topic Destinations. For example, you could assemble a Solace topic from a number of fields and constants. The destination must already exist on the target system.

Example: Build a Smart Topic Destination

In this example, we'll build a Solace topic for order creation using a constant and a payload field.

We start with a source Micro-Integration where we have imported the format of our payloads, in this case, order data. Our order payload data includes an orderId field. We want to use this field to build a topic that has the form order/create/{orderId}.

To create our mapping, we do the following:

1. Add a constant that represents the beginning portion of our topic. In this case, we create a String constant with the value order/create/.

2. Map this new constant to the Smart Topic Destination, as shown:

   

3. Click Add Transformation to build the topic expression by completing the following steps:

   1. From the function list, choose the Concatenate function

   2. Select the new constant, order/create/, and the orderId field as inputs, ensuring that the constant is selected as Input 1, and orderId is selected as Input 2, as shown here:

      

   3. Click Apply.

The new transformation appears in the mapping area: