runr_workflow (Resource)

One durable workflow definition declared through the API (workflows): its triggers, retries, timeout, concurrency limits, idempotency key and cancel events. The function's code implements the workflow under this name; the definition says when and how it runs.

The resource declares this one definition (PUT /api/projects/{project}/workflows/{workflow}); destroying it archives the workflow (DELETE …/workflows/{workflow}). The project's other definitions are not sent and stay as they are, their source too: what the function's SDK reported stays sdk. (An API before 0.6.0 has only the set: the resource declares the set again with this definition added, replaced or left out.) Definitions the function's SDK reports (source sdk) belong to the code and are refused. triggers left out keeps the definition's triggers — for example those of runr_workflow_trigger; set, it is the whole list (do not combine both for one workflow). Pausing (active = false) survives later declarations and syncs. Runs, events and the signing key are not configuration. Needs workflows.manage.

Import with <project name or id>/<workflow> or <project name or id>/<environment>/<workflow>.

Example Usage#

# process-order, implemented by the project's code, declared through the API.
resource "runr_workflow" "process_order" {
  project_id  = runr_project.orders.id
  name        = "process-order"
  description = "Charge, reserve stock and ship an order"
  triggers = [
    { event = "order.created", condition = "event.data.total > 0" },
    { queue = "orders" },
  ]
  retries     = 5
  timeout     = "1d"
  concurrency = [{ limit = 1, key = "event.data.customer_id" }]
  idempotency = "event.data.order_id"
  cancel_on   = [{ event = "order.cancelled", expression = "event.data.order_id == async.data.order_id" }]
}

# The nightly report of the staging environment, paused for now.
resource "runr_workflow" "nightly_staging" {
  project_id  = runr_project.orders.id
  environment = "staging"
  name        = "nightly-report"
  triggers    = [{ cron = "0 3 * * *", timezone = "Europe/Istanbul" }]
  active      = false
}

# Triggers left out of runr_workflow can come from runr_workflow_trigger.
resource "runr_workflow" "refunds" {
  project_id = runr_project.orders.id
  name       = "refund"
}

resource "runr_workflow_trigger" "refund_requested" {
  project_id = runr_project.orders.id
  workflow   = runr_workflow.refunds.name
  event      = "refund.requested"
}

Schema#

Required#

• name (String) Workflow name, as the function's code knows it (not app or sync).
• project_id (String) Project id.

Optional#

• active (Boolean) false pauses the workflow: triggers and the API start no runs; runs in progress go on. Left out: a new workflow is active, an existing one keeps its state (e.g. paused with runr workflows disable).
• cancel_on (Attributes List) Events that cancel matching active runs (at most 10). (see below for nested schema)
• concurrency (Attributes List) At most two concurrency limits, at most one of them keyed. (see below for nested schema)
• description (String) Description.
• environment (String) The project environment whose workflows these are (name or id; environments). Left out: the project's own workload (production).
• idempotency (String) Expression of the idempotency key: a second event with the same key starts no run, e.g. event.data.order_id.
• retries (Number) Retries of a failed step (0–20). Left out: a new workflow gets the installation's default (3), an existing one keeps its value.
• timeout (String) Longest a run may take, e.g. 1d (500ms, 30s, 15m, 2h, 1d, 1w, combinations, ISO 8601). Left out: no limit of the workflow's own.
• triggers (Attributes List) What starts a run: each an event (with an optional condition), a cron schedule (with an optional timezone) or a queue stream. Left out: the definition keeps the triggers it has (none for a new workflow), e.g. those runr_workflow_trigger adds. Set: exactly these ([]: none). (see below for nested schema)

Read-Only#

• id (String) <project_id>/<name>, or <project_id>/<environment>/<name> for an environment's workflow.

Nested Schema for cancel_on#

Required:

• event (String) Event name, e.g. order.cancelled.

Optional:

• expression (String) Expression the event must satisfy to cancel a run (async is the run's own event), e.g. event.data.order_id == async.data.order_id. Left out: every active run.

Nested Schema for concurrency#

Required:

• limit (Number) Runs at the same time (1–1000).

Optional:

• key (String) Expression the limit counts per value of, e.g. event.data.customer_id.

Nested Schema for triggers#

Optional:

• condition (String) Expression the event must satisfy (if), e.g. event.data.total > 100; event and queue triggers.
• cron (String) Five-field cron expression; one run per due minute.
• event (String) Event name, e.g. order.created.
• queue (String) Redis stream of the project's queue bridge; each message starts a run.
• timezone (String) IANA time zone of cron (default UTC).

Import#

Import is supported using the following syntax:

The terraform import command can be used, for example:

# <project name or id>/<workflow> (the project's own workload)
terraform import runr_workflow.process_order orders-api/process-order

# <project name or id>/<environment>/<workflow>
terraform import runr_workflow.nightly_staging orders-api/staging/nightly-report