Access Worker Directories

Workers directory is one of the most important and frequently used tools in an organization. It enables workers to connect with coworkers across the organization quickly and easily. The publicWorkers API provides read-only access to public information of all active workers in an organization. Using this API, workers can access generally available public person records from the workers directory. They can query their own record and search for other workers based on various criteria from the directory application. The application makes a REST service call to Oracle HCM Cloud to return and display the appropriate public data.

The data accessible in the workers directory is secured with the Public Person Security Profile which identifies people that you can search for in the workers directory. The data returned is non-sensitive in nature that all workers can access in a corporate directory. Based on your organizational needs, you can also define custom public person security profile to restrict the availability of workers in the directory.

Note:

Workers who have access to public information of other workers from the workers directory may not have the same level of access through the Managed Person Security Profile. The Managed Person security profile identifies people you can perform actions against. For example, you may have access to view your coworkers' public details such as work email, phone number, location, etc from the workers directory. However, you may not be able to access the same information from the transactional UI flows to view and manage the person or employment details.

For more information, see HCM Data Roles and Security Profiles in the Oracle Human Capital Management Cloud Securing HCM guide.

This use case discusses the following scenarios:

• Find Coworkers
• Retrieve Worker Photo and Phone
• Retrieve Worker Direct Reports
• Retrieve Worker HR Representative

Find Coworkers

Jason works in a global product team and wants to schedule a meeting with his team to discuss about an upcoming project. He uses the workers directory to verify the time zones of his team members and set up a suitable time for the meeting.

To retrieve worker details:

1. Query the worker by using a query parameter such as WorkEmail.
2. Retrieve the collection URL for the assignments child resource to get the location details.

Example URL

The following is the format of the resource URL.

GET

/hcmRestApi/resources/11.13.18.05/publicworkers?q=WorkEmail='[e-mail]'&expand=assignments

Example Response

The following is an example of the response body in JSON format.

