SAP Open Connectors

Creating and Managing Common Resources

Last Modified on 08/30/2021 12:57 pm EDT

On this page

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

Important: Only users at the account level can create common resources, but users at any level can map fields at the instance level. If you are not a user at the account level, skip to Transforming Fields.

Create a New Common Resource

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

Create a Common Resource in the UI

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

    The Create page shows your new resource.

    New Resource from Scratch 

  3. Enter a name for your common 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 Account Level Fields section, click Add.

  6. Click Save.

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

Create a Common Resource with the API

Make a POST /accounts/objects/definitions request.
curl -X POST \
  'https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/accounts/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":"account"
  }
}'

Request Body Parameters

objectNameThe name of the common 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 account or instance. Account users can create fields at the accountor instance level.Optional

Create a New Common Resource by Importing a JSON Payload

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

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

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

Clone from a Common Resource Template

Common 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 connectors that you select. The cloning process creates default mappings at the connector level, so later, when you authenticate an connector instance, the default mappings apply to it. 

  1. Access the Common Resources page.
  2. Click common resource 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 connector 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 Common Resource 

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

Clone a Common Resource in the UI

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

    The Create page shows your new resource with a default account-level field of id.

  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 common 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 Common Resource with the API

Endpoints used:

  • GET/accounts/objects/{objectName}/definitions
  • POST /accounts/objects/definitions
  1. Make a GET /accounts/objects/{objectName}/definitions request, replacing {objectName} with the name of the common resource that you want to clone.
    curl -X GET \
  'https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/accounts/objects/myResource/definitions' \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \
  -H 'Accept:application/json'
  2. Compose a POST /accounts/objects/definitions request.
  3. Copy the fields array in the response from step 1 to the JSON body forPOST /accounts/objects/definitions.
  4. Submit the POST /accounts/objects/definitions request with the fields array from step 1.
    curl -X POST \
  'https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/accounts/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":"account"
  }
}'
  5. Continue to the next step: map fields to create a transformation.

Request Body Parameters

objectNameThe name of the common 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 account or instance. Account users can create fields at the accountor instance level.Optional

Clone a Resource From a Connector

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

    The Create page shows your new resource with a default account-level field of id.

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

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

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

View Your Common Resources

To see all of your common resources in the My Resources catalog, click Common Resources on the left navigation menu.

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

Sorting Common 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 Objects with the API

Get a list of common resources with GET /accounts/objects/definitions

curl -X GET \
  https://api.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/accounts/objects/definitions \ 
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \
  -H 'Accept: application/json' \

Rename Common Resources

When you rename a common 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 Common Resource in the UI

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

Rename a Common Resource with the API

Change the name of a common resource at the account or instance level by passing a new objectName in the request body of the following endpoints:

  • PATCH /accounts/objects/{objectName}
  • PATCH /instances/objects/{objectName}

If the common 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 common 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.openconnectors.us2.ext.hana.ondemand.com/elements/api-v2/accounts/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":"account"
}

Related Information

  • None
User Icon

Thank you! Your comment has been submitted for approval.