The endpoints that act on a step

An orchestration approves, denies or sends back a business process step by calling the Business Process REST service's Event Steps API with a Send Workday API Request step. The three calls are POST /eventSteps/{ID}/approve, POST /eventSteps/{ID}/deny and POST /eventSteps/{ID}/sendBack, and they are the API equivalents of the Approve, Deny and Send Back buttons in the inbox.

The catch is who the call acts as. These endpoints act on a step that is awaiting the processing user. If the step isn't in progress, or isn't awaiting the user the request runs as, Workday rejects the call with error A212, This event is not awaiting your action.

Get the event step ID, not the event ID

{ID} is the ID of the event step, which is different from the business process event. If you only have the event, ask for its open steps first:

GET /businessProcess/v1/events/{eventId}/inProgressSteps

Each item in data has the step's id, its status (for example Awaiting Action) and awaitingPersons, the people the step waits on. Use that id in the approve, deny or send back path. In Orchestrate, read it with a JSONPath accessor on the response, for example:

data("GetOpenSteps", "response").asJSON().stringAtJsonPath("$.data[0].id")

If the event can have parallel open steps, don't take data[0] blindly. Pick the step whose awaitingPersons includes the user the call will run as.

Two other ways to find steps are useful. GET /eventSteps returns the steps awaiting the current processing user. It requires either a businessProcess query parameter, the Workday ID of the business process type, or a stepType parameter with a reference ID such as Workflow_Step_Type_ID=APPROVAL from Workday's step type reference. GET /eventSteps/{ID} reads back a single step.

If the orchestration was launched by the business process itself, it gets the event ID from the trigger's data. See getting the WID of the business process that launched an orchestration.

Request bodies

All three use the Business Process service. In Send Workday API Request, set the method to POST, put the path after the prepopulated Workday API address, and set the body on the Body tab as application/json.

Approve. comment is the one required field:

POST /businessProcess/v1/eventSteps/{eventStepId}/approve
{ "comment": "Approved: within cost center budget" }

The response includes eventStatus, so you can see straight away whether the event moved on.

Deny. Send a comment. The API reference also lists the step's id and, when there are multiple event steps, a stepAction ID among the fields to supply. Workday's guide sample sends only the comment:

POST /businessProcess/v1/eventSteps/{eventStepId}/deny
{ "comment": "Denied: duplicate Equipment Request" }

Workday's sample response shows a stepAction of Denied and an eventStatus of Process Terminated. Deny ends the event, so only automate it on a rule you would defend in an audit.

Send back. Name the step to return to in to.id, and give a reason. Both are required:

POST /businessProcess/v1/eventSteps/{eventStepId}/sendBack
{
  "reason": "Add the asset tag before approval",
  "to": { "id": "{completedEventStepId}" }
}

The to.id must be an event step the event has already completed, which you get from GET /events/{eventId}/completedSteps. The response shows status Sent Back. For an Extend business process, send back only works as a designed path when the business process allows SEND_BACK on its approval step, and then it must also define a revisePageRoute, the page the recipient uses to revise and resubmit.

For deny and send back, Workday also requires the processing person to have View access to the event at the time of the call.

Run the call as the person the step is waiting on

Because of A212, the credential decides whether this design works at all. An ISU credential makes the call as the ISU. Business process routing assigns approval steps to people and roles, so the step is normally not awaiting the ISU, and the call is rejected. Workday's own examples make each call as the person the step is awaiting. Workday also recommends access tokens over ISU credentials for the related Trigger Business Process component.

That leaves two patterns that work:

  1. The approver starts it. The approver acts in your Extend page, and the call is made as that signed-in person. If the page itself makes the call, no orchestration is needed at all. Workday's page-route documentation shows a page calling the Business Process service through an outbound endpoint with authType set to sso, which runs as the signed-in user. Use an orchestration only when the approval has to be combined with other work, and run its Workday calls as that user, not as an ISU.
  2. Reassign, then act. POST /eventSteps/{ID}/reassign lets a business process administrator who has access to the step and permission to reassign it add assignees with addAssignees. Reassigning moves the decision to another person. It doesn't approve anything, and the event's history will show the reassignment.

If the requirement is "approve automatically when a rule is met", that is usually a business process definition change rather than an orchestration. An entry condition on the approval step (Business Process > Maintain Step Conditions on the step) decides whether the step runs at all, and keeps the decision inside the framework's audit trail. Use the API when a person has decided and the system is only carrying the decision.

The SOAP alternative

The Integrations SOAP web service has Approve_Business_Process, Deny_Business_Process and Send_Back_Business_Process. They take an Event_Reference to the business process event, not an event step ID. Send_Back_Business_Process names the step to return to by its reference ID in Business_Process_Step_ID, and requires a Comment. The schema carries a deny validation that a business process can't be denied through the web service, and another for a task that has been delegated. The same rule applies as for REST: the operation acts for the processing user, so the credential question doesn't go away.

Prove the action took

Don't stop at a 2xx response. Read the event back:

  1. GET /events/{eventId}/inProgressSteps should no longer list the step you acted on. It shows whatever step the event moved to.
  2. GET /events/{eventId}/completedSteps should list your step, with your text in its comments.
  3. GET /events/{eventId} shows the event's overall status. After a deny, the event has ended.

Log the step ID, the action and the event status from the response with a Log step, so the run in Orchestration Activity records what it decided. For security failures on any of these calls, see Permission Denied (S22) in a business process orchestration.

Sources checked