Creating and Managing Virtual Data Resources

Last Modified on 03/04/2022 4:22 am MST

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

Important: Only users at the organization or account level can create virtual data resources, 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 Virtual Data Resource

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

Create a Virtual Data Resource in the UI

  1. Access the Virtual Data Resources page.
  2. Click Build a New Virtual Data Resource.

    The Create page shows your new resource.

    New Resource from Scratch 

  3. Enter a name for your virtual data resource, 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.

    Add Fields

  6. Click Save.

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

Create a Virtual Data Resource 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 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \
  -H 'Content-Type:application/json' \
  -d '{  
  "myResource":{  
    "fields":[  
      {  
        "path":"firstName",
        "type":"string"
      },
      {  
        "path":"lastName",
        "type":"string"
      }
    ],
    "level":"organization"
  }
}'

Request Body Parameters

objectNameThe name of the virtual data resource.Required
fieldsAn object containing the field names and data types of the resource.Required
pathThe name of the field.Required
typeThe 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

Create a New Virtual Data Resource by Importing a JSON Payload

  1. Access the Virtual Data Resources page and click Create New Virtual Data Resource.  
  2. Click IMPORT
  3. Name your resource and paste your sample payload and click IMPORT

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

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

Note: When creating custom VDRs or resources, make sure that the name does not contain the string “events” as it conflicts with the events API endpoint. This causes the GET and POST API calls to fail.

Example:

GET `/events/eventTest` → works.

GET `/events/eventsTest` → does not work.

Clone from a Virtual Data Resource Template

Virtual Data Resource 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 elements that you select. The cloning process creates default mappings at the element level, so later, when you authenticate an element instance, the default mappings apply to it. 

  1. Access the Virtual Data Resources page.
  2. Click VDR Templates.
  3. Select the resource to clone.
  4. Click Clone above or below the list of fields.

    We show you the list of premapped 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 element 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 Virtual Data Resource 

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

Clone a Virtual Data Resource in the UI

  1. Access the Virtual Data Resources page.
  2. Click Build a New Virtual Data Resource.

    The Create page shows your new resource with a default organization-level field of id. New Resource from Scratch 

  3. On the bottom left, click Create from Existing Resource.
  4. Select an existing resource from the list.
    Tip: If the list is long, use Search to filter it.
  5. Enter a name for your resource, and then click Create.

    The Transformations page shows your new virtual data resource with all of the fields that were in the original resource.

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

Clone a Virtual Data Resource with the API

Endpoints used:

  1. Make a GET /organizations/objects/{objectName}/definitions request, replacing {objectName} with the name of the virtual data resource that you want to clone.
    curl -X GET \
  'https://api.cloud-elements.com/elements/api-v2/organizations/objects/myResource/definitions' \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \
  -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 forPOST /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 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \
  -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

objectNameThe name of the virtual data resource.Required
fieldsAn object containing the field names and data types of the resource.Required
pathThe name of the field.Required
typeThe 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

Clone a Resource From an Element

You can clone resources available through an API provider's element. 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 Virtual Data Resources page.
  2. Click Build a New Virtual Data Resource.

    The Create page shows your new resource with a default organization-level field of id. New Resource from Scratch 

  3. On the bottom left, click Create from Existing Resource.
  4. Click Existing Element Instance Resource.
  5. From the Existing Element Instant Resources list, select the element instance that contains the resource that you want to use.
  6. From the Element Instance Resources list, select the resource.
    Tip: If the list is long, use Search to filter it.

    New Resource from Element Instance

  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 Virtual Data Resource instance resource. We've already mapped the source element instance to your resource.

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

View Your Virtual Data Resources

To see all of your virtual data resources in the My Resources catalog, click Virtual Data Resources on the left navigation menu.

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

Sorting Virtual Data Resource Fields

On the Mappings tab, 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 virtual data resources with GET /organizations/objects/definitions

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/organizations/objects/definitions \ 
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \
  -H 'Accept: application/json' \

Rename Virtual Data Resources

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

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

Rename a Virtual Data Resource in the UI

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

Rename a Virtual Data Resource with the API

Change the name of a virtual data resource 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 virtual data resource 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 virtual data resource 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/' \
  -H 'Accept: application/json' \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -d '{
"objectName" : "newObjectName"
}'

Example Response

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

Cloud Elements - For Public Use

User Icon

Thank you! Your comment has been submitted for approval.