Task

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

Note

This component is not intended to be created directly.

You’ll find this component returned by the task method of the StepFunctions component.

It’s also returned by convenience methods like lambdaInvoke, snsPublish, sqsSendMessage, and more.

---

Constructor

new Task(args)

Parameters

• args TaskArgs

TaskArgs

arguments?

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

The arguments to be passed to the APIs of the connected resources. Values can include outputs from other resources and JSONata expressions.

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

assign?

Type Record<string, any>

Store variables that can be accessed by any state later in the workflow, instead of passing it through each state.

This takes a set of key/value pairs. Where the key is the name of the variable that can be accessed by any subsequent state.

The value can be any JSON value; object, array, string, number, boolean, null.

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

Or, you can pass in a JSONata expression.

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

Learn more about passing data between states with variables.

integration?

Type Input<“response” | “sync” | “token”>

Default “response”

Specifies how a Task state integrates with the specified AWS service.

The response integration is the default. The Task state calls a service and progress to the next state immediately after it gets an HTTP response.

In sync integration, the Task state waits for the service to complete the job (ie. Amazon ECS task, AWS CodeBuild build, etc.) before progressing to the next state.

In token integration, the Task state calls a service and pauses until a task token is returned. To resume execution, call the SendTaskSuccess or SendTaskFailure API with the task token.

Learn more about service integration patterns.

{
  integration: "token"
}

name

Type string

The name of the state. This needs to be unique within the state machine.

output?

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

Transform the output of the state. When specified, the value overrides the default output from the state.

This takes any JSON value; object, array, string, number, boolean, null.

{
  output: {
    charged: true
  }
}

Or, you can pass in a JSONata expression.

{
  output: {
    product: "{% $states.input.product %}"
  }
}

Learn more about transforming data with JSONata.

permissions?

Type Object[]

• actions

• effect?

• resources

Permissions and the resources that the task needs to access. These permissions are used to create the task’s IAM role.

For example, allow the task to read and write to an S3 bucket called my-bucket.

{
  permissions: [
    {
      actions: ["s3:GetObject", "s3:PutObject"],
      resources: ["arn:aws:s3:::my-bucket/*"]
    }
  ]
}

Allow the task to perform all actions on an S3 bucket called my-bucket.

{
  permissions: [
    {
      actions: ["s3:*"],
      resources: ["arn:aws:s3:::my-bucket/*"]
    }
  ]
}

Granting the task permissions to access all resources.

{
  permissions: [
    {
      actions: ["*"],
      resources: ["*"]
    }
  ]
}

permissions[].actions

Type string[]

The IAM actions that can be performed.

{
  actions: ["s3:*"]
}

permissions[].effect?

Type “allow” | “deny”

Default “allow”

Configures whether the permission is allowed or denied.

{
  effect: "deny"
}

permissions[].resources

Type Input<Input<string>[]>

The resourcess specified using the IAM ARN format.

{
  resources: ["arn:aws:s3:::my-bucket/*"]
}

resource

Type Input<string>

The ARN of the task. Follows the format.

{
  resource: "arn:aws:states:::service:task_type:name"
}

For example, to start an AWS CodeBuild build.

{
  resource: "arn:aws:states:::codebuild:startBuild"
}

Learn more about task ARNs.

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.

{
  timeout: "10 seconds"
}

Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

{
  time: "{% $states.input.timeout %}"
}

Methods

catch

catch(state, args?)

Parameters

• state State

  The state to transition to on error.

• args? CatchArgs

  Properties to customize error handling.

Returns Task

Add a catch behavior to the Task state. So if the state fails with any of the specified errors, it’ll continue execution to the given state.

This defaults to.

sst.config.ts

sst.aws.StepFunctions.task({
  // ...
})
.catch({
  errors: ["States.ALL"]
});

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 to the given state.

sst.config.ts

sst.aws.StepFunctions.task({
  // ...
})
.next(state);

retry

retry(args?)

Parameters

• args? RetryArgs

  Properties to define the retry behavior.

Returns Task

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

This defaults to.

sst.config.ts

sst.aws.StepFunctions.task({
  // ...
})
.retry({
  errors: ["States.ALL"],
  interval: "1 second",
  maxAttempts: 3,
  backoffRate: 2
});

EcsRunTaskArgs

assign?

Type Record<string, any>

Store variables that can be accessed by any state later in the workflow, instead of passing it through each state.

This takes a set of key/value pairs. Where the key is the name of the variable that can be accessed by any subsequent state.

The value can be any JSON value; object, array, string, number, boolean, null.

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

Or, you can pass in a JSONata expression.

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

Learn more about passing data between states with variables.

environment?

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

The environment variables to apply to the ECS task. Values can include outputs from other resources and JSONata expressions.

{
  environment: {
    MY_ENV: "{% $states.input.foo %}",
    MY_URL: api.url,
    MY_KEY: 1
  }
}

integration?

Type Input<“response” | “sync” | “token”>

