INTRODUCTION

Oracle publishes a set of HCM REST APIs to allow for programmatic access to work with various business objects.  The /emps resource is being replaced with the /workers resource as the only method for accessing employees and related worker types.  Worker types include employee, contingent worker, and pending worker.

I’ll first set out some general information, and then go into a couple of specific use cases.

IMPORTANT NOTE
As always, REST APIs are meant for small targeted operations only and not for bulk operations.  To retrieve large amounts of data please use HCM Extracts.  Ideally, REST calls to retrieve worker data should be done in response to an ATOM feed notification or other targeted use case.

 

/emps resource withdrawal

As of release 23D the /emps resource will be fully desupported and may be unavailable at any time after that release.  The only supported method for getting employee and worker info via REST APIs will be with the /workers resource.  This includes, but is not limited to, usage by any custom code, by Oracle Integration Cloud (OIC), any ATOM feed integrations, and for Alerts resources.

 

Information on the /workers resource

The /workers resource is currently available as a fully supported, published API and customers should immediately begin transitioning from the /emps resource to use /workers.  Current documentation on the /workers resource can be found in the Oracle Help Center online documentation for REST API for Oracle HCM Cloud (https://docs.oracle.com/en/cloud/saas/human-resources/23a/farws/api-workers.html) The security considerations for working with the /workers API have changed somewhat from the /emps API.  Please review the security requirements here: https://docs.oracle.com/en/cloud/saas/human-resources/23b/farws/WorkersAPI_Security.html

 

Impacted Areas

REST APIs using the /emps resource

You must rewrite any custom integrations that use the /emps REST API to use the /workers API instead. If you are using the roles resource under /emps, you will need to rewrite this to use the userAccountRoles resource under /userAccounts.

Important Note: /workers API has different, finer-grained security than /emps.  Take the opportunity to review the documentation referenced above in the section Information on the /workers resource

Also review the Customer Connect Office Hours presentation here: https://community.oracle.com/customerconnect/categories/ccc-events?eventname=603788-hcm-office-hour-integrations-march-2022

Below I’ll go into some example use cases on how the /workers API can be used.  In addition to those direct usages of the API, there are several other areas that need to be examined and modified.  Let’s take a look at those first.

ATOM Feeds

If you consume links returned by ATOM feeds, you must not use the /emps resource links in ATOM feeds.  Instead use the /workers links.  This relates specifically to links returned by querying ATOM feeds.

To illustrate, a result from querying an ATOM feed for a changed assignment looks something like this:

<entry>
    <title type="text">Doe, John's Assignment Updated</title>
    <summary type="text">Pending Worker Assignment Updated</summary>
    <content type="text">{
  "Context" : [ {
    "AssignmentId" : "300000012345678",
    "PersonName" : "Doe, John",
    "PersonNumber" : "123",
    "WorkEmail" : "work_john.doe100@someemail.com",
    "PrimaryPhoneNumber" : "",
    "PersonId" : "300000000001234",
    "PeriodType" : "P",
    "WorkerType" : "PWK",
    "DMLOperation" : "UPDATE",
    "EffectiveDate" : "2023-03-04"
  } ],
  "Changed Attributes" : [ {
    "AssignmentStatusType" : {
      "old" : "ACTIVE",
      "new" : "INACTIVE"
    }
  }, {
    "ActionCode" : {
      "old" : "ADD_PEN_WKR",
      "new" : "HIRE"
    }
  } ]
}
}    </content>
    <author>
        <name>COE_ADMIN</name>
    </author>
    <link href="https://server.oraclecloud.com:443/hcmRestApi/resources/latest/emps?q=PersonId=300000000001234&amp;effectiveDate=2023-03-04" rel="related" reltype="emps"/>
    <link href="https://server.oraclecloud.com:443/hcmRestApi/resources/latest/workers?q=PersonId=300000000001234&amp;effectiveDate=2023-03-04" rel="related" reltype="workers"/>
    <updated>2023-03-04T00:00:00.000Z</updated>
    <id>urn:uuid:1234567890ABCDEF1234567890ABCDEF</id>
    <published>2023-03-03T09:25:31.667Z</published>
    <link href="https://server.oraclecloud.com:443/hcmRestApi/atomservlet/employee/empassignment/1234567890ABCDEF1234567890ABCDEF" rel="self"/>
    <link href="https://server.oraclecloud.com:443/hcmRestApi/atomservlet/employee/empassignment/1234567890ABCDEF1234567890ABCDEF" rel="edit"/>
</entry>

Note the two related links of reltype emps and workers in the result. You must use the workers link from now on.

