ConnectCloud Developers

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" }
  }'
  • spaceId and typeId take ids or keys. Without typeId the space's default type is used, without status the first status of phase new. source: api marks the channel (a key of enums.source).
  • Idempotency-Key (kept 7 days) and dedupeKey (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_fields names the required fields of the type's layout in missingFields; 400 invalid a value that does not fit (field names it).
  • The answer is the item with id, number (the ticket number customers see, #1234) and version. 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.

View as Markdown