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:
-
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: - definition (State or Chain, optional) –
-
execute
(name=None, inputs=None)¶ Starts a single execution of the workflow.
Parameters: Returns: An execution instance of the workflow.
Return type:
-
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:
-
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.
- name (str) –
-
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: 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:
-
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:
-
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 - (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