Argyll logo Argyll

Steps

A Step declares one unit of work, the Attributes it consumes, and the Attributes it produces.

Choose a Type

TypeUse
ServiceAn HTTP service does the work
ScriptA small Lua transformation runs inside the engine
FlowA reusable set of Goals runs as a child Flow

See HTTP Steps for the invocation contract and Async Steps for callbacks.

Connect Steps with Attributes

Matching Attribute names connect producers and consumers. This definition makes customer available to every planned Step that consumes it:

{
  "id": "load-customer",
  "type": "service",
  "attributes": {
    "customer_id": {"role": "required", "type": "string"},
    "customer": {"role": "output", "type": "object"}
  },
  "http": {
    "invoke": {
      "method": "GET",
      "endpoint": "https://api.example.com/customers/{customer_id}"
    }
  }
}

Attributes covers roles, collection, defaults, deadlines, mapping, and fan-out.

Run Inline Lua

Script inputs are available as variables. Return a table keyed by output Attribute name:

{
  "id": "format-name",
  "type": "script",
  "attributes": {
    "first_name": {"role": "required", "type": "string"},
    "last_name": {"role": "required", "type": "string"},
    "display_name": {"role": "output", "type": "string"}
  },
  "script": {
    "language": "lua",
    "script": "return {display_name = first_name .. ' ' .. last_name}"
  }
}

Argyll embeds Lua with the io, os, and debug modules excluded. Keep larger domain operations in the service that owns them so they retain that service’s tests, deployment lifecycle, and telemetry.

Tag a Step

Tags are metadata carried alongside a Step definition, held as a set of opaque strings. A prefix:value shape is a convention you may adopt, and a Step carries as many tags as it needs. A Step also carries an optional description, which is prose for people rather than something selectors match on:

{
  "id": "score-customer",
  "type": "service",
  "description": "score a customer for risk",
  "tags": ["domain:risk", "domain:payments", "tier:gold", "example"]
}

Tags leave planning untouched and drive grouping instead: a Space can use them alongside stable Step metadata to decide which Steps it holds. Both SDKs set them with WithTags/with_tags, each call merging into the set, and the Go generator accepts a //argyll:tags directive. The description has its own WithDescription/with_description and a //argyll:description directive.

Lifecycle

A planned Step starts as pending, becomes active when its inputs are ready, and finishes as completed, failed, or skipped. A false Predicate or an unsatisfied required match produces skipped; Argyll then releases upstream work whose remaining consumers are already satisfied.

Service Steps choose standard, memoized, or compensated handling. See Memoization and Compensation.

Next Spaces