ConnectCloud Developers

Check a blueprint without saving it (tenant:settings:write)

POST /api/workflow/v1/blueprints/validate

Module: Workflow · operationId: validateBlueprint · Tag: Blueprints · Auth: access token (Authorization: Bearer <accessToken>)

Runs the same checks as a save – field names, conditions, HR groups, trade transaction types, comms channels – and returns the problems found (empty when the blueprint is valid). A check that cannot reach trade or HR is reported as a problem.

Request body

application/json (required)

  • id (string, required): Free identifier, unique per tenant
  • steps (array of Step, required): Steps of the workflow; the first one runs unless trigger.nextStep names another
    • name (string, required): Unique within the blueprint; referenced by nextSteps[].step
    • stepType (string, required): UserStep (a person decides) or SystemStep (the engine decides) (one of UserStep, SystemStep)
    • action (string): Outcome when the workflow ends after this step: approve → APPROVED, reject → REJECTED (German synonyms accepted), else COMPLETED
    • allowInquiry (boolean): The assignee may ask another person (inquiry)
    • fields (array of Field): Fields shown in a user step
      • name (string, required): Trade field (GET /blueprints/fields), typeData.<key>, lines.<field>, or a workflow-local input field
      • editable (boolean): The user may change it; trade fields only if listed as editable
      • label (string): Label shown in the step
      • required (boolean): The user must fill it in to complete the step
      • visible (boolean, nullable): Whether the field is shown; null means visible
    • group (string): HR group UUID the user step is assigned to (required for user steps)
    • lines (LineActions): Line actions of a user step besides editing line fields
      • allowDelete (boolean): The user may delete lines
      • allowDuplicate (boolean): The user may duplicate lines
    • nextSteps (array of NextStep): Transitions: buttons of a user step, conditions of a system step
      • color (string): Button color of a user step transition
      • condition (string): System steps: expr condition, or default
      • icon (string): Button icon of a user step transition
      • label (string): Button label of a user step transition
      • step (string): Name of the target step
    • notificationEmail (string): E-mail address notified about this step
    • notifyAssigneesByEmail (boolean): E-mail the assignees (the step's user, else its group's members) when the task waits; user steps only
    • notifyAssigneesByTeams (boolean): Notify the assignees in their personal Teams chat; user steps only
    • teamsChannel (string): Comms webhook channel id notified about this step (see GET /channels)
    • teamsWebhookUrl (string): Legacy: a Teams webhook URL; saving moves it into a comms channel (teamsChannel)
    • user (string): E-mail of a person the user step is additionally assigned to
  • trigger (Trigger, required)
    • objectType (string, required): The only supported object type (one of transaction)
    • condition (string): Optional expr condition over the transaction data; false ends the start as TRIGGER_NOT_MATCHED
    • nextStep (NextStep)
      • color (string): Button color of a user step transition
      • condition (string): System steps: expr condition, or default
      • icon (string): Button icon of a user step transition
      • label (string): Button label of a user step transition
      • step (string): Name of the target step
    • statuses (array of string): Trade statuses that start the workflow
    • transactionTypes (array of string): Trade transaction type codes (active in trade)
  • active (boolean): Only active blueprints start workflows; missing means active
  • inquiryWebhookUrl (string): Webhook (JSON) notified about inquiries and their answers; ******** keeps the stored URL
  • overviewField1 (OverviewField)
    • label (string): Column label
    • name (string): Transaction field shown in task lists
  • overviewField2 (OverviewField)
    • label (string): Column label
    • name (string): Transaction field shown in task lists
  • updatedAt (string (date-time), read-only): Last modification of the stored blueprint
  • version (integer (int64)): Informational; set to 1 when 0 on save

Example:

