AWS Step Functions - AWS CodePipeline

AWS Step Functions

An AWS CodePipeline action that does the following:

  • Starts an AWS Step Functions state machine execution from your pipeline.

  • Provides an initial state to the state machine through either a property in the action configuration or a file located in a pipeline artifact to be passed as input.

  • Optionally sets an execution ID prefix for identifying executions originating from the action.

  • Supports Standard and Express state machines.

Action type

  • Category: Invoke

  • Owner: AWS

  • Provider: StepFunctions

  • Version: 1

Configuration parameters

StateMachineArn

Required: Yes

The Amazon Resource Name (ARN) for the state machine to be invoked.

ExecutionNamePrefix

Required: No

By default, the action execution ID is used as the state machine execution name. If a prefix is provided, it is prepended to the action execution ID with a hyphen and together used as the state machine execution name.

myPrefix-1624a1d1-3699-43f0-8e1e-6bafd7fde791

For an express state machine, the name should only contain 0-9, A-Z, a-z, - and _.

InputType

Required: No

  • Literal (default): When specified, the value in the Input field is passed directly to the state machine input.

    Example entry for the Input field when Literal is selected:

    {"action": "test"}
  • FilePath: The contents of a file in the input artifact specified by the Input field is used as the input for the state machine execution. An input artifact is required when InputType is set to FilePath.

    Example entry for the Input field when FilePath is selected:

    assets/input.json
Input

Required: Conditional

  • Literal: When InputType is set to Literal (default), this field is optional.

    If provided, the Input field is used directly as the input for the state machine execution. Otherwise, the state machine is invoked with an empty JSON object {}.

  • FilePath: When InputType is set to FilePath, this field is required.

    An input artifact is also required when InputType is set to FilePath.

    The contents of the file in the input artifact specified are used as the input for the state machine execution.

Input artifacts

  • Number of Artifacts: 0 to 1

  • Description: If InputType is set to FilePath, this artifact is required and is used to source the input for the state machine execution.

Output artifacts

  • Number of Artifacts: 0 to 1

  • Description:

    • Standard State Machines: If provided, the output artifact is populated with the output of the state machine. This is obtained from the output property of the Step Functions DescribeExecution API response after the state machine execution completes successfully.

    • Express State Machines: Not supported.

Output variables

This action produces output variables that can be referenced by the action configuration of a downstream action in the pipeline.

For more information, see Variables.

StateMachineArn

The ARN of the state machine.

ExecutionArn

The ARN of the execution of the state machine. Standard state machines only.

Example action configuration

Example for default input

YAML
Name: ActionName ActionTypeId: Category: Invoke Owner: AWS Version: 1 Provider: StepFunctions OutputArtifacts: - Name: myOutputArtifact Configuration: StateMachineArn: arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine ExecutionNamePrefix: my-prefix
JSON
{ "Name": "ActionName", "ActionTypeId": { "Category": "Invoke", "Owner": "AWS", "Version": 1, "Provider": "StepFunctions" }, "OutputArtifacts": [ { "Name": "myOutputArtifact" } ], "Configuration": { "StateMachineArn": "arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine", "ExecutionNamePrefix": "my-prefix" } }

Example for literal input

YAML
Name: ActionName ActionTypeId: Category: Invoke Owner: AWS Version: 1 Provider: StepFunctions OutputArtifacts: - Name: myOutputArtifact Configuration: StateMachineArn: arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine ExecutionNamePrefix: my-prefix Input: '{"action": "test"}'
JSON
{ "Name": "ActionName", "ActionTypeId": { "Category": "Invoke", "Owner": "AWS", "Version": 1, "Provider": "StepFunctions" }, "OutputArtifacts": [ { "Name": "myOutputArtifact" } ], "Configuration": { "StateMachineArn": "arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine", "ExecutionNamePrefix": "my-prefix", "Input": "{\"action\": \"test\"}" } }

Example for input file

YAML
Name: ActionName InputArtifacts: - Name: myInputArtifact ActionTypeId: Category: Invoke Owner: AWS Version: 1 Provider: StepFunctions OutputArtifacts: - Name: myOutputArtifact Configuration: StateMachineArn: 'arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine' ExecutionNamePrefix: my-prefix InputType: FilePath Input: assets/input.json
JSON
{ "Name": "ActionName", "InputArtifacts": [ { "Name": "myInputArtifact" } ], "ActionTypeId": { "Category": "Invoke", "Owner": "AWS", "Version": 1, "Provider": "StepFunctions" }, "OutputArtifacts": [ { "Name": "myOutputArtifact" } ], "Configuration": { "StateMachineArn": "arn:aws:states:us-east-1:111122223333:stateMachine:HelloWorld-StateMachine", "ExecutionNamePrefix": "my-prefix", "InputType": "FilePath", "Input": "assets/input.json" } }

Behavior

During a release, CodePipeline executes the configured state machine using the input as specified in the action configuration.

When InputType is set to Literal, the content of the Input action configuration field is used as the input for the state machine. When literal input is not provided, the state machine execution uses an empty JSON object {}. For more information about running a state machine execution without input, see the Step Functions StartExecution API.

When InputType is set to FilePath, the action unzips the input artifact and uses the content of the file specified in the Input action configuration field as the input for the state machine. When FilePath is specified, the Input field is required and an input artifact must exist; otherwise, the action fails.

After a successful start execution, behavior will diverge for the two state machine types, standard and express.

Standard state machines

If the standard state machine execution was successfully started, CodePipeline polls the DescribeExecution API until the execution reaches a terminal status. If the execution completes successfully, the action succeeds; otherwise, it fails.

If an output artifact is configured, the artifact will contain the return value of the state machine. This is obtained from the output property of the Step Functions DescribeExecution API response after the state machine execution completes successfully. Note that there are output length constraints enforced on this API.

Error handling

  • If the action fails to start a state machine execution, the action execution fails.

  • If the state machine execution fails to reach a terminal status before the CodePipeline Step Functions action reaches its timeout (default of 7 days), the action execution fails. The state machine might continue despite this failure. For more information about state machine execution timeouts in Step Functions, see Standard vs. Express Workflows.

    Note

    You can request a quota increase for the invoke action timeout for the account with the action. However, the quota increase applies to all actions of this type in all Regions for that account.

  • If the state machine execution reaches a terminal status of FAILED, TIMED_OUT, or ABORTED, the action execution fails.

Express state machines

If the express state machine execution was successfully started, the invoke action execution completes successfully.

Considerations for actions configured for express state machines:

  • You cannot designate an output artifact.

  • The action does not wait for the state machine execution to complete.

  • After the action execution is started in CodePipeline, the action execution succeeds even if the state machine execution fails.

Error handling

  • If CodePipeline fails to start a state machine execution, the action execution fails. Otherwise, the action succeeds immediately. The action succeeds in CodePipeline regardless of how long the state machine execution takes to complete or its outcome.

The following related resources can help you as you work with this action.