External Tasks

A reusable contract, independent occurrences

The model distinguishes the Definitiondefinition, which gives a stable identity to a class of work, its revision, which freezes the typed contract, and theoccurrence occurrence created when a process instance reaches the node.

A Definition such as add_company_to_crm may be shared by several processes. Each process nevertheless pins an exact revision: moving Working or publishing a new Release never reinterprets an occurrence already recorded.

Define a task class

In the Console, an External Task Definition carries a stable key, name, input contract, output contract, and optional routing output. Like other versioned artifacts, its snapshots are immutable and can be published as Releases. See Versions, Releases, and deployment for the shared lifecycle and retention.

The contract uses Ormuz types. A new revision can therefore add or modify fields without retroactively changing processes using an older revision. Several incompatible revisions can coexist during a migration.

Use an External Task in a process

The node selects a Definition and revision and maps its inputs like any other typed node. The Console exposes revision outputs as sources available to downstream nodes.

Two nodes use this contract: external_task_pull delegates durable work to an authorized consumer, while external_task_push calls an API Destination and receives the result in its response. Their execution policies differ and are frozen on each occurrence.

For general typing and source-availability rules, see Inputs, outputs, and bindings.

Choose between Pull and Push

With Pull, the external service claims an available occurrence, handles it, then submits a result or failure. This suits long-running work. Its policy sets maximum attempts, the delay before another attempt, and an optional deadline.

With Push, the process selects an authorized API Destination as well as the Definition and its revision. Ormuz sends the contract inputs to the service and expects a typed synchronous response. The total budget defaults to 5 seconds and can be set up to 10 seconds; the destination may impose a shorter limit. A deferred response cannot complete this node.

A Pull reservation is temporary. If it expires before settlement, the same occurrence may become available again under its policy. Push has no automatic retry: failure or timeout follows the process error handling.

Stopping the instance cancels External Tasks that are still open. A late result cannot resurrect the process.

Typed outputs and derived routing

Without a routing output, continuation is linear. With a required Choice output, its values become node routes. For example, created and existing may lead to two different branches.

The external service returns business data; it never directly chooses the next node. Ormuz validates the result against the pinned revision and then derives the route.

Technical retry and business idempotency are different

Ormuz prevents the same logical node occurrence from being materialized multiple times. In Pull, reservation and settlement operations are replayable. In Push, the called service must handle the same task identifier idempotently: a lost response may leave an external effect already performed, even without automatic retry.

They do not merge two distinct business requests. If two processes each create an add_company_to_crm occurrence for the same company, both tasks exist. The external service remains responsible for business semantics: perform the action, return success without a new effect, or report a conflict according to its own contract.

The general guarantees are detailed in Errors, retries, and idempotency.

Access and protected data

A consumer accesses only task classes explicitly authorized to it. Inputs and outputs retain their normal, sensitive and secret classifications. Protected values remain masked in observability surfaces.

For a web application, do not place a broad integration key in the browser. Have an authorized backend carry the protocol, or use a server-side surface targeted to the relevant occurrence.

See Data protection for common classification and masking rules.

Observe tasks and attempts

The Console separates DefinitionsDefinitions, used to design contracts, from External Tasksoccurrences, used in operations. The Operations view filters occurrences by key, status, or Process Instance and lets you inspect their attempts.

From a Process Instance detail, an External Task node links to its occurrence. The detail shows inputs and outputs according to protection rules, current state, key dates, attempts, diagnostic consumer identifier, and any errors.

This surface is intentionally observational: it offers no generic button to fabricate a business completion. For the machine contract, see the API reference.