{
  "active": true,
  "id": "er-freigabe",
  "overviewField1": {
    "label": "Lieferant",
    "name": "partnerCompany"
  },
  "overviewField2": {
    "label": "Brutto",
    "name": "grossTotal"
  },
  "steps": [
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Rechnungsnummer",
          "name": "externalTransactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "editable": true,
          "label": "Fällig am",
          "name": "dueDate"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        },
        {
          "label": "Bezeichnung",
          "name": "lines.name"
        },
        {
          "editable": true,
          "label": "Kostenstelle",
          "name": "lines.lineData.costCenter",
          "required": true
        },
        {
          "label": "Menge",
          "name": "lines.quantity"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "lines": {
        "allowDelete": true,
        "allowDuplicate": true
      },
      "name": "kontierung",
      "nextSteps": [
        {
          "color": "primary",
          "icon": "i-lucide-arrow-right",
          "label": "Weiter zur Freigabe",
          "step": "freigabe"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "notifyAssigneesByEmail": true,
      "stepType": "UserStep"
    },
    {
      "allowInquiry": true,
      "fields": [
        {
          "label": "Eingangsnr.",
          "name": "transactionNumber"
        },
        {
          "label": "Lieferant",
          "name": "partnerCompany"
        },
        {
          "label": "Brutto",
          "name": "grossTotal"
        }
      ],
      "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
      "name": "freigabe",
      "nextSteps": [
        {
          "color": "success",
          "icon": "i-lucide-check-circle",
          "label": "Freigeben",
          "step": "freigegeben"
        },
        {
          "color": "warning",
          "icon": "i-lucide-undo-2",
          "label": "Zurück zur Kontierung",
          "step": "kontierung"
        },
        {
          "color": "error",
          "icon": "i-lucide-x-circle",
          "label": "Ablehnen",
          "step": "abgelehnt"
        }
      ],
      "stepType": "UserStep"
    },
    {
      "action": "approve",
      "name": "freigegeben",
      "stepType": "SystemStep"
    },
    {
      "action": "reject",
      "name": "abgelehnt",
      "stepType": "SystemStep"
    }
  ],
  "trigger": {
    "nextStep": {
      "step": "kontierung"
    },
    "objectType": "transaction",
    "statuses": [
      "MATCHED"
    ],
    "transactionTypes": [
      "INBOUND_INVOICE"
    ]
  },
  "updatedAt": "2026-10-14T13:22:05Z",
  "version": 3
}

Responses

  • 200 Problems found (application/json)
  • 400 Error (application/json)
  • 401 Missing or invalid token (unauthorized) (application/json)
  • 403 Error (application/json)
  • 500 Error (application/json)

Fields of the 200 answer:

  • problems (array of BlueprintProblem): Problems found; empty or null when the blueprint is valid
    • message (string): What is wrong, human-readable
    • path (string): Where in the blueprint (empty for the whole blueprint)

Example 200 answer:

{
  "problems": [
    {
      "message": "HR-Gruppe '4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71' gibt es nicht",
      "path": "steps[1].group"
    }
  ]
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/workflow/v1/blueprints/validate' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"active":true,"id":"er-freigabe","overviewField1":{"label":"Lieferant","name":"partnerCompany"},"overviewField2":{"label":"Brutto","name":"grossTotal"},"steps":[{"allowInquiry":true,"fields":[{"label":"Eingangsnr.","name":"transactionNumber"},{"label":"Rechnungsnummer","name":"externalTransactionNumber"},{"label":"Lieferant","name":"partnerCompany"},{"editable":true,"label":"Fällig am","name":"dueDate"},{"label":"Brutto","name":"grossTotal"},{"label":"Bezeichnung","name":"lines.name"},{"editable":true,"label":"Kostenstelle","name":"lines.lineData.costCenter","required":true},{"label":"Menge","name":"lines.quantity"}],"group":"4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71","lines":{"allowDelete":true,"allowDuplicate":true},"name":"kontierung","nextSteps":[{"color":"primary","icon":"i-lucide-arrow-right","label":"Weiter zur Freigabe","step":"freigabe"},{"color":"error","icon":"i-lucide-x-circle","label":"Ablehnen","step":"abgelehnt"}],"notifyAssigneesByEmail":true,"stepType":"UserStep"},{"allowInquiry":true,"fields":[{"label":"Eingangsnr.","name":"transactionNumber"},{"label":"Lieferant","name":"partnerCompany"},{"label":"Brutto","name":"grossTotal"}],"group":"4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71","name":"freigabe","nextSteps":[{"color":"success","icon":"i-lucide-check-circle","label":"Freigeben","step":"freigegeben"},{"color":"warning","icon":"i-lucide-undo-2","label":"Zurück zur Kontierung","step":"kontierung"},{"color":"error","icon":"i-lucide-x-circle","label":"Ablehnen","step":"abgelehnt"}],"stepType":"UserStep"},{"action":"approve","name":"freigegeben","stepType":"SystemStep"},{"action":"reject","name":"abgelehnt","stepType":"SystemStep"}],"trigger":{"nextStep":{"step":"kontierung"},"objectType":"transaction","statuses":["MATCHED"],"transactionTypes":["INBOUND_INVOICE"]},"updatedAt":"2026-10-14T13:22:05Z","version":3}'

View as Markdown · Interactive reference · OpenAPI