SAP Cloud Platform Open Connectors

Introducing Common Resources v2 Engine

By default, any new common resources (COs) created in new user organizations across environments now utilize the CO 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 COs to use.

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

Differences between v1 and v2

New Data Structure

For COs created using the v1 engine, the level property exists in the root level of the CO object. However, for COs 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 CO 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 CO Engine

While the v2 engine is now the default for newly created COs, 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 COs 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 CO engine, follow these steps:

  1. After signing in to SAP Cloud Platform Open Connectors, click the Security tab from the left-side toolbar, select Roles, and then click Organization Administrator
  2. Under the COs category column, locate and enable the Modify Organization CO version privilege, and then click Update Roles in the top-right corner. 
  3. 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 COs, 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

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

Checking the Engine via API

  1. Make the following API call: http://api.openconnectors.ext.hanatrial.ondemand.com/elements/api-v2/organizations/me
  2. In the response body, find the vdrVersion parameter. The value listed indicates the engine being used.