Wednesday, February 3, 2021

#828 Oracle HCM Integration via the HCM Adapter / REST API - Managing Employee

 I am just trying out the HCM REST APIs via the OIC HCM adapter - 

In this post I will cover create, retrieve, update employee.

Create Employee 

The first thing I want to do is create a new employee using the REST api - this I can do so via the HCM Adapter.

Starting point for me is trying out the api call in Postman. The HCM REST api doc is available here

There is an example request payload mentioned - 

I simplify this somewhat -

So what have we got here? Basic data about the new employee and his job assignment. There are a lot of IDs in the payload, so let us look at them -

LegalEntityId - The legal entity for which the employee works. If you're new to HCM and need to read up on enterprise structures, then do so here

Now there is a REST call to retrieve the LegalEmployerLOV, but there is also the view - 

However, valid Legal Entity Ids can be found by querying the HCM DB views -

SELECT legal_entity_id, name FROM hr_legal_entities

Now, in this case, I did not find the entry - 300000046974965.

Then my esteemed HCM colleague, Nev, pointed me to the source of the view - this is included in the docs here

Nev advised me to drop the haotl.LANGUAGE =USERENV('LANG') criterion.

I did so and quelle surprise - 

BusinessUnitId - the unit within the entity for which the employee works.

SELECT bu_id, bu_name FROM fun_names_business_units_v

Job_id - id of the job for which the employee is hired.

SELECT job_id, name, job_code FROM per_job

SalaryBasisId - the basis of the salary to be paid

SELECT salary_basis_id, display_name, name FROM  cmp_salary_bases_vl

ManagerId - my starting point for this value was the result of a GET on all employees. I just picked one value from another employee and used it here.

In my case the value was - 300000047663122

I query this emp as follows - 

I execute the REST request in Postman and check out the result in HCM -

Doing the same in OIC

Let's switch now to OIC, now that we have this working in Postman.

I create a Lookup for Business Unit Ids, Job Ids etc.

I create an app-driven orchestration, with a REST trigger.

I drop the HCM adapter and configure the invoke as shown at the top of this post.

Now to the mapping - the default view in the mapper is the functional view - which can be somewhat challenging when one is looking for the exact same field names as the REST payload, defined in the api docs.

An example - 


Granted, one can work out First Name, Last Name etc. but it can be challenging for other fields.

So simply switch to the Developer view - note Title changes to Salutation

I use the Mapping Tester to check that I've mapping all the required fields -

Mapping Response - essentially just the PersonId

I activate and test -

I check out Larry in HCM - 

I now have the personId /empId - 300000205916350

I can use this to GET the employee - again, first test in Postman -

Now to update - 

this is a PATCH request against the self link returned by the GET.

The hashkey contained in the url above is used an the unique employee id.

I try this out in Postman - updating Larry's middle name to Gary.


Ok, so let's do this in OIC

Updating HCM Emps via OIC

This will be done in an app-driven orchestration that GETs the employess, based on PersonId, and then updates the employee, setting the MiddleName to a value that rhymes with Larry.

So the Request contains 2 fields - PersonId and NewMiddleName.

GET Emp HCM adapter configuration - 

Mapping for GetAll -

I test this, before proceeding -

Here is the result - 

Now to the update...

I create a new variable in the AssignEMPUID action - the key to update the right employee has been returned by the GetEmp action.

href has the following format - 

We are interested in the hashkey after /emps/

I use the substring-after() function to extract this.

The Action for UpdateEmployee is configured as follows - 

Now to the mapping - 

Let's test this, with the NewMiddleName of Cary.

Validate in HCM - 

No comments: