Routing Step Functions events using Amazon EventBridge - Amazon Step Functions
EventBridge payloadsStep Functions event examplesRouting a Step Functions event to EventBridge
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).

Routing Step Functions events using Amazon EventBridge

Amazon EventBridge is an Amazon service that enables you to respond to state changes in an Amazon resource. For example, you can respond to the execution status changes of a Step Functions Standard Workflow with EventBridge using the following two ways:

  • You can configure EventBridge rules to react to events that are emitted when the execution status of a Step Functions state machine changes. This enables you to monitor your workflows without having to constantly poll using the DescribeExecution API. Based on changes in state machine executions, you can use an EventBridge target to start new state machine executions, call Amazon Lambda functions, publish messages to Amazon Simple Notification Service (Amazon SNS) topics, and more.

  • You can also configure a Step Functions state machine as a target in EventBridge. This enables you to trigger an execution of a Step Functions workflow in response to an event from another Amazon service.

    For more information, see the Amazon EventBridge User Guide.

Express Workflows, however, do not emit events to EventBridge. To monitor the execution of an Express Workflow, you can use CloudWatch Logs. To do this, on the state machine Execution Details page, choose the Monitoring and Logging tabs. On the Monitoring tab, you can view the CloudWatch metrics for events, such as Execution Duration, Execution Errors, and Billed Memory. On the Logging tab, you can view recent logs and the logging configuration.

Tip

To deploy an example of an Express Workflow to your Amazon Web Services account and learn how to monitor Express Workflows, see the Monitoring Express Workflows module of The Amazon Step Functions Workshop.

EventBridge payloads

An EventBridge event can contain an input property in its definition. For some events, an EventBridge event can also contain an output property in its definition.

  • If the combined escaped input and escaped output sent to EventBridge exceeds 248KB, then the input will be excluded. Similarly, if the escaped output exceeds 248KB, then the output will be excluded. This is a result of the EventBridge events quotas.

  • You can determine whether a payload has been truncated with the inputDetails and outputDetails properties. For more information, see the CloudWatchEventsExecutionDataDetails Data Type.

  • For Standard Workflows, you can see the full input and output by using DescribeExecution.

  • DescribeExecution is not available for Express Workflows. If you want to see the full input/output, you can wrap your Express Workflow with a Standard Workflow. Another option is to use Amazon S3 ARNs. For information about using ARNs, see Using Amazon S3 ARNs instead of passing large payloads in Step Functions.

Step Functions event examples

The following are examples of Step Functions sending events to EventBridge:

In each case, the detail section in the event data provides the same information as the DescribeExecution API. The status field indicates the status of the execution at the time the event was sent, one of RUNNING, SUCCEEDED, FAILED, TIMED_OUT, or ABORTED depending on the event emitted.

Execution started

{
    "version": "0",
    "id": "315c1398-40ff-a850-213b-158f73e60175",
    "detail-type": "Step Functions Execution Status Change",
    "source": "aws.states",
    "account": "123456789012",
    "time": "2019-02-26T19:42:21Z",
    "region": "us-west-2",
    "resources": [
      "arn:aws-cn:states:us-west-2:123456789012:execution:state-machine-name:execution-name"
    ],
    "detail": {
        "executionArn": "arn:aws:states:us-west-2:123456789012:execution:state-machine-name:execution-name",
        "stateMachineArn": "arn:aws-cn::states:us-west-2:123456789012:stateMachine:state-machine",
        "name": "execution-name",
        "status": "RUNNING",
        "startDate": 1551225271984,
        "stopDate":  null,
        "input": "{}",
        "inputDetails": {
             "included": true
        },
        "output": null,
        "outputDetails": null
    }
}

Execution succeeded

{
    "version": "0",
    "id": "315c1398-40ff-a850-213b-158f73e60175",
    "detail-type": "Step Functions Execution Status Change",
    "source": "aws.states",
    "account": "123456789012",
    "time": "2019-02-26T19:42:21Z",
    "region": "us-west-2",
    "resources": [
      "arn:aws-cn:states:us-west-2:123456789012:execution:state-machine-name:execution-name"
    ],
    "detail": {
        "executionArn": "arn:aws-cn:states:us-west-2:123456789012:execution:state-machine-name:execution-name",
        "stateMachineArn": "arn:aws-cn:states:us-west-2:123456789012:stateMachine:state-machine",
        "name": "execution-name",
        "status": "SUCCEEDED",
        "startDate": 1547148840101,
        "stopDate": 1547148840122,
        "input": "{}",
        "inputDetails": {
             "included": true
        },
        "output": "\"Hello World!\"",
        "outputDetails": {
             "included": true
        }
    }
}

Execution failed

