​
Overview

A Field Mapping is a type of User Setting that allows your users to define a mapping between an object in your application (an “Application Object”) and an object in their connected integration account (an “Integration Object”). For example: let’s say your integration needs to sync your user’s Task records from your application to their Tasks in a Salesforce account. To do that, you’ll need to build up a Mapping between fields in your application’s Tasks and fields for a Task in a connected Salesforce account, as illustrated below:
To enable your user to provide this Mapping, you can use the Connect Portal to provide a User Setting that displays each field of a Task (Title, Description, Completed) and prompts them to select a matching field of a Salesforce Task.
Once this Mapping is completed, you’re able to use the Mapping like any other User Setting in the Workflow Editor to transform objects in either direction (from Application Object to Integration Object or from Integration Object to Application Object).

​
Adding Field Mapping to the Connect Portal

1

Navigate to Customize Connect Portal

In an integration in your project, click on Customize from the Connect Portal section in the dashboard.
2

Select the Field Mapping Input Type

Select Configuration, add a Setting, and then select Field Mapping as the type of User Setting.
3

Configure the Setting

Give this setting a descriptive name that explains what this Mapping represents for your integration. For example, if Contacts is your intended Application Object to be mapped to a Salesforce Object, you might title this input “Map Contacts to this object”.
4

Add Field Labels

Add a label for each property that should be mapped from your Application Object to a Salesforce Object. You might add labels for “First Name”, “Last Name”, and “Email”, if the schema for Contacts in your app includes these properties.
In your Connect Portal, your users will be prompted to select an object from their Salesforce instance when enabling this workflow. For each of the Application Object properties you labeled, your users will be prompted to select which Integration Object field that property should be mapped to. By this stage, you have configured a static Field Mapping in the dashboard and can call paragon.connect to render the Field Mapping in the Connect Portal in your frontend application.

​
Configuring Field Mapping

Many implementations of Field Mapping will warrant additional configuration options. Start by using the Paragon Dashboard to enable additional configuration options for your Field Mapping like Dynamic Application Fields. Then, learn how to pass dynamic fields through the Paragon SDK in your frontend to render dynamic Field Mapping elements in the Connect Portal.

​
Configuring your Field Mapping setting in the Dashboard

​
Dynamic Application Fields

If your Application Fields may vary between your users for a particular Mapping, you are able to provide those options from your frontend application, through the SDK, using Dynamic Application Fields.
Dynamic Application Fields is available for Paragon Enterprise customers and as an add-on for Paragon Pro customers. To learn more, contact your Customer Success Manager or [email protected].
Enable and configure Dynamic Application Fields by adding a Field Mapping input to your Connect Portal as described above. Configuration for Dynamic Application Fields will have a different interface depending on the integration.

Left: Pre-configured Field Mapping Input. Right: Field Mapping Input

Complete the dashboard configuration for Dynamic Application Fields using the following steps, depending on the interface you see:
Pre-configured Field Mappings simplify the paragon.connect call by rendering pre-built dropdowns for the most common object types and fields for you.
1

Toggle Dynamic Fields

Toggle on the “Use dynamic fields” slider option in your Field Mapping setting configuration.
2

Provide Object Name

Provide an Object Name that represents the name of your Application Object. This name will be used as an identifier to provide dynamic application fields through the SDK, as demonstrated in the code example to paragon.connect in the Passing Dynamic Fields through the SDK section.
3

Edit Example Fields for Testing in the Workflow Editor (Optional)

Edit the example fields included in the code snippet to represent realistic values that will be passed from your application. These values will be used for testing in the Workflow Editor, and will not affect the live configuration for your users. Learn more about testing your Field Mapping in the Testing Field Mapping in the Workflow Editor section.
4

Save Changes

Click Save to apply your changes.

​
Passing Dynamic Fields Through the SDK

