Transforming VDRs Fields with the API | Cloud Elements Help Center

A transformation is the result of the process of mapping fields in your element instance resources to existing fields and objects in a virtual data resource (VDR). After you create a VDR, you will select an element instance, choose the resource containing the objects that you want to map to the VDR, and map fields to the VDR. The end result is a a transformation of the selected objects in the element instance.

You can test the APIs described in this section using our interactive documentation. Open Cloud Elements, and then click API Docs in the header.

Retrieve a List of VDRs

You can retrieve a list of the VDRs in your account. The list includes all fields defined in the VDR.

To retrieve a list of VDRs:

Call the following:
```
  GET /accounts/objects/definitions
```
Continue to the next step: map fields to create a transformation.

cURL Example

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/accounts/objects/definitions \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json'

Map Fields to Create a Default Transformation

Cloud Elements provides several APIs to map resources. This section describes mapping fields for an account-level default transformation. The result is a default transformation for all instances of a specific element.

To map fields:

Construct a JSON body as shown below. For descriptions of each parameter, see Transformation JSON Parameters.

 {
  "level":"account",
  "vendorName":"<VENDOR_RESOURCE>",
  "fields":[
    {
      "path":"<VDR_FIELD>",
      "type":"<VDR_TYPE>",
      "vendorPath":"<VENDOR_FIELD>",
      "vendorType":"<VENDOR_TYPE>"
    }
  ]
}

Call the following, including the JSON body from the previous step:
```
  POST /accounts/elements/{keyOrId}/transformations/{objectName}
```
Note: Replace {keyOrId} with the element key or id and replace {objectName} with the name of the VDR.

Transformation JSON Parameters

Parameter	Description	Required (Y/N)
level	The access level of the transformation, either `account` or `instance`.	N. Default depends on endpoint.
vendorName	The name of the resource that contains the fields that you want to map to the VDR.	N
fields	An object containing the field names and data types of the VDR and the vendor resource. Tip: To get a list of fields in a resource, call `GET hubs/{hub}/objects/{RESOURCE}/metadata`.	N
path	The name of the field in the VDR.	Y
vendorPath	The name of the field in the vendor resource.	Y
type	The data type of the field in the VDR. Data types can be `boolean`, `string`, `date`, and `number`.	N
vendorType	The data type of the field at the vendor. Unless the format is `date`, you do not need to include this parameter. If the format is `date`, also include a mask.	N

cURL Example

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/accounts/elements/sfdc/transformations/myContacts \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \
  -d '
  {
  "level":"account",
  "vendorName":"Contact",
  "fields":[
    {
      "type":"string",
      "path":"FirstName",
      "vendorPath":"FirstName"
    },
    {
      "type":"string",
      "path":"id",
      "vendorPath":"Id"
    },
    {
      "type":"string",
      "path":"LastName",
      "vendorPath":"LastName"
    },
    {
      "type":"date",
      "path":"birthdate",
      "vendorPath":"Birthdate",
      "vendorType":"date",
      "configuration":[

      ]
    }
  ]
}'

Map Fields at the Instance Level

Using the Cloud Elements instances endpoint, you can map fields at the instance level. Mapping fields is a two-step process that includes creating an instance level resource, and then mapping fields to it.

To create an instance-level VDR and map fields to it:

Construct a JSON body for the instance level VDR as shown below (see New VDR JSON Parameters):
```
{
  "fields": [
    {
      "type": "<dataType>",
      "path": "<fieldName>"
    }
  ]
}
```
Create the VDR. Make the following API call with the JSON body from the previous step, replacing {id} with the instance id, and replacing {objectName} with the name of the VDR:
```
POST /instances/{id}/objects/{objectName}/definitions
```

Construct a JSON body to map fields to the new VDR as shown below. For descriptions of each parameter, see Transformation JSON Parameters.

{
  "level":"instance",
  "vendorName":"<VENDOR_RESOURCE>",
  "fields":[
    {
      "path":"<VDR_FIELD>",
      "type":"<VDR_TYPE>",
      "vendorPath":"<VENDOR_FIELD>",
      "vendorType":"<VENDOR_TYPE>"
    }
  ]
}

