What the step is, and why the orchestration comes first

An Orchestration Service step is a Service step whose Specify value is Orchestration Service. It launches an orchestration built on the Workday Business Process template when the event reaches that step. The work happens in two places. In Orchestration Builder you declare what the orchestration receives and deploy the app. In the tenant you edit the business process definition, add the step and map each value. Do them in that order, because the business process can only select an orchestration that is already deployed to the tenant.

Whether this hook is the right one at all, and how to choose the run-as user and the waiting behaviour, is covered in triggering an orchestration from a delivered business process. This page is the setup.

Build the orchestration side first

  1. In your Extend or integration app on the Developer Site, add an orchestration and choose the Workday Business Process template. Orchestration Builder creates it with a Business Process Trigger step at the start and an Orchestration End step at the end.
  2. Give it a credential. This starting point requires a credential of either the Integration System User (ISU) authentication type or the initiating-user type.
  3. On Business Process Trigger, click Configure Request and add one parameter for each value the business process will send. Note each name exactly. The business process side has to use the same keys.
  4. Add the steps that do the work. Put a Log step near the top that writes the incoming parameter. It's the quickest proof later that the mapping arrived.
  5. Save the app to App Hub and deploy it to the tenant where you'll edit the business process.

Workday's Request Credit Card sample app shows the smallest useful trigger. It declares one String parameter named actionEvent and reads it in later steps as:

data("start", "actionEvent")

The sample then runs a WQL query with that value to find the business object behind the event. Passing one ID and reading the rest at run time keeps the step's mapping short. The trade-offs are in getting the business process event WID in an orchestration.

Add the Service step to the business process definition

Editing a definition needs the Business Process Administration and Manage: Business Process Definitions domains in the System functional area.

  1. Find the business process type in the tenant, for example Hire or Change Job. From its related actions, select Business Process > Edit Definition.
  2. Select an Effective Date for the change.
  3. Add a row for the new step:
    • Order: one or more letters. The Initiation step is always a, and Workday sorts steps alphabetically when you save. To run after an approval at b, use c. To slot between b and c, use something like bb.
    • Type: Service.
    • Specify: Orchestration Service.
  4. Click OK to save the definition.

Choose the order letter with care. The orchestration launches only when the event reaches the step, so put it after the approval whose outcome it depends on. Also keep in mind Workday's limit of 72 consecutive non-manual steps on a business process. A long chain of automatic steps around your new one can reach it.

Configure Orchestration Service: which orchestration, wait or not, as whom, with what

After the save, the new step has a Configure Orchestration Service button on the definition. Click it.

  1. Select Launch a new Orchestration, then pick your orchestration. The Request Credit Card sample's setup shows this option.
  2. Decide on Advance business process step when orchestration completes. Selected, the business process holds at this step until the orchestration finishes. Cleared, the process moves on without waiting.
  3. Select the user who runs the orchestration. The default is the user who ran the previous business process step. You can instead choose a named user, or a user taken from a field on the event.
  4. In the data grid, add one row per trigger parameter. Set Key to the parameter name exactly as declared on Business Process Trigger. Then supply the value as Text Value (a constant) or Value from Field (a field on the event). Workday's course manual shows a key mapped to a WID taken from a field. The sample maps actionEvent to the Workday ID field.
  5. Click OK.

The keys are where most first attempts go wrong. Workday's step text is direct: the data you pass must match the parameters configured on the orchestration's Business Process Trigger step. Copy each name across character for character rather than retyping it.

Make the step conditional if it shouldn't always run

If the orchestration applies only to some events, for example one company or one worker type, add an entry condition to the Service step. Workday allows entry conditions on any step except Initiation. You add them from Business Process > View Definition and then Business Process > Maintain Step Conditions on the step itself. The Edit Business Process Definition page can't do it. Step conditions take their own effective date.

Workday's step conditions page has two notes on automated events that read differently: one says conditions aren't evaluated when a business process runs from a web service or EIB set to complete automatically, the other that entry conditions on Service steps are still evaluated when a web service automates the process. Test a conditional Service step with an event started from the task in the browser, not from an EIB load.

Prove the step fires and the data arrives

Start one real event in a non-production tenant, as a user who can initiate it, and move it past the step before the Service step.

  1. Open the event's process history. The Service step should be there. If you selected the advance check box, it should complete only after the orchestration finishes.
  2. On the Developer Site, open Orchestration Activity for the app and select the orchestration. A new run should appear with a Run ID, a Current Status such as SUCCESS or FAILED, and the tenant where it ran.
  3. From the run, click View Logs. Your Log step's message should show the value you mapped, for example the event's WID. If the run exists but the value is empty, the launch worked and the key mapping is the thing to check.

If the step starts and the event never moves on, see orchestration service steps stuck in progress. If later steps need values the orchestration produced, see returning orchestration results to the business process step.

Sources checked