Default “response”

Specifies how a Task state integrates with the specified AWS service.

The response integration is the default. The Task state calls a service and progress to the next state immediately after it gets an HTTP response.

In sync integration, the Task state waits for the service to complete the job (ie. Amazon ECS task, AWS CodeBuild build, etc.) before progressing to the next state.

In token integration, the Task state calls a service and pauses until a task token is returned. To resume execution, call the SendTaskSuccess or SendTaskFailure API with the task token.

Learn more about service integration patterns.

{
  integration: "token"
}

name

Type string

The name of the state. This needs to be unique within the state machine.

output?

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

Transform the output of the state. When specified, the value overrides the default output from the state.

This takes any JSON value; object, array, string, number, boolean, null.

{
  output: {
    charged: true
  }
}

Or, you can pass in a JSONata expression.

{
  output: {
    product: "{% $states.input.product %}"
  }
}

Learn more about transforming data with JSONata.

task

Type Task

The ECS Task to run.

sst.config.ts

const myCluster = new sst.aws.Cluster("MyCluster");
const myTask = new sst.aws.Task("MyTask", { cluster: myCluster });

sst.aws.StepFunctions.ecsRunTask({
  name: "RunTask",
  task: myTask
});

timeout?

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

Default “99999999 seconds”

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails.

{
  timeout: "10 seconds"
}

Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

{
  time: "{% $states.input.timeout %}"
}

EventBridgePutEventsArgs

assign?

Type Record<string, any>

Store variables that can be accessed by any state later in the workflow, instead of passing it through each state.

This takes a set of key/value pairs. Where the key is the name of the variable that can be accessed by any subsequent state.

The value can be any JSON value; object, array, string, number, boolean, null.

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

Or, you can pass in a JSONata expression.

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

Learn more about passing data between states with variables.

events

Type Object[]

• bus

• detail?

• detailType?

• source?

A list of events to send to the EventBridge.