For all Field Mapping inputs configured in the Dashboard to use Dynamic Application Fields, use the paragon.connect method in your frontend to fully configure the Integration Objects, Integration Fields, and Application Fields that are rendered dynamically in the Connect Portal. Pre-configured Field Mappings simplify the SDK call by pre-building dropdowns for the most common object types and fields for you and minimally require you to specify your Application Fields in the SDK. You can think of this as the right-hand-side of the Field Mapping input. For all other integrations, you must define the Integration Objects, their Integration Fields (the left-hand-side of the Field Mapping input), and your Application Fields.

​
Passing Application Fields for a Pre-configured Field Mapping

Pass your Application Fields by specifying the mapObjectFields option, with an object keyed by the name you specified in the “Object Name” field when configuring your setting:
Open a pre-configured Field Mapping with Dynamic Application Fields
paragon.connect("salesforce", {
  mapObjectFields: {
    "Task": {
      fields: [
        { label: "Title", value: "title" },
        { label: "Description", value: "description" },
        { label: "Completed?", value: "isCompleted" }
      ]
    }
  }
});
For each field passed, two values are specified:
  • label: The human-readable description for the field. This will be shown to the user in the Field Mapping input.
  • value: The field key used by the object as it exists in your application. This key does not yet support nested properties.
Calling the above would result in the Connect Portal appearing like below:

​
Passing Your Own Integration Objects and Fields

For all integrations, you can fetch and render any object type and its fields that are available in the user’s connected integration. Define the objectTypes and integrationFields properties and their get methods to render either a static list of objects and their fields, or a paginated list of objects and their fields via an API request.
  • objectTypes — defines the list of record types available in the user’s integration (e.g. “Contact”, “Deal”, “Opportunity”).
  • integrationFields — defines the fields available for the selected record type.
The both properties require a get method that must return either: 
// objectTypes
{
  get: async (cursor, search) => {
    return [
      { label: "Contact", value: "contact" },
      { label: "Deal", value: "deal" },
      { label: "Opportunity", value: "opportunity" }
    ]
  }
}
applicationFields When passing your own object types and fields, you must alter your paragon.connect call to explicitly define the applicationFields property. applicationFields defines the list of fields from your application. It should contain a fields array containing { label, value } pairs identical to the fields array in the Passing Application Fields for a Pre-configured Field Mapping example. The following are examples of how to fully configure objectTypes, integrationFields, and applicationFields when passing your own object types and fields: 
paragon.connect("salesforce", {
  mapObjectFields: {
    // Replace "CustomObjectMapping" with your Application Object Name as specified in
    // Field Mapping input options
    CustomObjectMapping: {
      objectTypes: {
        get: async (cursor, search) => {
          const res = await paragon.request("salesforce", "/v1/objects", { method: "GET" });
          return res.data.map((obj) => ({
            label: obj.name,
            value: obj.id
          }));
        }
      },
      // Integration fields from the selected objectTypes (Contacts' schema / field types)    
      // @returns Promise resolving to Integration Fields to display.
      // Each item: { label: string, value: string }
      integrationFields: {
        get: async ({ objectType }) => {
          const res = await paragon.request("salesforce", 
            `v1/objects/${objectType}/fields`, 
            { method: "GET" });
            
          return res.fields.map((field) => ({
            label: field.label,
            value: field.id
          }));  
        }
      },
      // Fields from your application that will be displayed in the Connect Portal
      applicationFields: {
        fields: [
          { label: "Title", value: "title" },
          { label: "Email", value: "email" }
        ],
        defaultFields: [],
        userCanRemoveMappings: true
      }
    }
  }
});

​
User-Configurable Mappings

If your use case requires it, you can allow users to control the number of Field Mappings that are set by adding the userCanRemoveMappings option alongside the fields array in your paragon.connect call. 
paragon.connect("salesforce", {
  mapObjectFields: {
    // Replace "Task" with your Application Object Name as specified in
    // Field Mapping input options
    "Task": {
      fields: [
        { label: "Title", value: "title" },
        { label: "Description", value: "description" },
        { label: "Completed?", value: "isCompleted" }
      ],
      userCanRemoveMappings: true
    }
  }
});
Setting this option will result in the Connect Portal appearing like below:
With this option, your users will be able to remove, re-add, and change any of the Mappings that are passed through fields. This option can be combined with the defaultFields option to achieve different display configurations:

