Two hooks exist, and they fire at different moments

A delivered business process can start an orchestration in two documented ways, and both need an orchestration built on the Workday Business Process template. The first is an Orchestration Service step inside the business process definition, which launches the orchestration when the event reaches that step. The second is the Configure Orchestrations related action, which launches an orchestration when someone cancels, rescinds, corrects or denies the event.

Pick by the question the orchestration answers. If it is "now that this hire is approved, provision the badge system", it belongs in the flow as a Service step. If it is "this hire was rescinded, revoke what we provisioned", it belongs on the status change. Workday's own example pairs the two that way: a Hire process provisions access in an external system, and a different orchestration revokes it when the hire is rescinded.

The two hooks are configured in different places and behave differently. The Service step takes its parameters from the step's own Key and Value rows. A status-change launch needs an Orchestration Launch Configuration, which Workday doesn't create for you even after the app is deployed. Workday's launch page says these orchestrations are typically started by the scheduler within 15 minutes, longer for Mass Cancel or Mass Rescind, which run through a background job. Don't build a status-change launch for work the user expects to see finish on screen.

The setup clicks for the Service step are in adding an orchestration service step to a business process definition. This page covers the design decisions you make before those clicks.

Pass the event's Workday ID, then read what you need

The Business Process Trigger step declares the parameters the orchestration accepts, and the business process step fills them from a text value or a field. You can pass a dozen fields, but passing one identifier usually holds up better: the Workday ID of the event. Workday's Request Credit Card sample app does exactly this. It declares a single String parameter, actionEvent, and the business process fills it from Value from Field with the Workday ID field. The orchestration reads it with:

data("start", "actionEvent")

From that ID the orchestration looks up the rest when it runs. The sample uses a WQL query on the event's data source. On a delivered process you can call the Business Process REST service's events endpoint. Reading at run time means the orchestration sees the event as it is when the step fires, not as it was when someone typed parameter mappings into a grid. When the payload changes, you change one orchestration. You don't have to touch every business process definition that calls it. Getting the right ID from each kind of event has its own pitfalls, covered in getting the business process event WID in an orchestration.

Before you add parameters at all, check the bp functions in Orchestrate's expression language. bp.actionEvent(), bp.eventTarget(), bp.initiatingPerson(), bp.aboutPerson() and bp.eventInitiationDateTime() return the action, the event target, the initiator, the person the event is about and the initiation time from the trigger's launch request. A worker-centric orchestration often needs nothing more than bp.aboutPerson().

Decide whether the business process waits for the orchestration

The Service step has an Advance business process step when orchestration completes check box. When it is selected, the business process doesn't move to its next step until the orchestration finishes. When it is cleared, the process carries on and the orchestration runs on its own.

Select it when later steps depend on the result. For example, a To Do that tells HR the external account exists only makes sense once the account does. Clear it when the external work is fire-and-forget, such as a notification to a downstream system that nothing in Workday reads back. Waiting has a cost. A step that waits on an orchestration that never finishes leaves the event sitting in progress, which is the failure covered in business process orchestration steps stuck in progress.

Choose who the orchestration runs as, and match the credential to it

Two separate settings decide identity. On the orchestration side, the Business Process Trigger starting point requires a credential of either the Integration System User (ISU) type or the initiating-user type. On the business process side, the Service step asks which user runs the orchestration. The default is the user who completed the previous step. You can also name a specific user, or take the user from a field.

The default sounds natural, but on a delivered process the previous step is often an approval done by a manager. That manager's security then decides what the orchestration can read and change. Combined with initiating-user authentication, an orchestration that works when an HR partner approves can fail when a manager does. If the orchestration needs the same access every time, run it under an ISU credential that holds exactly the domains it calls. In the Request Credit Card sample, the ISU's security group gets View on Worker Data: Staffing and WQL for Workday Extend, plus Get and Put on Set Up: Credit Card, and nothing more. That's a recommended approach, not a Workday rule. It makes the orchestration's behaviour independent of who happened to approve.

Status-change launches have their own documented rule. If the orchestration makes API calls it must use ISU authentication, and the launching user comes from the configuration item's User to Perform Orchestration Launches field, falling back to the same field on Edit Tenant Setup - Business Processes when the item has none.

Put the step after the decision it depends on

Workday sorts business process steps alphabetically by their Order letters, and the Service step only runs once the event reaches its letter. Place it after the approval it depends on, so an external system is never told about a hire that a manager later sends back. If the orchestration should run only for some events, for example only for one country or worker type, give the Service step an entry condition rather than branching inside the orchestration. Workday allows entry conditions on any step except Initiation.

Keep an eye on chains of automatic steps. Workday supports at most 72 consecutive non-manual steps on a business process. A Service step runs without user interaction, so a run of them next to integration and report steps counts toward that limit.

Cover the reversal before you go live

Anything the orchestration does outside Workday stays done when the event is undone, unless you build the reverse. Rescinding a delivered business process restores Workday's own data, but it can't reach into the badge system. Pair each Service-step orchestration that writes externally with a status-change orchestration on Rescind and Cancel, plus Correct if corrected data has to flow out too. Give both the same identifier parameter so the undo can find what the original created.

Workday adds two documented details for these launches. The Configure Orchestrations grid accepts condition rules, which Workday evaluates before it starts the orchestration. And a Relaunch option appears on the canceled, rescinded, corrected or denied event once the orchestration moves from Queued for Launch to In Progress. A relaunch skips the condition rules and lets you adjust parameters first.

Handle failure inside the orchestration

Don't plan on the business process to catch a failed orchestration for you. Workday's redirect options (send back, move to next step, rerun, advance automatically) are documented for Integration and Review Documents steps, not for Service steps. A Service step is described as starting a separate processing thread, much like an Action step. Put error handling in the orchestration itself: log the event ID and the external response with a Log step, so a failed run can be traced back to its event.

How to prove the trigger worked

Run one real event in a non-production tenant and check three places:

  1. The event's process history. The Service step should show as complete. If you selected the advance check box, it should complete only after the orchestration finishes.
  2. Orchestration Activity on the Developer Site. Find the orchestration and open its runs. Each run has a Run ID, a Current Status (such as SUCCESS, RUNNING, AWAITING_CALLBACK, COMPLETED_WITH_ERROR or FAILED) and a View Logs link to the run logs.
  3. The run logs. Your Log step's message should contain the event ID you passed. That proves the parameter mapping, not just the launch.

For status-change launches there's a fourth place. The event's Orchestrations tab shows the run's status, and Refresh Status pulls the latest state from Orchestrate. The tab shows Completed only if the initiating user can view the event.

kiweely can run this check in a non-production tenant: it starts a test event as the right user in the browser, then reads the event's process history and the orchestration's run back before calling the trigger working.

Sources checked