{
    "version": "0",
    "id": "315c1398-40ff-a850-213b-158f73e60175",
    "detail-type": "Step Functions Execution Status Change",
    "source": "aws.states",
    "account": "123456789012",
    "time": "2019-02-26T19:42:21Z",
    "region": "us-west-2",
    "resources": [
      "arn:aws-cn:states:us-west-2:123456789012:execution:state-machine-name:execution-name"
    ],
    "detail": {
        "executionArn": "arn:aws:states:us-west-2:123456789012:execution:state-machine-name:execution-name",
        "stateMachineArn": "arn:aws-cn:states:us-west-2:123456789012:stateMachine:state-machine",
        "name": "execution-name",
        "status": "FAILED",
        "startDate": 1551225146847,
        "stopDate": 1551225151881,
        "input": "{}",
        "inputDetails": {
             "included": true
        },
        "output": null,
        "outputDetails": null
    }
}

Execution timed out

{
    "version": "0",
    "id": "315c1398-40ff-a850-213b-158f73e60175",
    "detail-type": "Step Functions Execution Status Change",
    "source": "aws.states",
    "account": "123456789012",
    "time": "2019-02-26T19:42:21Z",
    "region": "us-west-2",
    "resources": [
      "arn:aws-cn:states:us-west-2:123456789012:execution:state-machine-name:execution-name"
    ],
    "detail": {
        "executionArn": "arn:aws:states:us-west-2:123456789012:execution:state-machine-name:execution-name",
        "stateMachineArn": "arn:aws-cn:states:us-west-2:123456789012:stateMachine:state-machine",
        "name": "execution-name",
        "status": "TIMED_OUT",
        "startDate": 1551224926156,
        "stopDate": 1551224927157,
        "input": "{}",
        "inputDetails": {
             "included": true
        },
        "output": null,
        "outputDetails": null
    }
}

Execution aborted

{
    "version": "0",
    "id": "315c1398-40ff-a850-213b-158f73e60175",
    "detail-type": "Step Functions Execution Status Change",
    "source": "aws.states",
    "account": "123456789012",
    "time": "2019-02-26T19:42:21Z",
    "region": "us-west-2",
    "resources": [
      "arn:aws-cn:states:us-west-2:123456789012:execution:state-machine-name:execution-name"
    ],
    "detail": {
        "executionArn": "arn:aws:states:us-west-2:123456789012:execution:state-machine-name:execution-name",
        "stateMachineArn": "arn:aws-cn:states:us-west-2:123456789012:stateMachine:state-machine",
        "name": "execution-name",
        "status": "ABORTED",
        "startDate": 1551225014968,
        "stopDate": 1551225017576,
        "input": "{}",
        "inputDetails": {
             "included": true
        },
        "output": null,
        "outputDetails": null
    }
}

Routing a Step Functions event to EventBridge in the EventBridge console

Use the following instructions to learn how to trigger the execution of a Step Functions state machine whenever a specific Step Functions state machine completes running successfully. You use the Amazon EventBridge console to specify the state machine whose execution you want to trigger.

  1. On the Details page of a state machine, choose Actions, and then choose Create EventBridge (CloudWatch Events) rule.

    Create EventBridge event rule

    Alternatively, open the EventBridge console at https://console.amazonaws.cn/events/. In the navigation pane, choose Rules under Buses.

  2. Choose Create rule. This opens the Define rule detail page.

  3. Enter a Name for your rule (for example, StepFunctionsEventRule) and optionally enter a Description for the rule.

  4. For Event bus and Rule type, keep the default selections.

  5. Choose Next. This opens the Build event pattern page.

  6. Under Event Source, keep the default selection of Amazon events or EventBridge partner events.

  7. Keep the default selections for the Sample event and Creation method sections.

  8. Under Event pattern, do the following:

    1. In the Event source dropdown list, keep the default selection of Amazon services.

    2. From the Amazon service dropdown list, choose Step Functions.

    3. From the Event type dropdown list, select Step Functions Execution Status Change.

    4. (Optional) Configure a specific status, state machine Amazon Resource Name (ARN), or execution ARN. For this procedure, choose Specific status(es), and then choose SUCCEEDED from the dropdown list.

  9. Choose Next. This opens the Select target(s) page.

  10. Under Target types, keep the default selection of Amazon service.

  11. From the Select a target dropdown list, choose an Amazon service. For example, you could launch a Lambda function, or run a Step Functions state machine. For this procedure, choose Step Functions state machine.

  12. From the State machine dropdown list, choose a state machine.

  13. Under Execution role, keep the default selection of Create a new role for this specific resource.

  14. Choose Next. This opens the Configure tags page.

  15. choose Next again. This opens the Review and create page.

  16. Review the details of the rule and choose Create rule.

    The rule is created and the Rules page is displayed, listing all your Amazon EventBridge rules.