{ userCanRemoveMappings: true, defaultFields: [] }

{ userCanRemoveMappings: true, defaultFields: ['title'] }

defaultFields is an array of strings matching the value property of your fields. Any fields with matching value keys will be included in the initial list of Field Mappings that your user sees, when viewing the Connect Portal for the first time. If defaultFields is unspecified, all fields specified in the fields property will appear in the initial list of Field Mappings.

​
User-Creatable Fields

If your Application Object supports freeform fields or a flexible schema, you can allow users to create their own fields in the Field Mapping input. 
paragon.connect("salesforce", {
  mapObjectFields: {
    // Replace "Task" with your Application Object Name as specified in
    // Field Mapping input options
    "Task": {
      fields: [
        { label: "Title", value: "title" },
        { label: "Description", value: "description" },
        { label: "Completed?", value: "isCompleted" }
      ],
      defaultFields: [],
      userCanCreateFields: true
    }
  }
});
If this option is specified, the Connect Portal will appear with an option for users to create their own fields, if the field is not available in the list populated by fields:

​
Testing Field Mapping in the Workflow Editor

When building workflows that use Field Mapping, you can test how your mappings work directly in the Workflow Editor. The mapping is applied based on what is configured for the Test User.

​
Configuring Test User Mappings

To configure the Field Mapping for the Test User:
  1. Return to the Customize Connect Portal section of your integration in the dashboard.
  2. Select the Field Mapping Input Type setting.
  3. Alter the Test Mapping code to change the static Integration Objects, Integration Fields, and Application Fields that are rendered in the preview Connect Portal. (This has no production impact.)
  4. Click Save to apply your changes.
  5. Preview the Connect Portal to see the updated mapping configuration and fill-in the inputs to mimic the mapping you want to test.

Configure the test data for the Field Mapping input

​
Usage in Workflows

After your user specifies their desired mapping in the Connect Portal, you can use their chosen values within workflow actions. A Field Mapping contains 2 pieces of information:
  • The selected Integration Object type (for example, a Salesforce Task).
  • The field-level mappings between your Application Object and the selected Integration Object type (for example, Title ⇄ Salesforce Task Subject, Description ⇄ Salesforce Task Description).
You can use the “Apply field mapping” option to transform Application Objects (from App Events or Request triggers) to Integration objects and vice versa.

​
Transforming from Application Object -> Integration Object

If you receive an Application Object in an App Event or Request payload, you can transform it into an Integration Object by selecting the Field Mapping Object Type in the “Apply field mapping” option for your App Event or Request trigger.
Once set, you will see the trigger output data update to show two objects:
  • originalPayload: This is the original App Event or Request payload received by the trigger.
  • mappedIntegrationObject: This is the Integration Object that was mapped based on the Field Mapping configured in the Connect Portal.
Note: The mapped Integration Object only applies to the root of the original payload. If your field exists within a nested JSON, it will not work as expected.

​
Transforming from Integration Object -> Application Object

When receiving an Integration Object in an Integration trigger (for example, a Salesforce “New Record” trigger), you can transform it into an Application Object using the Field Mapping specified by your user. In the trigger settings for your workflow, select the Field Mapping Object Type in the “Apply field mapping” option.
Once set, you will see the trigger output data update to show two objects:
  • originalPayload: This is the original Integration Object received by the trigger.
  • mappedApplicationObject: This is the Application Object that was mapped based on the field mapping configured in the Connect Portal.

​
Pre-configured Field Mapping Support

Paragon provides pre-configured Field Mapping support for most CRM integrations, along with select others. These integrations come with fully maintained dropdowns for common record types and fields — you only provide your application fields. All pre-configured Field Mapping integrations can be overridden by using the SDK to define custom field mapping dropdowns as explained above. This gives you full control over record types, fields, and how they appear in the Connect Portal. (See Passing Your Own Integration Objects and Fields).