The record comes first, the event second

An Extend business process (Workday also calls it a model business process) never carries data of its own: it runs against one record of an Extend business object, called its target. To create a transaction, you create that record, then start a business process event that points at it, and Workday's business process framework handles routing, inbox items, approvals and history from there.

That ordering explains most first-build confusion. The event-initiation endpoint accepts only two fields, businessProcessTarget and description. You can't pass the request's amount, dates or worker in the event body; they live on the business object, and every step page reads them from there.

What you define in App Builder

A business process component has a name, a targetBusinessObject, the security domains that govern its steps, and the page routes for each screen. Workday's Add Business Processes page shows the shape in Code mode; this one adds an action step and send-back:

{
  "id": 1,
  "name": "EquipmentRequestApproval",
  "label": "Equipment Request Approval",
  "targetBusinessObject": "EquipmentRequest",
  "securityDomains": ["ManageEquipmentRequests"],
  "allowsCancel": true,
  "approvalStep": {
    "actions": ["APPROVE", "DENY", "SEND_BACK"],
    "pageRoute": "/approve/{eventId}"
  },
  "details": { "pageRoute": "/details/{eventId}" },
  "actionSteps": [
    {
      "id": 1,
      "name": "ConfirmDelivery",
      "label": "Confirm Delivery",
      "pageRoute": "/actionStep/{eventStepId}"
    }
  ],
  "revisePageRoute": "/revise/{eventStepId}"
}

Each pageRoute must match a routingPattern in the tasks array of the app's AMD. The placeholder decides what the page receives: approval and details pages get the event in queryParams.eventId; action and revise pages get the step in queryParams.eventStepId.

Rules worth knowing before you design:

  • The target must be an Extend business object, not a Workday-delivered one.
  • If SEND_BACK is an allowed approval action, revisePageRoute is required.
  • Visual mode lets you add up to 5 steps on the Steps tab, and an app can hold up to 5 business processes.
  • If you leave out approvalStep, people configuring the definition can't add approval steps to it.
  • Security domains on the business process override the business object's default domains for the event objects, but don't grant access to the target record itself.
  • If the target business object has no "secureByTarget": true field, role-based security groups won't work properly in the business process security policy.

What each page does in the inbox

The framework sends each step's page to the assignee's inbox. The approval page should be a view page: Workday adds Approve, Deny and Send Back buttons for the allowed actions and moves the step itself. If you build it as an edit page anyway, the framework replaces the Submit button with those buttons and the page won't call any outbound endpoint. If the definition has several approval steps, they all share the same approval page, so branch inside it.

Action, initiation and revise pages are the only ones that can call outbound endpoints. An action page saves its data to the business object and then advances the step by calling the Business Process REST service:

{
  "name": "submitStep",
  "baseUrlType": "WORKDAY-BP",
  "url": "<% '/eventSteps/' + queryParams.eventStepId + '/submit' %>",
  "httpMethod": "POST",
  "authType": "sso",
  "values": [
    { "outboundPath": "stepAction.id", "value": "d9e4223e446c11de98360015c5e6daf6" }
  ]
}

WORKDAY-BP is a data provider in the AMD pointing at https://api.workday.com/businessProcess/v1/. Workday documents two step-action values: d9e4223e446c11de98360015c5e6daf6 submits an action step or revision, and d9e41a8c446c11de98360015c5e6daf6 saves an action step for later. The submit endpoint works only for Extend business processes, only through the Extend API Gateway, and only when the signed-in user is the one awaiting action on the step. If you omit an approval page route, Extend shows a basic approval in My Tasks with no context about the request.

Starting the event

Deploying the app generates an app-specific API with POST /{appId}/v1/{businessProcessName}Events. The resource name is the business process name with "Events" appended: Workday's samples call createCharityEvents for a process named CreateCharity, so EquipmentRequestApproval becomes equipmentRequestApprovalEvents. From an initiation page, the usual shape is two outbound endpoints in order: create the record, then start the event with the new record's ID.

{
  "name": "startApproval",
  "baseUrlType": "app",
  "url": "equipmentRequestApprovalEvents",
  "httpMethod": "POST",
  "authType": "sso",
  "values": [
    { "outboundPath": "businessProcessTarget.id", "value": "<% createRequest.id %>" },
    { "outboundPath": "description", "value": "<% itemName.value %>" }
  ]
}

The response returns the event's id and a descriptor such as "Equipment Request Approval: Laptop". Two documented limits shape how you call it: the event API doesn't support bulk operations, so events are started one at a time, and it's available only through the Extend API Gateway, not as a tenant-based REST URL. External callers need an OAuth 2.0 API client on the Developer Site with the Workday-Owned scope.

An orchestration can start the process too. Turn on Enable for Orchestrate ("useForOrchestrate": true) if you want the Trigger Business Process component to start it; the orchestration then pauses when the process starts and resumes only when an Orchestration Service step on the definition resumes it. The Trigger Business Process guide covers that path.

What Extend business processes can and can't do

Extend business processes support Action, Approval, Approval Chain, Checklist, Complete Questionnaire, Integration, Report, Report Group, Review Documents, Service and To Do steps, plus condition rules, comments, notifications, attachments and the business process security policy. They don't support Batch/Job, Consolidated Approval, Consolidated Approval Chain or Edit Additional Data steps, the Correct or Manual Advance actions, delegation, or more than one business process definition: you get one default definition, with no organization-based or rule-based variants. An Extend business process can't have subprocesses of its own, but it can be a subprocess of a Workday-delivered one, which is how you put an Extend step inside Onboarding or Hire.

The definition and its security policy live in the tenant, not in the app. After deploying, open App Manager, select the app, and configure the business process policy and definition the way you would for a delivered process.

Design choices Workday leaves to you

Workday doesn't lock the target record while the process runs or after approval. If a page edits the record later, the event details in the business process history can show the new values, though the business object's audit trail keeps the change. If history must reflect the data as approved, don't build pages that edit approved records. When a record must change after approval, Workday suggests an action step straight after the approval step, an asynchronous orchestration, or a scheduled integration that reads approval events.

Once a record is linked to a business process, that record can't be deleted. Workday also leaves parallel requests to you: decide whether one person may have several requests in flight at once, and if not, make the initiation page check for an open one.

Prove the process works

Check each stage against Workday rather than the page's success message:

  1. Read the event back: GET /events/{eventId} in the businessProcess service returns its status (for example "In Progress"), initiator and for, which should be the record you created.
  2. Read who holds it: GET /events/{eventId}/inProgressSteps lists the current step, its status ("Awaiting Action") and awaitingPersons. If awaitingPersons is empty on a step you expected to route, check the business process security policy and the secureByTarget field before the pages.
  3. Sign in as the approver, open the inbox item, and act on it. Then repeat step 1 and confirm the status moved.
  4. For send-back, confirm the revise page received eventStepId and that resubmitting returned the item to the approver. The send-back guide shows how to read the reviewer's comment on that page.

Sources checked