ConnectCloud Developers

Get a task with its current trade transaction (tenant:access)

GET /api/workflow/v1/tasks/{instanceId}

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

Every holder of tenant:access in the tenant can read any instance's details; readOnly tells whether the caller can work on it (assigned and not RETRYING_SYNC). document is the trade transaction as trade has it now (omitted if trade cannot be reached); pdfUrl is set when the transaction has a document and the caller holds tenant:dms:read.

Parameters

Name In Type Required Description
instanceId path string (uuid) yes Instance id (guid)

Responses

  • 200 Task details (application/json)
  • 401 Missing or invalid token (unauthorized) (application/json)
  • 403 Error (application/json)
  • 404 Error (application/json)

Fields of the 200 answer:

  • blueprintId (string): Id of the instance's blueprint
  • currentStepConfig (Step)
    • 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
  • document (object): The trade transaction now, with lines and typeData (field names as in GET /blueprints/fields)
  • instance (WorkflowInstance)
    • blueprint (Blueprint): A workflow definition. In responses, set webhook URLs are replaced by ********.
      • 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
      • 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)
        • 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
    • claimedAt (string (date-time)): When the task was claimed; omitted if unclaimed
    • claimedBy (string): E-mail of the person working on the task, empty if unclaimed
    • currentStep (Step | null): Null once the workflow has ended
    • customerId (TenantRef)
      • customerId (string): Customer number
      • tenantName (string): Tenant name
    • data (object): Transaction data at start, start metadata (blueprintId, objectNumber, initialNote, …), workflow-local input and open inquiry keys (inquiry_to, inquiry_text, …)
    • endTime (string (date-time)): When the instance ended; omitted while running
    • guid (string (uuid)): Instance id
    • history (array of HistoryEntry): Append-only history, oldest first
      • action (string): Free text, e.g. Step completed, CLAIMED, UNCLAIMED, FORCE_PULLED, NOTE, CANCELLED, Rückfrage gestellt
      • actor (string): E-mail of the person, or SYSTEM
      • branch (string): regular or inquiry
      • changes (ChangeSetDiff)
      • color (string): Color of the chosen transition button
      • comment (string): Comment, note text or inquiry answer
      • group (string): HR group UUID of the step
      • icon (string): Icon of the chosen transition button
      • nextStep (string): Name of the step the transition led to
      • stepName (string): Step the entry belongs to (START/END for the start and end of the workflow)
      • timestamp (string (date-time)): When it happened
      • user (string): E-mail of the person the step was assigned to
    • lastRetryAt (string (date-time)): Last automatic retry; omitted if none
    • objectNumber (string): Transaction number
    • objectType (string): Object type of the trigger
    • retryCount (integer): Attempts of a pending trade start or write-back
    • revision (integer (int64)): Optimistic-lock counter
    • startTime (string (date-time)): When the instance started
    • transactionId (string (uuid)): Trade transaction id
    • workflowState (WorkflowState): (one of OPEN, RETRYING_SYNC, APPROVED, REJECTED, COMPLETED, CANCELLED, TRIGGER_NOT_MATCHED, TECHNICALLY_FAILED)
  • pdfUrl (string): Path of the task document
  • readOnly (boolean): True when the caller cannot work on the task

Example 200 answer:

{
  "blueprintId": "er-freigabe",
  "currentStepConfig": {
    "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"
  },
  "document": {
    "documentDate": "2026-09-30",
    "dueDate": "2026-10-30",
    "externalTransactionNumber": "RE-482117",
    "grossTotal": 6911.52,
    "id": "8c2f4a6e-0b1d-4e3f-9a5c-7e9b1d3f5a7c",
    "lines": [
      {
        "articleNumber": "HW-1001",
        "id": "7d2e9a41-3b6c-4f0e-8a15-c9b2d4e6f801",
        "lineData": {
          "costCenter": "4100"
        },
        "name": "Notebook ProBook 14 G10, i5, 16 GB, 512 GB SSD",
        "position": 1,
        "quantity": 6,
        "taxRate": 19,
        "totalPriceNet": 4974,
        "unitPriceNet": 829
      },
      {
        "articleNumber": "HW-1004",
        "id": "1a3c5e7b-9d2f-4b4a-8c6e-0f2a4c6e8b0d",
        "lineData": {
          "costCenter": "4100"
        },
        "name": "USB-C Dockingstation 100 W",
        "position": 2,
        "quantity": 6,
        "taxRate": 19,
        "totalPriceNet": 834,
        "unitPriceNet": 139
      }
    ],
    "netTotal": 5808,
    "partnerCompany": "Nordlicht IT-Distribution GmbH",
    "transactionNumber": "ER-2026-00042",
    "transactionType": "INBOUND_INVOICE",
    "typeData": {}
  },
  "instance": {
    "blueprint": {
      "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
    },
    "claimedAt": "2026-11-17T09:05:40Z",
    "claimedBy": "christina.adler@muster-it.example",
    "currentStep": {
      "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"
    },
    "customerId": {
      "customerId": "99999",
      "tenantName": "DEMO"
    },
    "data": {
      "blueprintId": "er-freigabe",
      "externalTransactionNumber": "RE-482117",
      "grossTotal": 6911.52,
      "netTotal": 5808,
      "objectNumber": "ER-2026-00042",
      "partnerCompany": "Nordlicht IT-Distribution GmbH",
      "transactionNumber": "ER-2026-00042"
    },
    "guid": "3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60",
    "history": [
      {
        "action": "Workflow started",
        "actor": "SYSTEM",
        "nextStep": "kontierung",
        "stepName": "START",
        "timestamp": "2026-11-17T08:41:12Z"
      },
      {
        "action": "CLAIMED",
        "actor": "christina.adler@muster-it.example",
        "group": "4e7a1c2b-9f3d-4b8a-a6e1-5c0d2f8b3a71",
        "stepName": "kontierung",
        "timestamp": "2026-11-17T09:05:40Z"
      }
    ],
    "objectNumber": "ER-2026-00042",
    "objectType": "transaction",
    "retryCount": 0,
    "revision": 2,
    "startTime": "2026-11-17T08:41:12Z",
    "transactionId": "8c2f4a6e-0b1d-4e3f-9a5c-7e9b1d3f5a7c",
    "workflowState": "OPEN"
  },
  "pdfUrl": "/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60/document",
  "readOnly": false
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/workflow/v1/tasks/3f9c2a1e-8b7d-4c6e-a5f4-1d2b3c4e5f60' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI