REST APIs in Oracle HCM Cloud – Introduction

In this article I would like to tell you about new REST APIs in Oracle HCM Cloud that have become available since Oracle HCM Cloud Release 10.
Although the SOAP API continue to be supported, all new development is focused exclusively on the REST API. And this fact makes me happy because Oracle keeps pace with new technologies.

Oracle Fusion Applications provides REST APIs that customers can use to access data or integrate with external applications. To perform an operation, you can use a well-defined resource URL and a standard HTTP(S) method.

REST APIs in Oracle HCM Cloud – Architecture

The REST API services of Oracle Fusion Applications are based on the RESTful architecture style. The applications use simple HTTP/S requests to create, update, read, and delete data. All APIs support JSON.

A RESTful architecture is based on the following principles:

  • Stateless: The client holds the session state and each request contains the necessary information for the server to handle the request.
  • Caching: Resources can be cached whenever it’s possible. Response header indicates whether data is cacheable or not. Cache headers are supported to improve performance.
  • Layered system: mediator can exist between client and resource server
  • Uniform-interface:
    • All resources are identified by named URLs
    • Objects are manipulated though resource representation
    • Metadata is provided along with each resource
    • Hyper links are returned along with each response.

SOAP vs REST

In the following table you can see differentiation between SOAP and REST protocols:

In my opinion REST provides the following major benefits to service consumers:

  • Standardization
  • Discoverability
  • Mobile Apps much easier
  • Less complicated, more functional

REST API Services

REST API Service methods

  • Composite Resource that includes most commonly referenced child objects flattened into main resource. Oracle provides new media type: application/vnd.oracle.adf.resourceitem+json.
  • Operations
    • GET (Read)
    • POST (Create)
    • PATCH (Update)
    • DELETE

Security

  • Calls to the web services require a username/password or SAML token
  • Data returned will be subject to Oracle HCM Cloud authorization rules for the calling employee
  • Payload is transferred as encrypted over HTTP(s).

Resources

Here are details on making a simple GET request to return all records, just to illustrate what is available via the REST API. The URL to the API for a Oracle HCM Cloud instance looks like this:

http://<host>:<port>/hcmCoreApi/resources/11.1.10/<resource>

Here are the main REST resource services available in HCM Release 10:

  • /emps  – returns all employees with links to all child resources. Also supports POST and PATCH operations.
  • /locations – returns all locations.
  • /organizations – returns all organizations with their classification.
  • /jobs – returns all jobs.
  • /jobFamilies – returns all job families.
  • /positions – returns all positions.
  • /grades – returns all grades.

Complete list of all REST APIs in Oracle HCM Cloud and Endpoints for Oracle Global Human Resources Cloud Release 10 you can find here: https://docs.oracle.com/cloud/latest/globalcs_gs/FARWS/index.html

Please note that REST services do not implement the HCM Transaction Model, and therefore approvals are not initiated when an action (create, update, delete, and so on) occurs on the resources.

Child Resources for employee

You can perform operations on the parent resource or its child resources. To perform operations on a child resource, you need to retrieve the correct link to the child resource by first querying the parent resource. This query returns links to all the child resources and also a link to the parent resource. You can use these child links to perform operations on the child resources.
Note: To add a new child resource, perform a POST operation on the child collection URL. To modify an existing child resource, perform a PATCH operation on the specific child resource {id} URL.

Samples

For testing REST APIs Oracle recommends to use cURL. cURL is a command-line tool for transferring data using URL syntax. It is available on most UNIX and Mac environments, and can be downloaded for Windows.

GET (Query)

You use finders to filter the parent resources based on the child resource attribute criteria. For example, the following URL can be used to get all employees given department:
?finder=findByAssignmentAttr;DepartmentName=ABC

 

Response Body

 

And of course you can use filters to query parent records:
?q=LastName=Jones

PATCH (Update)

For example, to update an e-mail address, you need to:

  1. Query the employee
  2. Find {id} for the parent resource in the response.
  3. Perform a PATCH operation on this URL to update an e-mail address to that employee.

Let me start.
First I am going to get particular employee record:
curl -u <user:password> “https://zzz.oraclecloud.com/hcmCoreApi/resources/11.1.10/emps/?q=LastName=Jones

Response:

