ConnectCloud Developers

Check an automation's definition without storing it (desk access; a space the caller sees)

POST /api/desk/v1/automations/validate

Module: Desk · operationId: validateDeskAutomation · Tag: Automation · Auth: access token (Authorization: Bearer <accessToken>)

Scope tenant: everyone with desk access. Scope space:<id>: whoever sees the space (a space the caller does not see, or an unknown one, is 404; a malformed scope 400 scope). Validates the YAML with the inline profile against desk's catalogue and answers the findings (the same codes, paths and positions as flows) and the ports of every node. needsDurable says that the definition is fine but for parts only a flow in the background can run.

Parameters

Name In Type Required Description
scope query string yes Whose automations: tenant (every space) or space:<space id>

Request body

application/json (required)

  • yaml (string, required)

Example:

{
  "yaml": "schemaVersion: 1\nkey: vip-hoch\nname: VIP-Tickets mindestens hoch\ntriggers:\n  - { id: label, kind: event, event: desk.item.updated, filter: '\"vip\" in trigger.data.labels' }\nnodes:\n  hochstufen:\n    kind: action\n    action: desk.item.update\n    params: { ref: \"{{ trigger.data.itemId }}\", priority: hoch }\n    retry: { attempts: 3 }\nedges:\n  - label -\u003e hochstufen\n"
}

Responses

  • 200 The findings (application/json)
  • 400 Error (application/json)
  • 404 Error (application/json)

Fields of the 200 answer:

  • diagnostics (array of AutomationDiagnostic, required): Findings of the check (errors and warnings)
    • code (string, required): Stable code, e.g. unknown_action, missing_param, expression, needs_durable, inline_ignored
    • message (string, required): What is wrong
    • severity (string, required): Errors keep the automation from being enabled (one of error, warning)
    • col (integer): Column in the YAML definition
    • line (integer): Line in the YAML definition
    • nodeId (string): Node the finding refers to (empty: the whole definition)
    • params (object): needs_durable: reason (trigger, kind, action, foreign_action, foreign_event, recipient, too_many_nodes)
    • path (string): Dotted path in the definition
  • needsDurable (boolean, required): A finding is needs_durable: the definition runs only as a flow in the background
  • permissions (array of array of string, required): The any-of permission groups a flow with this definition would need
  • ports (object, required): The output ports of every node that parsed, by node id (the builder's handles)
  • profile (string, required): The profile the definition was checked with (one of inline)
  • valid (boolean, required): No finding is an error

Example 200 answer:

{
  "diagnostics": [
    {
      "code": "inline_ignored",
      "col": 7,
      "line": 12,
      "message": "Die Option „retry“ gilt nur für Flows im Hintergrund und wird hier ignoriert.",
      "nodeId": "hochstufen",
      "path": "nodes.hochstufen.retry",
      "severity": "warning"
    }
  ],
  "needsDurable": false,
  "permissions": [
    [
      "desk:write"
    ]
  ],
  "ports": {
    "hochstufen": [
      "main",
      "error"
    ]
  },
  "profile": "inline",
  "valid": true
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/automations/validate?scope=tenant' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"yaml":"schemaVersion: 1\nkey: vip-hoch\nname: VIP-Tickets mindestens hoch\ntriggers:\n  - { id: label, kind: event, event: desk.item.updated, filter: '\''\"vip\" in trigger.data.labels'\'' }\nnodes:\n  hochstufen:\n    kind: action\n    action: desk.item.update\n    params: { ref: \"{{ trigger.data.itemId }}\", priority: hoch }\n    retry: { attempts: 3 }\nedges:\n  - label -\u003e hochstufen\n"}'

View as Markdown · Interactive reference · OpenAPI