Help › Guide

Arazzo workflows

Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.

Arazzo is the OpenAPI Initiative's format for workflows over APIs: steps that call operations of OpenAPI (and AsyncAPI) descriptions, with inputs, outputs, criteria and actions. In Reqlyn an operation's source of truth is an Arazzo 1.1 document. Reqlyn compiles it to the operation it runs, so the desktop, the command line, the server, routes and MCP tools all run what the document says.

Working with documents

Command Does
reqlyn arazzo check <file> Reads an Arazzo 1.0 or 1.1 document, in YAML or JSON, and says what is wrong with it, each problem at its place. Runs nothing.
reqlyn arazzo compile <file> [--workflow <id>] Prints the operation and requests Reqlyn would run. What Reqlyn cannot run is named at its place, and it ends with 1.
reqlyn arazzo run <file> [--workflow <id>] --input <json> Compiles and runs the workflow on this computer, with the chosen environment's variables. Stores nothing.
reqlyn arazzo save <file> Compiles the document and stores it as a new operation, its source the document and its descriptions. A <name>.cases.yaml beside it is kept as its regression cases.
reqlyn arazzo export <operation> [--out <folder>] Writes a stored operation as an Arazzo document, an OpenAPI description for each origin it calls, an AsyncAPI description for each server it sends or hears messages on, and its cases. A file already there is not overwritten.

In the desktop, every saved operation has an "Arazzo source" part that shows its document and descriptions as last saved. Edit them and press "Save source": the operation becomes what the source compiles to, or, if it does not compile, nothing is saved and each problem is shown at its place.

Where descriptions come from

A document's sourceDescriptions are read from files beside it, by their url (./inventory.openapi.yaml). Nothing is fetched from an address. Another Arazzo document can be a source too, and its workflows are called as the document's own.

Servers, variables and credentials

A step's request goes to its description's server. A server written with a variable, such as url: "{inventory}", becomes the variable {{inventory}}, filled from the environment the workflow runs in: on this computer, the Variables tab of the chosen environment; on a server, the environment the version is activated in. On this computer, a server variable that no variable of that name sets takes the description's default (an empty one is no default), in a run as in a write preview's reads first and an undo, and --var <name>=<value> on reqlyn run or reqlyn arazzo run sets one for that run over both. A server never takes a default: an environment binds what a version names, and activation checks it.

An OpenAPI operation names the credential it is sent with by x-reqlyn-credential: <name>: a credential of that name under Connections on this computer, or bound in the environment on a server. A secret never goes in the document, and a credential header written as a literal is refused. A document run from a file never uses a secret variable.

An example

The fixtures' inventory and compliance APIs, with descriptions in fixtures/arazzo/:

arazzo: 1.1.0
info: { title: Device overview, version: 1.0.0 }
sourceDescriptions:
  - { name: inventory, type: openapi, url: ./inventory.openapi.yaml }
  - { name: compliance, type: openapi, url: ./compliance.openapi.yaml }
workflows:
  - workflowId: deviceOverview
    inputs:
      type: object
      required: [deviceId]
      properties:
        deviceId: { type: integer }
    steps:
      - stepId: device
        operationId: $sourceDescriptions.inventory.getDevice
        parameters:
          - { name: deviceId, in: path, value: $inputs.deviceId }
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          id: $response.body#/id
          hostname: $response.body#/hostname
      - stepId: compliance
        operationPath: '{$sourceDescriptions.compliance.url}#/paths/~1compliance~1devices~1{id}~1status/get'
        parameters:
          - { name: id, in: path, value: $steps.device.outputs.id }
        outputs:
          compliant: $response.body#/compliant
    outputs:
      hostname: $steps.device.outputs.hostname
      compliant: $steps.compliance.outputs.compliant

Each output is typed by what the description documents at that place, and the workflow's outputs become the operation's output contract. The tutorial Arazzo workflows runs it step by step.

What Reqlyn runs

Every construct of Arazzo 1.0 and 1.1 is read, kept when the document is written back, and checked. Compiling takes everything below; anything else is refused at its path, never silently left out.

