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:
- Query the worker by using a query parameter such as
WorkEmail
. - 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='John.Smith@examplemail.com'&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": "John.Smith@examplemail.com",
...
}
"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:
- Retrieve the worker by using a finder and providing parameter values such as
DisplayName
,JobName
andOnlyPrimaryAssignmentFlag
. - 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:
- Retrieve the worker by using a finder and providing parameter values such as
DisplayName
,WorkEmail
, andPositionName
. - Retrieve the collection URL for the
photos
child resource. - 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": "John.Smith@examplemail.com",
...
}
"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:
- Retrieve the worker by using a finder and providing parameter values such as
DisplayName
orWorkEmail
. - 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": "John.Smith@examplemail.com",
...
}
"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:
- Query the worker by using a query parameter such as
WorkEmail
. - Retrieve the collection URL for the
assignments
child resource to get the manager details. - 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:
- Query the worker by using a query parameter such as
DisplayName
orWorkEmail
. - Retrieve the collection URL for the
assignments
child resource to get the assignments details of the worker. - 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,
...
}
]