# 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](/reference/desk). The [Quickstart](/guides/quickstart) creates a first ticket; this guide covers
what a real integration needs around it.

| Step | Operations | Permission |
|---|---|---|
| Read the configuration | [`getBootstrap`](/reference/desk/getBootstrap) | `desk:read` |
| Create | [`checkItem`](/reference/desk/checkItem), [`createItem`](/reference/desk/createItem) | `desk:write` |
| Read and sync | [`getItem`](/reference/desk/getItem), [`listItems`](/reference/desk/listItems), [`searchItems`](/reference/desk/searchItems) | `desk:read` |
| Change and move | [`updateItem`](/reference/desk/updateItem), [`transitionItem`](/reference/desk/transitionItem) | `desk:write` |
| Reply | [`addItemEntry`](/reference/desk/addItemEntry), [`createItemMail`](/reference/desk/createItemMail), [`listItemEntries`](/reference/desk/listItemEntries) | `desk:write` (agent in the space) / `desk:read` |
| Attachments | [`createItemAttachment`](/reference/desk/createItemAttachment), [`listItemAttachments`](/reference/desk/listItemAttachments), [`getItemAttachmentContent`](/reference/desk/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`](/reference/desk/getBootstrap).

```bash
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`](/reference/desk/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.

```bash
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](/guides/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`](/reference/desk/transitionItem), never through
`PATCH`:

```bash
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`](/reference/desk/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`](/reference/desk/listItemEntries)): comments, internal
notes and mails in and out (`kind` `comment`, `email_in`, `email_out`, `system`).

**Comment or note** – [`addItemEntry`](/reference/desk/addItemEntry) with `body` (Markdown) and `visibility`:

```bash
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`](/reference/desk/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`](/reference/desk/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`](/reference/desk/listItemParticipants),
[`createItemParticipant`](/reference/desk/createItemParticipant)).

## Attachments

Files of a ticket are stored in the DMS and scanned for malware like every file (see [Documents](/guides/dms)).

```bash
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`](/reference/desk/createItemAttachment) (agent role, within the tenant's mail limits) answers
**201** with the file record; its `documentId` goes into `attachmentIds` of a mail.
[`listItemAttachments`](/reference/desk/listItemAttachments) lists every file of the ticket – uploads, mail
attachments, inline images, the original mails (`.eml`) – with `source`, `name`, `mime` and `portalVisible`.
[`getItemAttachmentContent`](/reference/desk/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`](/reference/desk/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](/guides/pagination). To react to changes without polling, subscribe
to `desk.item.created`, `desk.item.updated`, `desk.item.transitioned` and `desk.item.commented` through a
[webhook](/guides/webhooks); events carry ids, number, status and title but never the description or custom field
values – read the item for them.
