Skip to content
SST
Blog Docs Examples
23K
Console

Task

The Task state is internally used by the StepFunctions component to add a Task workflow state to a state machine.

You’ll find this component returned by task-specific methods of the StepFunctions component such as lambdaInvoke, snsPublish, sqsSendMessage, and more.

Constructor

new Task(args)

Parameters

TaskArgs

arguments?

Type Input<Record<string, Input<any>>>

Used to pass information to the API actions of connected resources. Values can include JSONata expressions. For more information, see Transforming data with JSONata in Step Functions.

{
  arguments: {
    product: "{% $states.input.order.product %}",
    count: 32
  }
}

assign?

Type Record<string, any>

Used to store variables. The Assign field accepts a JSON object with key/value pairs that define variable names and their assigned values. Alternatively, you can pass in a JSONata expression directly.

For more information, see Passing data between states with variables.

Provide a JSON object with variable names and values.

{
  assign: {
    productName: "product1",
    count: 42,
    available: true,
  }
}

Assign values from state input and result using JSONata expressions.

  {
    assign: {
      product: "{% $states.input.order.product %}",
      currentPrice: "{% $states.result.Payload.current_price %}"
    }
  }

comment?

Type Input<string>

A comment to describe the state.

name

Type string

The name of the state.

output?

Type Input<Record<string, any> | “{% ${string} %}”>

Specify and transform output from the state. When specified, the value overrides the state output default.

The output field accepts any JSON value (object, array, string, number, boolean, null). Alternatively, you can pass in a JSONata expression directly.

For more information, see Transforming data with JSONata in Step Functions.

permissions?

Type FunctionPermissionArgs[]

resource

Type Input<string>

role?

Type Input<string>

Specifies a target role the state machine’s execution role must assume before invoking the specified resource. See Task state’s Credentials field examples.

{
  role: "arn:aws:iam::123456789012:role/MyRole"
}

timeout?

