Paragon
Search…
⌃K
Links

Custom Object Mapping

Use a Custom Object Mapping User Setting to allow your users to define a mapping between objects in your application and their integration.
Custom Object 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").

Overview

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 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).

Supported Integrations

Custom Object Mapping settings are supported for all CRM integrations and a select number of other integrations, including:
  • Salesforce
  • HubSpot
  • Dynamics 365 Sales
  • Pipedrive
  • Marketo
  • Sage Intacct
  • Sharepoint

Adding to the Connect Portal

Custom Object Mapping settings can be added by visiting the "Customize Connect Portal" screen from a supported integration in your project, under the User Settings section.
Select "Custom Object Mapping" as the type for the User Setting:
You should 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".
Finally, add a label for each property that should be mapped from your Application Object to a Salesforce Object. In the example above, 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 object properties you labeled, your users will be prompted to select which object field that property should be mapped to.

Dynamic Fields

Dynamic Field Mapping is available for Paragon Enterprise customers only. To learn more, contact your Customer Success Manager or [email protected].
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 Fields.

Configuring your Custom Object Mapping setting

  1. 1.
    To set up Dynamic Field Mapping, toggle on the "Use dynamic fields" option in your Custom Object Mapping setting configuration:
  2. 2.
    Once you've toggled this on, provide an Object Name that represents the name of your Application Object. This name will be used as an identifier to provide dynamic fields through the SDK, as demonstrated in the code example that appears below.
  3. 3.
    (Optionally) Edit the example fields included in the code snippet to represent realistic values that will be passed from your application. This will not affect the live configuration for your users, since values must be passed from your frontend application through the SDK, but you might find this useful to test example field values while building workflows.
  4. 4.
    Click Save to apply your changes.

Passing Dynamic Fields through the SDK

After configuring your Custom Object Mapping input to use Dynamic Fields, you can modify your call to paragon.connect to include fields to be dynamically rendered in the Connect Portal.
You can pass these fields by specifying the mapObjectFields option, with an object keyed by the name you specified in the "Object Name" field when configuring your setting:
paragon.connect("salesforce", {
mapObjectFields: {
"Task": [
{ 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 Custom Object Mapping setting 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:

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 to your paragon.connect call.
paragon.connect("salesforce", {
mapObjectFields: {
// Replace "Task" with your Application Object Name as specified in
// Custom Object Mapping setting 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
// Custom Object Mapping setting 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: