Help › Tutorials

Tutorial 2: Arazzo workflows

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

In Reqlyn an operation's source is an Arazzo document: a workflow of steps over OpenAPI (and AsyncAPI) descriptions. This tutorial works with documents directly, from the command line. You will check, compile and run a workflow; add success criteria and a retry action; let a step be optional; run a WebSocket message workflow; then store the document as an operation, keep a case, and export it.

Every command below was run against the fixtures as written. It takes about twenty minutes.

Before you start

  • The fixture APIs are running (cargo run -p reqlyn-fixtures).
  • You have done tutorial 1, or at least step 1 of it: the variable inventory set to http://127.0.0.1:8787.
  • Copy the repository's fixtures/arazzo/ folder somewhere to work in, and open a terminal there. It holds device-overview.arazzo.yaml, inventory.openapi.yaml and compliance.openapi.yaml.

1. Export what you built

If you did tutorial 1, see it as Arazzo first:

reqlyn arazzo export "Device overview" --out exported

writes device-overview.arazzo.yaml, an OpenAPI description of the inventory as the workflow uses it, and device-overview.cases.yaml with the case you kept. Open the document: each step names an operationId, its parameters say where each value comes from ($inputs.deviceId, $steps.device.outputs.id), and the optional step is written as x-reqlyn-policy: { optional: true }.

2. Check, compile and run a document

reqlyn arazzo check device-overview.arazzo.yaml
Valid, and each of its 1 workflow(s) compiles. Nothing was run.

check reads the document and its descriptions and says what is wrong, at its place. compile prints what Reqlyn would run, the requests and the operation, still sending nothing:

reqlyn arazzo compile device-overview.arazzo.yaml

Note that the compliance request goes to {{compliance}}: the description's server is written url: "{compliance}", and a server variable becomes a variable of the environment. You did not set compliance, so it takes the description's default, http://127.0.0.1:8787. A variable set in the environment is taken over the default, and --var compliance=… on the command line over both, for that run.

Now run it:

reqlyn arazzo run device-overview.arazzo.yaml --input '{"deviceId": 4831}'
{
  "compliant": false,
  "findings": 2,
  "hostname": "pe01.pitb02-pa",
  "noted": "POST",
  "role": "PE"
}

Each output's type comes from what the description documents at that place.

3. Criteria and a retry

Make a copy, device-check.arazzo.yaml, to change. First a description for one more endpoint. The fixtures' /flaky/{key} answers 503 twice for each key, and then 200 with how many requests it took. Save this as health.openapi.yaml:

openapi: 3.1.0
info: { title: Health (fixture), version: "1" }
servers:
  - url: "{inventory}"
paths:
  /flaky/{key}:
    get:
      operationId: getHealth
      parameters:
        - { name: key, in: path, required: true, schema: { type: string } }
      responses:
        "200":
          description: Up, and how many requests it took
          content:
            application/json:
              schema:
                type: object
                properties:
                  attempt: { type: integer }
        "503":
          description: Not up yet

Then write device-check.arazzo.yaml:

arazzo: 1.1.0
info: { title: Device check, version: 1.0.0 }
sourceDescriptions:
  - { name: inventory, type: openapi, url: ./inventory.openapi.yaml }
  - { name: compliance, type: openapi, url: ./compliance.openapi.yaml }
  - { name: health, type: openapi, url: ./health.openapi.yaml }
workflows:
  - workflowId: deviceCheck
    summary: Device check
    inputs:
      type: object
      required: [deviceId, check]
      properties:
        deviceId: { type: integer }
        check: { type: string }
    steps:
      - stepId: health
        operationId: $sourceDescriptions.health.getHealth
        parameters:
          - { name: key, in: path, value: $inputs.check }
        successCriteria:
          - condition: $statusCode == 200
        onFailure:
          - name: notUpYet
            type: retry
            retryAfter: 1
            retryLimit: 3
            criteria:
              - condition: $statusCode == 503
        outputs:
          attempt: $response.body#/attempt
      - stepId: device
        operationId: $sourceDescriptions.inventory.getDevice
        parameters:
          - { name: deviceId, in: path, value: $inputs.deviceId }
        successCriteria:
          - condition: $statusCode == 200
          - context: $response.body#/hostname
            condition: '^[a-z]+[0-9]+\.'
            type: regex
        outputs:
          id: $response.body#/id
          hostname: $response.body#/hostname
          role: $response.body#/role
      - stepId: compliance
        operationId: $sourceDescriptions.compliance.getComplianceStatus
        parameters:
          - { name: id, in: path, value: $steps.device.outputs.id }
        successCriteria:
          - condition: $statusCode == 200
        outputs:
          compliant: $response.body#/compliant
          findings: $response.body#/findings
    outputs:
      attempts: $steps.health.outputs.attempt
      hostname: $steps.device.outputs.hostname
      role: $steps.device.outputs.role
      compliant: $steps.compliance.outputs.compliant
      findings: $steps.compliance.outputs.findings
  • The health step's onFailure action retries it a second later when the answer is 503, at most three times.
  • The device step's criteria hold only for a 200 whose host name matches the regular expression.