Type Input<“${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${number} second” | “${number} seconds” | “${number} day” | “${number} days” | “{% ${string} %}”>

Default "60 seconds" for HTTP tasks, "99999999 seconds" for all other tasks.

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails. Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

Methods

catch

catch(state, args?)

Parameters

  • state State

    The state to transition to on error.

  • args? CatchArgs

    Optional catch properties to customize error handling.

Returns Task

Add catch behavior to the Task state. If the state fails with any of the specified errors, continue execution with the given state.

next

next(state)

Parameters

  • state State

    The state to transition to.

Returns State

Add a next state to the Task state. If the state completes successfully, continue execution with the given state.

retry

retry(args?)

Parameters

  • args? RetryArgs

    Optional retry properties to customize retry behavior.

Returns Task

Add retry behavior to the Task state. If the state fails with any of the specified errors, retry execution using the specified parameters.

EcsRunTaskArgs

assign?

Type Record<string, any>

Used to store variables. The Assign field accepts a JSON object with key/value pairs that define variable names and their assigned values. Alternatively, you can pass in a JSONata expression directly.

For more information, see Passing data between states with variables.

Provide a JSON object with variable names and values.

{
  assign: {
    productName: "product1",
    count: 42,
    available: true,
  }
}

Assign values from state input and result using JSONata expressions.

  {
    assign: {
      product: "{% $states.input.order.product %}",
      currentPrice: "{% $states.result.Payload.current_price %}"
    }
  }

comment?

Type Input<string>

A comment to describe the state.

environment?

Type Input<Record<string, Input<string>>>

The environment variables to apply to the ECS task.

{
  environment: {
    MY_ENV: "{% $states.input.foo %}",
  },
}

name

Type string

The name of the state.

output?

Type Input<Record<string, any> | “{% ${string} %}”>

Specify and transform output from the state. When specified, the value overrides the state output default.

The output field accepts any JSON value (object, array, string, number, boolean, null). Alternatively, you can pass in a JSONata expression directly.

For more information, see Transforming data with JSONata in Step Functions.

role?

Type Input<string>

Specifies a target role the state machine’s execution role must assume before invoking the specified resource. See Task state’s Credentials field examples.

{
  role: "arn:aws:iam::123456789012:role/MyRole"
}

task

Type Task

The Task component to run.

timeout?

Type Input<“${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${number} second” | “${number} seconds” | “${number} day” | “${number} days” | “{% ${string} %}”>

Default "60 seconds" for HTTP tasks, "99999999 seconds" for all other tasks.

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails. Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

EventBridgePutEventsArgs

assign?

Type Record<string, any>

Used to store variables. The Assign field accepts a JSON object with key/value pairs that define variable names and their assigned values. Alternatively, you can pass in a JSONata expression directly.

For more information, see Passing data between states with variables.

Provide a JSON object with variable names and values.

{
  assign: {
    productName: "product1",
    count: 42,
    available: true,
  }
}

Assign values from state input and result using JSONata expressions.

  {
    assign: {
      product: "{% $states.input.order.product %}",
      currentPrice: "{% $states.result.Payload.current_price %}"
    }
  }

comment?

Type Input<string>

A comment to describe the state.

events

Type Object[]

The events to put to the EventBridge event bus.

{
  events: [
    {
      bus: myBus,
      source: "my-application",
      detailType: "order-created",
      detail: {
        orderId: "{% $states.input.orderId %}",
        customerId: "{% $states.input.customer.id %}",
        items: "{% $states.input.items %}"
      }
    }
  ]
}

events[].bus

Type Bus

The Bus component to send the event to.

events[].detail?

Type Input<Record<string, Input<unknown>>>

The event payload containing the event details as a JSON object. Values can include JSONata expressions for dynamic content.

events[].detailType?

Type Input<string>

The detail type of the event, which helps subscribers filter and route events. Can be a static string or a JSONata expression.

events[].source?

Type Input<string>

The source of the event, which identifies the service or component that generated it. Can be a static string or a JSONata expression.

name

Type string

The name of the state.

output?

Type Input<Record<string, any> | “{% ${string} %}”>

Specify and transform output from the state. When specified, the value overrides the state output default.

The output field accepts any JSON value (object, array, string, number, boolean, null). Alternatively, you can pass in a JSONata expression directly.

For more information, see Transforming data with JSONata in Step Functions.

role?

Type Input<string>

Specifies a target role the state machine’s execution role must assume before invoking the specified resource. See Task state’s Credentials field examples.

{
  role: "arn:aws:iam::123456789012:role/MyRole"
}

timeout?

Type Input<“${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${number} second” | “${number} seconds” | “${number} day” | “${number} days” | “{% ${string} %}”>

Default "60 seconds" for HTTP tasks, "99999999 seconds" for all other tasks.

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails. Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

LambdaInvokeArgs

assign?

Type Record<string, any>

Used to store variables. The Assign field accepts a JSON object with key/value pairs that define variable names and their assigned values. Alternatively, you can pass in a JSONata expression directly.

For more information, see Passing data between states with variables.

Provide a JSON object with variable names and values.

{
  assign: {
    productName: "product1",
    count: 42,
    available: true,
  }
}

Assign values from state input and result using JSONata expressions.

  {
    assign: {
      product: "{% $states.input.order.product %}",
      currentPrice: "{% $states.result.Payload.current_price %}"
    }
  }

comment?

Type Input<string>

A comment to describe the state.

function

Type Function

The Function component to invoke.

name

Type string

The name of the state.

output?

Type Input<Record<string, any> | “{% ${string} %}”>

Specify and transform output from the state. When specified, the value overrides the state output default.

The output field accepts any JSON value (object, array, string, number, boolean, null). Alternatively, you can pass in a JSONata expression directly.

For more information, see Transforming data with JSONata in Step Functions.

payload?

Type Record<string, Input<unknown>>

The payload to send to the Lambda function.

role?

Type Input<string>

Specifies a target role the state machine’s execution role must assume before invoking the specified resource. See Task state’s Credentials field examples.

{
  role: "arn:aws:iam::123456789012:role/MyRole"
}

timeout?

Type Input<“${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${number} second” | “${number} seconds” | “${number} day” | “${number} days” | “{% ${string} %}”>

Default "60 seconds" for HTTP tasks, "99999999 seconds" for all other tasks.

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails. Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

SnsPublishArgs

assign?

Type Record<string, any>

Used to store variables. The Assign field accepts a JSON object with key/value pairs that define variable names and their assigned values. Alternatively, you can pass in a JSONata expression directly.

For more information, see Passing data between states with variables.

Provide a JSON object with variable names and values.

{
  assign: {
    productName: "product1",
    count: 42,
    available: true,
  }
}

Assign values from state input and result using JSONata expressions.

  {
    assign: {
      product: "{% $states.input.order.product %}",
      currentPrice: "{% $states.result.Payload.current_price %}"
    }
  }

comment?

Type Input<string>

A comment to describe the state.

message

Type Input<string>

The message to send to the SNS topic.

messageAttributes?

Type Input<Record<string, Input<string>>>

The message attributes to send to the SNS topic.

messageDeduplicationId?

Type Input<string>

The message deduplication ID to send to the SNS topic.

messageGroupId?

Type Input<string>

The message group ID to send to the SNS topic.

name

Type string

The name of the state.

output?

Type Input<Record<string, any> | “{% ${string} %}”>

Specify and transform output from the state. When specified, the value overrides the state output default.

The output field accepts any JSON value (object, array, string, number, boolean, null). Alternatively, you can pass in a JSONata expression directly.

For more information, see Transforming data with JSONata in Step Functions.

role?

Type Input<string>

Specifies a target role the state machine’s execution role must assume before invoking the specified resource. See Task state’s Credentials field examples.

{
  role: "arn:aws:iam::123456789012:role/MyRole"
}

subject?

Type Input<string>

The subject of the message to send to the SNS topic.

timeout?

Type Input<“${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${number} second” | “${number} seconds” | “${number} day” | “${number} days” | “{% ${string} %}”>

Default "60 seconds" for HTTP tasks, "99999999 seconds" for all other tasks.

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails. Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

topic

Type SnsTopic

The SnsTopic component to publish the message to.

SqsSendMessageArgs

assign?

Type Record<string, any>

Used to store variables. The Assign field accepts a JSON object with key/value pairs that define variable names and their assigned values. Alternatively, you can pass in a JSONata expression directly.

For more information, see Passing data between states with variables.

Provide a JSON object with variable names and values.

{
  assign: {
    productName: "product1",
    count: 42,
    available: true,
  }
}

Assign values from state input and result using JSONata expressions.

  {
    assign: {
      product: "{% $states.input.order.product %}",
      currentPrice: "{% $states.result.Payload.current_price %}"
    }
  }

comment?

Type Input<string>

A comment to describe the state.

messageAttributes?

Type Input<Record<string, Input<string>>>

The message attributes to send to the SQS queue.

messageBody

Type Input<string>

The message body to send to the SQS queue.

messageDeduplicationId?

Type Input<string>

The message deduplication ID to send to the SQS queue.

messageGroupId?

Type Input<string>

The message group ID to send to the SQS queue.

name

Type string

The name of the state.

output?

Type Input<Record<string, any> | “{% ${string} %}”>

Specify and transform output from the state. When specified, the value overrides the state output default.

The output field accepts any JSON value (object, array, string, number, boolean, null). Alternatively, you can pass in a JSONata expression directly.

For more information, see Transforming data with JSONata in Step Functions.

queue

Type Queue

The Queue component to send the message to.

role?

Type Input<string>

Specifies a target role the state machine’s execution role must assume before invoking the specified resource. See Task state’s Credentials field examples.

{
  role: "arn:aws:iam::123456789012:role/MyRole"
}

timeout?

Type Input<“${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${number} second” | “${number} seconds” | “${number} day” | “${number} days” | “{% ${string} %}”>

Default "60 seconds" for HTTP tasks, "99999999 seconds" for all other tasks.

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails. Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

TaskBaseArgs

assign?

Type Record<string, any>

Used to store variables. The Assign field accepts a JSON object with key/value pairs that define variable names and their assigned values. Alternatively, you can pass in a JSONata expression directly.

For more information, see Passing data between states with variables.

Provide a JSON object with variable names and values.

{
  assign: {
    productName: "product1",
    count: 42,
    available: true,
  }
}

Assign values from state input and result using JSONata expressions.

  {
    assign: {
      product: "{% $states.input.order.product %}",
      currentPrice: "{% $states.result.Payload.current_price %}"
    }
  }

comment?

Type Input<string>

A comment to describe the state.

name

Type string

The name of the state.

output?

Type Input<Record<string, any> | “{% ${string} %}”>

Specify and transform output from the state. When specified, the value overrides the state output default.

The output field accepts any JSON value (object, array, string, number, boolean, null). Alternatively, you can pass in a JSONata expression directly.

For more information, see Transforming data with JSONata in Step Functions.

role?

Type Input<string>

Specifies a target role the state machine’s execution role must assume before invoking the specified resource. See Task state’s Credentials field examples.

{
  role: "arn:aws:iam::123456789012:role/MyRole"
}

timeout?

Type Input<“${number} minute” | “${number} minutes” | “${number} hour” | “${number} hours” | “${number} second” | “${number} seconds” | “${number} day” | “${number} days” | “{% ${string} %}”>

Default "60 seconds" for HTTP tasks, "99999999 seconds" for all other tasks.

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails. Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.