Creating Virtual Data Resources

A virtual data resource is a resource with normalized fields that you can use in place of specific elements to facilitate one-to-many integrations. In this section you will learn how to create a virtual data resource at the organization level and map element resource data to it for transformation. You can create a virtual data resource based on an existing resource (template, element resource, or existing virtual data resource) or as an entirely new resource. This guide includes instructions for both methods.

Important: Only users at the organization level can create virtual data resources, but users at any level can create transformations at the instance level. If you are not a user at the organization level, skip to Transforming Fields.

To create a virtual data resource, go to the steps that match how you plan to create the resource:

Create a New Virtual Data Resource

Follow the instructions in this section to create an entirely new virtual data resource. When finished, you will have a virtual data resource with a single default field called id.

Define a Virtual Data Resource in the UI

  1. Access the page.
  2. On the Virtual Data Resources page, click Create New Virtual Data Resource.

  3. Enter a name for your virtual data resource, such as "myContact" and click SAVE.  The Create page shows your new virtual data resource with a default organization-level field of id.


  4. Add additional fields: In the Organization Level Fields section, click Add.


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

Define a Virtual Data Resource via API

Endpoint used: POST /organizations/objects/definitions

  1. Construct a JSON body as shown below (see Request Body Parameters):
    {
      "<objectName>": {
        "fields": [
          {
            "path": "<fieldName>",
            "type": "<dataType>"
          }
        ]
      }
    }
  2. Call the following, including the JSON body you constructed in the previous step:
      POST /organizations/objects/definition
    
  3. Continue to the next step: map fields to create a transformation.

Request Body Parameters

objectName
The name of the virtual data resource.
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
levelThe 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

cURL Example

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

Create a virtual data resource Based on Another

You can create a virtual data resource based on another virtual data resource in your organization. You might do this to create variations of a virtual data resource for multiple different accounts.


Define a New Virtual Data Resource Based on Another via API

Endpoints used:

  1. Call the following, replacing {objectName} with the name of the virtual data resource that you want to copy:
      GET /organizations/objects/{objectName}/definitions
  2. Copy the fields array in the response to the JSON body for
    POST /organizations/objects/definitions
  3. Continue to the next step: map fields to create a transformation.

Request Body Parameters

objectName
The name of the virtual data resource.
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
levelThe 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

cURL Example

1. Get the Existing Virtual Data Resource Payload

curl --request GET \
  --url https://staging.cloud-elements.com/elements/api-v2/organizations/objects/[VDR_NAME]/definitions \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \

2. Create the Copy of the Virtual Data Resource

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