Creating Mappings

In this section, you will learn how to clone from a resource template or create your own mapping. You can create a mapping from scratch or clone them from existing resources (templates, existing mapping, or a resource available through a connector). This topic includes instructions for all methods. Please note that as a prerequisite to creating a mapping from a custom resource or custom connector, you must have models defined before a mapping can be created. For more information on this, please see this article.

Important

Icon

Only users at the organization or account level can create mappings, but users at any level can map fields at the instance level. If you are not a user at the organization or account level, skip to Transforming Fields.

Create a New Mapping

Follow the instructions in this section to create a new mapping from scratch. When finished, you will have a resource with a single default field called id.

Create a Mapping in the UI

  1. Access the Mappings page.
  2. Click Build a New Mapping.
    The Create page shows your new resource with a default organization-level field of id.
  3. Enter a name for your mapping, such as "myContact".
  4. Optionally add a Display Name. You can use the display name instead of the field name when building user interfaces.
  5. Add additional fields: In the Organization Level Fields section, click Add.
  6. Click Save.

  7. Continue to the next step: map fields to create a transformation.

Create a Mapping with the API

Make a POST /organizations/objects/definitions request.

curl -X POST \
  'https://api.cloud-elements.com/elements/api-v2/organizations/objects/definitions' \
  
  -H 'Content-Type:application/json' \
  -d '{  
  "myResource":{  
    "fields":[  
      {  
        "path":"firstName",
        "type":"string"
      },
      {  
        "path":"lastName",
        "type":"string"
      }
    ],
    "level":"organization"
  }
}

Request Body Parameters

objectName The name of the mapping. Required
fields An object containing the field names and data types of the resource. Required
path The name of the field. Required
type The data type of the field. Required
level The level at which the field exists, either organization, account, or instance. Organization users can create fields at any level; account users can create fields only at the accountor instance level. Optional

Create a New Mapping by Importing a JSON Payload

Clone from a Mapping Template

Mapping templates provide detailed fields for frequently integrated resources and mappings to popular API providers. You can clone from the templates to create default mappings to the API providers. We clone fields to the account level, but you can adjust the field level after cloning.

During the cloning process, you select the API providers to include in the mappings. You do not need to have existing authenticated instances of the connectors that you select. The cloning process creates default mappings at the connector level, so later, when you authenticate a connector instance, the default mappings apply to it. 

  1. Access the Mappings page.
  2. Click mapping Templates.
  3. Select the resource to clone.
  4. Click Clone above or below the list of fields.
    We show you the list of pre-mapped API providers and their resources that we've already mapped. If the list is long, use Search to find a specific API provider.
  5. Select the API provider mappings to include in your resource, and then click Confirm.
    Regardless of which API providers you selected, only those with existing authenticated connector instances appear on the Mapped Transformations (right) side.  When you authenticate with the API providers later, the instances will appear here.
  6. Optionally rename the resource. Click Edit next to the name, change the name, and then click Save.

After cloning, you can add or remove fields, add display names, and even update the transformations.

Clone an Existing Mapping 

You can clone a mapping and customize the new resource. You might do this to create variations for multiple different accounts.

Clone a Mapping in the UI

  1. Access the Mappings page.
  2. Click Build a New Mapping.
  3. The Create page shows your new resource with a default organization-level field of id.
  4. On the bottom left, click Create from Existing Resource.
  5. Select an existing resource from the list.

    Icon
    If the list is long, use Search to filter it.
  6. Enter a name for your resource, and then click Create.
    The Transformations page shows your new mapping with all of the fields that were in the original resource.

  7. Continue to the next step: map fields to create a transformation.

Clone a Mapping with the API

