Mapping your data by applying smart suggestions

Mapping assist uses a pre-trained algorithm and mapping histories to suggest mappings for the fields in the nodes that you add when building a flow.

About mapping assist

Mapping suggestions are generated as soon as you add a node 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 current node.

Above the filter bar, suggestions of the best possible matches (top suggestions) are indicated with a count (N suggestions), which identifies the total number of fields that will be populated with mappings. These top suggestions are estimated to have an 80% or higher level of accuracy or relevance, and, with a click, can be automatically inserted in inline preview mode into fields for review before being accepted.

Initial view of the count of top suggestions

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/Request body parameters/Object, and For each: Parsed CSV row.

Simple one-to-one field mapping
Availability: Mapping suggestions can be generated only for the following types of nodes within a flow:
  • Application (connector) nodes for actions
  • Response node (Supported only on App Connect Designer 12.0.4.0-r2 or later)
  • Set variable node (Supported only on App Connect Designer 12.0.5.0-r4 or later)


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 nodes.
    Simple one-to-one field mapping
  • Mapping histories are also stored for mappings that include multiple field selections, transformations, or JSONata functions. 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 with mapping assist

If Mapping Assist is enabled, when you add a node 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, a Preview button is displayed with a count of the top N mapping suggestions. (If using App Connect Designer 12.0.5.0-r3 or earlier, the top N suggestions are shown next to a View suggestions link Total suggestions.) 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


Auto-populating fields with the top suggestions

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

  1. Click Preview N mapping suggestions to switch to inline preview mode, which inserts a preview of the suggested mappings into the matching fields. The remaining unpopulated fields are shown in a disabled state. (If using App Connect Designer 12.0.5.0-r3 or earlier, click View suggestions to switch to inline preview mode.)
    Fields populated with suggestions
  2. Examine each of the preview mappings to verify that the mapping is suitable for your requirements.
    • If unsuitable, you can clear the mapping from any field by clicking the Clear suggestion icon (x), and will be able to manually populate the field later with your preferred choice.
      Inserted inline preview with the Clear suggestion icon
      Tip: You can hover over each mapping and then check the tooltip to verify that the inserted data from the specified node is your preferred match.
      Checking the value for an inserted mapping

      When you clear a suggestion, the mapping is removed from the field, which also then becomes disabled.

    • To exit from the inline preview mode without accepting any of the top suggestions, click Cancel.

      The initial view with the count of top suggestions that you can preview is displayed again.

      Initial view of top suggestions
  3. To accept the preview mappings (and exit the inline preview mode), click Apply suggestions. Those fields are populated with the top suggestions and the remaining fields remain blank. (If using App Connect Designer 12.0.5.0-r3 or earlier, click Apply N suggestions, where N represents the count Apply suggestions to populate fields with top suggestions.)
    Apply suggestions to populate fields with top suggestions
    Note: 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.

Replacing an inserted mapping for a top suggestion

If you want to replace the mapping for a top suggestion after it's inserted in a field, you can do so as follows:

  1. Delete the mapping from the field.

    When you delete the mapping, notice that the top suggestions count on the Preview button is incremented, and you can auto-populate the field again by clicking Preview N mapping suggestions and Apply suggestions. If you choose to add your own preferred mapping as described in the following steps, the count is decremented on the Preview button. (If using App Connect Designer 12.0.5.0-r3 or earlier, when you delete the mapping, its top suggestions count is redisplayed, and you can auto-populate the field again by clicking View suggestions and Apply N suggestions. If you choose to add your own preferred mapping, the count is removed and View 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 as follows:
    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

Manually inserting mappings into unpopulated fields

After the relevant fields are auto-populated with the top suggestions, you can manually insert mappings into any fields that remain unpopulated.

To manually insert mappings into any of the remaining blank fields, complete the following steps:

  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.

Populating the fields when no top suggestions or no suggested mappings are discovered

If no top suggestions are discovered for an action or node, or if suggested mappings are not discovered for any of the fields, the Preview button is shown with a count of zero (0) when the discovery process completes. (If using App Connect Designer 12.0.5.0-r3 or earlier, a grayed-out View suggestions link is displayed when the discovery process completes Grayed-out View suggestions link.)

Preview button with a count of zero (0)


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 Suggested mappings link

If an error is displayed because suggestions cannot be generated, see Troubleshooting mapping assist in App Connect Designer for help in resolving the error.



Disclaimer: You are responsible for any example data (including any personal information) used for, and any decision to proceed with, any automated flows which are suggested for your convenience when IBM® App Connect is used. IBM has no responsibility for any such automated flows and IBM warranties and support will not apply to them; they are used at your risk. IBM might periodically modify the underlying learning models in App Connect through updates, fixes, or patches in order to improve App Connect performance.