Web Services and API Integrations

Overview

Objectives

Leverage Workday web services in your orchestration workflows.
Configure and execute REST, SOAP, and External API calls using Workday Orchestrate components.
Process API responses to extract and transform data for downstream use.
Configure Orchestration Security.

Web Service Basics

Request
: The client, in this case Workday Orchestrate, sends a request to an API endpoint. The request includes at least a URL and HTTP method, and can include query parameters, headers, and a body.
Response
: The API server returns a response that includes a status code and, often, a body with data or error details. Common response formats include JSON and XML.

REST (REpresentational State Transfer).
SOAP (Simple Object Access Protocol).

REST is generally preferred for its simplicity and speed.
SOAP is chosen for its robust security and formal structure.

Fundamentals of API Calls in Workday Orchestrate

Making API Calls in the Orchestration Builder

Before you add an API call to an orchestration, decide whether you are calling an external service or a Workday API. Use Send HTTP Request for external endpoints and Send Workday API Request for Workday APIs.

To configure a basic external call with Send HTTP Request:

Open Orchestration Builder and add a step like Send HTTP Request.
In the Properties, select the HTTP method, such as GET, POST, PUT, PATCH, or DELETE. The component supports several methods, including DELETE, GET, OPTIONS, PATCH, POST, PUT, and HEAD.
Use Expression Builder to enter the request URL.
On the Auth tab, select an authentication type that matches the target service.
If the method requires a request body, configure it on the Body tab by selecting or composing the data and choosing an appropriate content type.

Request and Response Workflow

After you configure the API call, Workday Orchestrate runs the step, sends the request, and captures the response for use in subsequent steps.

Note

:

The response shown above is a dummy response, not the real data you will see when you try the API. This screen is only for documentation purposes.

Execute the Request:
Trigger the Send HTTP Request or Send Workday API Request step as part of the orchestration. Orchestrate sends the request to the configured endpoint.
Inspect the Response
: Review the response status code, such as 200 OK or 400 Bad Request, and the response body in JSON or XML format. Use the step's outputs to read headers, body content, and any error details.
Parse and Process Data
: Use downstream steps, such as Evaluate Expression or Create Values, to extract specific values from the response and store them in variables for further processing.
Integrate with Workflows
: Pass the processed data to later steps that send notifications, perform calculations, or update Workday records. For example, an orchestration can use retrieved exchange rates to calculate reimbursement amounts in different currencies.

REST Web Services

Retrieve data using GET methods.
Modify data using POST, PUT, PATCH, or DELETE methods.

Real-time access to business data for external or downstream processes.
Targeted, modular calls that retrieve or update specific resources.
Scalable integrations that handle frequent or high‑volume requests.

REST API Explorer

The REST API Explorer on the Workday Developer site documents Workday-delivered REST endpoints and provides an interactive interface to run them against a tenant. You can review endpoint details, configure requests, and inspect responses in the same view.

Key capabilities include:

Endpoint access
: Browse endpoints by service category, such as Expense or Workers.
Request input
: Enter query parameters and path variables in the Parameters area.
Payload testing
: Provide JSON request bodies for write operations.
Response review
: Execute requests and view status codes and JSON response data.
Security alignment
: Authenticate to a tenant and run APIs under that tenant’s security.

The REST API Explorer follows a similar workflow to the SOAP Explorer:

Log in to the Workday Developer Site.
Navigate to the REST API Explorer.
Select a service category, such as Supervisory Organizations.

Select the operation to test, such as GET /supervisoryOrganizations or GET /supervisoryOrganizations/{id}/workers.

Enter query parameters or path variables, such as a worker id.
Confirm required headers, such as Authorization and Content-Type, are present based on the endpoint and authentication model.
For POST, PUT, or PATCH operations, construct the JSON request body in the request area.
Execute the request and review the status code and returned data in the response section.

Adjust parameters or payloads as needed and resend the request until the response matches your requirements.

Handling REST API Responses

Handle REST API responses in Orchestrate the same way you handle other orchestration data: inspect the structure, extract only the fields you need, validate required values, and use Orchestration Logic components to control the flow. The patterns in this section apply to both paged and non‑paged REST steps.

