X

It's All About the Platform.

Understanding the Custom Object RESTful Web Services

Richard Bingham
Senior Development Manager

Overview

Starting from Release 10 RESTful web services were introduced, as explained in these articles. Along with using these services to interact with standard sales and transactions you can also use these to work with Oracle Sales Cloud's custom object records. This post introduces the basic steps required, including several key facts that should help you get started faster. Additional posts will look at specific parts of working with the custom object REST services in more detail.

To interrogate the RESTful services available for each of your custom objects, follow the following navigation:

1. Go to Application Composer - Click the Custom Objects (title) in the sidebar. Obviously this applies inside each application container (Sales or Common).
2. Look at the "Rest Resource" column in the table (it may be truncated off to the right, if so reorder the columns in the table to see it). Note that to get REST services for your custom objects created before Release 10 then you'll need to run the related MetaData Upgrade task.
3. As shown below, click on the Service and the Describe links, re-login using your applications user, to get the URI and details on the service.

 

Throughout this article we'll use a Sales Project custom object, with the API name SalesProject_c. Note where this value is used (e.g. in the resource) and replace it with your custom object API name.

 

Querying Records

Using the RESTful API you can return either all records or just one specific record using the REST API. At this time the criteria for specifying one record is the Id attribute. Obviously if you have more specific requirements then the equivalent SOAP services have findCriteria SDO's that allow for detailed queries.

To query all records in the RESTful API you create a HTTP request of type "GET" with the following URI elements combined:

  • endpoint: https://[yourCRMHost].oracleoutsourcing.com
  • resource: /salesApi/resources/latest/SalesProject_c/

To query just one record you use the same endpoint value with the Id of the record you want on the end of the resource value, such as:

  • https://[yourCRMHost].oracleoutsourcing.com/salesApi/resources/latest/SalesProject_c/300000115712415

Neither request requires any additional parameters or a payload. You'll obviously need to add authorization (basic) using your applications user and password and this will govern the data you can access.

The JSON response (always of content type application/json) provides full details for each custom object record, along with some collection information at the end. The following is an illustrative sample of the response for a SalesProject_c custom object records.

     {   "items":    [  {
         "Id": 300000115712414,
         "RowType": "SalesProject_c",
         "RecordName": "Discount on Product Y",
         "CreatedBy": "alan.hooper",
         "CreationDate": "2016-01-14T10:48:38+00:00",
         "LastUpdatedBy": "alan.hooper",
         "LastUpdateDate": "2016-01-14T10:48:55+00:00",
         "LastUpdateLogin": null,
         "CpdrfVerSor": null,
         "UserLastUpdateDate": null,
         "CpdrfLastUpd": null,
         "CpdrfVerPillar": null,
         "JobDefinitionPackage": null,
         "RequestId": null,
         "JobDefinitionName": null,
         "CurrencyCode": "USD",
         "CurcyConvRateType": "Corporate",
         "CorpCurrencyCode": "USD",
         "SourceType": "SALESPROJECT_C",
         "AttachmentEntityName": "SalesProject_c",
         "PKProxy": "300000115712414",
         "IsOwner": "true",
         "links":   [  { ... }  ]
      }
   "count": 1,
   "hasMore": false,
   "limit": 25,
   "offset": 0,
   "links": [   { ... }]
}

Creating Records

Use the following steps to create a new record for your custom objects. Note that custom object records can still be imported in bulk using the import functionality as explained here.

1. Set the HTTP request type to "POST".

2. Keep the same basic URI for the service, constructed from the following two values, for example:

  • endpoint: https://[yourCRMHost].oracleoutsourcing.com
  • resource: /salesApi/resources/latest/SalesProject_c/

3. Set the request's media type to the following specific value:

  • application/vnd.oracle.adf.resourceitem+json

Note that you'll get error "CannotParseContentException: The content type is not a ADFm REST entity" with the standard "application/json" request media type.

4.Your payload only needs the REQUIRED attributes for you object record, so for my simple SalesProject this is just the RecordName, so my payload is simply:

{
"RecordName" : "Sales Project ABC"
} 

Note you do not need the object name (SalesProject_c) as this is defined in the resource in the URI. No additional parameters are needed in the request.

 

Updating Records

To make changes to your existing custom objects use the following steps.

1. Set the resource part of the URI to include the Id value of the record you wish to update at the end, such as /salesApi/resources/latest/SalesProject_c/300000115712415

2. Define a HTTP request as a "PUT" type. Note that the documentation states that PATCH is supported however our testing contradicts that. Ensure the media type remains as application/vnd.oracle.adf.resourceitem+json.

3. In the payload just include the attributes which you wish to change, such as

{
"RecordName" : "Changed SalesPrj"
} 

 4. Check the response to verify the record has been updated as intended.

Deleting Records

To remove individual custom object records from your system use the following steps:

1. Set the resource part of the URI to have at the end the Id value of the
record you wish to delete, such as
/salesApi/resources/latest/SalesProject_c/300000115712415

2.
Define the HTTP request as a "PUT" type. Note that the documentation states
that PATCH is supported however our testing contradicts that.

3. The successful response will be empty, and if there is a problem you'll get a descriptive error. If the Id you specified is wrong you'll receive the message "Could not find the element in the tree."

Examples and Documentation

The following embedded video shows a simple example of interacting with the custom object RESTful web service.

In addition to the articles mentioned above, you can also look at the product documentation, specifically the whitepaper "Oracle Sales Cloud Using RESTful Web Services" in chapter 45 Custom Object Services.

Join the discussion

Comments ( 5 )
  • guest Wednesday, July 27, 2016

    I am not able to get any message when using describe in Restful Resource for a custom object. Is there any specific setting which should be changed to activate the use of Rest api in app composer?


  • Oliver Steinmeier Wednesday, August 10, 2016

    Hello, are you by any chance using Chrome? In my experience Chrome doesn't render the /describe response; it works for me in Firefox, though.

    There is also a bug that I have been tracking down recently that causes the /describe to fail if the custom object has a field of type "Record Type". Is that the case for you? Can you reproduce the problem with a very simple custom object with just one field?

    Thanks,

    Oliver

    Fusion Apps Developer Relations


  • guest Friday, October 14, 2016

    Hi,

    I am trying to delete task of a project but getting error like...oracle.adf.internal.model.rest.core.exception.ResourceNotFoundException: Could not find the element in the tree. KeyString: (Task_ID)KeyPath:


  • Genti Wednesday, March 1, 2017

    I am facing an issue while attempting to describe Oracle Sales Cloud resources.

    http://stackoverflow.com/questions/42503488/metadata-response-gets-chopped-by-oracle-sales-cloud-rest-api

    Any insight?

    Thank you in advance!


  • Oliver Steinmeier Thursday, March 2, 2017

    Genti,

    no insight. I just tried it in our environment, which has plenty of customizations, and it works fine for Account.

    Does it fail for all objects for you, or only Account? What's "special" about account?

    My recommendation is to file a service request with Support.

    Thanks,

    Oliver

    Fusion Apps Developer Relations


Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.