Step Functions

`steps`

Impact: ⚙️ Runtime Define the execution flow for the action. Steps run sequentially.

steps:
  - stepId: fetch_employees
    description: Fetch employee data from API
    stepFunction:
      functionName: request
      parameters:
        url: '/employees/directory'
        method: get
        args:
          - name: fields
            value: '{{$.inputs.fields ?? "firstName,lastName"}}'
            in: query
  - stepId: transform_response
    stepFunction:
      functionName: map_fields
      version: '2'
      parameters:
        fields:
          - targetFieldKey: employees
            expression: $.employees
        dataSource: $.steps.fetch_employees.output.data

Step Properties

Property	Type	Description
`stepId`	string	Unique identifier within action
`description`	string	What this step does (for debugging)
`condition`	JEXL	Skip step if condition is false
`onConditionError`	boolean \| `'break'`	How to handle an error while evaluating `condition`: `true`/`false` to treat the condition as met/unmet, or `'break'` to stop the step sequence
`ignoreError`	boolean	Continue execution if this step fails (default: `false`)
`stepFunction`	object	Function to execute (for simple steps)
`iterator`	JSONPath	Array expression: makes this a foreach step. See Iterator Steps
`stepFunctions`	array	Multiple functions to execute per iteration (use with `iterator`)

Conditional Steps

steps:
  - stepId: fetch_with_filter
    condition: '{{present(inputs.department)}}'
    stepFunction:
      functionName: request
      parameters:
        url: '/employees'
        args:
          - name: department
            value: $.inputs.department
            in: query

Condition expressions

Conditions use JEXL syntax with helper functions:

Function	Description	Example
`present(x)`	Value exists and not null	`present(inputs.filter)`
`blank(x)`	Value is null, undefined, or empty	`blank(inputs.cursor)`

Common patterns:

# Only run if parameter provided
condition: '{{present(inputs.employee_id)}}'

# Only run on first page
condition: '{{blank(inputs.cursor)}}'

# Multiple conditions
condition: '{{present(inputs.start_date) && present(inputs.end_date)}}'

`request`

Impact: ⚙️ Runtime Make an HTTP request to the provider API.

stepFunction:
  functionName: request
  parameters:
    url: '/employees/{employee_id}'
    method: get
    args:
      - name: employee_id
        value: $.inputs.employee_id
        in: path
      - name: fields
        value: '{{$.inputs.fields ?? "all"}}'
        in: query
      - name: Content-Type
        value: application/json
        in: headers

Parameter	Type	Description
`baseUrl`	string	Override connector baseUrl
`url`	string	Endpoint path (appended to baseUrl)
`method`	enum	`get`, `post`, `put`, `patch`, `delete`
`authorization`	object	Override connector authentication
`args`	array	Request parameters
`response.collection`	boolean	Whether response is an array (default: `true`)
`response.dataKey`	string	Extract data from this key in response
`response.indexField`	string	Field to use as index for keyed results
`customErrors`	array	Remap provider error responses (see below)

Args Location (`in`)

Value	Description
`path`	URL path parameter: `/employees/{id}`
`query`	Query string: `?field=value`
`body`	Request body (JSON)
`headers`	HTTP header

Request construction internals

The runtime builds requests as follows:

URL: baseUrl + url with path params interpolated
Query: All in: query args joined with &
Body: All in: body args merged into JSON object
Headers: Connector authentication headers + custom headers + in: headers args

Path parameter example:

url: '/employees/{employee_id}/time-off/{request_id}'
args:
  - name: employee_id
    value: $.inputs.employee_id
    in: path
  - name: request_id
    value: $.inputs.request_id
    in: path

Resolves to: /employees/123/time-off/456Body construction:

args:
  - name: firstName
    value: $.inputs.first_name
    in: body
  - name: lastName
    value: $.inputs.last_name
    in: body

Sends: { "firstName": "John", "lastName": "Doe" }

Custom error handling

Use customErrors to remap provider error responses. This is useful for:

GraphQL APIs that return errors with 200 status codes
Provider-specific error formats that need normalization
Custom error messages for better AI agent understanding