Map fields to the VDR. Call the following, including the JSON body from the previous step:
```
POST /instances/{id}/transformations/{objectName}
```
Note: Replace {id} with the instance id and replace {objectName} with the name of the VDR.

cURL Example

Step 1: Create the VDR

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/instances/{id}/objects/{objectName}/definitions \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \
  -d '
  {
    "fields": [
      {
        "type": "string",
        "path": "title"
      }
    ]
  }'

Step 2: Map fields to the VDR

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/instances/{id}/transformations/{objectName} \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \
  -d '
  {
    "vendorName": "Contact",
    "level": "instance",
    "fields": [
      {
        "path": "title",
        "type":"string",
        "vendorPath": "Title"
      }
    ]
  }'

Map Fields at the Account Level

Using the Cloud Elements accounts endpoint, you can map fields at the account level. Mapping fields is a two-step process that includes creating an account level resource, and then mapping fields to it.

To create an account-level VDR and map fields to it:

Construct a JSON body for the account level VDR as shown below (see New VDR JSON Parameters):
```
{
  "fields":[
    {
      "type":"<dataType>",
      "path":"<fieldName>"
    }
  ]
}
```
Create the VDR. Make one of the following API calls with the JSON body from the previous step, replacing {id} with the account id, and replacing {objectName} with the name of the VDR:
```
POST /accounts/objects/{objectName}/definitions
```
Note: Use this API call to create a VDR at the default account level.
```
  POST /accounts/{id}/objects/{objectName}/definitions
```
Note: Use this API call to specify an account by id.

Construct a JSON body to map fields to the new VDR as shown below. For descriptions of each parameter, see Transformation JSON Parameters.

{
  "level":"instance",
  "vendorName":"<VENDOR_RESOURCE>",
  "fields":[
    {
      "path":"<VDR_FIELD>",
      "type":"<VDR_TYPE>",
      "vendorPath":"<VENDOR_FIELD>",
      "vendorType":"<VENDOR_TYPE>"
    }
  ]
}

Map fields to the VDR. Call the following, including the JSON body from the previous step:
```
POST /accounts/{id}/elements/{keyOrId}/transformations/{objectName}
```
Note: Replace{id} with the instance id, replace {keyOrId} with the element key or id, and replace {objectName} with the name of the VDR.

cURL Example

Step 1: Create the VDR (default account)

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/accounts/objects/{objectName}/definitions \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '
  {
    "fields": [
      {
        "type": "string",
        "path": "title"
      }
    ]
  }'

Step 1: Create the VDR (specific account)

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/accounts/{id}/objects/{objectName}/definitions \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '
  {
    "fields": [
      {
        "type": "string",
        "path": "title"
      }
    ]
  }'

Step 2: Map fields to the VDR

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/accounts/{id}/elements/{keyOrIdtransformations}/{objectName} \
  -H 'authorization: User <USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -d '{
    "vendorName": "Contact",
    "level": "account",
    "fields": [
      {
        "path": "title",
        "type":"string",
        "vendorPath": "Title"
      }

  }'

Map Complex Objects

You can use regular expressions as values for the JSON body parameters.

Examples:

Get the value of the name field from the Products array where id = 4.

{
  "fields": [
    {
      "path": "AppleIpadName",
      "vendorPath": "Products[id=4].name"
    }
  ]
}

Get the value of the name field from the Products array where id = 2.

{
  "fields": [
    {
      "path": "AppleNewProductName",
      "vendorPath": "details.Products[?(@.id==2)].name"
    }
  ]
}

Get the touchId value from the Products array with id=2 which is inside the features object.

{
  "fields": [
    {
      "path": "AppleTouchProductId",
      "vendorPath": "Products[?(@.features.touchId==true)].id"
    }
  ]
}

Get the Id value of the Products array at index 0.

{
  "fields": [
    {
      "path": "AppleProductId",
      "vendorPath": "Products[0].id"
    }
  ]
}

Get a count of the Products array.

{
  "fields": [
    {
      "path": "AppleProductsCount",
      "vendorPath": "Products[*].size()"
    }
  ]
}