Inspect the API Response

Start by understanding the JSON structure returned by the upstream step.

Use Run Logs and API Logs in Orchestration Builder to review status codes, paths, and payload sizes while you test.
Use orchestration debugging and Log / Log to File steps when you need to see intermediate values during development.
Identify whether the top-level structure is an object or array.

For Workday REST APIs, you can also inspect responses in the REST API Explorer before wiring the endpoint into your orchestration. Use the Explorer only for Workday APIs; it does not test external endpoints.

Parse and Extract Relevant Data

Use Expression Builder and JSON member functions to pull specific values from the REST response. The common pattern is:

Reference the upstream REST step response as a DataType value, then treat it as JSON.
Use JSON path accessors:
Use stringAtJsonPath to retrieve string values from JSON, such as worker IDs or descriptors.
Use numberAtJsonPath when you expect a numeric value.
When the response contains an array, use iterator("$.path[*]") and a Loop step or a text template each block to process each item.

Validate the Response

Validation generally focuses on two questions:

Are the required fields present (not empty or missing)?
Do the values match the types and patterns your orchestration expects?

Recommended patterns:

Check for existence before extraction:
For XML, the reference guidance is to use …WithDefault variants to avoid failing when a node is missing.
Apply the same pattern to JSON: prefer stringAtJsonPathWithDefault or similar variants when a field might be missing.
Combine checks with and()
When validating multiple required fields in JSON, use logical functions such as and() instead of chaining inline comparisons.
Example pattern: and(exists(fieldA), exists(fieldB)) to require both fields before processing.
Use Orchestration Logic for failures
Use Continue on Conditions to stop the orchestration when required output is missing or invalid and log a clear message.
Or use Branch on Conditions to route valid and invalid responses down different paths, as in the address‑selection example.

Store or Pass the Data

After you extract and validate the data, either use it within the same integration event or send it to another system. In most integration scenarios, data flows directly from the REST step into downstream logic or outbound calls within the same integration event, without additional persistent storage.

Use Store Document only when you have a clear requirement to persist data for audit or support purposes and, optionally, attach it to the integration event.

Store Document saves a DataType document and can attach it to the integration event.
Tags must already exist in the tenant; using a tag that is not defined causes the step to fail.

Using the Send Paged Workday REST Call Component

Use the Send Paged Workday REST Call component to request paginated responses from Workday REST APIs. Use this component when a GET collection endpoint supports limit and offset and can return large result sets, such as worker lists or WQL data. The component works like the Send Paged Workday SOAP Call component, but for JSON responses from REST APIs instead of XML SOAP responses.

Configuring the Send Paged Workday REST Call Component

When you run the Send Paged Workday REST Call step, Orchestrate sends a series of GET requests using the limit, offset, and Max Pages values you configured. It stops when it reaches the Max Pages setting or when the endpoint returns no additional items. Use this procedure to point the step at a specific REST collection endpoint and control how many pages it returns.

In Orchestration Builder, select the Send Paged Workday REST Call step and open its properties.
Alongside the prepopulated GET method and Workday API address, use Expression Builder to append the endpoint path (e.g., /staffing/v1/workers).
On the General tab, select the authentication credential to use for the request. The component uses this credential to handle Workday API authentication; you do not add Authorization headers.
Still on the General tab, set the pagination fields:
Limit: Items per page.
Offset: Starting index.
Max Pages: Maximum number of pages to request.
Flatten Result: Whether to combine all pages into one dataset.
If the endpoint supports additional filters or options, add them as key‑value pairs on the Query Parameters tab.
On the Settings tab, choose an HTTP retry policy if you want Orchestrate to retry failed calls under defined conditions.

Processing the Response

After the Send Paged Workday REST Call step runs, it returns JSON data from one or more pages of a REST collection endpoint. You process that data the same way you process any JSON response in an orchestration, with the main difference that it may represent multiple pages.

Use a Loop step with the component’s iterator output when you want to handle each item or page separately, mirroring the Loop pattern used with the SOAP pagination component but for JSON instead of XML.
The response body is a DataType document. Cast or treat it as JSON in Expression Builder, then use JSON functions to access fields (e.g., IDs, descriptors, or nested objects).
Use Create Values or other data operations to collect items from each iteration into a single structure that downstream steps can consume, following the same aggregation approach you used in the SOAP pagination workflow.