stepFunction:
  functionName: request
  parameters:
    url: /graphql
    method: post
    customErrors:
      - receivedStatus: 200
        targetStatus: 400
        condition: '{{present(data.errors)}}'
        message: GraphQL query failed
      - receivedStatus: 404
        targetStatus: 400
        message: Resource not found
      - receivedStatus: 200
        targetStatus: 401
        condition: '{{data.ok == false}}'
        message: '{{data.error}}'

customErrors properties:

Property	Type	Description
`receivedStatus`	number	HTTP status to match from provider
`targetStatus`	number	HTTP status to return instead
`condition`	string	JEXL expression (only trigger error if true)
`message`	string	Error message. Pass a plain string for a static message, or a JEXL expression like `{{data.error}}` to pull the value from the response body. If the expression resolves to null or undefined, the message falls back to the standard HTTP status text (e.g. `Unauthorized`).

The condition property is useful for GraphQL APIs where errors are returned in the response body with a 200 status code.

`paginated_request`

Impact: ⚙️ Runtime Automatically handle pagination for list endpoints. The iterator block describes the outgoing request and the response block describes what comes back.

stepFunction:
  functionName: paginated_request
  parameters:
    baseUrl: 'https://api.provider.com'
    url: '/employees'
    method: get
    iterator:
      key: cursor        # request field that carries the page token
      in: query          # query | body
      mode: cursor       # cursor | offset | page (optional)
    response:
      dataKey: $.employees      # path to the records in the response
      nextKey: $.paging.next    # path to the next-page token
      nextKeyIn: data           # data | headers (optional, default: data)
    args:
      - name: page_size
        value: '{{$.inputs.page_size ?? 25}}'
        in: query

`iterator`

Property	Type	Description
`key`	string	Request field carrying the page token/number (required)
`in`	enum	`query` or `body` (required)
`mode`	enum	`cursor`, `offset`, or `page` (optional)
`condition`	JEXL	Only paginate while the expression is true (optional)
`startPage`	number	First page number — only valid when `mode: page`
`maxPage`	number	Cap on pages fetched — only valid when `mode: page`

`response`

Property	Type	Description
`dataKey`	string	Path to the records array in the response
`nextKey`	string	Path to the next-page token/cursor
`nextKeyIn`	enum	Where the next token lives: `data` (body) or `headers`
`indexField`	string	Field to key results by (optional)

Pagination modes

iterator.mode selects how the engine advances:

cursor — reads response.nextKey and sends it back as iterator.key on the next request, until no token is returned.
offset — advances a numeric offset carried in iterator.key.
page — advances a page number in iterator.key; supports startPage and maxPage.

For a next token that arrives in a response header, set nextKeyIn: headers (e.g. nextKey: X-Pagination-Next).Result format:

{
  "data": [...all records...],
  "next": "cursor_for_next_page_or_null"
}

MCP behavior: When an agent calls a list action, they receive the first page. The next cursor allows fetching subsequent pages by passing it back as an input parameter.

`map_fields`

Impact: ⚙️ Runtime Transform data between formats.

stepFunction:
  functionName: map_fields
  version: '2'
  parameters:
    fields:
      - targetFieldKey: id
        expression: $.employeeId
        type: string
      - targetFieldKey: full_name
        expression: $.firstName + ' ' + $.lastName
        type: string
      - targetFieldKey: is_active
        expression: $.status == 'Active'
        type: boolean
      - targetFieldKey: hire_date
        expression: $.hireDate
        type: datetime_string
    dataSource: $.steps.fetch_employees.output.data

Parameter	Type	Description
`fields`	array	Mapping definitions
`dataSource`	JSONPath	Source data to transform
`fields[].targetFieldKey`	string	Output field name
`fields[].expression`	JEXL	Value expression
`fields[].type`	enum	Output type

Field mapping expressions

Expressions support JEXL syntax with the source object as context:Simple path:

expression: $.employeeId

Concatenation:

expression: $.firstName + ' ' + $.lastName

Conditional:

expression: $.status == 'Active' ? 'employed' : 'terminated'

Null coalescing:

expression: $.middleName ?? ''