Steps and their requests

  • A step's operation by operationId (plain, or $sourceDescriptions.<name>.<id>) or by an operationPath pointer.
  • Parameters in the path, query and header: literals, $inputs.<name>, $steps.<id>.outputs.<name>, and {$…} inside text. A workflow's own parameters, and parameters from the components by reference.
  • Request bodies: a JSON payload with expressions (typed by the input or the description), replacements put at their targets, a JSON payload written as text with {$expression}s in it, a form, a multipart body (a file part filled by a file input, an input of type: string, format: binary), or text.
  • timeout up to 30,000 milliseconds, and dependsOn.
  • Inputs: an object schema of strings, integers, numbers, booleans and files.

Outputs and selectors

  • A step's outputs from $response.body#/<pointer>, $response.header.<name> and $message.payload and $message.header.<name> for a message.
  • Selector objects of type jsonpointer and jsonpath (RFC 9535) in a step's outputs, a parameter's value, a payload's values and a workflow's outputs. A JSONPath query that selects one value gives the first it selects; a list output gives each.
  • Selector objects of type xpath, with XPath 3.1, over an XML response. The step keeps its response as XML; each selector gives text, or a list when it selects several. A document type or entity in the XML is refused, and XPath reads no file or network.

Criteria

successCriteria, and an action's criteria, as:

  • simple conditions: &&, ||, !, parentheses, ==, !=, <, <=, >, >=, over $statusCode, $method, $url, $response.header.<name>, $response.body and pointers into it, $request.header, .query, .path and .body (what the step itself writes), $inputs.<name> and $steps.<id>.outputs.<name>, each followed by [<index>] or .<name>;
  • regex criteria on a context, matched in linear time;
  • jsonpath criteria, holding when the query selects something;
  • xpath criteria, holding by XPath's effective boolean value.

Nothing is converted to compare. A criterion that looks at the status decides the step's success whatever the status. A criterion has at most 64 parts, 8 deep.

Actions

onSuccess and onFailure actions, the workflow's successActions and failureActions after the step's own, and actions from the components:

  • end, anywhere;
  • goto a step, earlier or later, or a workflow with its parameters;
  • retry with retryAfter (up to 300 seconds), retryLimit (up to 10) and a stepId or workflowId taken first.

The first action whose criteria hold is taken; a retry that is spent is passed over. A request that writes is never retried. A run that loops is bounded by its limits and by 1,000 steps taken.

Workflows calling workflows

  • A step with workflowId runs that workflow's steps in its place, named <step>.<its step>, its inputs given by the step's parameters. Its outputs are the step's.
  • dependsOn another workflow runs that workflow first, once; $workflows.<id>.outputs.<name> reads its outputs.
  • A workflow of another Arazzo document is $sourceDescriptions.<name>.<workflowId>.
  • A workflow that would run itself, or calls more than 8 deep, is refused.

Messages: AsyncAPI steps

An AsyncAPI 2.6 or 3.0 description can be a source. A step that names an AsyncAPI operation (by operationId or operationPath) or a channel (channelPath) sends or receives a message instead of making an HTTP request, with action and, for a receive, correlationId. Its outputs and criteria read $message.payload and $message.header.<name>.

Protocol Server's protocol Address Sends Receives
WebSocket ws, wss the channel's address a text message a message heard on the same socket
Server-sent events sse, sses the channel's address — an event of the stream
HTTP bindings http, https the channel's address a request with the payload as its body a request whose answer is the message
Kafka kafka, kafka-secure kafka://<broker>/<topic> a record to the topic's first partition, keyed by the step's header key, which is not sent as a header; not compressed a record of any partition since the run began, its key as the header key, compressed or not (gzip, snappy, zstd, lz4)
MQTT mqtt, secure-mqtt mqtt://<broker>/<topic>, mqtts:// over TLS published at QoS 1, or the QoS and retain the operation's bindings.mqtt says subscribed before the run's first step, at that QoS
AMQP 0-9-1 amqp, amqps amqp://<broker>/<queue or routing key>, with exchange and vhost from the channel's binding to a queue, or a routing key on an exchange from a queue, or a queue of the run's own bound to the exchange; a named queue has to be on the broker, and one that is not is refused by its name, Reqlyn making none
AMQP 1.0 amqp1, amqp1s amqp1://<broker>/<address> by a sender, its headers as application properties by a receiver; its headers are the application properties, the standard properties (message_id, correlation_id, subject, to, reply_to, content_type, group_id) and the message annotations

