Workday Extend Orchestration Tutorial: From Basics to Advanced Patterns

Introduction to Workday Extend Orchestration

Workday Extend empowers organizations to build custom applications that seamlessly integrate with their Workday environment. A cornerstone of this capability is Workday Orchestration Builder, a powerful tool that enables developers to create real-time, event-driven processes across Workday and other external systems. These processes, known as orchestrations, are fundamental for complex integration workflows, data transformations, and automated business logic.

An orchestration is essentially a series of interconnected components designed to manipulate data and execute actions in a step-by-step manner. Workday processes these orchestrations from top to bottom, ensuring a clear and predictable flow of operations. This tutorial will guide you through the core concepts of building orchestrations, from defining basic steps and conditional logic to implementing robust error handling and understanding various integration patterns. By the end, you'll have a comprehensive understanding of how to leverage Workday Extend Orchestrations to build sophisticated and resilient solutions.

Core Concepts of Workday Extend Orchestrations

At its heart, Workday Extend Orchestration is about defining a sequence of operations to achieve a specific business outcome. This section will lay the groundwork by explaining what an orchestration is, how it's constructed, and the fundamental principles of its operation.

What is an Orchestration?

An orchestration is a structured process composed of various components linked together to manipulate data and interact with systems. Workday Orchestration Builder provides a visual, drag-and-drop interface for constructing these processes. Every new orchestration automatically includes starting and ending steps, forming the boundaries of your process. Additional components, organized into logical groups such as "Data Requests" and "Orchestration Logic," are available in a panel within the Orchestration Builder interface. Each component comes with its own set of associated properties that you configure to define its specific behavior.

Orchestrations are purpose-built for creating real-time, event-driven integrations. For instance, a business process event within Workday can trigger an orchestration, which then proceeds to call a series of APIs to update data in multiple external systems, and finally sends a notification back to Workday.

Orchestration Builder Basics

The Orchestration Builder is the visual environment where you design and configure your orchestrations. It utilizes a drag-and-drop interface, allowing you to easily connect various steps to form your workflow. When you add a component to the canvas, you typically provide a meaningful Reference Name for that step, which helps in identifying its purpose within the orchestration.

Steps and Data Flow

Workday processes orchestrations on a step-by-step basis, executing components sequentially from top to bottom. This sequential execution is crucial for understanding how data flows through your orchestration. Data manipulated in an earlier step can be referenced and used in subsequent steps, enabling complex data transformations and dynamic decision-making.

A key feature of Orchestrate is its ability to easily transform data between different formats. For example, you can take the JSON output from a REST API call and map it to the XML format required by a SOAP service. This capability is vital for integrating disparate systems that may use different data structures.

Practical Examples: Building Orchestration Logic

Once you understand the basics, you can start building more sophisticated orchestrations using conditional logic, managing execution paths, and handling errors.

Conditional Logic

Conditional logic is essential for creating dynamic orchestrations that adapt their behavior based on specific data or circumstances. Workday Extend provides several ways to implement conditions.

Adding Conditions in Expression Builder

Anywhere in Orchestration Builder where you see the Add condition for value button, you can define how your orchestration proceeds under specific conditions. Each condition is composed of two values and a relational operator. To define a condition:

1. Define the first value: Use the Expression Builder to specify the data point or expression for the first value.
2. Select a relational operator: Choose from the Condition drop-down menu (e.g., equals, greater than, contains).
3. Define the second value: Use the Expression Builder again to specify the data point or expression for the second value.

The values you define can leverage data from other parts of the orchestration, allowing for highly dynamic conditions. Orchestration Builder compares these values using the selected operator to determine if the expression evaluates to true.

Conditions can also be nested, meaning you can add conditions to the expressions that define your primary conditions. The Orchestration Builder interface darkens with each level of nesting to indicate you're working on a deeper condition. You can also compare numbers directly using member functions of the Number type.

For scenarios requiring multiple conditions within a single statement, you have two options:

• All of these conditions must be met: This evaluates the conditions using a logical AND. The entire condition is true only if every individual condition evaluates to true.
• One of these conditions must be met: This evaluates the conditions using a logical OR. The entire condition is true if any of the individual conditions evaluate to true.

Branch on Conditions Component