Nested access:

expression: $.department.name

Array operations:

expression: $.tags|join(',')

Type coercion: The type field ensures output matches expected type:

string - Converts to string
number - Converts to number
boolean - Converts to boolean
datetime_string - Formats as ISO 8601

`group_data`

Impact: ⚙️ Runtime Combine the outputs of several previous steps into a single grouped structure, keyed by step ID.

stepFunction:
  functionName: group_data
  parameters:
    stepsDataToGroup:
      - fetch_profile
      - fetch_compensation
    isSingleRecord: true

Parameter	Type	Description
`stepsDataToGroup`	array	Step IDs whose `output.data` should be grouped together
`isSingleRecord`	boolean	`true` nests each step’s data under its step ID for a single record; when omitted/false, data is merged per key across steps and returned as an array

Group data usage

With isSingleRecord: true, the output nests each referenced step’s data under its step ID:

{
  "fetch_profile": { "id": "1", "name": "John" },
  "fetch_compensation": { "salary": 90000 }
}

Useful for stitching together data fetched across multiple requests (e.g. a base record plus enrichment steps) before a final map_fields.

`typecast`

Impact: ⚙️ Runtime Coerce fields to declared types. typecast has two versions — set version explicitly to choose:

version: '2' (recommended) — takes a fields array (each with a targetFieldKey and type) and a dataSource, and casts those fields in place. Mirrors map_fields v2.
version: '1' (default when version is omitted) — takes no parameters. It casts the step’s result using the action’s top-level fieldConfigs instead.

stepFunction:
  functionName: typecast
  version: '2'
  parameters:
    fields:
      - targetFieldKey: count
        type: number
      - targetFieldKey: is_active
        type: boolean
    dataSource: $.steps.previous.output.data

Parameter	Type	Description
`fields`	array	Fields to cast (optional)
`fields[].targetFieldKey`	string	Field to cast
`fields[].type`	enum	`string`, `number`, `boolean`, `datetime_string`, `enum`, or `object`
`fields[].array`	boolean	Field holds an array of the given type (default: `false`)
`fields[].properties`	array	Nested field casts for `type: object`
`dataSource`	JSONPath	Source data to cast (required)

The parameters above apply to version: '2'. If you omit version, the step runs v1, which ignores parameters entirely and casts using the action’s fieldConfigs. Always set version: '2' when using the fields/dataSource form.

`soap_request`

Impact: ⚙️ Runtime Make SOAP API requests. Used primarily for enterprise providers like Workday.

stepFunction:
  functionName: soap_request
  parameters:
    baseUrl: 'https://${credentials.workday_host}'
    url: '/ccx/service/${credentials.tenant}/Human_Resources'
    method: post
    authorization:
      type: bearer
      token: ${credentials.accessToken}
      includeBearer: true
    soapOperation: Get_Workers
    useSoapContext: true
    namespaces:
      - namespaceIdentifier: bsvc
        namespace: 'urn:com.workday/bsvc'
    args:
      - name: '@_bsvc:version'
        in: body
        value: v45.1
      - name: bsvc:Request_Criteria
        in: body
        value:
          'bsvc:Transaction_Log_Criteria_Data':
            - 'bsvc:Transaction_Date_Range_Data':
                'bsvc:Updated_From': '{{$.inputs.updated_after}}'

Parameter	Type	Description
`baseUrl`	string	SOAP service base URL
`url`	string	SOAP endpoint path
`method`	enum	HTTP method (typically `post`)
`authorization`	object	Auth config (same as `request`)
`soapOperation`	string	SOAP operation name
`useSoapContext`	boolean	Use SOAP context (default: `true`)
`namespaces`	array	XML namespace definitions
`args`	array	Request parameters

SOAP namespace configuration

Namespaces map XML prefixes to URIs:

namespaces:
  - namespaceIdentifier: bsvc
    namespace: 'urn:com.workday/bsvc'
  - namespaceIdentifier: wd
    namespace: 'urn:com.workday/bsvc/wd'

Reference namespaces in field names with the identifier prefix:

