Mapping your data by applying smart suggestions

When you add an action to a flow in App Connect Designer, you can use Mapping Assist to help you populate the fields for the action with mapped data from previous nodes. Mapping Assist generates smart suggestions that are the best matches for the target fields.

Note: Mapping Assist is available for use in the flow editor only if the feature was enabled when your App Connect Designer instance was created.

About Mapping Assist

Mapping Assist uses a pre-trained algorithm and mapping histories to suggest mappings for the fields in an action when you build a flow. Mapping suggestions are generated as soon as you add an action to a flow, and these suggestions identify output from previous nodes in the flow, which could possibly serve as input for the fields in the action.

Suggestions of the best possible matches (top suggestions) can be automatically inserted into fields with a single click. These top suggestions are estimated to have an 80% or higher level of accuracy or relevance, and the count (N suggestions) identifies the total number of fields that will be populated with mappings.

Simple one-to-one field mapping

In any fields that remain unpopulated, you can click to check for suggested mappings. If found, these mappings are shown in a Suggested mappings list, which displays up to five suggestions with assigned percentage matches with a 30% threshold. For each mapping, the field hierarchy identifies the origin of the content, such as the application or node name, action, and object; for example, Salesforce/Retrieve contacts/Contacts, Request filter parameters/Object/where, BigCommerce/Update order/orders, and For each: Parsed CSV row.

Simple one-to-one field mapping

Techniques applied for matching

To identify matches, Mapping Assist uses a pre-trained algorithm that applies fuzzy matching and semantic rules, as well as mapping histories that are stored for started flows.

Mapping Assist algorithm techniques for estimating matches

The Mapping Assist algorithm currently provides mapping suggestions for simple (unnested) fields, and navigates parent hierarchy structures to suggest the best possible matches for nested fields.

Mapped nested fields

For nested array fields, Mapping Assist returns suggestions as follows:

  • Mapping suggestions are generated for exact schema matches, where the source array and destination array (schema structure and field names) are identical. For example, this would apply if you wanted to transfer data across two separate instances of an application for which you had set up separate App Connect accounts.
    Mapped array fields for exact schema matches
  • Mapping suggestions are also generated for an array of complex fields by using artificial intelligence (AI) modeling to identify the best possible matches that can be automatically inserted as top suggestions, or manually inserted at a field level.
    Mapping suggestions for complex array fields

If an action has multiple fields with the same or a similar name, a mapping that is identified as a top suggestion will be automatically inserted only into the field that is deemed to be the closest match. For example, if there are two fields called Email and Email adress, an Email mapping suggestion will have a higher level of accuracy associated with the Email field, and will be auto-inserted into that field only. If you want to populate any of the other fields with the same mapping suggestion, you must manually insert that mapping into the field.

The data types of the fields are also considered when suggesting matches; for example, source and destination fields with identical names, but different data types, are not considered a match. In the following example where JSON schema has been generated in the CSV parser, no mapping will be suggested for the Catalog ID integer field (123) because the source Catalog ID field in the generated schema is set to a string data type. If changed to integer, a suggested mapping with a 100% rating is expected between these two fields.

Simple one-to-one field mapping
Mapping history techniques for estimating matches

App Connect Designer instances in which Mapping Assist is enabled will collect and store your mapping data in an internal database by tracking the mapping history of any flow that you start. The sole purpose of the data collection is to preserve mapping selections between source and destination nodes so that they can be learnt and presented as future mapping suggestions that reflect your personal preferences.

For example, if you have a started flow that includes an Insightly/Create lead/First name (destination) field, which is populated with mapped content from a Salesforce/Retrieve contact/First name (source) field, this mapping is preserved and will be suggested with a 100% rating in any future flows that you develop with these two applications if the same actions and node order apply.

The following rules apply:

  • Mapping histories are stored for one-to-one field mappings between application (connector) nodes. The Request, Response, and toolbox nodes are excluded.
    Simple one-to-one field mapping
  • Mappings that include multiple field selections, transformations, or JSONata functions are not stored. For example:
    Multiple field mappings
    Transformation field mappings
    JSONata field mapping
