Worker REST API of Oracle HCM Cloud | Create, Get & Update a Worker

In this post I have tried to explain how we can use Create, Get & Update Worker REST API of HCM cloud with one simple example.

Knowledge :👀

You can use Oracle HCM REST APIs to view and manage data stored in Oracle HCM Application Cloud and can be used as a bridge between external applications and oracle HCM Cloud.

Article Overview :

        1. Will create one worker by invoking Create Worker API

        2. after that will get the same worker detail which we created above by invoking Get Worker API

        3. and at the last will update the same worker detail by invoking Update Worker API

Create a Worker 

POST

/hcmRestApi/resources/11.13.18.05/workers

• Open SoapUI Tool (you can download it from internet). Click on REST icon.

Knowledge :👀

SoapUI Tool : SoapUI is an open-source web service testing application for Simple Object Access Protocol (SOAP) and representational state transfers (REST)

• Paste the Create Worker REST API URI. Below is a sample format of Worker REST API URI and then click OK. 

                    https://<your HCM domain name>/hcmRestApi/resources/11.13.18.05/workers

• Select Method ='POST' and then add Basic Authorization i.e. Enter user credentials of your HCM Cloud Environment. [check below image for your reference]

• For Create Worker operation we need to pass Headers. So lets configure the Headers. Click on ➕ icon 

• Paste Effective-Of and then click okay.

• In the value column , paste RangeStartDate=2000-01-01

• Below is the JSON Payload with minimum columns that need to pass to Create a Worker. 

Please Note :  LegalEmployerName ,BusinessUnitName and LegislationCode, these element value are application specific. You can't use the same which I have used. So update their value in the JSON payload according to your HCM application and then Paste the payload in SoapUI .

{

      "phones":       [

                  {

            "PhoneType": "W1",

            "PhoneNumber": "9999999991",

            "FromDate": "2020-01-01",

            "PrimaryFlag": true

         }

      ],

      "workRelationships": [      

  {

         "LegalEmployerName": "<!-ENTER VALUE--> ",

         "WorkerType": "E",

         "PrimaryFlag": true,

         "StartDate": "2020-01-01",

         "assignments": [         

{

            "ActionCode": "HIRE",

            "BusinessUnitName": "<!-ENTER VALUE--> "

           

         }

]

      }

  ],

      "names": [      

  {

         "LegislationCode": "<!-ENTER VALUE-->",

         "LastName": "Lal",

         "FirstName": "Chaman",

         "Title": "MR."

      }],

      "addresses": [      

  {

         "AddressLine1": "Near Red Fort",

         "Country": "IN",

         "TownOrCity": "Delhi",

         "AddressType": "HOME",

         "PrimaryFlag": true

      }]

}

• After pasting the payload, click Run  ➤ . You can see the message in the Response window  : 201 Created. Worker Created successfully in the HCM cloud application. Please Note : Copy the Person Number value which you get in he SoapUI response window and save it. We need it later in this article during Get & Update API call.

Create Worker Response Payload

Get a Worker 

GET 

/hcmRestApi/resources/11.13.18.05/workers/{workersUniqID}

Lets fetch the same worker details which we have created above using Create Worker API.

• Create a new REST Project and paste the below URI

                    https://<your HCM domain name>/hcmRestApi/resources/11.13.18.05/workers

• Add the Basic Authentication same as we did above (in Create Operation). Select HTTPS Method : Get and then Click on ➕ icon and add below query parameter because we just need detail of the worker whose Person Number is '100216' (this is the same person number which I have copied above from Create Worker Response Payload)

• Name : q
• Value : PersonNumber='100216' (Note :  in my case it is 100216, you have to enter value which get generated in your case during Create Worker API Call)

Knowledge :👀

• If we don't pass any query parameter , we will get all worker details in the response payload.
• To decrease the size of the resulting payload, specify which attributes should be returned by using the fields parameters :  GET   

        https://<your HCM domain name>/hcmRestApi/resources/11.13.18.05/workers?fields=PersonNumber

• Click Run ➤ and then click JSON tab to see the response payload.

• If you want to see the complete details of the worker i.e. its child elements also, then we need to add one more parameter. We have to add 'expand:all' parameter Then click run button ➤ 

• Name : expand
• Value : all

• You can see in above image, this time we get all the child elements also in the response payload. This way we have successfully tested GET Operation. Now do one thing expand the addresses element and copy 'href' URL from its links. We need this later for UPDATE operation.

Knowledge :👀

Self Link (i.e href url used above) is used to get access to a specific resource. You can use Self Link to get specific attributes of a child resource

Example : GET

https://<HCM Domain        URL>/hcmRestApi/resources/11.13.18.05/workers/00020.....908/child/addresses/00020000000EACE...00?fields=DisplayName,FirstName,LastName;assignments:JobId,DepartmentId

Update a worker

PATCH

/hcmRestApi/resources/11.13.18.05/workers/{workersUniqID}

Now lets try to update the same worker details which we have created above (i.e. Person Number : '100216') using UPDATE WORKER API. Lets Update its Addresses - "AddressLine1" value. Currently its value is " Near Red Ford "  (check below image ), will update it to "Near India Gate"

• Create a new REST API Project and Paste the copied 'href' url (address element href) which we have copied above from Get operation Response payload. So now you can ask - why that specific address href ?? 🤔Because our requirement is to update Addresses Element Value. So we need Addresses href. If your equiremnt is to Update Name, you need to use Name Href URL for update.

Sample href URL :  https://<HCM Domain        URL>/hcmRestApi/resources/11.13.18.05/workers/00020.....908/child/addresses/00020000000EACE...00 

Knowledge :👀

To Exclude all links from the response payload , you can use onlyData parameter. It can help you to reduce the size of  retrieved message :

GET

https://<your HCM domain name>/hcmRestApi/resources/11.13.18.05/workers?fields=DisplayName,FirstName,LastName,HireDate&onlyData=true

• Add the basic authorization and select HTTP method as "PATCH" 

• For Update operation we need to pass Headers. So lets configure the Headers. Click on ➕ icon and Paste 'REST-Framework-Version' and click ok

• Now enter 4 as its value.

• Similarly add the below two headers and its value (take reference from from below image)

Header   : Effective-Of 

Value    : RangeMode=UPDATE;RangeStartDate=2020-01-01;RangeEndDate=4712-12-31

Header   : Content-Type

Value    : application/vnd.oracle.adf.resourceitem+json

• After that lets pass the data which we want to update. In my case I am updating AddressLine1 of Addresses.  So lets passes the Updated value (as below) in the payload and then click run ➤ 

 {

     "AddressLine1":"Near India Gate"

  }

• You can clearly see the Update is successful. AddressLine1 value updated to "Near India Gate" which was " Near Read Fort" earlier.

To cross check the Address got updated or Not, you can run the Get Worker API for the same worker again and check the AddressLine1 Value 😀

For Further detail, you can check Oracle Document