How your organization structure directs work¶

An organization chart explains where people sit. Work routing also depends on the kind of task, the selected version of that structure and the assignments effective when the task is resolved. A primary holder, an acting holder and a co-occupant can appear on the same position without receiving the same work.

This guide explains the inspected core WorkOS behavior. It supports structure owners, managers, administrators and people investigating an unexpected recipient. It does not establish that every product uses these rules or that the current frontend preview sends real work. Use the browsing guide to inspect a structure and the administration guide to understand changes.

Match the rule to its purpose¶

These differences matter during temporary cover. For example, if a position has both a primary holder and a different acting holder, direct-position routing selects the primary holder. A manager lookup for that same position can select the acting holder. Check the actual task rule before concluding that the chart or recipient is wrong.

A co-occupant can appear in a direct-report list or qualify through a shared-queue membership. That does not make them the automatic replacement for a vacant primary or acting holder in direct-position routing.

Understand the selected structure and time¶

Ordinary live resolution uses the active published structure. A specific structure reference changes that context: some internal reads can inspect drafts or historical structures, while other operations require publication or the current live view.

The core workflow checks an explicitly selected structure for publication when resolving a specified position, manager source position or queue. A published historical structure can still satisfy that publication check; the check does not universally require it to remain active. The evidence-handoff people picker is stricter and does not offer people from a historical view.

Effective dates are assessed when the relevant read runs, unless that read explicitly requests a historical time. Workflow assignment calls in this composition use the current time; they do not automatically reuse the date when the process or structure was first created. Several reads are separate operations, so changes between them can affect the result.

A historical read reconstructs effective assignments and relationships from the saved data. It is not a guarantee that every detail is an immutable copy of the past. Assignment correction can replace stored details, and the administration guide records the current published-edit enforcement gap.

Publishing a new structure does not, by itself, prove that all existing tasks are reassigned. An existing task, a newly resolved task, a simulation and a historical evidence view can have different context. Verify the consuming workflow's reassignment behavior before announcing a change to recipients.

Interpret placement and reporting lists¶

Profiles use primary placement to describe a person's department, unit, title and manager chain. The current projection rejects multiple primary positions for one person rather than choosing one silently. The assignment-writing rules do not enforce that organization-wide uniqueness in every write, so inconsistent assignments can later cause profile or placement reads to fail.

A direct-report list follows the selected manager position's immediate administrative reporting lines. It can include primary holders, acting holders and co-occupants on the reporting positions, with each person appearing once. It is not a recursive list of every descendant in the organization, and it does not automatically include functional or advisory reports.

A blank department, missing manager or shortened manager chain needs investigation. Missing structure references and circular relationships can prevent a complete display. A successful chart read also does not prove the person is employed, signed in, available or entitled to perform a particular task.

Understand fallback and unresolved authority¶

When direct-position routing finds no primary or acting holder, it follows that position's fallback. Each fallback uses the same primary-then-acting rule. A circular fallback chain fails, and an exhausted chain produces an unresolved-assignee error.

The core resolver does not silently assign the requester as a replacement. It also does not use a co-occupant as that replacement. Ask the structure and workflow owners to correct the intended authority or routing rule, then use the workflow's supported recovery procedure.

Manager routing first needs a configured relationship of the requested kind. It does not automatically substitute an administrative manager when the requested functional or advisory manager is missing. If the manager position exists but has no resolved holder, its fallback chain can be used.

Interpret shared-queue membership¶

A person can belong to a shared queue through a temporary direct-person override, an ordinary direct-person membership, or an effective assignment on a member position. The membership period and the position-assignment period must both be effective for that last path.

The person's queue catalogue shows one row per active queue, even if several membership paths apply. Its explanation prefers a temporary override, then an ordinary direct-person membership, then primary, acting and co-occupant paths. This priority chooses the explanation shown for that person; it does not rank every queue member for assignment.

Queue assignment is separate. The core workflow resolver can return a queue without choosing a person, checking that its membership is nonempty, or checking the queue's active flag at that point. Other catalogue reads do filter inactive queues. Therefore, absence from a person's catalogue and a stored queue assignment can coexist.

The administration guide explains adding memberships and the current limits on changing or ending them. Do not add duplicate memberships to repair a routing error. Claiming, reassignment, workload distribution and additional eligibility checks belong to the consuming workflow and require their own verification.

Know what an active-person check proves¶

When checking a manually assigned person, the current workflow uses their permission to access WorkOS. That check does not also require active employment or absence from leave. Automatic position/manager assignment follows the effective authority details without running that same person-access check at this stage.

These are different conditions: having an effective assignment, being employed, being allowed into WorkOS, being on leave and having permission for a task. None should be inferred from one “active” label. Administrators should review each relevant condition before changing access or assigning responsibility.

Understand people offered for evidence handoff¶

The selected-view people lookup used by evidence handoff distinguishes:

For an available structure, the lookup shows at most 25 matching people. A person with several memberships is represented once, preferring primary, acting and then co-occupant context. Search applies to that selected context, so the same person's other position may not appear as a matching result.

A person missing from a short result list is not necessarily outside the organization. Check the selected view, search text, effective period and WorkOS access. An available view with no matching people differs from an unavailable or historical view. This is a description of the lookup behavior; it does not invent an unverified handoff screen or establish that a handoff has been delivered.

Investigate an unexpected result¶

Start with the workspace, task or request, selected structure, routing rule and time of the decision. Compare the effective primary and acting assignments, the requested manager relationship, any fallback and the relevant queue membership. Use the saved task's actual recipient rather than a preview toast or a chart badge as evidence of assignment.

Share only the personnel information needed for authorized investigation. Structure owners should approve responsibility changes, workflow owners should confirm the consuming rule, and support should verify the actual result. Connected frontend, environment and audience walkthroughs remain pending.