Desk tickets
Desk is ConnectCloud's service desk: tickets, requests, incidents and tasks in spaces, each of a type that
follows a workflow of statuses. Everything below is under https://api.mbcom.cloud/api/desk/v1; every operation is in the
Desk reference. The Quickstart creates a first ticket; this guide covers
what a real integration needs around it.
| Step | Operations | Permission |
|---|---|---|
| Read the configuration | getBootstrap |
desk:read |
| Create | checkItem, createItem |
desk:write |
| Read and sync | getItem, listItems, searchItems |
desk:read |
| Change and move | updateItem, transitionItem |
desk:write |
| Reply | addItemEntry, createItemMail, listItemEntries |
desk:write (agent in the space) / desk:read |
| Attachments | createItemAttachment, listItemAttachments, getItemAttachmentContent |
desk:write (agent) / desk:read |
Spaces with visibility members add a space role on top: viewer < reporter (create and comment) < agent (edit,
transition, mail) < maintainer. A token sees only the spaces and items its owner may see; everything else is 404.
Read the configuration first
Spaces, types, workflows, statuses, priorities and custom fields are tenant configuration. Every tenant has its own
keys – stoerung, in_bearbeitung or hoch in one tenant may not exist in the next, and administrators rename and
add them at any time. Never hard-code them: read them from GET /bootstrap.
curl 'https://api.mbcom.cloud/api/desk/v1/bootstrap' -H "Authorization: Bearer $ACCESS_TOKEN"
| Key | What you take from it |
|---|---|
spaces[] |
id, key (SUP), name, typeIds (allowed types; empty = all), defaultTypeId |
types[] |
id, key, name, workflowId, layout (the custom fields of the type), closeRequired |
workflows[] |
statuses[] (key, label, phase, closed) and transitions[] (from, to, requiredFields, requireComment; empty = any status to any) |
fields[] |
custom field definitions: key, label, kind (text, select, date, …), options |
priorities[] |
key, label, rank, isDefault |
enums |
tenant value lists, e.g. source |
Every status belongs to one of four fixed phases – new, active, waiting, done – and these are the only
values you may rely on: filter by phase (listItems?phase=active) and decide "open" or "closed" from a status's
phase and closed, not from its key. revision changes with every configuration change; the answer carries a weak ETag, so cache it and send
If-None-Match – an unchanged configuration answers 304. Read it again when a write answers 422 for a key you
took from your cache.
Create a ticket
Map your data to the configuration you read: pick the space by key, a type the space allows and custom fields from
the type's layout. checkItem runs every check of a create without storing anything
(with preview=true it also tells the due date and SLA the ticket would get), useful while you set up the mapping.
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items' \
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-H 'Idempotency-Key: 0b6f3c2e-5a4d-4e8f-9b1a-7c2d3e4f5a6b' \
-d '{
"spaceId": "SUP",
"typeId": "stoerung",
"source": "api",
"title": "Drucker im 2. OG druckt nicht",
"description": "Der Drucker zeigt seit dem Update den Fehler **E-204**.",
"customer": { "id": "K-10023", "name": "Muster GmbH" },
"customFields": { "betroffenes_system": "Drucker 2. OG" }
}'
spaceIdandtypeIdtake ids or keys. WithouttypeIdthe space's default type is used, withoutstatusthe first status of phasenew.source: apimarks the channel (a key ofenums.source).Idempotency-Key(kept 7 days) anddedupeKey(your own id, e.g. the id of the record in your system) make the create safe to repeat: a repeated request answers the existing item with 200 instead of 201. See Idempotency and concurrency.- 422
missing_fieldsnames the required fields of the type's layout inmissingFields; 400invalida value that does not fit (fieldnames it). - The answer is the item with
id,number(the ticket number customers see,#1234) andversion. Paths accept either the id or the number.
Change the status
Status changes go through the workflow with transitionItem, never through
PATCH:
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/1234/transition' \
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-d '{"status": "geloest", "version": 3, "comment": "Treiber neu installiert.", "commentVisibility": "public"}'
Pick the target from the workflow's transitions whose from holds the current status (or *). version is the
version you read: a ticket that changed since is 409 version_conflict – read it again and decide. 422 answers
a refused move: transition_denied (not allowed from here or not for your role), same_status, comment_required
(the transition has requireComment) or missing_fields (its requiredFields, or the type's closeRequired when
closing). Fields can be set in the same call with fields.
Other changes use updateItem (PATCH, only sent keys, null clears,
customFields are merged) with the version as well.
Reply: comments and mail
A ticket's conversation is its entries (listItemEntries): comments, internal
notes and mails in and out (kind comment, email_in, email_out, system).
Comment or note – addItemEntry with body (Markdown) and visibility:
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/1234/entries' \
-H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' \
-d '{"body": "Wir haben den Druckertreiber aktualisiert. Bitte testen Sie erneut.", "visibility": "public"}'
internal is a note only staff see. A public comment is shown to the requester in the customer portal and mailed to
them through the space's mailbox: the answer then has kind: email_out. When it could not be mailed, mailNote says
why (no_mailbox, no_recipient, mail_unavailable, or work_type for types that never mail).
A mail with full control – createItemMail (agent role) writes a mail with
to, cc, bcc, subject, body, attachmentIds and mailboxId; send: true sends it, otherwise it is a draft.
getItemMailDefaults gives the defaults of an answer (requester, people in
copy, the subject with the ticket tag, the mailbox). The mail entry's mail.deliveryState then moves
queued → sent → delivered (or bounced, failed); mails always go out through ConnectCloud's mail module, never
from your system. Requesters and people in copy are the ticket's participants
(listItemParticipants,
createItemParticipant).
Attachments
Files of a ticket are stored in the DMS and scanned for malware like every file (see Documents).
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/1234/attachments' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F 'file=@fehlerbild.png;type=image/png'
createItemAttachment (agent role, within the tenant's mail limits) answers
201 with the file record; its documentId goes into attachmentIds of a mail.
listItemAttachments lists every file of the ticket – uploads, mail
attachments, inline images, the original mails (.eml) – with source, name, mime and portalVisible.
getItemAttachmentContent serves one (download=true as attachment);
it answers 409 scan_pending while the malware scan has not cleared the file – still being scanned (retry after a
few seconds) or failed and scanned again later; DMS answers the same state as not_scanned – and 403 infected
when the scan found malware.
Keep a system in sync
listItems pages by cursor (limit up to 500) and filters by space, type, phase,
status, customer, custom field (cf.<key>) and more. For a sync, store the time of your last run and ask for
updatedSince – see Pagination and delta sync. To react to changes without polling, subscribe
to desk.item.created, desk.item.updated, desk.item.transitioned and desk.item.commented through a
webhook; events carry ids, number, status and title but never the description or custom field
values – read the item for them.