ConnectCloud Developers

Check an automation's definition without storing it (tenant:forge:read)

POST /api/forge/v1/projects/{key}/automations/validate

Module: Forge · operationId: validateForgeAutomation · Tag: Automations · Auth: access token (Authorization: Bearer <accessToken>)

Requires tenant:forge:read and a project the caller sees. Validates the YAML with the inline profile against forge'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
key path string yes Project key (e.g. APP)

Request body

application/json (required)

  • yaml (string, required): The definition (YAML of the flow language)

Example:

{
  "yaml": "schemaVersion: 1\nkey: review-erinnerung\nname: Review-Erinnerung\ntriggers:\n  - { id: review, kind: event, event: forge.item.status_changed, filter: 'trigger.data.statusKey == \"review\"' }\nnodes:\n  warten:\n    kind: wait\n    duration: 48h\n  erinnern:\n    kind: action\n    action: forge.comment.add\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", body: Das Review wartet seit zwei Tagen. }\nedges:\n  - review -\u003e warten\n  - warten -\u003e erinnern\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): The findings, errors and warnings
    • code (string, required): Stable code, e.g. unknown_action, missing_param, expression, needs_durable, inline_ignored
    • message (string, required): Human-readable text of the finding
    • severity (string, required): Errors keep the automation from being enabled (one of error, warning)
    • col (integer): Column in the YAML definition (when known)
    • line (integer): Line in the YAML definition (when known)
    • nodeId (string): The node the finding is about
    • params (object): needs_durable: reason (trigger, kind, action, foreign_action, foreign_event, recipient, mail_option – a mail node sets mandatory or mailChannel, which only a tenant flow without scope may –, 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": "needs_durable",
      "col": 3,
      "line": 8,
      "message": "Der Knoten „warten“ kann nicht sofort laufen; als Flow im Hintergrund ist er möglich.",
      "nodeId": "warten",
      "params": {
        "reason": "kind"
      },
      "path": "nodes.warten",
      "severity": "error"
    }
  ],
  "needsDurable": true,
  "permissions": [
    [
      "tenant:forge:write",
      "tenant:forge:admin"
    ]
  ],
  "ports": {
    "erinnern": [
      "main",
      "error"
    ],
    "warten": [
      "main",
      "error"
    ]
  },
  "profile": "inline",
  "valid": false
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/string/automations/validate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"yaml":"schemaVersion: 1\nkey: review-erinnerung\nname: Review-Erinnerung\ntriggers:\n  - { id: review, kind: event, event: forge.item.status_changed, filter: '\''trigger.data.statusKey == \"review\"'\'' }\nnodes:\n  warten:\n    kind: wait\n    duration: 48h\n  erinnern:\n    kind: action\n    action: forge.comment.add\n    params: { key: \"{{ trigger.data.projectKey }}\", number: \"{{ trigger.data.number }}\", body: Das Review wartet seit zwei Tagen. }\nedges:\n  - review -\u003e warten\n  - warten -\u003e erinnern\n"}'

View as Markdown · Interactive reference · OpenAPI