A channel a step receives on is listened to from the run's start when the inputs alone fill its address, so a message sent in answer to an earlier step is not missed. A receive takes the first message, heard since the run began, that its correlation id names, within the step's timeout; at most 1,000 messages are kept for a channel until a step takes one. Channels stay open until the run ends.

On a server or a private agent, a message step is held to the allowed destinations as a request is: a WebSocket by its HTTP counterpart's origin (http://host:port for ws://host:port), a broker by its own (kafka://host:port), and each to the addresses the guard allows. WebSocket, AMQP and MQTT steps go through the proxy or the SSH bastion set under Connections, by their tunnel, and server-sent events and HTTP bindings as any request does. Kafka steps go through the proxy or the bastion, by a bridge of Reqlyn's own on this computer, which through the bastion opens only the first broker's port. An AsyncAPI server names the credential it is reached with by x-reqlyn-credential. Kafka takes a basic credential as SASL PLAIN; AMQP 1.0 takes it as SASL PLAIN, and ANONYMOUS without one. TLS is the transport's own, with the same certificate authorities as any request; MQTT's is the platform's TLS (OpenSSL on Linux), and AMQP 0-9-1's is its client's own; both trust the platform's authorities and those added under Connections. A server's x-reqlyn-client-certificate, in a source this computer keeps, names the client certificate they present; its key has to be PKCS#8.

A broker is an origin a server must be allowed to reach, such as kafka://broker:9092 in REQLYN_ALLOWED_DESTINATIONS.

An MQTT server whose protocolVersion is 5 (or 5.0) is spoken in MQTT 5: a send's headers go as user properties, content-type as the message's content type, and a message heard has its user properties and content type as headers, so a correlation id or an output may be read from one. Otherwise MQTT 3.1.1, which carries no headers.

A Kafka server's credential is named by x-reqlyn-credential on the server. A basic credential signs in by SASL PLAIN, or by SCRAM-SHA-256 or SCRAM-SHA-512 when the server's security names a scheme of type scramSha256 or scramSha512; a bearer token, or an OAuth client's token, signs in by OAUTHBEARER.

Reqlyn's own fields

Where Arazzo has no word for what a step does, Reqlyn writes an x-reqlyn-* field:

Field On Means
x-reqlyn-when a step The step's condition: it runs only when its comparisons hold
x-reqlyn-policy a step Optional, retries, when a success is an error, waiting for a value (until), a callback
x-reqlyn-each a step Repeat the step for each item of a list
x-reqlyn-pages a step Read a paged list to its end
x-reqlyn-join a step Join two steps' results on a key
x-reqlyn-bare a step Places in a payload where a carried value is written as it is, not quoted
x-reqlyn-undo a step The request that undoes the step, sent only when a person asks
x-reqlyn-before, x-reqlyn-at a step The request that reads what the step writes to, for a write preview, and where the record is in its answer
x-reqlyn-environment a step Variables of this computer the step's request names outside its origin
x-reqlyn-place a step Where its block was put on the canvas, { x, y } in the canvas's pixels; none, in the row. Only drawing reads it. An older Reqlyn says it does not know it
x-reqlyn-script a step Its JavaScript: before its request is sent, after its response, and the names the after script sets, which later steps' requests hold as {{name}}. Not on a message step. Runs on the desktop, the command line, a server and a private agent
x-reqlyn-action a failure action A plain retry of the step that is an action of its own, taken on any failure, and not the step's retries (which a first plain retry is otherwise read as)
x-reqlyn-owner, x-reqlyn-list-outputs a workflow Its owner; which outputs are lists
x-reqlyn-credential an OpenAPI operation, an AsyncAPI server The credential's name
x-reqlyn-client-certificate an OpenAPI operation, an AsyncAPI server A client certificate's name, used only by a source this computer keeps; a server refuses it

How a version is hosted (limits, fields never kept, reading only, keeping bodies, routes) is not in the document: it belongs to the deployment manifest.

Not run yet

  • An XPath selector over an earlier step's output, or over a pointer into a body: an XML step's outputs are text, not XML.
  • gRPC: it is not an Arazzo source. An operation's step calls it, streams included, from a saved request (Requests).

Help for Reqlyn 0.5.1. All help topics