Mapping your data by inserting references

When you add an action to your flow, you need to specify data for any required target fields for the action (or invoked API operation) to be performed. You can map data from preceding nodes in the flow by inserting references to source fields in those nodes.

In each field of an action (or invoked API operation), you can add a reference to source fields in preceding nodes in the flow to have the value of those fields passed to a target application.

In the following example, an action has an Email Address field. A reference has been inserted to an Email field of a preceding node in the flow. When the flow runs, it adds Jane Doe@email.com to the required target field Email Address if the value of the source field Email is Jane Doe@email.com (the source application must pass such a valid email address).

Figure 1. Target field containing Email source field reference
Target field containing Email source field reference

To add a reference to a source field, click in the target field. This displays the Insert a mapping icon Icon to map a field from earlier node in a flow next to the field.

  1. If you start typing the name of a source field (like email) and then pause briefly, App Connect offers you choices for fields based on what you are typing. Alternatively, you can click the "Insert a mapping icon" to see the full choice of fields that you can insert.
  2. You can select fields from the event or from previous target applications in the flow. For example:
    Choice of fields from an Eventbrite event and Salesforce acion

    (Click image to view full size)

In each required field for the target application, ensure that you provide a value as needed by the target application. If you map the name of a source field, you should ensure that the source application will pass a suitable value; otherwise, if a value passed is invalid the flow can't complete successfully. In your flow, you can use conditional logic to do something appropriate if a value passed is invalid.

Tip: If a field name is truncated, hover over the field name to display the full name.
Figure 2. A required field with truncated name and mouse pointer used to show full name
A required field with truncated name and mouse pointer used to show full name
Tip: For information about the data relating to specific applications, go to the "How to" guides for apps page and click the "How to" link for that app.

Behavior of mappings that evaluate to null or undefined in fields of type string or date-time

Depending on your source data, it is possible for the source mapping in a target field of type string (String icon for a field) or date-time (Date-time icon for a field) to evaluate to a null or undefined value (equivalent to having no value) when a flow runs. If this happens, the null or undefined input value is retained and reflected in the resulting output when the mapping is evaluated.

For example, consider a Salesforce Create lead action, which creates a lead by using contact details from another system. In the First Name target field for this Salesforce action, a mapping is inserted to set the new lead's first name to the contact's first name.

Example of a source mapping in a target field

If the inserted First Name mapping evaluates to null or undefined at runtime, the null or undefined value is honored as the input for First Name and is reflected in the output. The following examples depict "null" and "undefined" inputs for a First Name field (together with valid Last Name and Company inputs), and the respective outputs when the Try this action feature Try this action icon is applied to the Salesforce Create lead action. Each output in this example also includes the lead ID, which Salesforce generates whenever a lead is created.

Input Output

First Name = null

Sample null input

Sample null output

First Name = undefined

Sample undefined input

Sample undefined output
Exception: This behavior for null or undefined mappings is reflected in all actions except for these:
  • The if condition for an If node
  • The filter condition for any Retrieve, Update, Update or create, Delete, or Batch process action


Previous behavior in App Connect Designer (in a containerized environment) and App Connect on IBM Cloud

In App Connect Designer 12.0.2.0-r1 or earlier, and prior to November 2021 on App Connect on IBM Cloud, if the source mapping in a target field of type string or date-time evaluated to a null or undefined value, the output of the mapping was set to "" (that is, an empty string), as shown in the following table.

Input Output

First Name = null

Sample null input


In JSON format, First Name = null is represented as follows:

{
  Trigger: {
    profile: {
      first_name: null
    }
  }
}

Sample null output


In JSON format, First Name = null and First Name = undefined are both represented as follows:

{
  FirstName: ""
}

First Name = undefined

Sample undefined input


In JSON format, First Name = undefined is represented as follows:

{}
Note: In later Designer versions, any previously authored flows with a single source mapping that evaluates to null or undefined will no longer show "" (an empty string) as the output value, but will instead show the null or undefined value. This change will affect all flows in a Stopped or Started state, and all mappings that are inserted in target fields (of type string or date-time) for an action.

If you want to retain the existing behavior in later Designer versions because you rely on a mapping to always output "" (an empty string) when the input is null or undefined, you can update the target field mapping by using the following Boolean (JSONata) functions:

  • isNull(sourceMapping): Checks whether the evaluated input to the function is a null value, and returns true if it is.
  • isUndefined(sourceMapping): Checks whether the evaluated input to the function is undefined, and returns true if it is.

For example, suppose you want to ensure that the following First name mapping returns "" if the input is null or undefined.

Example of a source mapping in a target field

You can apply the isNull(sourceMapping) and isUndefined(sourceMapping) functions to the First name mapping as shown in the following example.

isNull and isUndefined functions in the Functions list

The completed JSONata expression is:

{{$isNull($Trigger.profile.first_name) or $isUndefined($Trigger.profile.first_name) ? "" : $Trigger.profile.first_name }}

Applying the isNull and isUndefined functions to a mapping

This JSONata expression will exhibit the following behavior: if the First name input is either null or undefined, set the mapping to "" (an empty string); otherwise, set the mapping to the value of the First name input.