args:
  - name: 'bsvc:Worker_Reference'
    in: body
    value:
      'bsvc:ID':
        '@_bsvc:type': 'Employee_ID'
        '#text': '{{$.inputs.employee_id}}'

XML attribute syntax: Use @_ prefix for XML attributes and #text for text content.

`static_values`

Impact: ⚙️ Runtime Return predefined static values without making an API request. Useful for enum lookups or constant data.

stepFunction:
  functionName: static_values
  parameters:
    values:
      - id: question
        name: Question
      - id: incident
        name: Incident
      - id: problem
        name: Problem
      - id: task
        name: Task

Parameter	Type	Description
`values`	array	Array of static objects to return

Static values use cases

Use static_values when:

Provider doesn’t have an API endpoint for enum values:

# Ticket types are hardcoded in Zendesk
stepFunction:
  functionName: static_values
  parameters:
    values:
      - id: question
        name: Question
      - id: incident
        name: Incident

Providing defaults that a later step reads via its dataSource:

steps:
  - stepId: default_types
    stepFunction:
      functionName: static_values
      parameters:
        values:
          - id: default
            name: Default Type
  - stepId: fetch_types
    stepFunction:
      functionName: request
      parameters:
        url: /custom-types

`code_execution_lambda`

Impact: ⚙️ Runtime Invoke an AWS Lambda function and use the response as the step output. Useful for offloading custom transformations, provider-specific logic, or computation that doesn’t fit other step functions.

stepFunction:
  functionName: code_execution_lambda
  parameters:
    lambdaName: my-lambda-function
    region: us-east-1
    invocationType: RequestResponse
    args:
      - name: userId
        value: $.inputs.user_id
      - name: count
        value: $.inputs.count

Parameter	Type	Description
`lambdaName`	string	Name or ARN of the Lambda function to invoke
`region`	string	AWS region of the Lambda function (optional)
`endpoint`	string	Custom Lambda endpoint URL (optional)
`invocationType`	enum	`RequestResponse`, `Event`, or `DryRun` (default: `RequestResponse`)
`qualifier`	string	Function version or alias (optional)
`args`	array	Key/value pairs combined into the JSON payload sent to the Lambda function
`args[].name`	string	Payload field name
`args[].value`	any	Payload field value (supports expressions)
`args[].condition`	string	JEXL expression: only include this arg when true (optional)
`dataKey`	string	Extract data from this key in the Lambda response (optional)

Invocation Types

Value	Description
`RequestResponse`	Synchronous: wait for the Lambda to return a response
`Event`	Asynchronous: fire-and-forget, no response body returned
`DryRun`	Validate parameters and permissions without invoking the function

Output

Field	Type	Description
`data`	any	Parsed Lambda response (after `dataKey` extraction if set)
`raw`	any	Full Lambda response payload
`statusCode`	number	HTTP status code returned by the Lambda invocation
`message`	string	Error or status message (optional)
`executedVersion`	string	Version of the Lambda function that was executed (optional)

Payload construction and response handling

The args array is assembled into a single JSON object and sent as the Lambda payload:Input args:

args:
  - name: userId
    value: $.inputs.user_id
  - name: count
    value: $.inputs.count

Sent payload:

{ "userId": "abc123", "count": 5 }

Conditional args:

args:
  - name: filter
    value: ${inputs.filter}
    condition: '{{present(inputs.filter)}}'

Extracting a nested response:

stepFunction:
  functionName: code_execution_lambda
  parameters:
    lambdaName: enrich-user
    region: us-east-1
    dataKey: result
    args:
      - name: userId
        value: ${inputs.user_id}

If the Lambda returns { "result": { "score": 0.9 }, "meta": {...} }, then $.steps.{stepId}.output.data is { "score": 0.9 }.

`soap_paginated_request`

Impact: ⚙️ Runtime The paginated variant of soap_request walks through paged SOAP responses automatically. The iterator block describes the outgoing request and the response block describes what comes back.

stepFunction:
  functionName: soap_paginated_request
  parameters:
    baseUrl: 'https://${credentials.workday_host}'
    url: '/ccx/service/${credentials.tenant}/Human_Resources'
    method: post
    soapOperation: Get_Workers
    namespaces:
      - namespaceIdentifier: bsvc
        namespace: 'urn:com.workday/bsvc'
    iterator:
      key: Page
      in: body
    response:
      dataKey: $.Response_Data
      nextKey: $.Response_Results.Page
      nextKeyIn: data
    args:
      - name: '@_bsvc:version'
        in: body
        value: v45.1

Parameter	Type	Description
`iterator.key`	string	Request field that carries the page token/number (required)
`iterator.in`	enum	`query` or `body` (required)
`response.nextKey`	string	Path to the next-page token in the response
`response.nextKeyIn`	enum	`data` or `headers`
`response.dataKey`	string	Path to the records within the response

All other parameters (baseUrl, url, method, authorization, namespaces, soapOperation, soapAction, useSoapContext, args, customErrors) match soap_request.

`upload_file`

Impact: ⚙️ Runtime Upload a file to the provider as a multipart request. The file is described by a structured file object.

stepFunction:
  functionName: upload_file
  parameters:
    url: '/files'
    method: post
    file:
      fieldName: file
      content: $.inputs.file_content   # base64
      filename: $.inputs.file_name
      contentType: application/pdf
    additionalFields:
      - name: folder_id
        value: $.inputs.folder_id

Parameter	Type	Description
`url`	string	Upload endpoint
`method`	enum	HTTP method (default: `post`)
`file.fieldName`	string	Multipart form field name for the file
`file.content`	string	File content as a base64-encoded string
`file.filename`	string	Filename used in the upload
`file.contentType`	string	MIME type of the file (optional)
`additionalFields`	array	Extra multipart form fields (`name`, `value`, optional `contentType`/`condition`)
`authorization`	object	Override connector auth (optional)
`args`	array	Additional query/header params

`upload_binary`

Impact: ⚙️ Runtime Upload raw binary content as the request body (rather than multipart form data). Use when the provider expects the file bytes directly.

stepFunction:
  functionName: upload_binary
  parameters:
    url: '/files/${inputs.file_id}/content'
    method: put
    binaryContent:
      content: $.inputs.file_content   # base64
      contentType: application/octet-stream

Parameter	Type	Description
`url`	string	Upload endpoint
`method`	enum	HTTP method (default: `post`)
`binaryContent.content`	string	File content as a base64-encoded string
`binaryContent.contentType`	string	MIME type (defaults to `application/octet-stream`)
`authorization`	object	Override connector auth (optional)
`args`	array	Additional query/header params

`download_file`

Impact: ⚙️ Runtime Download binary content from the provider and expose it as the step output. Supports downloading into memory (buffer, default) or returning a stream, plus extracting file content wrapped in a JSON response.

stepFunction:
  functionName: download_file
  parameters:
    url: '/files/${inputs.file_id}/content'
    method: get

Parameter	Type	Description
`url`	string	Download endpoint
`method`	enum	HTTP method (default: `get`)
`responseMode`	enum	`buffer` (default) or `stream`
`encoding`	enum	For buffer mode: `base64` (default), `utf8`, `binary`, `raw`, or `none`
`response.dataKey`	string	JSONPath to file content when wrapped in a JSON response (optional)
`response.urlKey`	string	JSONPath to a download URL to follow when the response returns one (optional)
`authorization`	object	Override connector auth (optional)
`args`	array	Additional query/header params

`emit_event`

Impact: ⚙️ Runtime Emit a normalized event from within an action — used by webhook/event actions to hand a processed payload to the events pipeline.

stepFunction:
  functionName: emit_event
  parameters:
    event:
      eventType: employee.updated
      eventId: $.steps.transform.output.data.id
      eventDate: $.steps.transform.output.data.updated_at
      data: $.steps.transform.output.data

Parameter	Type	Description
`event.eventType`	string	Event type name (required)
`event.eventId`	string	Unique event identifier (optional)
`event.eventDate`	string	Event timestamp (optional)
`event.data`	any	Normalized event payload (optional)

`browser_use`

Impact: ⚙️ Runtime Drive a headless browser agent for providers without a usable API. Any action containing a browser_use step must declare executionMode: async — it is dispatched to the Temporal workflow runtime rather than run inline. The runtime user instruction is supplied by the caller and merged with the action’s systemPrompt.

- actionId: submit_form
  executionMode: async
  steps:
    - stepId: run_browser
      description: Complete the form in a browser session
      stepFunction:
        functionName: browser_use
        parameters:
          startUrl: 'https://app.provider.com/login'
          systemPrompt: |
            Log in with the provided credentials, then submit the onboarding form.
          budgets:
            maxDurationMs: 120000
            maxSteps: 40
          auth:
            sensitiveKeys:
              - x_username
              - x_password

Parameter	Type	Description
`startUrl`	string (URL)	Page where the browser session starts (required)
`budgets`	object	Required `maxDurationMs` and `maxSteps` limits
`systemPrompt`	string	Author-defined preamble/guardrails merged with the caller’s instruction (optional)
`viewport`	object	`width`/`height` (optional)
`locale`	string	Browser locale (optional)
`auth.sensitiveKeys`	array	Credential keys substituted into the page and masked from the LLM (optional)
`auth.allowedDomains`	array	Override the allowed-domains policy for SSO flows crossing domains (optional)

`sign_jwt`

Impact: ⚙️ Runtime Create a signed JWT (e.g. for providers using JWT-bearer auth or service-account assertions). The signed token becomes available as the step output for use in a subsequent request.

stepFunction:
  functionName: sign_jwt
  parameters:
    algorithm: RS256
    privateKey: $.credentials.privateKey
    claims:
      iss: $.credentials.clientId
      scope: 'https://www.googleapis.com/auth/admin'

Parameter	Type	Description
`algorithm`	enum	Signing algorithm — `RS256`
`privateKey`	string	PEM private key used to sign (typically from credentials)
`claims`	object	JWT claims (string or number values) — e.g. `iss`, `scope`, `aud`, `exp`

Iterator Steps

Impact: ⚙️ Runtime Iterator steps (foreach) execute step function(s) for each item in an array. Define by adding the iterator property to a step.

- stepId: get_employee_details
  description: Fetch detailed data for each employee
  iterator: $.steps.list_employees.output.data.employees[*].id
  stepFunction:
    functionName: request
    parameters:
      url: /employees/${iterator.item}
      method: get

Property	Type	Description
`iterator`	JSONPath	Expression that evaluates to an array
`stepFunction`	object	Single function to execute per item
`stepFunctions`	array	Multiple functions to execute per item (mutually exclusive with `stepFunction`)

Iterator context variables

Inside an iterator step, these additional variables are available:

Variable	Description
`$.iterator.item`	Current array element
`$.iterator.index`	Current iteration index (0-based)
`$.iterator.current`	Output from previous step function in `stepFunctions` sequence
`${iterator.item}`	String interpolation of current item (for URLs)

Multiple step functions per iteration:

- stepId: enrich_employees
  iterator: $.steps.list.output.data[*].id
  stepFunctions:
    - functionName: request
      parameters:
        url: /employees/${iterator.item}/details
        method: get
    - functionName: request
      parameters:
        url: /employees/${iterator.item}/compensation
        method: get

Each iteration collects the final step function output. All iteration results are combined into $.steps.{stepId}.output.data as an array.

​steps

​Step Properties

​Conditional Steps

​Step Functions

​request

​Args Location (in)

​paginated_request

​iterator

​response

​map_fields

​group_data

​typecast

​soap_request

​static_values

​code_execution_lambda

​Invocation Types

​Output

​soap_paginated_request

​upload_file

​upload_binary

​download_file

​emit_event

​browser_use

​sign_jwt

​Iterator Steps

`steps`

Step Properties

Conditional Steps

Step Functions

`request`

Args Location (`in`)

`paginated_request`

`iterator`

`response`

`map_fields`

`group_data`

`typecast`

`soap_request`

`static_values`

`code_execution_lambda`

Invocation Types

Output

`soap_paginated_request`

`upload_file`

`upload_binary`

`download_file`

`emit_event`

`browser_use`

`sign_jwt`

Iterator Steps