{
  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 also include a JSONata expression.

{
  detail: {
    type: "order",
    message: "{% $states.input.message %}"
  }
}

events[].detailType?

Type Input<string>

The detail type of the event. This helps subscribers filter and route events. This can be a string or JSONata expression.

events[].source?

Type Input<string>

The source of the event. This string or JSONata expression identifies the service or component that generated it.

integration?

Type Input<“response” | “sync” | “token”>

Default “response”

Specifies how a Task state integrates with the specified AWS service.

The response integration is the default. The Task state calls a service and progress to the next state immediately after it gets an HTTP response.

In sync integration, the Task state waits for the service to complete the job (ie. Amazon ECS task, AWS CodeBuild build, etc.) before progressing to the next state.

In token integration, the Task state calls a service and pauses until a task token is returned. To resume execution, call the SendTaskSuccess or SendTaskFailure API with the task token.

Learn more about service integration patterns.

{
  integration: "token"
}

name

Type string

The name of the state. This needs to be unique within the state machine.

output?

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

Transform the output of the state. When specified, the value overrides the default output from the state.

This takes any JSON value; object, array, string, number, boolean, null.

{
  output: {
    charged: true
  }
}

Or, you can pass in a JSONata expression.

{
  output: {
    product: "{% $states.input.product %}"
  }
}

Learn more about transforming data with JSONata.

timeout?

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

Default “99999999 seconds”

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails.

{
  timeout: "10 seconds"
}

Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

{
  time: "{% $states.input.timeout %}"
}

LambdaInvokeArgs

assign?

Type Record<string, any>

Store variables that can be accessed by any state later in the workflow, instead of passing it through each state.

This takes a set of key/value pairs. Where the key is the name of the variable that can be accessed by any subsequent state.

The value can be any JSON value; object, array, string, number, boolean, null.

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

Or, you can pass in a JSONata expression.

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

Learn more about passing data between states with variables.

function

Type Function | Input<string | FunctionArgs | “arn:aws:lambda:${string}”>

The Function to invoke.

integration?

Type Input<“response” | “sync” | “token”>

Default “response”

Specifies how a Task state integrates with the specified AWS service.

The response integration is the default. The Task state calls a service and progress to the next state immediately after it gets an HTTP response.

In sync integration, the Task state waits for the service to complete the job (ie. Amazon ECS task, AWS CodeBuild build, etc.) before progressing to the next state.

In token integration, the Task state calls a service and pauses until a task token is returned. To resume execution, call the SendTaskSuccess or SendTaskFailure API with the task token.

Learn more about service integration patterns.

{
  integration: "token"
}

name

Type string

The name of the state. This needs to be unique within the state machine.

output?

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

Transform the output of the state. When specified, the value overrides the default output from the state.

This takes any JSON value; object, array, string, number, boolean, null.

{
  output: {
    charged: true
  }
}

Or, you can pass in a JSONata expression.

{
  output: {
    product: "{% $states.input.product %}"
  }
}

Learn more about transforming data with JSONata.

payload?

Type Record<string, Input<unknown>>

The payload to send to the Lambda function. Values can include outputs from other resources and JSONata expressions.

{
  payload: {
    env: "{% $states.input.foo %}",
    url: api.url,
    key: 1
  }
}

timeout?

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

Default “99999999 seconds”

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails.

{
  timeout: "10 seconds"
}

Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

{
  time: "{% $states.input.timeout %}"
}

SnsPublishArgs

assign?

Type Record<string, any>

Store variables that can be accessed by any state later in the workflow, instead of passing it through each state.

This takes a set of key/value pairs. Where the key is the name of the variable that can be accessed by any subsequent state.

The value can be any JSON value; object, array, string, number, boolean, null.

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

Or, you can pass in a JSONata expression.

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

Learn more about passing data between states with variables.

integration?

Type Input<“response” | “sync” | “token”>

Default “response”

Specifies how a Task state integrates with the specified AWS service.

The response integration is the default. The Task state calls a service and progress to the next state immediately after it gets an HTTP response.

In sync integration, the Task state waits for the service to complete the job (ie. Amazon ECS task, AWS CodeBuild build, etc.) before progressing to the next state.

In token integration, the Task state calls a service and pauses until a task token is returned. To resume execution, call the SendTaskSuccess or SendTaskFailure API with the task token.

Learn more about service integration patterns.

{
  integration: "token"
}

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. Values can include outputs from other resources and JSONata expressions.

{
  messageAttributes: {
    env: "{% $states.input.foo %}",
    url: api.url,
    key: 1
  }
}

messageDeduplicationId?

Type Input<string>

The message deduplication ID to send to the SNS topic. This applies to FIFO topics only.

This is a string that’s used to deduplicate messages sent within the minimum 5 minute interval.

messageGroupId?

Type Input<string>

The message group ID to send to the SNS topic. This only applies to FIFO topics.

name

Type string

The name of the state. This needs to be unique within the state machine.

output?

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

Transform the output of the state. When specified, the value overrides the default output from the state.

This takes any JSON value; object, array, string, number, boolean, null.

{
  output: {
    charged: true
  }
}

Or, you can pass in a JSONata expression.

{
  output: {
    product: "{% $states.input.product %}"
  }
}

Learn more about transforming data with JSONata.

subject?

Type Input<string>

An optional subject line when the message is delivered to email endpoints.

timeout?

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

Default “99999999 seconds”

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails.

{
  timeout: "10 seconds"
}

Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

{
  time: "{% $states.input.timeout %}"
}

topic

Type SnsTopic

The SnsTopic component to publish the message to.

SqsSendMessageArgs

assign?

Type Record<string, any>

Store variables that can be accessed by any state later in the workflow, instead of passing it through each state.

This takes a set of key/value pairs. Where the key is the name of the variable that can be accessed by any subsequent state.

The value can be any JSON value; object, array, string, number, boolean, null.

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

Or, you can pass in a JSONata expression.

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

Learn more about passing data between states with variables.

integration?

Type Input<“response” | “sync” | “token”>

Default “response”

Specifies how a Task state integrates with the specified AWS service.

The response integration is the default. The Task state calls a service and progress to the next state immediately after it gets an HTTP response.

In sync integration, the Task state waits for the service to complete the job (ie. Amazon ECS task, AWS CodeBuild build, etc.) before progressing to the next state.

In token integration, the Task state calls a service and pauses until a task token is returned. To resume execution, call the SendTaskSuccess or SendTaskFailure API with the task token.

Learn more about service integration patterns.

{
  integration: "token"
}

messageAttributes?

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

The message attributes to send to the SQS queue. Values can include outputs from other resources and JSONata expressions.

{
  messageAttributes: {
    env: "{% $states.input.foo %}",
    url: api.url,
    key: 1
  }
}

messageBody

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

The message body to send to the SQS queue. The maximum size is 256KB.

messageDeduplicationId?

Type Input<string>

The message deduplication ID to send to the SQS queue. This applies to FIFO queues only.

This is a string that’s used to deduplicate messages sent within the minimum 5 minute interval.

messageGroupId?

Type Input<string>

The message group ID to send to the SQS queue. This only applies to FIFO queues.

name

Type string

The name of the state. This needs to be unique within the state machine.

output?

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

Transform the output of the state. When specified, the value overrides the default output from the state.

This takes any JSON value; object, array, string, number, boolean, null.

{
  output: {
    charged: true
  }
}

Or, you can pass in a JSONata expression.

{
  output: {
    product: "{% $states.input.product %}"
  }
}

Learn more about transforming data with JSONata.

queue

Type Queue

The Queue component to send the message to.

timeout?

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

Default “99999999 seconds”

Specifies the maximum time a task can run before it times out with the States.Timeout error and fails.

{
  timeout: "10 seconds"
}

Alternatively, you can specify a JSONata expression that evaluates to a number in seconds.

{
  time: "{% $states.input.timeout %}"
}