How to put an Extend app into the Onboarding or Hire business process

Two ways in, depending on what the app needs

There are two documented ways to make an Extend app part of the Onboarding or Hire business process. The light one is a To Do: add a context-free model task to a To Do with the Maintain To Dos task, then add a To Do step that uses it to the business process definition. The heavier one is an Extend subprocess: make an Extend business process a subprocess of the delivered process, so its initiation page appears in My Tasks as a step of the hire.

Pick by one question: does the page need to know which hire it belongs to, or need its own approvals? If the new hire only has to open a form and fill it in for themselves, a To Do is enough. If the page must read the hire event, write a record linked to it, or route the result for approval, use a subprocess.

Route 1: a context-free task as a To Do

A To Do is an independent task added as a step to a business process; Workday's own example is a new hire completing a tax form during hiring. Workday lists To Dos among the entry points for context-free model tasks, alongside dashboards, announcements and Journeys.

1. In App Builder, add a Task component with no businessObject, so it is context-free. Its routePath must match a routingPattern in the AMD, and securityDomains must name domains defined in the app:

   {
     "id": 1,
     "name": "CompleteEquipmentRequest",
     "label": "Request Your Equipment",
     "routePath": "/newHireEquipment",
     "securityDomains": ["NewHireEquipment"]
   }
   

2. Deploy the app, then in the tenant run Maintain To Dos and add the task to the To Do. The instructional text you write there is what shows on the My Tasks item.

3. Edit the Onboarding (or Hire) business process definition and add a To Do step that uses it.

4. In the app's domain security policy, add the groups who will run the task.

Step 4 depends on contextual security. If no SINGLE_INSTANCE field anywhere in the app has "secureByTarget": true, Workday allows only public and unconstrained security groups on the app's domains. A self-service group like Employee as Self needs the app to apply contextual security somewhere, typically a worker field on the business object the page writes.

Place the step where the new hire can reach it. Workday's onboarding guidelines recommend putting Onboarding after the Create Workday Account step in Hire, and assigning self-service onboarding steps to both the pre-hire and the active worker groups so a moved start date doesn't leave the task unassigned. You can make several To Do and action steps appear together by giving them the same order letter.

What a To Do can't do is hand the page any context. The task opens the app's page cold: no hire event, no worker ID in the route. For a new hire filling in their own request, read the signed-in worker with /workers/me and write that worker onto the record; the current-user guide shows the endpoint. If someone other than the hire completes the To Do, such as a hiring manager or IT administrator, a context-free page has no way to know which hire they mean, and that is the signal to use a subprocess.

A To Do also doesn't prove the work was done. Workday's onboarding guidelines point out that people can submit a To Do step without completing the intended action, so the hire can move on whether or not your app's record exists. In the subprocess route the step advances only when the initiation page submits it.

Route 2: an Extend subprocess under Onboarding or Hire

Here the Extend business process becomes part of the delivered process. First check the View Business Processes Available to Extend report in the tenant; only the delivered processes it lists can be parents.

1. In App Builder Visual mode, open the Extend business process and select the Parent Business Processes tab.
2. Click Add Initiating Action and select the parent process. One Extend subprocess can take up to 5 initiating actions and up to 5 unique parent processes.
3. Enter an Initiation Task Name. It must be unique in the parent's configuration and is what appears in the parent's definition, with "(Workday Extend: App Name)" appended so you can tell apps apart.
4. Enter an Initiation Page Route, such as /initEquipment/{eventStepId}. This page appears in My Tasks for whoever the initiating step routes to.
5. In App Manager, configure the subprocess's business process security policy and definition, then add the initiating step to the parent's definition.

Rescind is turned on automatically for a new Extend business process configured as a subprocess.

What the initiation page has to do

At initiation, the subprocess event's target is the parent event, not one of your records. The page has to fix that, in this order:

1. Read the current step with GET eventSteps/{eventStepId} using queryParams.eventStepId, and read its event with GET events/{id} from the step's event.id. That event's for.id leads to the parent event, which carries the hire's own target and initiator. The processing user needs access to the parent event, for example View All on the parent's security policy.
2. Create or select a record of your Extend business object.
3. PATCH the subprocess event, {businessProcessName}Events/{eventId}, with businessProcessTarget.id set to that record.
4. Submit the initiation step with POST eventSteps/{eventStepId}/submit, but only if the PATCH succeeded.

Workday's example guards step 4 with an exclude on the submit endpoint:

"exclude": "<% !patchEquipmentEvent.businessProcessTarget %>"

Without that guard, a failed PATCH leaves the parent event as the subprocess target: the My Tasks item for the initiation step disappears, and the subprocess routes on the parent event's target instead of your record. Workday's example of a failing PATCH is empty input, when the user can't create the record or didn't select one.

How routing changes after the first step

The initiation step routes by the parent event's target. Workday's example is Create Position, whose target is a supervisory organization: a role-based group works on the initiating action, but Employee as Self leaves the step unassigned because self-service groups can't apply to an organization. Check what your parent process targets before you choose groups. To see an event's security context, use the Business Process > View Security related action on the event (secured by the Business Process Administration domain).

Once the initiation step is submitted, the target is your Extend record, and every later step of the subprocess routes on that record's security like a standalone Extend business process. See model business processes for how those steps and their pages work.

One permanent consequence: after you promote the app from a Development tenant, you can't detach the subprocess from its parent. You can only remove the step from the parent's business process definition.

Prove it in a hire, not in the app

Neither route can be checked from the app on its own, because both depend on the tenant's business process definition. In a non-Production tenant:

1. Run a hire through to the step you added.
2. Sign in as the person it should reach and confirm the My Tasks item is there. If it isn't, open the event's process history and look for an unassigned step; the awaiting-action guide covers reading that.
3. Complete the page, then read your business object record back and confirm it holds the right worker. For a subprocess, also confirm the subprocess event's target is that record, and that the next step went to the people your Extend definition names.

With the client's consent, kiweely can do this walk in their sandbox: run the hire, open the task in the browser as the assigned role, and read the record and event back afterwards, so routing problems surface as an unassigned step you can see rather than a complaint on someone's first day.