Note: The information collected by Mapping Assist is not used by any other App Connect Designer instance, or in any other capacity by IBM, and the mapping histories will be deleted when your App Connect Designer instance is deleted.

Applying mapping suggestions

If Mapping Assist is enabled, when you add an action to a flow, you'll see a Generating suggestions message (briefly) above the filter bar.

Generating suggestions for Mapping Assist

After all the potential mappings are discovered, the top N suggestions are shown next to an Insert suggestions link. (If multiple mappings with matching ratings of 80% or higher are discovered for the same field, those mappings are excluded from the top suggestions count to enable you to choose the best match. You can manually inspect these mappings and make a choice as described later.)

Total suggestions

To auto-populate the fields with the top suggestions, complete the following steps:

  1. Click Insert suggestions. Those fields are populated and the remaining fields remain blank.
    Fields populated with suggestions
    • Existing mappings are preserved in any fields that you might have manually populated before clicking Insert suggestions.
    • If multiple mappings with matching ratings of 80% or higher are discovered for the same field, that field will not be auto-populated. You will instead be expected to manually inspect such mappings to determine the best match for the data that you want to map, as described later.
  2. Hover over the mapping in each auto-populated field and check the tooltip to verify that the inserted data from the specified node is the best match.
    Checking the value for an inserted mapping

If you want to replace the mapping in an auto-populated field, you can do so as follows:

  1. Delete the mapping from the field. (When you delete the mapping, notice that its top suggestions count (N suggestions) is displayed again, and you can auto-populate the field again by clicking Insert suggestions. If you choose to add your own preferred mapping as described in the following steps, the count is removed and Insert suggestions is disabled.)
  2. Remove the focus from the field and then click within the field again to display the Suggested mappings list. Alternatively, click the Insert a mapping icon Insert a mapping icon to open the Available mappings list and then click Suggested mappings. Then choose another mapping:
    1. Inspect the mappings and then choose any one that you prefer. (You can view the percentage matches of these mappings by hovering over the rating icon Rating icon.)
      Checking the rating for a suggested mapping
    2. If you would prefer to choose from a wider range of mappings, click All mappings to switch to the Available mappings list, which displays all mappings from all the previous nodes in the flow. Expand the sections to locate and select your required mapping.
      Tip: From the Available mappings list, you can switch back to the Suggested mappings list by clicking Suggested mappings.
      Available mappings list

In any remaining fields that were not automatically populated, you can manually insert mappings into each field as follows:

  1. Click within the field.
  2. If suggested mappings are available for this field, the Suggested mappings list is immediately displayed. These mappings fall into two categories, and you can make a selection as follows:
    • Multiple mappings with the same percentage match: Inspect any such mappings to decide on the best match and then click the mapping that you prefer.
    • Mappings with individual percentage matches of 30% or higher: Inspect such mappings to decide on the best match and then click the mapping that you prefer.

    If you prefer to choose from a wider range of mappings, you can click All mappings to switch to the Available mappings list.

  3. If no suggested mappings are discovered for this field, click the Insert a mapping icon Insert a mapping icon to open the Available mappings list and then select your required mapping from one of the sections.

If no top suggestions are discovered for an action, or if suggested mappings are not discovered for any of the fields, the initial Generating suggestions message is replaced by a grayed-out Insert suggestions link when the discovery process completes.

Grayed-out Insert suggestions link

For either of these cases, you must manually select mappings by clicking within the fields:

  • If suggested mappings are available, you can use the Suggested mappings list to inspect and select mappings.
  • If no suggested mappings were found, you can use the Insert a mapping icon Insert a mapping icon to choose a mapping from the Available mappings list. Note that the Suggested mappings link will be grayed out in this list.
    Grayed-out Insert suggestions link
Tip: If an error is displayed because suggestions cannot be generated, see Troubleshooting Mapping Assist in App Connect Designer for help in resolving the error.