## 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:

```json
{
  "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:

```json
{
  "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

```bash
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}'
```