Endpoints used:

  • GET/organizations/objects/{objectName}/definitions
  • POST /organizations/objects/definitions
  1. Make a GET /organizations/objects/{objectName}/definitions request, replacing {objectName} with the name of the mapping that you want to clone.

    curl -X GET \
      'https://api.cloud-elements.com/elements/api-v2/organizations/objects/myResource/definitions' \
      
      -H 'Accept:application/json' 
  2. Compose a POST /organizations/objects/definitions request.
  3. Copy the fields array in the response from step 1 to the JSON body for POST /organizations/objects/definitions.
  4. Submit the POST /organizations/objects/definitions request with the fields array from step 1.

    curl -X POST \
      'https://api.cloud-elements.com/elements/api-v2/organizations/objects/definitions' \
      
      -H 'Accept:application/json' \
      -H 'Content-Type:application/json' \
      -d '{  
      "clonedResource":{  
        "fields":[  
          {  
            "path":"firstName",
            "type":"string"
          },
          {  
            "path":"lastName",
            "type":"string"
          }
        ],
        "level":"organization"
      }
    }'
  5. Continue to the next step: map fields to create a transformation.

Request Body Parameters

objectName The name of the mapping. Required
fields An object containing the field names and data types of the resource. Required
path The name of the field. Required
type The data type of the field. Required
level The level at which the field exists, either organization, account, or instance. Organization users can create fields at any level; account users can create fields only at the account or instance level. Optional

Clone a Resource From a Connector

You can clone resources available through an API provider's connector. You might do this to create variations for multiple different accounts. For example, if you want your /contacts resource to match the data in the Salesforce Contact resource, create a new resource by cloning the Salesforce Contact resource.

  1. Access the Mappings page.
  2. Click Build a New Mapping.
    The Create page shows your new resource with a default organization-level field of id.
  3. On the bottom left, click Create from Existing Resource.
  4. Click Existing Connector Instance Resource.
  5. From the Existing Connector Instant Resources list, select the connector instance that contains the resource that you want to use.
  6. From the Connector Instance Resources list, select the resource.

    Icon
    If the list is long, use Search to filter it.
  7. Enter a name for your resource, and then click Create.

    The Transformations page shows your new resource with all of the fields in the connector instance resource. We've already mapped the source connector instance to your resource.

  8. Continue to the next step: map fields to create a transformation.

View Your Mappings

To see all of your mappings in the My Resources catalog, click Mappings on the left navigation menu.

The resource cards show the mapped to the mapping. If you haven't mapped any yet, the card prompts you to add a mapping.

Sorting VDR Fields

On the Mappings tab, VDR fields can be sorted alphabetically, most frequently mapped, or unmapped first. You can sort the listed fields by clicking the Sort Fields By menu and selecting an option.

List Resources with the API

Get a list of mappings with GET /organizations/objects/definitions.

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/organizations/objects/definitions \ 
  
  -H 'Accept: application/json' \

Rename Mappings

When you rename a mapping, be aware that it could potentially affect flows that reference the resource. We check flows for the resource name and warn you if we find it.

However, we do not check everything in flows. The name could be part of the JavaScript code or used in a path description. We recommend that you investigate your flows before renaming to prevent errors.

Rename a Mapping in the UI

On the Transformations page, click Edit next to the name, rename it, and then click Save.

Rename a Mapping with the API

Change the name of a mapping at the organization, account and instance level by passing a new objectName in the request body of the following endpoints:

  • PATCH /organizations/objects/{objectName}
  • PATCH /accounts/objects/{objectName}
  • PATCH /instances/objects/{objectName}

If the mapping includes different level fields, those are not changed by this request. This essentially splits the resource where the renamed resource includes only the fields at the level of the endpoint, while the previous name includes only fields at the other levels. Use the other endpoints to change the name of the mapping associated with the different level fields. Once all levels are changed, the resource is unified under the new name.

Example Request

curl -X PATCH \
  'https://api.cloud-elements.com/elements/api-v2/organizations/objects/{{objectName}}' \
  -H 'Accept: application/json' \
   \
  -d '{
"objectName" : "newObjectName"
}'

Example Response

{  
  "id":69496,
  "objectName":"newObjectName",
  "fields":[  
    {  
      "type":"string",
      "path":"firstName"
    },
    {  
      "type":"string",
      "path":"lastName"
    }
  ],
  "level":"organization"
}

Related Links