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 tenantname(string, required): Name of the workflowstatuses(array of Status, required): Statuses of the workflowkey(string, required): Key of the status, unique in the workflowlabel(string, required): Display labelphase(Phase, required): (one ofnew,active,waiting,done)closed(boolean): The item counts as closed in this statuscolor(string): Display colordescription(string): Description of the statuspausesSla(boolean): SLA clocks pause in this status
archived(boolean): Archived: the workflow is kept for existing data but no longer offered in pickersdescription(string): Description of the workflowid(string, read-only): Id of the workflowscope(string): Serves item types (item, default) or project types (project); fixed after creation (one ofitem,project)transitions(array of Transition): Empty = free workflowfrom(array of string, required): Source statuses; "*" = anyid(string, required): Id of the transitionto(string, required): Target statusallowedRoles(array of string): Space roles allowed (at least one of them); empty: agent and abovelabel(string): Label of the actionrequireComment(boolean): A comment is requiredrequiredFields(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 tenantname(string, required): Name of the workflowstatuses(array of Status, required): Statuses of the workflowkey(string, required): Key of the status, unique in the workflowlabel(string, required): Display labelphase(Phase, required): (one ofnew,active,waiting,done)closed(boolean): The item counts as closed in this statuscolor(string): Display colordescription(string): Description of the statuspausesSla(boolean): SLA clocks pause in this status
archived(boolean): Archived: the workflow is kept for existing data but no longer offered in pickersdescription(string): Description of the workflowid(string, read-only): Id of the workflowscope(string): Serves item types (item, default) or project types (project); fixed after creation (one ofitem,project)transitions(array of Transition): Empty = free workflowfrom(array of string, required): Source statuses; "*" = anyid(string, required): Id of the transitionto(string, required): Target statusallowedRoles(array of string): Space roles allowed (at least one of them); empty: agent and abovelabel(string): Label of the actionrequireComment(boolean): A comment is requiredrequiredFields(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 statusid(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_usecustomerNames(array of object, required): The customer portal's names (what requesters read) of removed or phase-changed statuses that change;afterempty = 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 keysphaseChanged(array of object)from(string)key(string)to(string)
removed(array of string): Status keysrenamed(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 workflowstatuses(array of object, required): Removed and phase-changed statuses with what sits in themitems(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}'