Error Handling

Handle errors for Send Paged Workday REST Call the same way you handle errors for other REST data‑request steps, with a focus on HTTP retry policies and orchestration control flow.

Define an HTTP retry policy in Orchestration Settings and assign it on the component’s Settings tab to control how often and under which conditions Orchestrate retries failed requests.
Add an error handler to the Send Paged Workday REST Call step when you want to catch failures locally, log details, or set a fallback result before the orchestration continues. This mirrors the pattern you use for the SOAP pagination component, but the error context and body are JSON instead of XML.
After the step, use Branch on Conditions or Continue on Conditions to change the flow based on outputs such as status, error flags, or empty‑result conditions, matching the “error handler or branch on conditions” approach from the SOAP pagination section.

SOAP and Workday Web Services

How SOAP Fits Within WWS

SOAP is one of the main protocols exposed by Workday Web Services. Each SOAP service publishes a WSDL that defines available operations, request structures, and response structures. This contract‑first model is well suited for tasks that require strong validation and predictable responses, such as Get operations that return paged data or Put operations that initiate business processes.

Key Elements of SOAP Operations

SOAP Get operations follow a consistent pattern that balances precision and flexibility:

Request Structure:

Request references that identify specific objects, such as worker IDs or organization IDs.
Request criteria that filter results, such as excluding inactive records.
Response filters that control page size and record counts.
Response groups that select which parts of the data model to return, such as personal data or compensation data.

Response Structure:

The response echoes the request filters so that you can confirm what the service evaluated.
Response results summarize the number of records and pages. </wd:Total_Results>">
Response data returns only the requested, security‑filtered data.

While the SOAP API Explorer will help provide you with a model of a request, that typically will not be enough. Workday Community has more complete documentation. The following will take you to the SOAP API Reference page on Community. https://community-content.workday.com/content/workday-community/en-us/public/products/platform-and-product-extensions/soap-api-reference.html?lang=en-us There you will probably want to look at the Public Web Services API Directory, or the Operations Directory for the complete documentation on WWS services.

Important

:

There are five different WWS that allow you to update contact information, like email addresses. You must do the research and decide which is the best for your use case. We know that our test case in the class is limited to only a few workers. Our WWS that we chose, Maintain_Contact_Information can easily handle that volume in our loop. But, there may be better performing options. Or options that allow for bulk updates. Do the research.

Implementing SOAP with WWS

Accessing the WSDL File:

In Workday Web Services documentation or SOAP API Explorer, locate the service and version that you need.
Review the operations, request elements, and response elements so that you understand the required references, criteria, and response groups.

Constructing a SOAP Request:

Use tools such as Workday Studio’s Web Services Tester or API Explorer to compose and validate the SOAP envelope.
For example, a Get_Workers request can include a Response_Filter with a Count element and any criteria that exclude inactive workers. </wd:Count>">
Wrap the request with a SOAP envelope.

Processing SOAP Responses:

Unwrap the response from the SOAP envelope.
Inspect the echoed request elements and response results to confirm that the service used the expected filters and page settings.
Extract data from the response using built‑in, type‑specific functions in Orchestrate. For multi‑step processing, use Create Values to store extracted values so that you do not repeat the same parsing and transformation in later steps.

Parsing XML Data

XML is used widely in integrations, especially with Core Connectors and some third-party systems. In Workday Orchestrate, you use XPath expressions in Expression Builder to extract values from XML so that orchestrations can work with specific elements or attributes.

XPath is a query language for navigating XML structures. Orchestrate supports a subset of XPath and provides type‑specific functions such as stringAtXPath, countItemsAtXPath, and iterator.

To select data with XPath:

All employee names: /Employees/Employee/Name.
The department of the first employee: /Employees/Employee[1]/Department.

Processing XML Collections with a Loop

XML often contains repeating elements, such as a list of Employee nodes. You do not need to “extract” these nodes first. Instead, you configure an iterator over the set of elements you want and loop through them one at a time.