The Branch on Conditions component is a powerful tool for directing the flow of your orchestration based on a condition. When you drag this component onto the canvas, Orchestration Builder automatically creates IF and ELSE branches.

• IF Branch: The properties panel for the IF branch opens, where you use Expression Builder to specify the condition. If this condition evaluates to true, the components within the IF branch are executed.
• ELSE Branch: This branch doesn't have properties and is executed if the IF condition evaluates to false.

You can add any other orchestration components within these branches to define the specific actions for each path. To create additional conditional paths, you can select Add Branch from the branch section's related actions menu, creating more IF branches. Orchestrate evaluates these branches from left to right and executes only the first branch that evaluates to true. You can reorder IF branches by dragging and dropping them.

To make the outputs of a branch available in subsequent steps outside the branch, select the Enable outputs checkbox in the Branch on Conditions component's properties. When enabling outputs, it's crucial to ensure that each branch's output data type is the same to maintain consistency.

Continue on Conditions Component

The Continue on Conditions component serves a specific purpose: to evaluate a condition or a set of conditions and control the orchestration's continuation. If the evaluation result is true, the orchestration proceeds to the next step. If the result is false, the orchestration stops, and Orchestration Builder logs a specified message. This component is useful for implementing checkpoints or validation points where the orchestration should halt if certain criteria are not met.

Parallel Execution (Conditional Paths)

While Workday processes orchestrations step-by-step from top to bottom, the "Branch on Conditions" component allows you to define different sequential paths based on conditions. This means that while multiple branches are defined, only one path is executed at a time based on the evaluation of the conditions. For scenarios requiring true simultaneous parallel execution of multiple independent steps, consult the official Workday documentation, as the provided knowledge base does not detail a specific component for this functionality.

Error Handling

Robust error handling is critical for building resilient orchestrations. Initially, Workday Orchestrate did not have a built-in error handling framework, leading developers to create their own mini frameworks. These often involved logging incoming payloads to a Model object to easily recreate the initial state of an orchestration, and using the Alert framework to notify if orchestrations were not in a 'complete' status.

However, Workday has since introduced user-defined error handling capabilities. As of April, this feature enables orchestrate developers to embed the specific logic and behavior needed to respond to errors appropriately. This means you can now design your orchestrations to catch and manage errors within the flow, rather than relying solely on external monitoring.

Furthermore, an orchestration can be configured to explicitly throw an error if a response, such as from an API call, returns a non-200 status code. This allows for immediate error detection and the activation of your defined error handling logic.

For general logging and debugging, the Log component is invaluable. You can provide a meaningful message using Expression Builder. Optionally, you can specify a condition under which the message is logged at runtime. If the condition isn't met, the message isn't logged, allowing for targeted logging based on specific events or data states.

Integration Patterns and Best Practices

Workday Extend Orchestrations are powerful tools for integration. Understanding common patterns and best practices ensures your orchestrations are efficient, scalable, and maintainable.

Integration Patterns

Orchestrations are central to various integration patterns within Workday Extend:

• API-Driven Workflows: Orchestrations are built by connecting a series of steps, many of which are API calls. The drag-and-drop interface allows you to call Workday REST APIs, SOAP services, or external APIs.
• Data Transformations: Orchestrate excels at transforming data between different formats, such as mapping JSON output from a REST API to XML for a SOAP service.
• Real-time, Event-Driven Processes: Orchestrations are ideal for reacting to business process events in Workday, triggering a sequence of API calls to update external systems, and sending notifications back to Workday.
• Public REST APIs: Synchronous Orchestrations can be exposed as public REST APIs, allowing external solutions to invoke them and receive responses directly. You can configure the request and response objects for these APIs.
• Import API Patterns: For scenarios involving Workday Import APIs, the supported pattern often involves using two Integration System (O4I) orchestrations configured onto an integration Business Process. The first orchestration executes the Import API call(s). The integration framework then handles internal notifications generated by the background jobs, ensuring that the subsequent integration (orchestration) is not executed until all jobs created by the first have completed.

Timeout Management

One of the most common challenges in orchestrations, especially with large data volumes or external system calls, is managing timeouts.

