Overview

Oracle HCM Cloud application provides several features to extend the application’s capabilities beyond what is provided out-of-box. Extending the SaaS data model using flex fields is an important feature. In this blog, let’s take quick look at the types of important flex fields and how to access them over HCM REST API in detail.

Types of flex fields

Descriptive flex field and extensible flex fields are frequently used with HCM business objects. Here is a quick comparison of these two flex field types. To learn more about flex fields, refer to HCM Cloud online documentation for the current version.

Figure 1

Accessing flex fields over REST API 

HCM REST API is increasingly used by customers for integrations and extensions. So, an obvious question is how to enable access to the flex fields over REST API.  This will be necessary for accessing a person’s information on an extension web page or an extension mobile app, deployed on Oracle VBCS, for example.

Consider the new worker below, who is assigned “Employee” role.  If this person looks up info on an extension page, no data will be returned. I’ve shown a postman code snippet for the API call invoked to get DFFs on behalf this person.  Note that the user’s credentials are supplied in this example, but in runtime, IDCS oAuth or JWT token from fusion would be the right way to authenticate this user.  

curl --location --request GET 'https://<hcm_host_name>/hcmRestApi/resources/11.13.18.05/workers/<person_guid>/child/workersDFF' \

--header 'Authorization: Basic authtoken='

 The response would be a HTTP 403 Forbidden, because this person does have access to REST services and to own information over REST service. Now let’s look at the steps to make this API work for the new worker. These are the high level activities.

• Create a new role (or use an existing role, if already exists)
• Assign REST security function privilege and data privilege to one’s own information
• Assign the role to the new worker.

Note that for next worker onward, an existing role can be automatically assigned to new workers, so you need not repeat all steps.

Step-by-step instructions 

As a user with access to security console, navigate to security console and click on roles tab.  Follow the screens below to create a new role. I have named it “TEST_HCM_REST_JOB”.

Figure 2

Make sure to select HCM Job as role type and enter a description. Next, add a Function Security Policy to enable access to REST service, by clicking on “Add Function Security Policy” and selecting privilege “Use REST Service - Worker as Worker” as shows in the 2 figures shown below.

Figure 3

Figure 4

The crucial next step is to define data security policy. Without this step, worker will not see any data from the REST service. In the 3^rd step of “Create new role” flow, click on “Create Data Security Policy”. Select the values as shown below. For “condition name”, select “ORA:HCM:PER:PER_ALL_PEOPLE_F:View Own Record”.  For actions, select values relevant for the flex fields of interest. In this case, I’ve selected “View Person”.  See screenshots below.

Figure 5

Figure 6

Skip the next few steps and save and close to create the role.

Assign “TEST_HCM_REST_JOB” role to the new worker in security console.  We’re ready to test the API now. Run the REST request below, shown as Postman code. This code requests worker DFF over REST api. To test EFF, use the URL specific to EFF.

curl --location --request GET 'https://<hcmhostname>/hcmRestApi/resources/11.13.18.05/workers/<worker GUID>/child/workersDFF' \

--header 'Authorization: Basic <authtoken>'

This time the response is HTTP 200, with a value for “employeeRewardsPoints” DFF set in the HCM instance where I tested this request.

{

  "items": [

    {

      "employeeRewardsPoints": 500,

      "__FLEX_Context": null,

      "__FLEX_Context_DisplayValue": null,

      "links": [...],

  "count": 1,

  "hasMore": false,

  "limit": 25,

  "offset": 0,

  "links": [...]

}

Please leave questions or comments or connect with us at Cloud Customer Connect.