Introducing Virtual Data Resources v2 Engine

By default, any new virtual data resources (VDRs) created in new user organizations across environments now utilize the VDR v2 engine.

This article explains some of the differences between the v1 and v2 engines, as well as how to specify which engine you want new VDRs to use.

You can find a Postman collection for the VDR v2 engine here.

Differences between v1 and v2

New Data Structure

For VDRs created using the v1 engine, the level property exists in the root level of the VDR object. However, for VDRs created using the v2 engine, the level property is nested in the configuration parameter. Additionally, you now have access to a unique identifier fields[*].id for each field in your object.

Example v1 Structure

In this v1 example, level is at the root level and on the last line of the object:

{
  "id": 12345,
  "objectName": "songs",
  "fields": [
    {
      "type": "string",
      "path": "artists[*].name",
      "displayName": "artists"
    },
    {
      "type": "string",
      "path": "songName",
      "displayName": ""
    }
  ],
  "level": "organization"
}

Example v2 Structure

In this v2 example, level is nested under fields:

{
    "id": 12345,
    "objectName": "songs",
    "fields": [
      {
        "type": "string",
        "id": 11059,
        "path": "artists[*].name",
        "level": "organization",
        "displayName": "artists"
      },
      {
        "type": "string",
        "id": 11060,
        "path": "songName",
        "level": "organization",
        "displayName": ""
      }
}

New /VDRs APIs

The VDR v2 engine includes the new collection of /VDRs APIs. A Postman collection for the API is available here (same link as earlier in this article), and will soon also be available via the API Docs in the UI.

Changing the VDR Engine

While the v2 engine is now the default for newly created VDRs, you can change whether you want to default to v1 or v2.

Note: If you are migrating to the v2 engine using the instructions below, any v1 VDRs in your organization will be converted to the v2 model.

You must be assigned an org-admin role and relevant permissions; if you do not have the required permissions, the functionality in the subsequent steps will not be accessible.

To change the default VDR engine, follow these steps:

After signing in to Cloud Elements, click the Security tab from the left-side toolbar, select Roles, and then click Organization Administrator.
Under the VDRs category column, locate and enable the Modify Organization VDR version privilege, and then click Update Roles in the top-right corner.
Make one of the following calls:
- To enable the v2 engine:
```
PUT /vdrs/upgrade/v2
```
- To enable the v1 engine:
```
DELETE /vdrs/upgrade/v2
```

A successful call will receive an empty Status 200 response.

Determining your Current Engine

If you do not know which engine your organization is utilizing for your newly built VDRs, you can check by either through the UI or an API call. In addition, the selected version is managed independently between staging and production environments; changing the selected version in one environment does not automatically carry over to others.

Checking the Engine via UI

Sign in to Cloud Elements and click API Docs in the top-right corner.
From the Platform API Documentation column on the left, click Organizations.
Under the Organizations APIs list, click GET /organizations/me.
Click Try it out, and then click Execute.
In the response body, find the vdrVersion parameter. The value listed indicates the engine being used.

Checking the Engine via API

Make the following API call: https://staging.cloud-elements.com/elements/api-v2organizations/me
In the response body, find the vdrVersion parameter. The value listed indicates the engine being used.