ConnectCloud Developers

Update a workflow, or check its impact first with dryRun (desk:admin)

PUT /api/desk/v1/workflows/{id}

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

Statuses used by items cannot be removed (409 in_use). The key cannot change. With dryRun=true nothing is saved: the answer is the change's impact (WorkflowImpact) – statuses added, removed, renamed and moved to another phase, transitions added and removed, how many items and projects sit in each removed or phase-changed status, whether saving would be refused (blocked) and the automations of the tenant and its spaces whose definitions mention those statuses (a hint: a key built at run time is not found). The workflow is validated as for saving.

Parameters

Name In Type Required Description
id path string (uuid) yes
dryRun query boolean Answer the impact, save nothing

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:

{
  "id": "4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01",
  "key": "service",
  "name": "Service",
  "note": "Status „Wartet auf Dritte“ pausiert jetzt die SLA-Uhr",
  "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": [
        "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
}

Responses

  • 200 Saved (the workflow), or with dryRun the impact (application/json)
  • 409 Error (application/json)

Fields of the 200 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)
  • automations (array of object, required): Automations whose definitions mention a removed or phase-changed status
    • id (string)
    • key (string)
    • name (string)
    • scope (string)
    • statuses (array of string)
  • blocked (boolean, required): A removed status is still in use – saving would answer 409 in_use
  • customerNames (array of object, required): The customer portal's names (what requesters read) of removed or phase-changed statuses that change; after empty = the status is gone. Empty for project workflows and tenants without portal settings.
    • after (string)
    • before (string)
    • key (string)
  • diff (object, required)
    • added (array of string): Status keys
    • phaseChanged (array of object)
      • from (string)
      • key (string)
      • to (string)
    • removed (array of string): Status keys
    • renamed (array of object)
      • from (string)
      • key (string)
      • to (string)
    • transitionsAdded (array of object)
      • from (string): A status key or *
      • to (string)
    • transitionsRemoved (array of object)
      • from (string)
      • to (string)
  • dryRun (boolean, required): Always true – tells the impact from a saved workflow
  • statuses (array of object, required): Removed and phase-changed statuses with what sits in them
    • items (integer)
    • key (string)
    • projects (integer)

Example 200 answer:

{
  "automations": [],
  "blocked": true,
  "customerNames": [],
  "diff": {
    "added": [],
    "phaseChanged": [],
    "removed": [
      "wartet_dritte"
    ],
    "renamed": [],
    "transitionsAdded": [],
    "transitionsRemoved": [
      {
        "from": "neu",
        "to": "wartet_dritte"
      },
      {
        "from": "in_bearbeitung",
        "to": "wartet_dritte"
      }
    ]
  },
  "dryRun": true,
  "statuses": [
    {
      "items": 3,
      "key": "wartet_dritte",
      "projects": 0
    }
  ]
}

Example request

curl -X PUT 'https://api.mbcom.cloud/api/desk/v1/workflows/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"id":"4c1d2e3f-5a6b-4c7d-8e9f-1a2b3c4d5e01","key":"service","name":"Service","note":"Status „Wartet auf Dritte“ pausiert jetzt die SLA-Uhr","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":["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}'

View as Markdown · Interactive reference · OpenAPI