Create, maintain and publish a workflow definition¶

Use this guide to prepare the reusable route that governs work. Individual requests and assigned tasks belong in their own work areas.

Current availability: These instructions follow the latest inspected WorkOS final screens. The frontend is still in progress: the inspected library, creation, editor and detail pages show sample content, and their visible actions do not establish saved backend changes. Use the steps for review and preparation until your administrator confirms the connected experience is available. Do not enter live business information into a preview or treat its success labels as confirmation.

Before you start¶

You need the correct organization/workspace, permission to view definitions, and permission to manage definitions when creating, editing, simulating or publishing. Being named as the owner team or owner role does not grant those permissions. If you cannot access Operations, ask your tenant administrator to verify your access rather than borrowing another account.

Prepare a clear purpose, a unique stable definition code, the workflow family, the owning team and role where appropriate, and the organizational view used by assignments. Agree the start and completion points, decisions, exceptions, approval responsibilities and any downstream handoff. A blank draft needs its route built before it can be published.

Find and inspect a definition¶

1. Open Operations, then Workflow definitions.
2. Choose the workflow-family and status filters you need, then select Apply filters. Use Previous and Next to browse pages when the connected library offers them.
3. Select Open definition beside the intended entry. Confirm its code, version, family and status; similar names can describe different routes.
4. Review its description, ownership, organogram view, publication information and latest simulation. Open Handoff, Workflow steps and Route rules to inspect the saved configuration.

The detail views are read-only. Edit draft is the intended entry for changes while the definition is still a draft. The library supports status/family filtering; the inspected contract does not establish a name-search feature. Do not use the request-search help text shown in the current design as instructions for searching this library.

Create a draft from a starter¶

1. From the library, select Create draft.
2. In Select a starter definition, review the purpose and family of each starter. Select Use starter for the best fit, then Continue. Selecting a starter alone does not save anything.
3. In Provide draft details, enter the definition name and unique code. Review the selected starter and its family/category. The intended form locks those choices to the starter; go back to the first step to change the starter.
4. Add a useful description. Choose the optional Owner team, Owner role and Organogram view where your process requires them.
5. Select Create draft. In the connected experience, a successful creation should save the setup and open the draft editor. Verify the saved definition and its identity before continuing.

The backend requires name, code and category for a blank draft, and a valid family. It normalizes the code for consistent comparison and rejects a code already in use. Description is optional in the current backend even though the creation design marks it required. Include one for clarity; that mismatch remains design follow-up.

Start from scratch¶

Choose Start from scratch in the first creation step. Complete the blank draft's details, including Workflow family and Process category, which remain selectable because no starter fixes them. Add ownership and organizational context, then select Create draft.

A blank creation saves the definition details without starter steps. It cannot be published until a suitable route has been added and passes validation. Check that the selected category suits the family: case and project workflows have specific category requirements.

Edit and save the draft¶

Open the definition, select Edit draft, and use the three editor companions. Each repeats the shared details so the definition's identity and ownership remain visible.

Select Save draft after reviewing the changes. Discard changes represents abandoning unsaved edits in the intended design; the current preview does not prove persistence or unsaved-change protection. In the connected experience, reopen the saved detail and compare all three sections before simulation. Saving one section must preserve the other sections: the service replaces the complete supplied structure.

Coordinate with other authors. The inspected save contract does not provide an expected draft revision for detecting an out-of-date edit. Reopen the latest version before editing and agree who is making changes. Do not assume the product will merge simultaneous edits.

Build a route that can finish¶

Keep at least one start step and at least one end step. Required steps need a reachable path from the start, and reachable unfinished steps need a path to an end. References to assignment rules, approval rules and destination steps must belong to the same supplied structure.

For parallel routes, use the appropriate split and join steps and a supported completion rule. A parallel split needs multiple branches that can converge on its join. A required branch count is different from an approval count. The sample queue step's “reviewers required” wording should not be used as a general explanation of parallel joins.

Assignment choices depend on organizational data. Check that positions, managers, team heads or queues can resolve as required. Some manager assignments need the context of a real request before they can resolve. Passing a definition simulation does not prove every future employee's manager route will work.

Configure handoff carefully¶

Map the required workflow information to the receiving destination's fields. Avoid duplicate source/destination pairs and preserve their intended order. Only choose a destination confirmed for your environment and integration.

The current implementation defines handoff after workflow completion. The final-screen examples still say “After submission” and use “Requests” as the destination; those examples are under correction and must not be treated as supported configuration. A saved mapping does not prove that the destination accepts the payload, creates a record or acknowledges delivery. Confirm those outcomes through the consuming feature's supported process.

Run simulation and resolve issues¶

1. Save the draft, return to detail and select Run simulation.
2. Review whether the current draft revision passed. Read both structural issues and simulation issues, including the affected step or route where supplied.
3. Return to the editor to correct the configuration or ask the responsible administrator to correct organizational dependencies.
4. Save and rerun simulation. An earlier pass becomes stale after a structural edit.

Typical issues include a missing start/end, a missing assignment or approval rule, an unreachable required step, a dead-end path, a parallel branch that cannot reach its join, a family/category mismatch, or an organizational target that cannot resolve. If the underlying organizational service is unavailable, treat the check as unresolved; do not change the business route merely to hide a temporary service failure.

Simulation checks the saved structure and supported routing lookups. It does not execute a real request, dispatch work to recipients, exhaustively test every condition or certify downstream delivery. A clean result supports publication review, not a guarantee of every future outcome.

Publish and confirm the result¶

The intended detail screen makes Publish draft available after the current draft revision passes simulation. Before selecting it, confirm the saved details, all route sections, the accountable owner and any agreed rollout requirements.

The server runs validation and simulation again during publication. If checks fail, resolve the reported issue and try again after saving; an old green result is not a bypass. A successful publication records the publisher and time and makes that definition version read-only. Reopen its detail and confirm the published status and correct version.

The observed screens do not establish an additional confirmation dialog or a complete effective-date form, so this guide does not invent either. If scheduling is required, confirm the supported process with your administrator before publication. Publication alone does not start a request or change every running workflow.

Recover from a problem¶

When requesting help, provide the workspace, definition name/code and version, intended action, approximate time and displayed message. Use the approved support channel for any sensitive details; do not include access tokens or confidential form contents.

Review before rollout¶

Process owners should walk through a representative case with the intended author and participants: identify the route, explain each decision, correct a failed simulation and confirm the saved publication. Include missing access, an unavailable dependency and uncertain-save recovery. These walkthroughs and environment checks remain pending for this documentation. See the overview for responsibilities and lifecycle limits.

As part of rollout, review runtime route and parallel-work limits with the process owner. Use that explanation alongside the authored definition when deciding which automation is ready.

Before assigning a default policy to a workflow step, review SLA policies and timing. Policy changes affect new task timing snapshots; they do not recalculate existing task snapshots.