Discover the Power of Temporal's Scheduled Actions

Table of Contents

1. Introduction
2. The Need for Improved Scheduled Actions
3. Issues with the Existing Temporal Cron Functionality
4. Introducing Scheduled Actions
5. How to Define a Scheduled Action
6. The Action Object
7. The Spec Configuration Object
8. The Policies Object
9. Starting a Scheduled Action
10. Monitoring and Editing Scheduled Actions
11. Pausing and Resuming Scheduled Actions
12. Deleting Scheduled Actions
13. Conclusion

Introduction

Hey there, I'm Ryland, and I'm here to talk about the exciting new scheduled actions functionality which just shipped with the temporal server v120 release. Scheduled actions are a successor to the existing temporal cron functionality, which is now becoming legacy. In this article, we'll explore the need for improved scheduled actions, the issues with the existing temporal cron functionality, and how the introduction of scheduled actions aims to address those problems.

The Need for Improved Scheduled Actions

The temporal cron functionality has historically been one of the most popular features of Temporal. Many users are attracted to Temporal because they are looking for a Durable and reliable cron solution. However, despite its popularity, there are several practical problems with the temporal cron functionality that hinder the overall user experience. These issues include:

1. Inability to stop the temporal cron functionality without affecting the workflows it starts.
2. Unable to terminate cron jobs without affecting the underlying cron functionality.
3. No support for pausing or updating cron jobs.
4. Lack of support for overlapping runs.
5. Limited visibility and control over cron schedules.

Recognizing these limitations, Temporal set out to improve the cron functionality and address these practical issues. The result is the introduction of scheduled actions, which aims to provide a revamped experience with enhanced user capabilities.

Issues with the Existing Temporal Cron Functionality

When using the temporal cron functionality, users have encountered various challenges that significantly impact their Workflow Management. Some of the main issues with the existing temporal cron functionality include:

1. Inability to stop cron functionality without affecting workflows: Currently, stopping the temporal cron functionality also halts the workflows it initiates. This bi-directional frustration hampers workflow management and control.

2. Lack of workflow termination without affecting cron functionality: Conversely, terminating a workflow associated with cron functionality also affects the cron itself. This limitation creates a cumbersome and inefficient workflow management process.

3. No support for pausing or updating cron jobs: The temporal cron functionality lacks the ability to pause or update cron jobs. This hinders the flexibility and adaptability of workflows, limiting their ability to accommodate changing requirements.

4. Absence of overlapping runs: The temporal cron functionality does not support overlapping runs, which leads to inefficient Scheduling and missed opportunities for optimized workflow execution.

5. Limited visibility and control: The existing temporal cron solution lacks a comprehensive visibility and control framework. Users struggle to monitor and manage their cron schedules effectively, leading to challenges in maintaining efficient workflow execution.

Recognizing these challenges and the popularity of cron functionality among users, Temporal set out to improve and enhance the cron experience. The development of scheduled actions aims to address these practical issues, providing users with a more streamlined and powerful solution for their workflow management needs.

Introducing Scheduled Actions

Scheduled actions are a new feature introduced in the temporal server v120 release to overcome the limitations of the existing temporal cron functionality. After a year of hard work and dedication by the Temporal team, scheduled actions offer an improved and enhanced user experience. With scheduled actions, users can expect all the powerful capabilities of temporal cron with a much better user interface and usability.

The primary goal of scheduled actions is to provide a reliable and durable solution for scheduling and executing workflows. By addressing the limitations of the temporal cron functionality, scheduled actions aim to streamline workflow management, enhance control and visibility, and improve overall user satisfaction.

In the following sections, we will explore how to define and configure scheduled actions, the different components involved, and the steps to start, monitor, and edit scheduled actions. We will also discuss pausing, resuming, and deleting scheduled actions. By the end of this article, you will have a comprehensive understanding of how to leverage the power of scheduled actions in your workflow management.

How to Define a Scheduled Action

To define a scheduled action in Temporal, you need to specify three major objects or configurations:

1. The Action Object
2. The Spec Configuration Object
3. The Policies Object

These objects work together to determine the frequency, behavior, and control of your scheduled actions. Let's explore each one in detail:

The Action Object

The action object defines the type of action you want to perform with your scheduled action. Currently, Temporal only supports one type of action, which is the start of a workflow. This means that when the schedule fires, it will initiate the specified workflow type.

The action object also requires the following parameters:

1. Workflow Type: This specifies the type of workflow that will be started when the schedule fires. You need to specify the workflow type based on your requirements.

2. Args: The args parameter specifies the arguments to be passed to the workflow when the schedule fires. These arguments can be an array or a JSON object, depending on your workflow's signature.

3. Task Queue: The task queue parameter indicates the task queue to which the workflow should be delivered and run.

By defining the action object, you can specify the desired workflow type, pass necessary arguments, and ensure the workflow is executed in the appropriate task queue.

The Spec Configuration Object

The spec configuration object determines how often your schedule will run. It offers two main formats:

1. Interval Format: The interval format allows you to specify a straightforward, human-readable interval for your schedule. For example, you can define it to run every 10 seconds, once every two minutes, or every other day. This format is ideal for representing explicit and straightforward intervals.

