Data Mapping task

You're viewing Apigee X documentation.
View Apigee Edge documentation.

The Data Mapping task lets you perform variable assignments in your integration. Use this task to map the output values of a task to another task's input values, as shown in the figure below:

image showing data mapping of string variables

The Data Mapping task lets you perform variable assignments in your integration. The variables can be integration variables or task variables. For example, you can assign values from integration variable X to a task variable Y or from a task variable Y to integration variable X. For more information about variable types, see Using variables in Apigee Integration.

Configure the Data Mapping task

To configure the Data Mapping task:

  1. Go to the Apigee UI and sign in.
  2. Select your organization using the drop-down menu in the upper left corner of the UI.
  3. Click Develop > Integrations.
  4. Search for or select the integration to edit from the Integrations list and click to open the integration designer.
  5. Click Add a task/trigger > Tasks to view the list of available tasks.
  6. Drag the Data Mapping element to the integration designer.
  7. Click the Data Mapping element on the designer to open the Data Mapping configuration pane.

The following image shows the layout of the Data Mapping Editor:

image showing data mapping editor

Add a mapping

To add a mapping, perform the following steps:

  1. Click Open Data Mapping Editor.

    The Data Mapping Editor lets you map input variables to the output variables, using the available transformation functions. The output is then available as a variable to any other integration task or trigger. For more information about passing data as variables, see Using variables in Apigee Integration.

  2. Configure the Input and Output columns:
    1. Drag a variable from the left-hand variable list into the Input column.
    2. Alternatively, click enter a value to input a literal or reference value.
      • Enter an initial value (of type string, integer, double, or Boolean) or choose an existing variable.
      • To choose an existing variable, type an existing variable name into the search field.
      • To create a new variable, click + Add new variable to enter the name and data type of the new variable.
      • Click Done.
    3. Click + Add function on any input variable to view the list of available transform functions.

      The Data Mapping task lets you apply a number of data mapping functions to transform the data in the input variable.

      To remove or delete the most recently added function, click the - symbol.

    4. Drag a variable from the right-hand variable list into the Output column. If the variable is not available, click + Add new variable to configure the name and data type of the new variable. Optionally, you can select whether to use the variable as an output of the integration, or as an input to another integration, as shown in the image below:

      image of variable config pane

  3. To remove a variable, click the x icon on the variable pill.
  4. To delete a mapping row, click Delete this mapping.
  5. Once your mapping is complete, close the pane. Any changes will be autosaved.

The completed data mapping is available to view from the Integration editor, by clicking on the Data Mapping element, as shown in the figure below:

image showing data mapping editor

Supported data types

Apigee Integration supports the following data types for variables in the Data Mapping task:

  • Strings and String arrays
  • Integers and Integer arrays
  • Doubles and Double arrays
  • Booleans and Boolean arrays
  • JSON
The following table lists the data mapping functions available for each of the data types.
Data type Supported mapping functions
Boolean AND, EQUALS, NAND, NOR, NOT, OR, TO_JSON TO_STRING, XNOR XOR
Boolean array APPEND, APPEND_ALL, CONTAINS, GET, REMOVE, REMOVE_AT, SET, SIZE, TO_JSON, TO_SET
Double ADD, DIVIDE, CEIL, EQUALS, EXPONENT, GREATER_THAN, GREATER_THAN_EQUAL_TO, FLOOR, LESS_THAN, LESS_THAN_EQUAL_TO, MOD, MULTIPLY, ROUND, SUBTRACT, TO_JSON, TO_STRING
Double array APPEND, APPEND_ALL, AVG, CONTAINS, GET, MAX, MIN, REMOVE, REMOVE_AT, SET, SIZE, SUM, TO_JSON, TO_SET
Integer ADD, DIVIDE, EQUALS, EXPONENT, GREATER_THAN, GREATER_THAN_EQUAL_TO, LESS_THAN, LESS_THAN_EQUAL_TO, MOD, MULTIPLY, SUBTRACT, TO_DOUBLE, TO_JSON, TO_STRING
Integer array APPEND, APPEND_ALL, AVG, CONTAINS, GET, MAX, MIN, REMOVE, REMOVE_AT, SET, SIZE, SUM, TO_JSON, TO_SET
JSON APPEND_ELEMENT, FLATTEN, GET_ELEMENT, GET_PROPERTY, MERGE, SET_PROPERTY, SIZE, TO_BOOLEAN, TO_BOOLEAN_ARRAY, TO_DOUBLE, TO_DOUBLE_ARRAY, TO_INT, TO_INT_ARRAY, TO_STRING, TO_STRING_ARRAY
String CONCAT, CONTAINS, EQUALS, EQUALS_IGNORE_CASE, LENGTH, REPLACE_ALL, SPLIT, SUBSTRING, TO_BASE_64, TO_BOOLEAN, TO_DOUBLE, TO_INT, TO_JSON, TO_LOWERCASE, TO_UPPERCASE
String array APPEND, APPEND_ALL, CONTAINS, GET, REMOVE, REMOVE_AT, SET, SIZE, TO_JSON, TO_SET
For more information on each of data mapping function, see Data Mapping Functions Reference.

Retry on failure

You can configure various retry strategies to handle errors in a task. The retry strategies allow you to specify how to rerun the task in case of an error. For more information, see Error handling strategies.

Best practices

Using the Data Mapping task can be a powerful way to transform and pass key variables to various tasks in your integration. Here are a few tips to keep in mind as you build your integration:

  • Mappings are run in sequence from top to bottom. That is, if input variable A is mapped to an output variable B in the first row, the variable B is available for mapping in the subsequent rows.
  • In each row, the data type of the Input column must match the data type of the Output column. To cast between types, use transformation functions such as TO_STRING, TO_INT, etc.
  • There are no limitations on the length of transformation chaining. However, debugging large chained transformations can be difficult. We recommend keeping input transformations readable and splitting complex transformations into multiple mappings.
  • If a mapping requires a fallback value, set a fallback value for the mapping. If you do not provide a fallback value, the mapping returns an error when the input value or transformation returns null.
  • When deleting a variable, make sure to delete any mapping that contains it.

Considerations

We do not recommend using the Data Mapping task to loop over arrays. Instead, create a variable representing an element of the array and then map each subsequent element in a sub-integration. You can call the resulting sub-integration using one of the following tasks: