ConnectCloud Developers

Create a workflow (desk:admin)

POST /api/desk/v1/workflows

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

Request body

application/json (required)

  • key (string, required): Key of the workflow, unique in the tenant
  • name (string, required): Name of the workflow
  • statuses (array of Status, required): Statuses of the workflow
    • key (string, required): Key of the status, unique in the workflow
    • label (string, required): Display label
    • phase (Phase, required): (one of new, active, waiting, done)
    • closed (boolean): The item counts as closed in this status
    • color (string): Display color
    • description (string): Description of the status
    • pausesSla (boolean): SLA clocks pause in this status
  • archived (boolean): Archived: the workflow is kept for existing data but no longer offered in pickers
  • description (string): Description of the workflow
  • id (string, read-only): Id of the workflow
  • scope (string): Serves item types (item, default) or project types (project); fixed after creation (one of item, project)
  • transitions (array of Transition): Empty = free workflow
    • from (array of string, required): Source statuses; "*" = any
    • id (string, required): Id of the transition
    • to (string, required): Target status
    • allowedRoles (array of string): Space roles allowed (at least one of them); empty: agent and above
    • label (string): Label of the action
    • requireComment (boolean): A comment is required
    • requiredFields (array of string): Fields that must be filled for the transition
  • version (integer): Version of the workflow; send it back on change (409 version_conflict when it is outdated)
  • note (string): Why the configuration changes (trimmed, at most 500 characters, line breaks allowed; empty = no note) (max length 500)

Example:

{
  "description": "Änderungen mit Freigabe durch den Kunden",
  "key": "freigabe",
  "name": "Freigabe",
  "note": "Neuer Ablauf für Changes mit Kundenfreigabe",
  "scope": "item",
  "statuses": [
    {
      "color": "info",
      "key": "neu",
      "label": "Neu",
      "phase": "new"
    },
    {
      "color": "warning",
      "key": "wartet_freigabe",
      "label": "Wartet auf Freigabe",
      "pausesSla": true,
      "phase": "waiting"
    },
    {
      "color": "primary",
      "key": "umsetzung",
      "label": "In Umsetzung",
      "phase": "active"
    },
    {
      "closed": true,
      "color": "success",
      "key": "erledigt",
      "label": "Erledigt",
      "phase": "done"
    }
  ],
  "transitions": [
    {
      "from": [
        "neu"
      ],
      "id": "freigabe_anfordern",
      "label": "Freigabe anfordern",
      "to": "wartet_freigabe"
    },
    {
      "from": [
        "wartet_freigabe"
      ],
      "id": "freigegeben",
      "label": "Freigegeben",
      "requireComment": true,
      "to": "umsetzung"
    },
    {
      "from": [
        "umsetzung"
      ],
      "id": "abschliessen",
      "label": "Abschließen",
      "to": "erledigt"
    }
  ]
}

Responses

  • 201 Created (application/json)
  • 400 Error (application/json)

Fields of the 201 answer:

  • key (string, required): Key of the workflow, unique in the tenant
  • name (string, required): Name of the workflow
  • statuses (array of Status, required): Statuses of the workflow
    • key (string, required): Key of the status, unique in the workflow
    • label (string, required): Display label
    • phase (Phase, required): (one of new, active, waiting, done)
    • closed (boolean): The item counts as closed in this status
    • color (string): Display color
    • description (string): Description of the status
    • pausesSla (boolean): SLA clocks pause in this status
  • archived (boolean): Archived: the workflow is kept for existing data but no longer offered in pickers
  • description (string): Description of the workflow
  • id (string, read-only): Id of the workflow
  • scope (string): Serves item types (item, default) or project types (project); fixed after creation (one of item, project)
  • transitions (array of Transition): Empty = free workflow
    • from (array of string, required): Source statuses; "*" = any
    • id (string, required): Id of the transition
    • to (string, required): Target status
    • allowedRoles (array of string): Space roles allowed (at least one of them); empty: agent and above
    • label (string): Label of the action
    • requireComment (boolean): A comment is required
    • requiredFields (array of string): Fields that must be filled for the transition
  • version (integer): Version of the workflow; send it back on change (409 version_conflict when it is outdated)

Example 201 answer:

{
  "archived": false,
  "description": "Service-Desk-Ablauf mit Wartezuständen und Abschlussangaben",
  "id": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01",
  "key": "service",
  "name": "Service",
  "scope": "item",
  "statuses": [
    {
      "color": "info",
      "key": "neu",
      "label": "Neu",
      "phase": "new"
    },
    {
      "color": "info",
      "key": "in_bearbeitung",
      "label": "In Bearbeitung",
      "phase": "active"
    },
    {
      "color": "warning",
      "key": "wartet_kunde",
      "label": "Wartet auf Kunde",
      "pausesSla": true,
      "phase": "waiting"
    },
    {
      "color": "warning",
      "key": "wartet_dritte",
      "label": "Wartet auf Dritte",
      "pausesSla": true,
      "phase": "waiting"
    },
    {
      "closed": true,
      "color": "success",
      "key": "geloest",
      "label": "Gelöst",
      "phase": "done"
    },
    {
      "closed": true,
      "color": "neutral",
      "key": "geschlossen",
      "label": "Geschlossen",
      "phase": "done"
    }
  ],
  "transitions": [
    {
      "from": [
        "neu",
        "wartet_kunde",
        "wartet_dritte"
      ],
      "id": "bearbeiten",
      "label": "In Bearbeitung nehmen",
      "to": "in_bearbeitung"
    },
    {
      "from": [
        "geloest",
        "geschlossen"
      ],
      "id": "wieder_oeffnen",
      "label": "Wieder öffnen",
      "to": "in_bearbeitung"
    },
    {
      "from": [
        "neu",
        "in_bearbeitung",
        "wartet_dritte"
      ],
      "id": "warten_kunde",
      "label": "Auf Kunde warten",
      "to": "wartet_kunde"
    },
    {
      "from": [
        "neu",
        "in_bearbeitung",
        "wartet_kunde"
      ],
      "id": "warten_dritte",
      "label": "Auf Dritte warten",
      "to": "wartet_dritte"
    },
    {
      "from": [
        "neu",
        "in_bearbeitung",
        "wartet_kunde",
        "wartet_dritte"
      ],
      "id": "loesen",
      "label": "Lösen",
      "to": "geloest"
    },
    {
      "from": [
        "geloest"
      ],
      "id": "schliessen",
      "label": "Schließen",
      "to": "geschlossen"
    }
  ],
  "version": 3
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/workflows' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"description":"Änderungen mit Freigabe durch den Kunden","key":"freigabe","name":"Freigabe","note":"Neuer Ablauf für Changes mit Kundenfreigabe","scope":"item","statuses":[{"color":"info","key":"neu","label":"Neu","phase":"new"},{"color":"warning","key":"wartet_freigabe","label":"Wartet auf Freigabe","pausesSla":true,"phase":"waiting"},{"color":"primary","key":"umsetzung","label":"In Umsetzung","phase":"active"},{"closed":true,"color":"success","key":"erledigt","label":"Erledigt","phase":"done"}],"transitions":[{"from":["neu"],"id":"freigabe_anfordern","label":"Freigabe anfordern","to":"wartet_freigabe"},{"from":["wartet_freigabe"],"id":"freigegeben","label":"Freigegeben","requireComment":true,"to":"umsetzung"},{"from":["umsetzung"],"id":"abschliessen","label":"Abschließen","to":"erledigt"}]}'

View as Markdown · Interactive reference · OpenAPI