Copy page

Build & Test

USSD DSL Action Chains

Action chains let you execute multiple actions in sequence before navigating to the next menu. They are defined inline on menu options or transitions using the actions array.

Action Chain Syntax

Code
menu "PaymentMenu" {
  text = "Enter amount to pay:"

  option "*" {
    label = "Amount"
    goto  = "ConfirmPayment"
    actions = [
      {
        name   = "normalize-amount"
        type   = "string"
        op     = "trim"
        inputs = ["{{session.input}}"]
        target = "amount"
      },
      {
        name   = "validate-amount"
        type   = "validate"
        source = "amount"
        min    = 1
        max    = 5000
      }
    ]
    error_target  = "InvalidAmount"
    transactional = true
  }
}

Chain Fields

Field	Required	Description
actions	Yes	Ordered list of inline action objects (minimum 1, maximum 10).
error_target	No	Menu/block to route to when any action fails.
transactional	No	When true, variable changes are rolled back on failure (default: true).

Inline Action Objects

Each entry in actions is an inline action definition with a type plus type-specific fields.

Code
{
  name   = "fetch-balance"
  type   = "http"
  method = "GET"
  url    = "https://api.example.com/balance/{{session.msisdn}}"
  target = "balance_response"
}

Field	Required	Description
name	No	Action name used for tracing (auto-generated when omitted).
type	Yes	Action type (arithmetic, env, set, inc, dec, delete, conditional, http, grpc, string, validate, crypto, noop).
next	No	Menu/block to navigate to after the action completes successfully.
on_error	No	Error handling configuration (see below).
target	No	Target variable for actions that return a value (type-dependent).

Validation Contract Shape

The flow validation API expects each action to be represented as:

Code
{
  "type": "http",
  "params": {
    "client": "default",
    "method": "GET",
    "url": "https://api.example.com/balance/{{session.msisdn}}"
  }
}

When documenting or validating flows, note that the API contract uses params and camelCase fields (for example, responseMap and timeoutSeconds) while the DSL uses inline fields like response_map and timeout.

Error Handling

Inline actions can specify on_error for per-action handling. When absent, the chain-level error_target applies.

Code
{
  name = "fetch-profile"
  type = "http"
  method = "GET"
  url = "https://api.example.com/profile/{{session.msisdn}}"
  on_error = {
    mode = "fallbackValue"
    value = "unknown"
  }
  target = "profile"
}

Field	Required	Description
mode	Yes	Error mode: fail-fast, fallbackAction, or fallbackValue.
next	No	Menu/block to route to for fallbackAction.
value	No	Fallback value for fallbackValue.

Operands and Variables

Many actions accept operands that can be literal values or variable references. Variable references support both {{variable}} and $variable forms.

Code
{
  name = "fee-adjustment"
  type = "arithmetic"
  operator = "subtract"
  left = "{{balance}}"
  right = 50
  target = "net_balance"
}

OpenAPI Contract Reference

The validation contract for action chains and extended actions is defined in specs/005-dsl-extended-actions/contracts/dsl-actions.openapi.yaml.