2. Calendar Format: The calendar format provides more granular control over when your schedule fires. It allows you to precisely define the schedule based on specific dates, times, or even using a traditional cron STRING. If you have an existing cron solution, you can easily migrate it to Temporal using the calendar format. This format allows for greater control and flexibility in defining your schedules.

By utilizing either the interval or calendar format, you can define the frequency and precision of your scheduled actions.

The Policies Object

The policies object enables you to control and customize the behavior of your scheduled actions in different scenarios. There are two essential policies to consider:

1. Catch-up Window: The catch-up window determines the behavior of your schedule when the temporal cluster experiences downtime. Suppose your schedule was supposed to fire during a period when the cluster was down. In that case, the catch-up window defines whether the missed schedule should be executed when the cluster comes back online. By default, the catch-up window is set to one minute, allowing missed schedules within that timeframe to be executed upon cluster recovery. However, you can define any time range for your catch-up window, ensuring flexibility based on your specific requirements.

2. Overlap Policy: The overlap policy controls how your scheduled actions behave when a workflow execution from a previous run is still running while the next run is about to start. The default behavior is to skip the new run. However, you have the option to customize the overlap policy to cancel the running execution, buffer the execution until the previous one completes, or allow all executions to run simultaneously. This policy provides precise control over how your scheduled actions handle overlapping runs.

By configuring the policies object, you can fine-tune the behavior of your scheduled actions, optimizing workflow execution and resource allocation.

In the following sections, we will walk through the steps to start, monitor, and edit your scheduled actions using Temporal's TypeScript SDK. We will also explore options for pausing, resuming, and deleting scheduled actions, providing you with a holistic understanding of managing and leveraging scheduled actions for enhanced workflow management.

Starting a Scheduled Action

Starting a scheduled action requires using the Temporal client to create the schedule. The code snippet below demonstrates how to start a schedule using the TypeScript SDK:

// Code example for starting a scheduled action
const scheduleId = "sample-schedule-id";
const action = {
  workflowType: "reminder-workflow",
  args: { text: "Sample reminder message" },
  taskQueue: "sample-task-queue",
};

const interval = "every 10 seconds"; // Define the schedule interval

// Create the schedule using the Temporal client
const result = await client.schedule.start(scheduleId, action, interval);

By following this example, you can initiate a scheduled action by providing the necessary parameters, such as the schedule ID, action object, and schedule interval. This will enable you to start your schedule and trigger your desired workflow at the specified intervals.

Monitoring and Editing Scheduled Actions

With the introduction of scheduled actions, Temporal also provides enhanced visibility and control for monitoring and editing your schedules. The Temporal UI offers a dedicated area for managing your scheduled actions, allowing you to easily monitor and modify their configurations.

By accessing the Temporal UI, you can view important details about your scheduled actions, such as creation timestamps, frequency, recent runs, upcoming runs, and more. This comprehensive overview enables you to track the performance and execution of your schedules, ensuring smooth workflow management.

Furthermore, the Temporal UI provides convenient editing options for modifying your scheduled actions. You can easily update parameters like workflow type, task queue, and schedule interval directly from the UI. These editing capabilities offer flexibility and agility in adapting your schedules to changing requirements.

Pausing and Resuming Scheduled Actions

One of the exciting capabilities introduced with scheduled actions is the ability to pause and Resume your schedules. Temporal allows you to easily pause a schedule, temporarily halting its execution, and preventing new workflow runs. This feature is invaluable when you need to temporarily pause a recurring workflow or make critical updates.

By pausing a schedule, you can ensure that no new workflow executions start during the paused period. This gives you the freedom to make necessary adjustments to your schedules, fine-tune configurations, or address any issues without interruption.

When you're ready to resume the schedule, Temporal provides a simple operation to restart the execution and allow new workflow runs according to the specified interval. This pause and resume functionality adds a layer of control and flexibility to your workflow management process.

Deleting Scheduled Actions

In addition to pausing and resuming, Temporal also allows you to delete scheduled actions when they are no longer needed. Deleting a schedule terminates the associated workflows and prevents any new runs from occurring. This feature helps maintain a clean and organized workflow environment, removing unnecessary schedules and freeing up resources.

When deleting a schedule, it's crucial to note that the associated workflows will be closed and finalized. Additionally, the workflow responsible for managing the scheduled action will also terminate. However, this ensures that no further workflow executions are initiated, streamlining your workflow management process.

By leveraging these deletion capabilities, you can manage your scheduled actions effectively, maintaining an optimized workflow environment and reducing clutter.

Conclusion

In conclusion, Temporal's new scheduled actions functionality offers an exciting and improved experience for managing and executing workflows. By addressing the limitations of the existing temporal cron functionality, scheduled actions provide enhanced control, flexibility, and visibility.

Through the Action, Spec Configuration, and Policies objects, users can define, customize, and fine-tune their schedules according to their specific requirements. The ability to start, monitor, edit, pause, resume, and delete schedules offers unparalleled workflow management capabilities.

With the introduction of scheduled actions, Temporal continues to empower users with a reliable and powerful workflow orchestration solution. Whether you are a developer, system administrator, or operations manager, scheduled actions provide a robust toolset to streamline your workflow execution, optimize resource allocation, and improve overall productivity.

So, don't wait! Start utilizing the power of Temporal's scheduled actions today and take your workflow management to the next level.