{
“items” : [ {
“Salutation” : null,
“FirstName” : “Vinnie”,
“MiddleName” : null,
“LastName” : “Jones”,
“PreviousLastName” : null,
“NameSuffix” : null,
“DisplayName” : “Jones Vinnie”,
“PreferredName” : null,
“Honors” : null,
“CorrespondenceLanguage” : null,
“PersonNumber” : “77002”,

“WorkEmail” : null, <———-!!!
“AddressLine1” : null,
“AddressLine2” : null,
“AddressLine3” : null,
“City” : null,

“MilitaryVetStatus” : “N”,
“CreationDate” : “2015-09-22T09:36:00+00:00”,
“LastUpdateDate” : “2015-09-22T09:36:21+00:00”,
“links” : [ {
“rel” : “self”,
“href” : “https://zzz.oraclecloud.com:443/hcmCoreApi/resources/11.1.10/emps/000200000069ACED00057372000D6A617…D9319925A8“,
“name” : “emps”,


“count” : 1,
“hasMore” : false,
“limit” : 25,
“offset” : 0,
“links” : [ {
“rel” : “self”,
“href” : “https://zzz.oraclecloud.com:443/hcmCoreApi/resources/11.1.10/emps”,
“name” : “emps”,
“kind” : “collection”
} ]
}

In the response body we got URL with {id} that we provide to the PATH operation.
I will use SoapUI to show an update operation:

Make sure that you provide additional required parameters for the header:
Content-Type: application/vnd.oracle.adf.resourceitem+json
Effective-Of: RangeMode=CORRECTION;RangeStartDate=2015-01-14

And of course you have to provide JSON payload for PATCH operation:
{
“WorkEmail”: “[email protected]

}

And finally to be completely sure that an update operation has been completed I will check it through UI:

 

 

 

———————

In conclusion, I would like to remind that REST APIs are still under controlled availability and you have to provide a clear justification to convince Oracle support to give an access to them.

Regards,
Volodymyr

8 responses on "REST APIs in Oracle HCM Cloud - Introduction"

  1. Thanks for the comprehensive details, very helpful. I tried GET operations and all are working fine.
    Got stuck with POST (New Hire) I am passing below payload
    {
    “HireDate” : “2017-01-01”,
    “Salutation” : “MS.”,
    “FirstName”: “AmyTest”,
    “MiddleName”: “M”,
    “LastName”: “MarlinTest”,
    “NameSuffix”:”Jr.”,
    “DisplayName” : “AmyTest MarlinTest”,
    “WorkEmail” : “MarlinTest”@yahoo.com”,
    “WorkPhoneCountryCode” : “1”,
    “WorkPhoneAreaCode” : “718”,
    “WorkPhoneNumber” : “-993-0000”,
    “Ethnicity”: “1”,
    “MaritalStatus”: “S”
    “LegalEntityId” : “300000000823729”,
    “NationalIdType”: “SSN”,
    “NationalId”: “000-00-0001”,
    “UserName”:”AmyTest”,
    “assignments” : [ {
    “AssignmentName”: “HRBL-FEB-0817”,
    “BusinessUnitId” : “100000000021403”,
    “ActionCode” : “HIRE”,
    “ActionReasonCode” : “HIREREPL”,
    “AssignmentStatus” : “ACTIVE”
    “AssignmentCategory”: “FR”,
    “WorkingAsManager”: “N”,
    }]
    }
    and header Content-Type: application/vnd.oracle.adf.resourceitem+json
    But in response I am getting full employee list and New Hire is not working
    REST – http:///hcmCoreSetupApi/resources/latest/emps

    Please Help

    Regards,
    Tarun

  2. Hi,

    Can you create blog how to run HCM Cloud BI Report through JAVA API?

  3. Super helpful blog post. Thanks mate!

  4. I’m doing an integration with Orcle HCM via REST, and now i have to do some actions with the employee, like promotion and resignation, but i don’t know how to do via REST api, I’ve tried send a PATCH with action codes like “PROMOTION” and “RESIGNATION” in the assignment, but doesn’t work. Can you help me?

  5. thanks for the information.

    i tried employee PATCH request for update employee details.

    but getting following error

    Unexpected character (‘<' (code 60)): expected a valid value (number, String, array, object, 'true', 'false' or 'null')
    at [Source: weblogic.servlet.internal.ServletInputStreamImpl@4ed83331; line: 1, column: 2]

    any idea for that ??

  6. Hi,

    This requires additional research and unfortunately we cannot provide the same in the blog. You can set up for a one-one-session to work on such specific solutions.
    https://erpwebtutor.com/ask-the-oracle-expert/

    Kind regards,
    Volodymyr

Leave a Message

top
ERPWebTutor
2011-2017, All rights reserved © A part of the Orison Consulting Group
PO Box 16014 San Juan Puerto Rico 00908
Email: [email protected]
Terms of Use
Contact Us
close slider

Contact