• Default Timeout: The default response time limit for an orchestration is 20 seconds. If an orchestration exceeds this limit, it will fail with a "Client timeout waiting for a response" error.
• Adjusting Timeout: You can adjust the default timeout setting to a custom value within the Orchestration Builder. It's crucial to increase the response timeout for all relevant steps, not just the initial one, if a long-running operation is involved.
• PMD and O4I Considerations: If an orchestration is invoked from a Workday Process Model Definition (PMD), the PMD has its own timeout limit of 25 seconds. For Orchestrations for Integrations (O4I), consider switching to a Workday RAAS REST call if time restrictions are a concern, as RAAS REST calls do not enforce the same time limits for O4I requests.
• Asynchronous Execution: For orchestrations that consistently exceed the synchronous timeout limits (e.g., beyond 24-25 seconds), moving to an asynchronous orchestration is the recommended approach. Asynchronous orchestrations are largely similar to synchronous ones, and with features like copy/paste, conversion is relatively straightforward. This is particularly important for processing large numbers of records, where synchronous timeouts can lead to incomplete batches.
• Optimization: For orchestrations processing only a few records, consider optimizing the steps to avoid hitting timeout limits unnecessarily.

Orchestration Builder run logs are invaluable for diagnosing timeout issues and identifying exactly where an orchestration is failing.

Logging and Monitoring

Effective logging and monitoring are crucial for understanding orchestration behavior, debugging issues, and ensuring operational stability.

• Log Component: Utilize the Log component to insert messages at various points in your orchestration. These messages can be dynamic, using Expression Builder to include relevant data. You can also conditionally log messages, ensuring they only appear when specific criteria are met.
• Orchestration Run Logs: The Orchestration Builder provides detailed run logs that are essential for filtering and identifying where an orchestration is failing, including timeout errors.
• Custom Logging Frameworks: While user-defined error handling is now available, for historical context, developers previously built mini frameworks to log incoming payloads to a Model object. This allowed for easy recreation of the initial state of the orchestration for debugging purposes.
• Alerting: The Workday Alert framework can be leveraged to notify administrators if orchestrations are not completing successfully or are in an 'incomplete' status.

Design for Scalability

When designing orchestrations, especially for high-volume scenarios, consider scalability:

• Bulk Transactions: Orchestrations are generally well-suited for handling bulk transactions.
• Asynchronous for Large Data: For processing huge incoming data or operations that inherently take longer, asynchronous orchestrations are the preferred method to avoid timeout issues and ensure complete processing.
• Integration System Orchestrations for Import APIs: As noted, for Workday Import APIs, leveraging two Integration System (O4I) orchestrations in sequence allows the Workday integration framework to manage the background jobs and ensure all processing is complete before the next stage begins.

Conclusion

Workday Extend Orchestrations provide a robust and flexible framework for building sophisticated, real-time, and event-driven processes. By mastering the Orchestration Builder, understanding how to implement conditional logic, effectively manage timeouts, and leverage the new user-defined error handling capabilities, developers can create powerful solutions that seamlessly integrate Workday with external systems. The ability to transform data, orchestrate complex API calls, and respond dynamically to business events makes Workday Extend Orchestrations an indispensable tool for extending Workday's capabilities and automating critical business processes.

Key Takeaways

• Orchestrations are Step-by-Step: Workday processes orchestrations sequentially from top to bottom, manipulating data through interconnected components.
• Conditional Logic is Key: Use the Add condition for value in Expression Builder for simple conditions, and the Branch on Conditions component for complex, multi-path logic (IF/ELSE, multiple IF branches).
• Control Flow with Continue on Conditions: This component allows you to halt an orchestration if a condition is false, logging a message.
• User-Defined Error Handling: Workday now supports user-defined error handling, allowing developers to embed custom logic to respond to errors within the orchestration flow.
• Timeout Management is Crucial: Be aware of the default 20-second orchestration timeout and the 25-second PMD timeout. Adjust timeout settings for long-running steps and consider asynchronous orchestrations for processes exceeding these limits.
• Leverage Run Logs and Logging Components: Use Orchestration Builder run logs for debugging and the Log component for conditional runtime messages.
• Integration Powerhouse: Orchestrations facilitate API-driven workflows, data transformations, and event-driven processes, including specific patterns for Workday Import APIs.

Author: Knokit Team