SAP Cloud Platform Open Connectors

Creating Common Resources

A common 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 common resource at the organization level and map connector resource data to it for transformation. You can create a common resource based on an existing resource (template, connector resource, or existing common resource) or as an entirely new resource. This guide includes instructions for both methods.

Important: Only users at the organization level can create common 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 common resource, go to the steps that match how you plan to create the resource:

Create a New Common Resource

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

Define a Common Resource in the UI

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

  3. Enter a name for your common resource, such as "myContact" and click SAVE.  The Create page shows your new common 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 Common 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 common 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.openconnectors.us2.ext.hana.ondemand.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 common resource Based on Another

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


Define a New Common Resource Based on Another via API

Endpoints used:

  1. Call the following, replacing {objectName} with the name of the common 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 common 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 Common 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 Common Resource

curl -X POST \
  https://api.openconnectors.us2.ext.hana.ondemand.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"
      }
      ]
    }
  }
'