Using Amazon EventBridge Scheduler with Amazon Step Functions - Amazon Step Functions
Set up the execution roleCreate a scheduleRelated resources
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using Amazon EventBridge Scheduler with Amazon Step Functions

Amazon EventBridge Scheduler is a serverless scheduler that allows you to create, run, and manage tasks from one central, managed service. With EventBridge Scheduler, you can create schedules using cron and rate expressions for recurring patterns, or configure one-time invocations. You can set up flexible time windows for delivery, define retry limits, and set the maximum retention time for failed API invocations.

For example, with EventBridge Scheduler, you can start a state machine execution on a schedule when a security related event occurs or to automate a data processing job.

This page explains how to use EventBridge Scheduler to start execution of a Step Functions state machine on a schedule.

Set up the execution role

When you create a new schedule, EventBridge Scheduler must have permission to invoke its target API operation on your behalf. You grant these permissions to EventBridge Scheduler using an execution role. The permission policy you attach to your schedule's execution role defines the required permissions. These permissions depend on the target API you want EventBridge Scheduler to invoke.

When you use the EventBridge Scheduler console to create a schedule, as in the following procedure, EventBridge Scheduler automatically sets up an execution role based on your selected target. If you want to create a schedule using one of the EventBridge Scheduler SDKs, the Amazon CLI, or Amazon CloudFormation, you must have an existing execution role that grants the permissions EventBridge Scheduler requires to invoke a target. For more information about manually setting up an execution role for your schedule, see Setting up an execution role in the EventBridge Scheduler User Guide.

Create a schedule

To create a schedule by using the console

  1. Open the Amazon EventBridge Scheduler console at https://console.amazonaws.cn/scheduler/home.

  2. On the Schedules page, choose Create schedule.

  3. On the Specify schedule detail page, in the Schedule name and description section, do the following:

    1. For Schedule name, enter a name for your schedule. For example, MyTestSchedule.

    2. (Optional) For Description, enter a description for your schedule. For example, My first schedule.

    3. For Schedule group, choose a schedule group from the dropdown list. If you don't have a group, choose default. To create a schedule group, choose create your own schedule.

      You use schedule groups to add tags to groups of schedules.

    1. Choose your schedule options.

      Occurrence Do this...

      One-time schedule

      A one-time schedule invokes a target only once at the date and time that you specify.

      For Date and time, do the following:

      • Enter a valid date in YYYY/MM/DD format.

      • Enter a timestamp in 24-hour hh:mm format.

      • For Timezone, choose the timezone.

      Recurring schedule

      A recurring schedule invokes a target at a rate that you specify using a cron expression or rate expression.

      1. For Schedule type, do one of the following:

        • To use a cron expression to define the schedule, choose Cron-based schedule and enter the cron expression.

        • To use a rate expression to define the schedule, choose Rate-based schedule and enter the rate expression.

          For more information about cron and rate expressions, see Schedule types on EventBridge Scheduler in the Amazon EventBridge Scheduler User Guide.

      2. For Flexible time window, choose Off to turn off the option, or choose one of the pre-defined time windows. For example, if you choose 15 minutes and you set a recurring schedule to invoke its target once every hour, the schedule runs within 15 minutes after the start of every hour.

  5. (Optional) If you chose Recurring schedule in the previous step, in the Timeframe section, do the following:

    1. For Timezone, choose a timezone.

    2. For Start date and time, enter a valid date in YYYY/MM/DD format, and then specify a timestamp in 24-hour hh:mm format.

    3. For End date and time, enter a valid date in YYYY/MM/DD format, and then specify a timestamp in 24-hour hh:mm format.

  6. Choose Next.

  7. On the Select target page, choose the Amazon API operation that EventBridge Scheduler invokes:

    1. Choose Amazon Step Functions StartExecution.

    2. In the StartExecution section, select a state machine or choose Create new state machine.

      Currently, you can't run Synchronous Express workflows on a schedule.

    3. Enter a JSON payload for the execution. Even if your state machine doesn't require any JSON payload, you must still include input in JSON format as shown in the following example.

      {
    "Comment": "sampleJSONData"
}

  8. Choose Next.

  9. On the Settings page, do the following:

    1. To turn on the schedule, under Schedule state, toggle Enable schedule.

    2. To configure a retry policy for your schedule, under Retry policy and dead-letter queue (DLQ), do the following:

      • Toggle Retry.

      • For Maximum age of event, enter the maximum hour(s) and min(s) that EventBridge Scheduler must keep an unprocessed event.

      • The maximum time is 24 hours.

      • For Maximum retries, enter the maximum number of times EventBridge Scheduler retries the schedule if the target returns an error.

        The maximum value is 185 retries.

      With retry policies, if a schedule fails to invoke its target, EventBridge Scheduler re-runs the schedule. If configured, you must set the maximum retention time and retries for the schedule.

    3. Choose where EventBridge Scheduler stores undelivered events.

      Dead-letter queue (DLQ) option Do this...
      Don't store Choose None.
      Store the event in the same Amazon Web Services account where you're creating the schedule

      1. Choose Select an Amazon SQS queue in my Amazon Web Services account as a DLQ.

      2. Choose the Amazon Resource Name (ARN) of the Amazon SQS queue.

      Store the event in a different Amazon Web Services account from where you're creating the schedule

      1. Choose Specify an Amazon SQS queue in other Amazon Web Services accounts as a DLQ.

      2. Enter the Amazon Resource Name (ARN) of the Amazon SQS queue.

    4. To use a customer managed key to encrypt your target input, under Encryption, choose Customize encryption settings (advanced).

      If you choose this option, enter an existing KMS key ARN or choose Create an Amazon KMS key to navigate to the Amazon KMS console. For more information about how EventBridge Scheduler encrypts your data at rest, see Encryption at rest in the Amazon EventBridge Scheduler User Guide.

    5. To have EventBridge Scheduler create a new execution role for you, choose Create new role for this schedule. Then, enter a name for Role name. If you choose this option, EventBridge Scheduler attaches the required permissions necessary for your templated target to the role.

  10. Choose Next.

  11. In the Review and create schedule page, review the details of your schedule. In each section, choose Edit to go back to that step and edit its details.

  12. Choose Create schedule.

    You can view a list of your new and existing schedules on the Schedules page. Under the Status column, verify that your new schedule is Enabled.

To confirm that EventBridge Scheduler invoked the state machine, check the state machine's Amazon CloudWatch logs.

For more information about EventBridge Scheduler, see the following: