Triggering a Workday Business Process from an Extend App (and Reading Status Back)

Triggering a model business process in a Workday Extend app is a two-step API sequence: first, create or select an instance of the target Custom Business Object (POST /apps/{appId}/v1/{collection}), and second, pass that record's Workday ID inside businessProcessTarget.id to the generated Extend Business Process Event REST API (POST /apps/{appId}/v1/{businessProcessName}Events). To read the approval status, current assignees, or completed steps back into your app, call the Workday Business Process REST service (GET /businessProcess/v1/events/{eventId} and GET /businessProcess/v1/events/{eventId}/inProgressSteps).

Whether you are initiating an Extend model business process, triggering a Workday-delivered business process via Graph API or REST, or pausing an asynchronous orchestration until an approval completes, the endpoints, payload schemas, and inbox routing rules follow strict contracts.

Four ways an Extend app interacts with Workday business processes

Step-by-step: Initiating an Extend model business process

Every Extend business process (limit: 5 per app) must be associated with a targetBusinessObject in its .businessprocess model file and secured by an app security domain configured in App Manager.

Because the Extend Business Process Event API does not accept arbitrary business object fields in its request body (it accepts only businessProcessTarget and description, up to 500 characters), your PMD edit page or orchestration must create the Custom Business Object record first and chain its returned id into the event creation call.

1. Create the target Custom Business Object instance

On your PMD initiation page (or in an orchestration), define the first outbound endpoint to POST the user's form inputs to the Custom Business Object API:

POST https://api.workday.com/apps/tuitionApp_abcdef/v1/tuitionRequests

Workday returns the newly created business object instance, including its 32-character Workday ID (id).

2. Initiate the Business Process Event

Define a second outbound endpoint in outboundEndPoints[] after the business object endpoint. Workday invokes PMD endpoints sequentially in the order they appear in the PMD file, so the second endpoint can reference <% createTuitionRequest.id %> directly:

{
  "outboundData": {
    "outboundEndPoints": [
      {
        "name": "createTuitionRequest",
        "baseUrlType": "app",
        "url": "tuitionRequests",
        "httpMethod": "POST",
        "authType": "sso"
      },
      {
        "name": "initiateTuitionBP",
        "baseUrlType": "app",
        "url": "tuitionReimbursementApprovalEvents",
        "httpMethod": "POST",
        "authType": "sso",
        "values": [
          {
            "outboundPath": "businessProcessTarget.id",
            "value": "<% createTuitionRequest.id %>"
          },
          {
            "outboundPath": "description",
            "value": "<% 'Tuition reimbursement for ' + worker.descriptor %>"
          }
        ]
      }
    ]
  }
}

Notice the URL naming convention: Workday appends Events to the name of your .businessprocess component (TuitionReimbursementApproval becomes tuitionReimbursementApprovalEvents). The response returns the new business process event id, descriptor, and businessProcessTarget.

Configuring inbox page routes and advancing steps

When an Extend business process routes steps to a user's Workday Inbox (My Tasks), your .businessprocess model definition maps each step type to a PMD pageRoute that matches a routingPattern in your App Metadata (.amd) tasks[] array:

{
  "id": 1,
  "name": "TuitionReimbursementApproval",
  "label": "Tuition Reimbursement Approval",
  "targetBusinessObject": "TuitionReimbursementRequest",
  "allowsCancel": true,
  "useForOrchestrate": true,
  "approvalStep": {
    "actions": ["APPROVE", "DENY", "SEND_BACK"],
    "pageRoute": "/approve/{eventId}"
  },
  "details": {
    "pageRoute": "/details/{eventId}"
  },
  "actionSteps": [
    {
      "id": 1,
      "name": "ReviewRequest",
      "label": "Review Reimbursement Request",
      "pageRoute": "/actionStep/{eventStepId}"
    }
  ],
  "revisePageRoute": "/revise/{eventStepId}"
}

How {eventId} and {eventStepId} work on routed PMD pages

Advancing an Action or Revision step via /eventSteps/{id}/submit

To advance an Action step or a sent-back Revision step from its PMD edit page, add a data provider for https://api.workday.com/businessProcess/v1/ in your .amd and call POST /eventSteps/{id}/submit with the required stepAction.id WID:

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

Workday accepts two fixed WIDs for stepAction.id:

• d9e4223e446c11de98360015c5e6daf6: Submitted (used on both Action steps and Revision pages)
• d9e41a8c446c11de98360015c5e6daf6: Saved for Later (supported on Action steps only)

(Note: POST /eventSteps/{id}/submit is a built-in Business Process service endpoint, even though it is not listed in the public REST API Explorer.)

Reading business process status and assignees back into your app

