← Back to blog

Get an Oracle Fusion User and Line Manager by Entity Using OPAL

7 min read Oracle FusionHCMWorkers APIUser AccountsOPALREST APILine Manager

Oracle Fusion HCM teams often need to validate a flow using an existing employee-manager relationship.

A common requirement is simple:

Find an active worker from a selected legal employer, identify that worker’s line manager, then retrieve the Fusion usernames for both records.

This is useful for approval-flow validation, employee self-service checks, manager self-service checks, role troubleshooting, and environment verification.

The challenge is not the business logic. The challenge is finding the right data quickly across large Oracle Fusion HCM responses.

In this article, we will build a small OPAL flow using two Oracle Fusion REST APIs:

  1. workers
  2. userAccounts

The first API helps us identify the worker and manager relationship. The second API gives us the unique Fusion username for each person.

The target result

At the end of the flow, we want this kind of output:

Selected Entity Worker
- PersonNumber
- DisplayName
- Username

Line Manager
- PersonNumber
- DisplayName
- Username

The important point is that Username is unique in Oracle Fusion. Once we have the correct PersonNumber, we can use userAccounts to retrieve the matching user account record.

No manual search in the User Accounts page is required.

Why we need two APIs

The workers API is the best starting point because it can return worker data, names, work relationships, assignments, and manager assignment information.

However, the workers API does not always return the Fusion login username.

The userAccounts API is the better resource for that:

GET /hcmRestApi/resources/latest/userAccounts

So the flow is:

workers
  -> find a worker under the selected legal employer
  -> extract the worker PersonNumber
  -> extract the ManagerAssignmentNumber
  -> derive the manager PersonNumber
  -> call userAccounts for both person numbers

In OPAL, open the workers endpoint and create a GET request.

Use expand to bring the related name, email, assignment, and manager data into one response:

GET /hcmRestApi/resources/latest/workers?onlyData=true&limit=10&expand=names,emails,workRelationships.assignments.managers&q=workRelationships.LegalEmployerName%20like%20%27%25Acme%25%27

For a full URL:

https://your-fusion-host/hcmRestApi/resources/latest/workers?onlyData=true&limit=10&expand=names,emails,workRelationships.assignments.managers&q=workRelationships.LegalEmployerName%20like%20%27%25Acme%25%27

For another entity, change the text inside the like condition.

Example:

GET /hcmRestApi/resources/latest/workers?onlyData=true&limit=10&expand=names,emails,workRelationships.assignments.managers&q=workRelationships.LegalEmployerName%20like%20%27%25Globex%25%27

This response includes the information needed to identify a worker and their manager assignment in one place.

Important: do not pass q twice

A common mistake is accidentally sending this:

&q=q=workRelationships.LegalEmployerName like '%Acme%'

That fails because Oracle receives the value as:

q=workRelationships.LegalEmployerName like '%Acme%'

The query parameter name should appear only once:

&q=workRelationships.LegalEmployerName like '%Acme%'

In URL encoded format:

&q=workRelationships.LegalEmployerName%20like%20%27%25Acme%25%27

In OPAL, this is easier because you can put q in the Params tab and avoid manually building the full query string.

Step 2: Pick the worker record

From the workers response, choose a worker record that matches your scenario.

For a reliable result, check the active primary assignment:

AssignmentStatusType = ACTIVE
PrimaryAssignmentFlag = true
ManagerType = LINE_MANAGER

In one response, the record you want may be at items[2]. In another environment, it may be a different index. For a reusable flow, choose the correct row after reviewing the response.

Step 3: Extract the worker person number

Example extraction:

Variable name: UserPersonNumber
JSON path: items[2].PersonNumber
Example value: <workerPersonNumber>

In OPAL, add this in the Extract tab:

UserPersonNumber = items[2].PersonNumber

This gives us the worker’s PersonNumber.

Step 4: Extract the manager assignment number

The manager value is available under the assignment manager child data.

Example path:

items[2].workRelationships.items[0].assignments.items[0].managers.items[0].ManagerAssignmentNumber

Add this extraction rule:

Variable name: ManagerAssignmentNumber
JSON path: items[2].workRelationships.items[0].assignments.items[0].managers.items[0].ManagerAssignmentNumber
Example value: E100002

This value is an assignment number, not a person number.

For many HCM employee assignments, the format looks like this:

E100002

The manager PersonNumber is usually:

100002

So the conversion rule is:

Remove the leading assignment prefix, such as E or C.
If the value has a suffix like E123456-2, remove the suffix after the dash.

Examples:

E100002   -> 100002
E123456-2 -> 123456
C101881   -> 101881

If your OPAL flow supports variable transformation, create:

