Flows

Overview

A flow is an automation: one or more triggers start it, and one or more actions run when it starts. Use flows to notify an endpoint when a new asset is discovered, to open a Jira or ServiceNow ticket every morning, or to let an external system start work in DeviceQuest through a signed webhook.

You need flows:read to open the page and flows:write to create, edit, run, activate or delete flows. A flow that contains a Run command action also needs flows:command.

Screen tour

Click to enlarge

Click a flow name to open its side sheet. When flows were added since your last visit, a line under the title says how many; click × to dismiss it.

Create a flow

The wizard has two steps.

Click to enlarge

1. Click New Flow (or press n).
2. Enter a Name, an optional Description, and set Active.
3. Click Next: Triggers & Actions →. If the name is empty, the wizard shows Name is required and stays on step 1.
4. Under Triggers, choose a trigger type and fill in its settings. Click + Add trigger to add more triggers; any of them starts the flow.
5. Under Actions, choose an action type and fill in its fields. Click + Add action to add more; the actions run in order.
6. Click Create flow. A confirmation appears and the flow is added to the top of the list.

Click to enlarge

To change a flow later, choose Edit definition from the More actions menu, or press e on a focused row. The wizard opens with the current values and the save button reads Save changes.

Triggers

Schedule presets

To use your own schedule, type a standard five-field cron expression (minute, hour, day of month, month, day of week) in Cron expression.

Actions

Create ticket

Saved connection lists the connectors you set up on the Integrations page, shown as “name · Jira” or “name · ServiceNow”. If the list is empty, add a connector there first (see Integrations).

Summary and Description accept event data in double braces:

• {{asset.name}}: the name of the asset in the event.
• {{event.type}}: the event type, for example NEW_ASSET.
• {{payload.custom_field.value}}: any value from the event payload, by its path.

For example, New asset: {{asset.name}} becomes New asset: web-01.

Run command

Commands run on the DeviceQuest server, so they need extra care:

• Saving a flow with a Run command action needs the flows:command permission in addition to flows:write.
• The server runs only commands on its allowlist (by default common read-only tools such as ls, cat, echo, grep, df, uptime and hostname). Your administrator enables command actions and manages the allowlist.
• When you click Run now on a flow with a command action, a Run flow dialog asks you to confirm: “This flow contains a command action that will execute on the server.” Click Run now to continue or Cancel to stop.

Webhook trigger

A Webhook trigger gives the flow its own inbound URL. Any system that knows the flow’s signing secret can start the flow by sending a signed HTTP POST to that URL.

Click to enlarge

Get the URL and secret

1. Create a flow with a Webhook trigger and click Create flow.
2. Without reloading the page, open the new flow from the list. Under Triggers, the Webhook card shows the URL and the Secret.
3. Click Copy next to Secret and store it in your secret manager now. For security, the secret is shown only once, when the flow is created, and cannot be retrieved later. Afterwards the card reads “Hidden for security.”

The inbound URL has this format:

https://<your-devicequest-host>/api/v1/flows/webhook/<webhook-id>

<webhook-id> is generated by DeviceQuest and looks like wh_a02ca7499c969a2f33512447.

Sign each request

Send the request body as JSON, and add the header X-DeviceQuest-Signature. Its value is the lowercase hex HMAC-SHA256 of the raw request body, keyed with the flow’s secret. There is no prefix such as sha256=.

Sign the exact bytes you send. If you pretty-print or re-encode the body after signing, the signature no longer matches.

Outbound webhooks from the Developer page use the same header but also sign the timestamp; see What each delivery contains.

WEBHOOK_URL="https://devicequest.example.com/api/v1/flows/webhook/wh_a02ca7499c969a2f33512447"
SECRET="paste-the-flow-secret-here"
BODY='{"source":"ci","asset":{"name":"web-01"},"build":"1842"}'

SIGNATURE=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.*= //')

curl --fail-with-body -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-DeviceQuest-Signature: $SIGNATURE" \
  --data-binary "$BODY"

A request that is accepted returns 200 with {"status":"ok"}, and the flow runs with the body as its trigger payload.

Verify a signature

To check a signature yourself, for example while testing a client, compute the HMAC of the saved body and compare it with the header value:

# body.json holds the exact bytes that were sent; RECEIVED holds the header value.
EXPECTED=$(openssl dgst -sha256 -hmac "$SECRET" -hex < body.json | sed 's/^.*= //')

if [ "$EXPECTED" = "$RECEIVED" ]; then
  echo "signature valid"
else
  echo "signature mismatch"
fi

Payload and responses

• A JSON object body becomes the trigger payload, so actions can use its fields, for example {{payload.build}}.
• A body that is not JSON is passed on as text in the _raw field of the payload.

Flow details and executions

Click a flow to open its side sheet. It has three parts.

Header

• The health chip of the last run, an Active or Inactive badge, and Last run with its age.
• Activate / Deactivate: turns the flow on or off.
• Run now: runs the flow immediately. The trigger payload is {"trigger":"manual"}.
• More actions: Edit definition and Delete flow.
• Last error: the start of the last error message, when the latest run failed.

Definition

• Triggers: one card per trigger, with its settings. Webhook triggers show the URL, Secret and Signature rows.
• Actions: one card per action, with its settings. Copy copies the action as JSON.

Recent executions

• The 20 most recent runs, newest first, with status, start time and duration.
• Click a run to expand it. You see the Error (when the run failed), the Trigger payload and the Execution result. Values such as tokens, secrets and passwords are masked as ••••••. Copy copies the JSON.

After Run now, a message “Flow run complete — view executions.” appears. Click View executions to open the flow’s side sheet.

Run, pause or delete a flow

• Run now: click the play button on the row, or Run now in the side sheet. Flows with a Run command action ask you to confirm first.
• Pause or resume: click the Status toggle on the row, or Deactivate / Activate in the side sheet. Paused flows ignore their triggers.
• Delete: choose Delete flow from More actions. The Delete flow dialog warns that all execution history for this flow is also deleted. Click Delete flow to confirm.

Statuses

Health chip

The chip is also marked as stale when an active flow’s last successful run is more than 30 days old.

Execution status

Keyboard shortcuts

Shortcuts work when the focus is not in a text field. Press ? to show them on the page.

Related pages

• Integrations
• Developer portal
• Helpdesk