{
"PersonId": 300100027007285,
"PersonNumber": "955160008176350",
"LastName": "Smith",
"FirstName": "John",
"WorkEmail": "[e-mail]",
 ...
}
"assignments": {
    "items": [
               {
                  ...
                  "LocationTownOrCity": "SEATTLE",
                  "LocationPostalCode": "98104",
                  "LocationCountry": "US",
                  "LocationTimezoneCode": "PST"
                  ...

Brian is employed by a chain of restaurants. He works as a Chef in Restaurant A from Friday to Sunday and Restaurant B from Tuesday to Thursday. Brian is working in the same legal entity on two different assignments, one being the primary assignment.

To retrieve the worker's primary assignment:

1. Retrieve the worker by using a finder and providing parameter values such as DisplayName, JobName and OnlyPrimaryAssignmentFlag.
2. Verify the assignment details returned in the response.

Example URL

The following is the format of the resource URL.

GET

/hcmRestApi/resources/11.13.18.05/publicWorkers?finder=findByWorkerAttr;DisplayName=Brian Lee,JobName=Chef, OnlyPrimaryAssignmentFlag=true&expand=assignments

Example Response

The following is an example of the response body in JSON format.

{
"PersonId": 300100027007285,
"PersonNumber": "955160008176350",
"LastName": "Lee",
"FirstName": "Brian",
 ...
}
"assignments": {
    "items": [
               {
                ...
                "AssignmentName": "RESTAURANT-A-01",
                "LegalEmployerName": "Vision City",
                "PrimaryFlag": true,
                "JobName": "Chef",
                 ...
                }

Retrieve Worker Photo and Phone

Sarah has an in-person meeting with John who heads the Project Management Office. There are other workers in the same organization with the first name John. Sarah uses the workers directory to retrieve John's details and verifies the profile photo to identify him.

To retrieve a worker photo:

1. Retrieve the worker by using a finder and providing parameter values such as DisplayName, WorkEmail, and PositionName.
2. Retrieve the collection URL for the photos child resource.
3. Find the link for enclosure to get the photo image of the worker.

Example URL

The following is the format of the resource URL.

GET

/hcmRestApi/resources/11.13.18.05/publicWorkers?finder=findByWorkerAttr;DisplayName=John,PositionName=Director Program Management&expand=photos

Example Response

The following is an example of the response body in JSON format.

{
"PersonId": 300100027007285,
"PersonNumber": "955160008176350",
"DisplayName": "John Smith",
"LastName": "Smith",
"FirstName": "John",
"WorkEmail": "[e-mail]",
 ...
}
 "photos": {
    "items": [
               {
                  ...
                  "PhotoId": 300100131701615,
                  "PrimaryFlag": true,
                  "PhotoType": "PROFILE",                                       
                   ...
                  "links": [
                            {
                             "rel": "enclosure",
                              ...
                            }

Sarah needs some additional information on the project from her coworker, James, before her discussion with John. She looks up James' phone number in the workers directory and sets up a call with him.

To retrieve the worker phone:

1. Retrieve the worker by using a finder and providing parameter values such as DisplayName or WorkEmail.
2. Retrieve the collection URL for the phones child resource to get the phone details.

Example URL

The following is the format of the resource URL.

GET

/hcmRestApi/resources/11.13.18.05/publicWorkers?finder=findByWorkerAttr;DisplayName=James Gordon&expand=phones&onlyData=true

Example Response

The following is an example of the response body in JSON format.

{
"PersonId": 300100027007285,
"PersonNumber": "955160008176350",
"DisplayName": "John Smith",
"LastName": "Smith",
"FirstName": "John",
"WorkEmail": "[e-mail]",
 ...
}
 "phones": {
                "items": [
                    {
                        "PhoneId": 300100171529222,
                        "PrimaryFlag": true,
                        "PhoneType": "W1",
                        "CountryCodeNumber": "1",
                        "AreaCode": "209
                        "PhoneNumber": "111-2222",
                        ...                  
                    }

Retrieve Worker Direct Reports

Sandy is an Applications Developer who works with Bill from the Product Management team. Bill is out of office and Sandy requires some critical information for her project. Sandy looks up the workers directory and verifies Bill's organization details to contact Bill's manager or direct reports who could help her during Bill's absence.

To retrieve the manager and direct reports of the worker:

1. Query the worker by using a query parameter such as WorkEmail.
2. Retrieve the collection URL for the assignments child resource to get the manager details.
3. Retrieve the direct reports of the worker by accessing the allReports child resource.

Example URL

The following is an example of the resource URL.

GET

/hcmRestApi/resources/11.13.18.05/publicworkers/{Id}/child/assignments/{Id}/child/allReports?q=Level=1

Example Response

The following is an example of the response body in JSON format.

"items": [
        {
            "AssignmentName": "CDET Project",
            "DisplayName": "John Brook",
            "RelationshipType": "Line Manager",
            "Level": 1,
            ...        
        }
       ]

Retrieve Worker HR Representative

Amy has recently joined a new organization and she needs more information about her benefits plan. She uses the workers directory to find the HR Representative for her organization who can guide her on the corporate 401K plan and other benefits.

To retrieve the HR representative of the worker:

1. Query the worker by using a query parameter such as DisplayName or WorkEmail.
2. Retrieve the collection URL for the assignments child resource to get the assignments details of the worker.
3. Retrieve the representatives of the worker for the specific assignment by accessing the representatives child resource.

Example URL

The following is an example of the resource URL.

GET

/hcmRestApi/resources/11.13.18.05/publicworkers/{Id}/child/assignments/{Id}/ child/representatives?q=ResponsibilityType='HR Representative'

Example Response

The following is an example of the response body in JSON format.

"items": [
        {
            "AsgResponsibilityId": 300100118795087,
            "ResponsibilityType": "HR Representative",
            "ResponsibilityName": "HR Representative",
            "DisplayName": "Brooklyn Anderson",
            "WorkContactsFlag": true,
            ...
       }
      ]