ManagerPersonNumber = ManagerAssignmentNumber without the first letter and without anything after '-'

If not, keep the raw ManagerAssignmentNumber visible and use the derived number in the next request.

Step 5: Get usernames from userAccounts

Now call the userAccounts endpoint.

Use the worker person number and the manager person number in the same query:

GET /hcmRestApi/resources/latest/userAccounts?onlyData=true&limit=20&q=PersonNumber%3D%27{{UserPersonNumber}}%27%20or%20PersonNumber%3D%27{{ManagerPersonNumber}}%27

Readable version:

q=PersonNumber='{{UserPersonNumber}}' or PersonNumber='{{ManagerPersonNumber}}'

Example response shape:

{
  "items": [
    {
      "Username": "[email protected]",
      "PersonNumber": "<workerPersonNumber>"
    },
    {
      "Username": "[email protected]",
      "PersonNumber": "<managerPersonNumber>"
    }
  ]
}

Use placeholder values in public documentation. Do not publish real usernames, emails, person numbers, or employee names from your Fusion environment.

Step 6: Extract the usernames

From the userAccounts response, match each item by PersonNumber.

You need two final values:

WorkerUsername
ManagerUsername

Example logic:

WorkerUsername  = item where PersonNumber = UserPersonNumber -> Username
ManagerUsername = item where PersonNumber = ManagerPersonNumber -> Username

If your result order is stable, you may extract by index. But matching by PersonNumber is safer because Oracle does not guarantee that the response order will always match your query order.

OPAL flow summary

Create a flow with two tabs:

Tab 1: workers
Tab 2: userAccounts

Tab 1: workers

Purpose:

Find workers under the selected legal employer and extract worker + manager identifiers.

Request:

GET /hcmRestApi/resources/latest/workers?onlyData=true&limit=10&expand=names,emails,workRelationships.assignments.managers&q=workRelationships.LegalEmployerName%20like%20%27%25Acme%25%27

Extract:

UserPersonNumber = items[2].PersonNumber
ManagerAssignmentNumber = items[2].workRelationships.items[0].assignments.items[0].managers.items[0].ManagerAssignmentNumber

Example values:

UserPersonNumber = <workerPersonNumber>
ManagerAssignmentNumber = E100002
ManagerPersonNumber = 100002

Tab 2: userAccounts

Purpose:

Get the unique Fusion usernames for the worker and manager.

Request:

GET /hcmRestApi/resources/latest/userAccounts?onlyData=true&limit=20&q=PersonNumber%3D%27{{UserPersonNumber}}%27%20or%20PersonNumber%3D%27{{ManagerPersonNumber}}%27

Readable q value:

PersonNumber='{{UserPersonNumber}}' or PersonNumber='{{ManagerPersonNumber}}'

Why this is useful

This flow saves time because it turns a manual lookup process into a repeatable API workflow.

Without OPAL, you usually need to:

  1. Call the Workers API.
  2. Search through a large JSON response.
  3. Copy the worker person number.
  4. Copy the manager assignment number.
  5. Convert the manager assignment number to a person number.
  6. Build another request for user accounts.
  7. Copy the usernames into your validation notes.

With OPAL, the flow keeps the calls together, extracts the important values, and lets you reuse them in the next tab.

That makes the process easier for:

A note about privacy

This workflow may return real employee records from your Oracle Fusion environment.

For internal troubleshooting, that is expected. For documentation, demos, screenshots, blog posts, and knowledge sharing, always replace real names, usernames, emails, and person numbers with placeholders.

Good public examples:

[email protected]
[email protected]
<workerPersonNumber>
<managerPersonNumber>

Avoid publishing real environment data unless it has been explicitly approved for public use.

A note about expand and filtering

This flow uses expand=names,emails,workRelationships.assignments.managers because we want a quick view of related worker data in one call.

That is good for discovery and validation workflows.

But remember: expand brings child data into the response. It does not always mean Oracle will filter nested child records exactly the way you expect.

For stronger validation, confirm that you are using the active primary assignment:

AssignmentStatusType = ACTIVE
PrimaryAssignmentFlag = true
ManagerType = LINE_MANAGER

If you need strict assignment-level filtering, call the assignment child resource directly instead of relying only on expanded worker data.

Final recommendation

Use the workers API to discover the worker and line manager relationship.

Use the userAccounts API to retrieve the unique Fusion usernames.

Use OPAL variables to pass person numbers from one tab to the next.

This gives you a simple, repeatable flow for finding a worker and manager by entity without switching between tools or manually rebuilding every request.

Download OPAL here:

https://opalapi.dev

This post is part of our complete Oracle HCM API guide — base URLs, authentication, q filters, finders, key endpoints, and common errors in one place.