<link href=”https://server.oraclecloud.com:443/hcmRestApi/resources/latest/emps?q=PersonId=300000000001234&amp;effectiveDate=2023-03-04″ rel=”related” reltype=”emps“/>

<link href=”https://server.oraclecloud.com:443/hcmRestApi/resources/latest/workers?q=PersonId=300000000001234&amp;effectiveDate=2023-03-04″ rel=”related” reltype=”workers“/>

Alerts

You will need to end usage of resource alerts that use the /emps resource and recreate all of those alerts to use the /workers resource.

As an example of an alert that has been recreated you can examine the differences between Worker Hire Date (ORA-ORA-EMTOP004) and Worker Hire Date V2 (ORA-WRKOP004)  These illustrate what must change when creating a new version of the resource alert using the /workers resource.

 

worker hire alert - emps
Desupported alert using emps resource

 

 

worker hire alert - workers
V2 Alert using workers resource

 

You must make any changes to the alert in the UI.  It’s recommended to create a new version of the alert using the workers resource.

To determine which Resource Alerts reference the /emps resource you can do an export of Alerts using FSM by the process documented here: https://www.oracle.com/webfolder/technetwork/tutorials/obe/fusionapps/HCM/AlertsCompuserFSM_Import_Export/html/index.html

Once exported, you can download the configuration package and open in a zip file editor.  Traverse to find zip files stored in the \businessObjectData\ORA_HCM_ALERTS.zip\Alerts\ folder of the zip file. 

exported alerts

Those files (e.g. 1_Batch.zip) can be expanded to the file HRC_ALERTS.xml.  

exported alerts

Open the file in a text editor and search for <ResourcePath>/hcmRestApi/resources/latest/emps</ResourcePath>  Any custom alert that contains this element should be modified.  You can tell the name of the Alert by looking for the <Name> element.  The name is contained within a CDATA section.  This process should be used only to identify which alerts must be modified.  You must make any modifications to the alerts in the UI.

emps resource alert name
The alert JRL2 must be modified to use the /workers resource

 

For reference, here is a table listing the seeded alerts showing the V1 emps alerts and V2 workers alerts

Seeded alerts

 

Oracle Integration Cloud (OIC)

You must examine existing OIC integrations and modify or recreate any integrations using ATOM /emps resource links and /emps REST resources to use the worker links and resources as described above.  Please see https://docs.oracle.com/en/cloud/paas/application-integration/hcm-adapter/subscribe-atom-feeds-scheduled-integration.html for further info.

If using REST resources directly using the HCM Adapter, these must be reworked to use /workers

As an example, you can look for integrations using REST connections. Then within those integrations examine any REST endpoints to see if they use the /emps resource.  Modify those which do to use /workers instead.

REST connections
This REST connection is used by 9 integrations

 

 

REST endpoints
Look for REST connections that might use /emps

 

 

emps endpoint
Verify if /emps is used and modify to use /workers instead

 

Sample /workers use cases

IMPORTANT NOTE
As always, REST APIs are meant for small targeted operations only and not for bulk operations.  To retrieve large amounts of data please use HCM Extracts.  Ideally, REST calls to retrieve worker data should be done in response to an ATOM feed notification or other targeted use case.


Retrieving Assignments

There is a change in how the assignments are retrieved.  In /emps you query a list of assignments from an employee.  In /workers you query based on a period of service id (work relationship).

Some examples (these examples use REST-Framework-Version > 1):

In the following queries, all are against the /hcmRestApi/resources/11.13.18.05/workers resource.  I’m just varying the parameter passed.

I’m also limiting the fields returned to just a representative set.

To get assignments for a particular worker as of a certain date you add the PersonNumber to the query parameter, and then pass the effectiveDate:

/hcmRestApi/resources/11.13.18.05/workers?effectiveDate=2023-03-05&q=PersonNumber='778'&expand=workRelationships.assignments&onlyData=true&fields=PersonNumber;workRelationships:WorkerType,PrimaryFlag,StartDate;workRelationships.assignments:AssignmentNumber,ActionCode,EffectiveStartDate,EffectiveEndDate,AssignmentStatusType

 

The returned data shows two assignments as of March 5 2023:

