Workflow

This module provides classes which abstract workflow and workflow executions for AWS Step Functions. These classes are used for interacting directly with the AWS Step Functions service in the cloud.

class stepfunctions.workflow.ExecutionStatus

Bases: enum.Enum

Enumeration for workflow status.

Running = 'RUNNING'
Succeeded = 'SUCCEEDED'
Failed = 'FAILED'
TimedOut = 'TIMED_OUT'
Aborted = 'ABORTED'
class stepfunctions.workflow.Workflow(name, definition, role, tags=[], execution_input=None, timeout_seconds=None, comment=None, version=None, state_machine_arn=None, format_json=True, client=None)

Bases: object

Class for creating and managing a workflow.

Parameters:
  • name (str) –

    The name of the workflow. A name must not contain:

    • whitespace
    • brackets < > { } [ ]
    • wildcard characters ? *
    • special characters ” # % ^ | ~ ` $ & , ; : /
    • control characters (U+0000-001F , U+007F-009F )
  • definition (State or Chain) – The Amazon States Language definition of the workflow.
  • role (str) – The Amazon Resource Name (ARN) of the IAM role to use for creating, managing, and running the workflow.
  • tags (list) – Tags to be added when creating a workflow. Tags are key-value pairs that can be associated with Step Functions workflows and activities. (default: [])
  • execution_input (ExecutionInput, optional) – Placeholder collection that defines the placeholder variables for the workflow execution. This is also used to validate inputs provided when executing the workflow. (default: None)
  • timeout_seconds (int, optional) – The maximum number of seconds an execution of the workflow can run. If it runs longer than the specified time, the workflow run fails with a States.Timeout Error Name. (default: None)
  • comment (str, optional) – A human-readable description of the workflow. (default: None)
  • version (str, optional) – The version of the Amazon States Language used in the workflow. (default: None)
  • state_machine_arn (str, optional) – The Amazon Resource Name (ARN) of the workflow. (default: None)
  • format_json (bool, optional) – Boolean flag set to True if workflow definition and execution inputs should be prettified for this workflow. False, otherwise. (default: True)
  • client (SFN.Client, optional) – boto3 client to use for creating, managing, and running the workflow on Step Functions. If not provided, a default boto3 client for Step Functions will be automatically created and used. (default: None)
classmethod list_workflows(max_items=100, client=None, html=False)

Lists all the workflows in the account.

Parameters:
  • max_items (int, optional) – The maximum number of items to be returned. (default: 100)
  • client (SFN.Client, optional) – boto3 client to use for the query. If not provided, a default boto3 client for Step Functions will be automatically created and used. (default: None)
  • html (bool, optional) – Renders the list as an HTML table (If running in an IPython environment). If the parameter is not provided, or set to False, a Python list is returned. (default: False)
Returns:

The list of workflows. Refer to SFN.Client.list_state_machines() for the response structure.

Return type:

list

classmethod attach(state_machine_arn, client=None)

Factory method to create an instance attached to an exisiting workflow in Step Functions.

Parameters:
  • state_machine_arn (str) – The Amazon Resource Name (ARN) of the existing workflow.
  • client (SFN.Client, optional) – boto3 client to use for attaching the existing workflow in Step Functions to the Workflow object. If not provided, a default boto3 client for Step Functions will be automatically created and used. (default: None)
Returns:

Workflow object attached to the existing workflow in Step Functions.

Return type:

Workflow

create()

Creates the workflow on Step Functions.

Returns:The Amazon Resource Name (ARN) of the workflow created. If the workflow already existed, the ARN of the existing workflow is returned.
Return type:str
update(definition=None, role=None)

Updates an existing state machine by modifying its definition and/or role. Executions started immediately after calling this method may use the previous definition and role.

Parameters:
  • definition (State or Chain, optional) –

    The Amazon States Language definition to update the workflow with. (default: None)

  • role (str, optional) – The Amazon Resource Name (ARN) of the IAM role to use for creating, managing, and running the workflow. (default: None)
Returns:

The state machine definition and/or role updated. If the update fails, None will be returned.

Return type:

str

execute(name=None, inputs=None)

Starts a single execution of the workflow.

Parameters:
  • name (str, optional) – The name of the workflow execution. If one is not provided, a workflow execution name will be auto-generated. (default: None)
  • inputs (str, list or dict, optional) – Input data for the workflow execution. (default: None)
Returns:

An execution instance of the workflow.

Return type:

stepfunctions.workflow.Execution

list_executions(max_items=100, status_filter=None, html=False)

Lists the executions for the workflow.

Parameters:
  • max_items (int, optional) – The maximum number of items to be returned. (default: 100)
  • status_filter (ExecutionStatus, optional) – If specified, only list the executions whose current status matches the given filter. (default: None)
  • html (bool, optional) – Renders the list as an HTML table (If running in an IPython environment). If the parameter is not provided, or set to False, a Python list is returned. (default: False)
Returns:

List of workflow run instances.

Return type:

list(stepfunctions.workflow.Execution)

delete()

Deletes the workflow, if it exists.

render_graph(portrait=False)

Renders a visualization of the workflow graph.

Parameters:portrait (bool, optional) – Boolean flag set to True if the workflow graph should be rendered in portrait orientation. Set to False, if the graph should be rendered in landscape orientation. (default: False)
get_cloudformation_template()

Returns a CloudFormation template that contains only the StateMachine resource. To reuse the CloudFormation template in a different region, please make sure to update the region specific AWS resources (e.g: Lambda ARN, Training Image) in the StateMachine definition.

class stepfunctions.workflow.Execution(workflow, execution_arn, start_date, status, client=None, name=None, stop_date=None)

Bases: object

Class for managing a workflow execution.

Parameters:
  • workflow (Workflow) – Step Functions workflow instance.
  • execution_arn (str) – The Amazon Resource Name (ARN) of the workflow execution.
  • start_date (datetime.datetime) – The date the workflow execution was started.
  • status (RunStatus) – Status of the workflow execution.
  • client (SFN.Client, optional) – boto3 client to use for running and managing the workflow executions on Step Functions. If no client is provided, the boto3 client from the parent workflow will be used. (default: None)
  • name (str, optional) – Name for the workflow execution. (default: None)
  • stop_date (datetime.datetime, optional) – The date the workflow execution was stopped, if applicable. (default: None)
stop(cause=None, error=None)

Stops a workflow execution.

Parameters:
  • error (str, optional) – The error code of the failure. (default: None)
  • cause (str, optional) – A more detailed explanation of the cause of the failure. (default: None)
Returns:

Datetime of when the workflow execution was stopped. Example below:

{
    'stopDate': datetime(2015, 1, 1)
}

Response structure:

  • (dict)
    • stopDate (datetime): The date the workflow execution is stopped

Return type:

dict

list_events(max_items=100, reverse_order=False, html=False)

Lists the events in the workflow execution.

Parameters:
  • max_items (int, optional) – The maximum number of items to be returned. (default: 100)
  • reverse_order (bool, optional) – Boolean flag set to True if the events should be listed in reverse chronological order. Set to False, if the order should be in chronological order. (default: False)
  • html (bool, optional) – Renders the list as an HTML table (If running in an IPython environment). If the parameter is not provided, or set to False, a Python list is returned. (default: False)
Returns:

Object containing the list of workflow execution events. Refer to SFN.Client.get_execution_history() for the response structure.

Return type:

dict

describe()

Describes a workflow execution.

Returns:Details of the workflow execution.

Response structure:

  • (dict)
    • executionArn (string): The Amazon Resource Name (ARN) that identifies the workflow execution.
    • stateMachineArn (string): The Amazon Resource Name (ARN) of the workflow that was executed.
    • name (string): The name of the workflow execution.
    • status (string): The current status of the workflow execution.
    • startDate (datetime): The date the workflow execution is started.
    • stopDate (datetime): If the workflow execution has already ended, the date the execution stopped.
    • input (string): The string that contains the JSON input data of the workflow execution.
    • output (string): The JSON output data of the workflow execution.
Return type:dict
render_progress(portrait=False, max_events=25000)

Renders a visualization of the workflow execution graph.

Parameters:
  • portrait (bool, optional) – Boolean flag set to True if the workflow execution graph should be rendered in portrait orientation. Set to False, if the graph should be rendered in landscape orientation. (default: False)
  • max_events (int, optional) – Specifies the number of events to be visualized in the workflow execution graph. (default: 25000)
get_input()

Get the input for the workflow execution.

Returns:Workflow execution input.
Return type:list or dict
get_output(wait=False)

Get the output for the workflow execution.

Parameters:wait (bool, optional) – Boolean flag set to True if the call should wait for a running workflow execution to end before returning the output. Set to False, otherwise. Note that if the status is running, and wait is set to True, this will be a blocking call. (default: False)
Returns:Workflow execution output.
Return type:list or dict