To display real-time approval status, initiator details, awaiting approvers, or comments inside an Extend page or orchestration, call the businessProcess/v1 REST endpoints through the API Gateway. Users calling these endpoints require permissions on the Core Navigation and Public Business Processes (Tenant Non-Configurable) security domains, plus view permissions on the business process security policy.

1. Reading status when you have the eventId

Call GET https://api.workday.com/businessProcess/v1/events/{eventId}:

{
  "id": "49367bfa904f9001addc140bf5f50000",
  "descriptor": "Tuition Reimbursement Approval: Request 104",
  "for": {
    "id": "49367bfa904f9001add1a9fbe1530000",
    "descriptor": "Request 104"
  },
  "status": {
    "id": "e2d08afc53614c37b32b31270bb8bee3",
    "descriptor": "In Progress"
  },
  "initiator": {
    "id": "3aa5550b7fe348b98d7b5741afc65534",
    "descriptor": "Logan McNeil"
  },
  "creationDate": "2026-11-04"
}

Note that for.id returns the Workday ID of the underlying Custom Business Object (businessProcessTarget), which your approval or details page (queryParams.eventId) can pass to a second inbound endpoint (GET /apps/{appId}/v1/{collection}/<% bpEvent.for.id %>) to load all custom fields of the record.

2. Reading status from an Action step page where you only have eventStepId

On an Action step or Revision PMD page, Workday passes queryParams.eventStepId rather than eventId. Chain two inbound endpoints in endPoints[]:

1. stepInfo: GET /businessProcess/v1/eventSteps/<% queryParams.eventStepId %> — returns event.id.
2. eventInfo: GET /businessProcess/v1/events/<% stepInfo.event.id %> — returns status.descriptor and for.id (the target Custom Business Object ID).

3. Inspecting awaiting approvers, completed steps, or worker event lists

Connecting Business Processes and Orchestrate

1. Pausing an asynchronous orchestration on an Extend BP (useForOrchestrate: true): Set "useForOrchestrate": true (Enable for Orchestrate) in your .businessprocess file when an orchestration initiates the Extend business process via Send API Request and needs to pause while human approvals run, resuming only when an Orchestration Service step on the business process definition signals completion.
2. Triggering an orchestration from a business process step: Create an orchestration using the Workday Business Process starting point, configure its expected input keys on the Business Process Trigger step, deploy the app, and add a Service step (Orchestration Service) to the business process definition in your tenant. Check Advance business process step when orchestration completes if the workflow must wait for the orchestration to finish.
3. Launching an orchestration on Cancel, Rescind, Correct, or Deny: After deploying a Workday Business Process orchestration (which must use ISU authentication if it makes API calls), set User to Perform Orchestration Launches in Edit Tenant Setup - Business Processes, then open Business Process > Configure Orchestrations on the business process and create an Orchestration Launch Configuration (Workday does not create launch configurations automatically on deployment). Remember that a Rescind action on an Extend business process only marks the event as rescinded—it does not automatically roll back Custom Business Object data unless your rescinding orchestration explicitly reverses those writes.

How kiweely fits

kiweely builds your Custom Business Objects, .businessprocess definitions, inbox PMD pages, and status-tracking endpoints against your live tenant—verifying that step actions, security policies, and page routes work end to end. In your Workday personal developer account and its tenant, Kiweely Personal is free (Kiweely Personal is free for your Workday personal developer account and its tenant. Any other tenant needs a Personal licence, $99 a month, or a seat in your firm.).

Frequently asked questions

Why did my outbound endpoint on an Approval page never run when the approver clicked Approve?

On a PMD page mapped to approvalStep.pageRoute, Workday's business process framework replaces the standard page Submit button with the configured approval action buttons (Approve, Deny, Send Back) and does not invoke any outboundEndPoints defined on that PMD. Workday recommends using a view page for approvalStep.pageRoute. If an approver needs to enter data and trigger an outbound endpoint during the workflow, use an Action step (actionSteps[]) instead, or trigger an orchestration from the business process definition after the approval step completes.

Can I pass custom fields directly into POST /{businessProcessName}Events or run it with ?bulk=true?

No to both. The Extend Business Process Event REST API does not support ?bulk=true (each event must be initiated individually), and its POST body only accepts businessProcessTarget.id and description. Store all custom payload fields on the target Custom Business Object first, then retrieve them on your approval or action PMD pages using for.id from GET /events/{eventId}.

Why can't I select my newly deployed orchestration in the Configure Orchestrations task?

Deploying an app to your tenant does not automatically create an Orchestration Launch Configuration. When pairing a Cancel, Rescind, Correct, or Deny status change in Business Process > Configure Orchestrations, select Create Orchestration Launch Configuration in the Orchestration prompt first, map your input parameters, and then select that new configuration.