Typical pattern:

In Expression Builder, call response.iterator("/Employees/Employee") on the XML document to create an XmlTypeIterator over the Employee elements.
Configure a Loop step to iterate over that iterator so that each iteration receives one Employee element as the current item.
Extract values from the current item:
ID: stringAtXPath("/Employee/ID").
Name: stringAtXPath("/Employee/Name").

SOAP API Explorer

The SOAP API Explorer on the Workday Developer Site provides a guided way to view these elements, test requests, and review responses before you configure an orchestration.

Access the SOAP API Explorer:

Sign in to the Workday Developer Site.
Open the SOAP API Explorer and sign in to the target tenant.
Select a service and version, such as Human_Resources and a specific version.
Choose an operation, such as Get_Workers for retrieving worker data.

Configure the SOAP Request

After you select an operation, the SOAP API Explorer generates a base XML request.

Start with the prepopulated XML template for the operation.
Edit key elements in the body to match your use case:
Request references for specific business objects, such as worker instance references.
Request criteria that limit the result set, such as excluding inactive workers.
Response filters that control page size and record limits.
Response groups that specify which sections of data to return.
Send the request to test the configuration and review the XML response, including the echoed filters and response results.

Note

: Before your request is sent to the server, the application will perform certain validations to ensure integrity and accuracy of the request.

Handling SOAP Responses

SOAP responses from WWS are XML documents that include the envelope, body, and the service‑specific response. Before you extract data, review the structure to identify important elements and namespaces, such as Envelope, Body, and service prefixes like wd.

In Workday Orchestrate:

Use the unwrapSOAP global function in Expression Builder to remove the SOAP envelope and body from the response. This returns the inner service XML so that your XPath expressions can start at the service response node instead of at /env:Envelope/env:Body.
Apply XPath global functions to the unwrapped XML to extract and validate data. For example:
Extract a worker ID: stringAtXPath("/wd:Get_Workers_Response/wd:Response_Data/wd:Worker/wd:ID[@wd:type='Employee_ID']")
Count workers: countItemsAtXPath("/wd:Get_Workers_Response/wd:Response_Data/wd:Worker")
Handle missing values with a default: stringAtXPathWithDefault("/wd:Get_Workers_Response/wd:Response_Data/wd:Worker/wd:Name", "Unknown")
For multi-step processing, store extracted values in a Create Values step so that you do not repeat the same XPath expressions across multiple steps and branches.

Key elements include:

Root
Elements
: Envelope and Body.
Response
Data
: Hierarchical nodes like Worker with child elements (ID, Name).
Namespaces
: Ensure correct usage of prefixes (env, wd) in XPath queries.

Tip

: Use tools like the SOAP API Explorer or SOAP UI to inspect and test responses before integrating them into an orchestration.

Workday Orchestrate provides XPath functions to extract data efficiently from SOAP responses. Use these functions within the Expression Builder to retrieve specific elements, attributes or to validate the incoming data.

Examples:

Extract a worker's ID: stringAtXPath("/env:Envelope/env:Body/wd:Get_Workers_Response/wd:Response_Data/wd:Worker/wd:ID[@wd:type='Employee_ID']")
Extract a worker's name: stringAtXPath("/env:Envelope/env:Body/wd:Get_Workers_Response/wd:Response_Data/wd:Worker/wd:Name")
Count the number of workers: countItemsAtXPath("/env:Envelope/env:Body/wd:Get_Workers_Response/wd:Response_Data/wd:Worker")
Handle null values with default values: stringAtXPathWithDefault("/env:Envelope/env:Body/wd:Get_Workers_Response/wd:Response_Data/wd:Worker/wd:Name", "Unknown")

About Security

Domain security policies.
Authentication credentials for orchestrations.
Endpoint authentication.

Endpoint Authentication

Specify an authentication scheme for each endpoint invoked by an integration app.

Access Token From Initiating User, uses the same credentials as the user that launches the Integration. And can be applied to Workday REST APIs, Workday SOAP APIs, and Prism APIs.
The Integration System User endpoint authentication scheme is also available for Business Process Template orchestrations.