Access Oracle Sales Automation Data Using RESTful Services
Each API contains standard Oracle Sales
Automation objects and each object is associated with a REST Resource or Resource Collection. For instance, in the RESTful API the Opportunities resource endpoint is used to track information about a potential sale. However, before using Oracle Sales
Automation RESTful web services you must take into account the security requirements for gaining access, and also identify which web services to use, along with their corresponding supported methods and expected payload structures.
About Resources in Oracle Sales Automation RESTful APIs
Oracle Sales Automation provides a collection of REST resources for standard and custom objects.
An important concept in any RESTful API is the resource. A resource is an object with a type (for example, Opportunities), associated data, relationships to other resources, and a set of methods that operate on it. These resources are organized in a hierarchical fashion that includes:
-
Root resource: Corresponds to a logical object, like an Opportunity or Lead.
-
Sub-resource(s): These are resources that belong to a parent resource; for example a contact for an opportunity.
-
List of Values resource: A list of valid values that can be used when setting a value for a field. There are two types: Lookup (static list) or Dynamic (based on context).
Within the Oracle Sales Automation RESTful API, there are two types of resources: A single resource or a collection resource. A single resource can represent a single entity like an employee or a purchase order, while a collection resource can be more comprehensive like a list of employees or a list of purchase orders that can be paged.
About REST Support for Custom Objects
Oracle Sales Automation includes standard objects which account for many business needs and scenarios. However, in addition to standard objects, you can use the Application Composer tool to create both top-level custom objects and child custom objects if you have a unique business need.
Application Composer is a browser-based tool that business analysts and administrators (not just developers) can use to customize Oracle Sales Automation. By using this tool, you can make the types of data model changes which in the past were made only by developers. In the Application Composer tool you can make changes on the fly and they become immediately available for usage without having to sign back into the application, this includes the creation of Custom Objects which can be added to the Oracle Sales Automation RESTful API.
Performance Tips
To get the best performance out of Oracle Fusion Sales Cloud REST APIs, follow these tips.
- Query just the data that you need.
- Query just the data, not the metadata.
salesApi/resources/latest/opportunitiessalesApi/resources/latest/opportunities?fields=Name,OptyNum&onlyData=trueSearch for RESTful Resources Using “Describe” Endpoints
You can obtain specific details about the different Oracle Sales
Automation RESTful APIs by sending an HTTP GET request that returns a JSON object containing resource information and complementary metadata.
Get the Service Endpoints for RESTful Web Services
You can infer the name of an Oracle Sales Automation RESTful Web Service endpoint by specifying the service name instead of the keyword “describe” in the API URL.
About REST Operations and Payload Structures
The RESTful web service for each standard Oracle Sales Automation object provides several create, read, update and delete (CRUD) operations.
You can execute the following standard methods for interacting with either a singular resource or a resource collection through their URLs:
| Method | Available for a Singular Resource | Available for a Resource Collection |
|---|---|---|
| Get | Y | N |
| Post | N | Y |
| Patch | Y | N |
| Delete | Y | N |
About the Get Method
Use this method to query and retrieve information. However, the parameters used in the query to refine the search or narrow down the results in a singular resource are different from those used in a resource collection.
Parameters for both Singular and Collection Resources
The following parameters are used in the method for querying a singular resource as well as a collection resource:
| Parameter | Format | Description |
|---|---|---|
expand |
or
|
Returns the parent resource including its children. By default it doesn’t return any child. |
fields |
fields=<FieldName1>,<FieldName2>... |
Select only certain field(s) for which the information is required. |
onlyData |
or
|
Retrieve only data and not any resource URLs. By default all resource children URLs are returned. |
Parameters for Collection Resources
A GET method for collection resource uses the parameters discussed above as well as the following parameters:
| Parameter | Format | Description |
|---|---|---|
limit |
|
An integer greater than 0 that specifies the maximum number of items returned by the server. If no limit value is specified, the server will use a default limit value. |
offset |
offset=<Integer> |
An integer value that specifies the index of the first item to be returned. The offset index begins at 0. |
q |
|
Specify a filter condition to restrict the items returned in the collection. The value of this query parameter contains one or more expressions separated by “;”. For example Supported operators:
Special characters:
|
totalResults |
or
|
A Boolean value that specifies whether to return the total number of items that match the “q” query parameter.
|
orderBy |
|
Specifies the order of items returned in the response payload. The query parameter value is a comma separated string of field names, each optionally followed by a colon and the keyword If not specified, the server returns items in ascending order. |
finder |
|
Uses a predefined “query” which has its own special parameters. For example, the |
dependency |
|
Used for cascading List of Values resources. For example if a Location resource has a State field, those values will be derived from another States resource that returns a list of States for a specific Country (location). If for example Location is: US and State is CA. The States resource contains a list of all US States, but if user in the web page changes the locale to be Brazil, the way to retrieve all brazilian states would be with a call like this:
|
About the Post Method
Use this method to create a new item. The request media type header is:
application/vnd.oracle.adf.resourceitem+jsonFor example, to create a new opportunity under Opportunities resource , the request passes the new Opportunity name parameter in a JSON object:
{
"Name" : "New Opportunity Name"
}The response body of the JSON object returned by the POST request would be something like this:
{
BudgetAvailableDate: null
BudgetedFlag: false
PrimaryOrganizationId: 204
ChampionFlag: false
CreatedBy: "SALES_ADMIN"
CreationDate: "2015-06-04T03:08:27-07:00"
CurrencyCode: "USD"
SalesMethodId: 100000012430001
SalesStageId: 100000012430007
Name: "New Opportunity Name"
OptyId: 300100111705686
OptyNumber: "CDRM_332708"
OwnerResourcePartyId: 3807
StatusCode: "OPEN"
PrimaryRevenueId: 300100111705687
SalesMethod: "Standard Sales Process"
SalesStage: "01 - Qualification"
DescriptionText: "Looking for the Right Contacts, Characteristics,
Determining the Need, Budget and Sponsor"
AverageDaysAtStage: 30
MaximumDaysInStage: 800
PhaseCd: "QUALIFICATION-DISCOVERY"
QuotaFactor: 3
RcmndWinProb: 0
StageStatusCd: "OPEN"
StgOrder: 1
EffectiveDate: "2015-06-24"
Revenue: 0
WinProb: 0
PartyName1: "Charles Taylor"
DownsideAmount: 0
UpsideAmount: 0
EmailAddress: "firstname lastname@orcl.com"
ExpectAmount: 0
ForecastOverrideCode: "CRITERIA"
SalesChannelCd: "ZPM_DIRECT_CHANNEL_TYPES"
…
}About the Patch Method
Use this method for making partial updates to a resource. Only the fields contained in the request body will be updated.
The request media type is:
application/vnd.oracle.adf.resourceitem+jsonFor example, to update an existing Opportunity from Oppurtunities resource, the HTTP PATCH request passes the following JSON object as the request body:
{
"Name": "Opportunity Name Updated"
}The response from this request is a JSON object similar to this:
{
BudgetAvailableDate: null
BudgetedFlag: false
PrimaryOrganizationId: 204
ChampionFlag: false
CreatedBy: "SALES_ADMIN"
CreationDate: "2015-06-04T03:08:27-07:00"
CurrencyCode: "USD"
SalesMethodId: 100000012430001
SalesStageId: 100000012430007
Name: "Opportunity Name Updated"
OptyId: 300100111705686
OptyNumber: "CDRM_332708"
OwnerResourcePartyId: 3807
StatusCode: "OPEN"
PrimaryRevenueId: 300100111705687,
SalesMethod: "Standard Sales Process"
SalesStage: "01 - Qualification"
DescriptionText: "Looking for the Right Contacts, Characteristics,
Determining the Need, Budget and Sponsor"
AverageDaysAtStage: 30
MaximumDaysInStage: 800
PhaseCd: "QUALIFICATION-DISCOVERY"
QuotaFactor: 3
RcmndWinProb: 0
StageStatusCd: "OPEN"
StgOrder: 1
EffectiveDate: "2015-06-24"
Revenue: 0
WinProb: 0
PartyName1: "Charles Taylor"
DownsideAmount: 0
UpsideAmount: 0
EmailAddress: "firstname_lastname@orcl.com"
ExpectAmount: 0
ForecastOverrideCode: "CRITERIA"
SalesChannelCd: "ZPM_DIRECT_CHANNEL_TYPES"
…
}About the Delete Method
Use this method to delete a resource. It doesn’t require a request body.
For example, to delete an Opportunity object from the Opportunities resource, the DELETE request needs to be made directly to the URI of the child Opportunity resource to be deleted, without passing any parameter to it:
https://<crm_server:PortNumber>/salesApi/resources/latest/opportunities/<OpportunityNumber>
About the Custom Action Methods
Sometimes, a resource exposes a custom action that does not fit into the CRUD standard. A custom action is always invoked with POST (for both singular and resource collections) and its request media type is:
application/vnd.oracle.adf.action+jsonThe response media type is:
application/vnd.oracle.adf.actionresult+jsonFor example, in Oracle Sales
Automation, the leads resource under https://<crm_server:portNumber>/salesApi/resources/latest/describe/leads/ has a custom action to convert a lead to an opportunity called: convertLeadToOpty.
{
"name" : "convertLeadToOpty",
"parameters" : [ {
"name" : "leadId",
"type" : "number",
"mandatory" : false
} ],
"resultType" : "string",
"method" : "POST",
"requestType" : [ "application/vnd.oracle.adf.action+json" ],
"responseType" : [ "application/json", "application/vnd.oracle.adf.actionresult+json" ]
},Think of a custom action as a series of steps, a process, or a combination of different CRUD operations to achieve a specific goal. In the example above the request body of a Custom Action has to pass the “name” that is going to be that custom action name (i.e. convertLeadToOpty), and optionally an array of input parameters for the custom action (i.e. leadId).
Usually the JSON body of the POST request contains:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "Action execution representation.",
"description": "Represents the action execution and its
parameters.",
"properties": {
"name": {
"type": "string",
"description": "Action name."
},
"parameters": {
"type": "array",
"description": "Parameter name/value pair.",
}
},
"required": [
"name"
]
}The JSON response object holds the result of the custom action method in the “results” field.
About Batch Support
To improve performance, multiple operations can be combined into a single HTTP request by sending a JSON object containing a field named: “parts” as an array of objects. Each object within the array contains a unique id, a relative path to the resource, an operation, and optionally a payload.
The JSON schema of the HTTP request is:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"title": "Batch execution",
"description": "Group multiple requests together ('part').",
"definitions": {
"Part": {
"type": "object",
"allOf": [
{
"properties": {
"id": {
"type": "string",
"description": "An identification
provided by the client to distinguish each part provided in the
batch request."
},
"path": {
"type": "string",
"description": "Resource's location."
},
"operation": {
"type": "string",
"enum": [
"get",
"create",
"update",
"replace",
"delete"
],
"description": "The operation that will
be performed."
},
"preconditionSucceeded": {
"type": "boolean",
"description": "This attribute is set in
the batch response only when ifMatch or ifNoneMatch are provided in
the request. It will be 'true' if the precondition
(ifMatch/ifNoneMatch) was satisfied, otherwise 'false'."
},
"payload": {
"oneOf": [
{
"$ref": "resource-item.json",
"description": "The payload that
will be used in the operation. Example: a resource instance should
be provided in order to execute a 'create'."
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"path",
"operation"
]
}
],
"anyOf": [
{
"properties": {
"ifMatch": {
"type": "string",
"description": "This attribute is
analogous to the If-Match header. It represents a precondition to
execute this operation. The value can be null (same effect of 'If-
Match: *') or an array of resource versions."
}
}
},
{
"properties": {
"ifNoneMatch": {
"type": "string",
"description": "This attribute is
analogous to the If-None-Match header. It represents a precondition
to execute this operation. The value can be null (same effect of
'If-None-Match: *') or an array of resource versions."
}
}
}
],
"description": "Represents a request."
}
},
"properties": {
"parts": {
"type": "array",
"items": {
"$ref": "#/definitions/Part"
},
"description": "Array that represents multiple
requests."
}
},
"required": [
"parts"
]
}
For example, the following request will fetch an existing employee and update another employee:
POST /myapi/resources/latest/hremployees HTTP/1.1
Host: example.oracle.com
Content-type:application/vnd.oracle.adf.batch+json
{
"parts": [
{
"id": "part1",
"path": "/latest/hremployees/101",
"operation": "get"
},
{
"id": "part2",
"path": "/latest/hremployees/102",
"operation": "update",
"payload": {
"Salary": 18000
}
}
]
}
The response of the previous request uses the same media type as the request and returns a JSON object such as:
{"parts":[
{
"id":"part1",
"path":"/latest/hremployees/101",
"operation":"get",
"payload" : {
"EmployeeId" : 101
…
},
{
"id" : "part2",
"path" : "/latest/hremployees/102",
"operation" : "update",
"payload" : {
"EmployeeId" : 102,
} ]}Test an Oracle Sales Automation RESTful Web Service Request
To test a RESTful API and get the required data, you can use the cURL command line tool to transfer data from or to a server using one of the supported protocols such as HTTP or HTTPS.