{
   "items": [   {
      "PersonNumber": "778",
      "workRelationships":       {
         "items":          [
                        {
               "WorkerType": "E",
               "PrimaryFlag": true,
               "StartDate": "2023-03-03",
               "assignments":                {
                  "items": [                  {
                     "AssignmentNumber": "E778",
                     "ActionCode": "HIRE",
                     "EffectiveStartDate": "2023-03-03",
                     "EffectiveEndDate": "4712-12-31",
                     "AssignmentStatusType": "ACTIVE"
                  }],
                  "count": 1,
                  "hasMore": false,
                  "limit": 25,
                  "offset": 0,
                  "links": [                  {
                     "rel": "self",
                     "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000110D93418F71A0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800000186AF116C0078/child/workRelationships/300000044666110/child/assignments",
                     "name": "assignments",
                     "kind": "collection"
                  }]
               }
            },
                        {
               "WorkerType": "P",
               "PrimaryFlag": false,
               "StartDate": "2023-03-03",
               "assignments":                {
                  "items": [                  {
                     "AssignmentNumber": "P778",
                     "ActionCode": "HIRE",
                     "EffectiveStartDate": "2023-03-04",
                     "EffectiveEndDate": "4712-12-31",
                     "AssignmentStatusType": "INACTIVE"
                  }],
                  "count": 1,
                  "hasMore": false,
                  "limit": 25,
                  "offset": 0,
                  "links": [                  {
                     "rel": "self",
                     "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000110D93418F71A0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800000186AF116C0078/child/workRelationships/300000044712941/child/assignments",
                     "name": "assignments",
                     "kind": "collection"
                  }]
               }
            }
         ],
         "count": 2,
         "hasMore": false,
         "limit": 25,
         "offset": 0,
         "links": [         {
            "rel": "self",
            "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000110D93418F71A0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B5974190300007870770800000186AF116C0078/child/workRelationships",
            "name": "workRelationships",
            "kind": "collection"
         }]
      }
   }],
   "count": 1,
   "hasMore": false,
   "limit": 25,
   "offset": 0,
   "links": [   {
      "rel": "self",
      "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers",
      "name": "workers",
      "kind": "collection"
   }]
}

To find assignments for that person as of the current system date, just leave off effectiveDate.

Another example is if you want to get workers whose assignments started on a particular day you can query for that start date by doing the following:

?q=workRelationships.assignments.EffectiveStartDate='2023-03-03'&expand=workRelationships.assignments&onlyData=true&fields=PersonNumber;workRelationships:WorkerType,PrimaryFlag,StartDate;workRelationships.assignments:AssignmentNumber,ActionCode,EffectiveStartDate,EffectiveEndDate,AssignmentStatusType

 

 The returned data shows two workers who have assignments that started on March 3 2023

 