Run it with a check key the fixture has not seen:

reqlyn arazzo run device-check.arazzo.yaml --input '{"deviceId": 4831, "check": "first"}'

It takes about two seconds, and gives "attempts": 3 beside the device: two 503s, each retried after a second, then the answer. Run it again with the same key and it is 4, with no retry. (A retry is never made of a request that writes.)

4. An optional step

Device 4840 is not known to the compliance API:

reqlyn arazzo run device-check.arazzo.yaml --input '{"deviceId": 4840, "check": "second"}'
Step "compliance": the server answered 404, which is not success, so there is no output.

To have the host name anyway, let the run go on without the step. Add to the compliance step:

        x-reqlyn-policy:
          optional: true

and run again. Reqlyn now refuses to compile it:

workflows[0]: The output field "compliant" comes from the step "compliance", which the run may go on without, so it has to allow null.

An output takes its type from the description, and the description says compliant is always a boolean. In your copy of compliance.openapi.yaml, allow null for the two fields:

                  compliant: { type: [boolean, "null"] }
                  findings: { type: [integer, "null"] }

Now 4840 gives its host name and role, "compliant": null and "findings": null, says it went on without the compliance step, and ends with 3: a partial result.

5. A message over a WebSocket

A step can send or receive a message on a channel of an AsyncAPI description instead of making an HTTP request. The fixtures echo on a WebSocket at ws://127.0.0.1:8793: they greet a new connection with {"connected": …} and answer each message with {"echo": "<what was said>"}. Save echo.asyncapi.yaml:

asyncapi: 3.0.0
info: { title: Fixture echo, version: "1" }
servers:
  echo: { host: 127.0.0.1:8793, protocol: ws }
channels:
  echo:
    address: /
    servers: [{ $ref: "#/servers/echo" }]
    messages:
      said:
        payload:
          type: object
          properties:
            echo: { type: string }
            connected: { type: boolean }
operations:
  say: { action: receive, channel: { $ref: "#/channels/echo" } }
  hear: { action: send, channel: { $ref: "#/channels/echo" } }

An AsyncAPI operation is written from the application's side: the echo receives what the workflow says, and sends what the workflow hears. Then echo.arazzo.yaml:

arazzo: 1.1.0
info: { title: Echo, version: 1.0.0 }
sourceDescriptions:
  - { name: echo, type: asyncapi, url: ./echo.asyncapi.yaml }
workflows:
  - workflowId: echo
    inputs:
      type: object
      required: [line]
      properties:
        line: { type: string }
    steps:
      - stepId: greeted
        operationId: $sourceDescriptions.echo.hear
        successCriteria:
          - condition: $message.payload#/connected == true
      - stepId: say
        operationId: $sourceDescriptions.echo.say
        requestBody:
          contentType: application/json
          payload:
            said: $inputs.line
      - stepId: echoed
        operationId: $sourceDescriptions.echo.hear
        timeout: 5000
        outputs:
          echo: $message.payload#/echo
    outputs:
      echo: $steps.echoed.outputs.echo
reqlyn arazzo run echo.arazzo.yaml --input '{"line": "hello from Reqlyn"}'
{
  "echo": "{\n  \"said\": \"hello from Reqlyn\"\n}"
}

The channel is listened to from the run's start, so the greeting is not missed; it stays open until the run ends. Kafka, MQTT and AMQP channels are written the same way, with their own servers: see Arazzo workflows.

6. Store it, keep a case, export it

reqlyn arazzo save device-check.arazzo.yaml
reqlyn list
reqlyn run "Device check" --input '{"deviceId": 4832, "check": "third"}' --keep-case pe02
reqlyn test "Device check"
reqlyn arazzo export "Device check" --out check-export
  • save compiles the document and stores it as an operation whose source is the document and its descriptions. It shows in the desktop's Operations too, with its source in the Arazzo source part.
  • run --keep-case runs it and keeps the run as the case pe02; test replays it with nothing sent: 1 of 1 cases hold.
  • export writes it back: the document, its descriptions and device-check.cases.yaml. That folder is what you keep in a repository, and what tutorial 4 checks in CI.

What you did

  • check, compile and run worked on a document with nothing stored.
  • Success criteria (a status and a regular expression) and a retry action shaped what counts as success and what happens after a failure.
  • An optional step needed its outputs to allow null, which the description says.
  • A workflow sent and heard messages on a WebSocket channel.
  • A document became a stored operation with a case, and was exported for version control.

Everything Reqlyn runs of Arazzo, and what it does not run yet, is in the guide.

Help for Reqlyn 0.5.1. All help topics