{
   "items":    [
            {
         "PersonNumber": "778",
         "workRelationships":          {
            "items":             [
                              {
                  "WorkerType": "E",
                  "PrimaryFlag": true,
                  "StartDate": "2023-03-03",
                  "assignments":                   {
                     "items": [                     {
                        "AssignmentNumber": "E778",
                        "ActionCode": "HIRE",
                        "EffectiveStartDate": "2023-03-03",
                        "EffectiveEndDate": "4712-12-31",
                        "AssignmentStatusType": "ACTIVE"
                     }],
                     "count": 1,
                     "hasMore": false,
                     "limit": 25,
                     "offset": 0,
                     "links": [                     {
                        "rel": "self",
                        "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000110D93418F71A0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B597419030000787077080000018796CF980078/child/workRelationships/300000044666110/child/assignments",
                        "name": "assignments",
                        "kind": "collection"
                     }]
                  }
               },
                              {
                  "WorkerType": "P",
                  "PrimaryFlag": false,
                  "StartDate": "2023-03-03",
                  "assignments":                   {
                     "items": [                     {
                        "AssignmentNumber": "P778",
                        "ActionCode": "HIRE",
                        "EffectiveStartDate": "2023-03-04",
                        "EffectiveEndDate": "4712-12-31",
                        "AssignmentStatusType": "INACTIVE"
                     }],
                     "count": 1,
                     "hasMore": false,
                     "limit": 25,
                     "offset": 0,
                     "links": [                     {
                        "rel": "self",
                        "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000110D93418F71A0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B597419030000787077080000018796CF980078/child/workRelationships/300000044712941/child/assignments",
                        "name": "assignments",
                        "kind": "collection"
                     }]
                  }
               }
            ],
            "count": 2,
            "hasMore": false,
            "limit": 25,
            "offset": 0,
            "links": [            {
               "rel": "self",
               "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000110D93418F71A0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B597419030000787077080000018796CF980078/child/workRelationships",
               "name": "workRelationships",
               "kind": "collection"
            }]
         }
      },
            {
         "PersonNumber": "779",
         "workRelationships":          {
            "items":             [
                              {
                  "WorkerType": "E",
                  "PrimaryFlag": true,
                  "StartDate": "2023-03-03",
                  "assignments":                   {
                     "items": [                     {
                        "AssignmentNumber": "E779",
                        "ActionCode": "HIRE",
                        "EffectiveStartDate": "2023-03-03",
                        "EffectiveEndDate": "4712-12-31",
                        "AssignmentStatusType": "ACTIVE"
                     }],
                     "count": 1,
                     "hasMore": false,
                     "limit": 25,
                     "offset": 0,
                     "links": [                     {
                        "rel": "self",
                        "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000110D93418F78D0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B597419030000787077080000018796CF980078/child/workRelationships/300000044666360/child/assignments",
                        "name": "assignments",
                        "kind": "collection"
                     }]
                  }
               },
                              {
                  "WorkerType": "P",
                  "PrimaryFlag": false,
                  "StartDate": "2023-03-03",
                  "assignments":                   {
                     "items": [                     {
                        "AssignmentNumber": "P779",
                        "ActionCode": "HIRE",
                        "EffectiveStartDate": "2023-03-04",
                        "EffectiveEndDate": "4712-12-31",
                        "AssignmentStatusType": "INACTIVE"
                     }],
                     "count": 1,
                     "hasMore": false,
                     "limit": 25,
                     "offset": 0,
                     "links": [                     {
                        "rel": "self",
                        "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000110D93418F78D0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B597419030000787077080000018796CF980078/child/workRelationships/300000044713223/child/assignments",
                        "name": "assignments",
                        "kind": "collection"
                     }]
                  }
               }
            ],
            "count": 2,
            "hasMore": false,
            "limit": 25,
            "offset": 0,
            "links": [            {
               "rel": "self",
               "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers/00020000000EACED00057708000110D93418F78D0000004AACED00057372000D6A6176612E73716C2E4461746514FA46683F3566970200007872000E6A6176612E7574696C2E44617465686A81014B597419030000787077080000018796CF980078/child/workRelationships",
               "name": "workRelationships",
               "kind": "collection"
            }]
         }
      }
   ],
   "count": 2,
   "hasMore": false,
   "limit": 25,
   "offset": 0,
   "links": [   {
      "rel": "self",
      "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/workers",
      "name": "workers",
      "kind": "collection"
   }]
}

 

Working with Roles

Instead of using the /emps resource and traversing to get the roles associated with an employee, you simply use the userAccounts resource to retrieve the roles for users.

To get all roll assignments for a PersonNumber you could use the query for the userAccounts resource:

/hcmRestApi/resources/11.13.18.05/userAccounts?q=PersonNumber='130'&onlyData=true&expand=userAccountRoles&fields=PersonNumber,Username;userAccountRoles:RoleCode

 

PersonNumber 130 has five roles:

{
   "items": [   {
      "PersonNumber": "130",
      "Username": "Matt.Wagner",
      "userAccountRoles":       {
         "items":          [
            {"RoleCode": "ORA_PER_LINE_MANAGER_ABSTRACT"},
            {"RoleCode": "ORA_FND_APPLICATION_DEVELOPER_JOB"},
            {"RoleCode": "ORA_PER_EMPLOYEE_ABSTRACT"},
            {"RoleCode": "COE_LEARNING_VIEWALL_DATA"},
            {"RoleCode": "COE_PER_EMPLOYEE_ABSTRACT"}
         ],
         "count": 5,
         "hasMore": false,
         "limit": 25,
         "offset": 0,
         "links": [         {
            "rel": "self",
            "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/userAccounts/84E4CA2B57AD711AE0503B0A4D4358EC/child/userAccountRoles",
            "name": "userAccountRoles",
            "kind": "collection"
         }]
      }
   }],
   "count": 1,
   "hasMore": false,
   "limit": 25,
   "offset": 0,
   "links": [   {
      "rel": "self",
      "href": "https://server.oraclecloud.com:443/hcmRestApi/resources/11.13.18.05/userAccounts",
      "name": "userAccounts",
      "kind": "collection"
   }]
}

 

There are many other use cases available in the documentation to be found here: https://docs.oracle.com/en/cloud/saas/human-resources/23b/farws/Manage_Workers.html and here: https://docs.oracle.com/en/cloud/saas/human-resources/23b/farws/Manage_User_Account_Roles.html

 

I’ve given a couple of examples on how to migrate usage of the /emps resource to use the /workers resource.  The support for /emps ends with release 23D, so I encourage you to begin this migration as soon as possible if not already started.