# Handoff and conversion

Desk (service desk) and forge (software development) work on their own items. Between them – and between two desk
spaces or two forge projects – an item can be **handed off** (*Übergabe*: a new, linked item on the other side, the
original stays), **handed back** (*Zurückgeben*: the receiver returns the handoff with a note) or **converted**
(*Umwandeln*: the item moves to the other module, the original stays as a read-only tombstone). All four directions
work the same way.

| What | Desk | Forge | Permission |
|---|---|---|---|
| List the handoffs of an item | [`listItemHandoffs`](/reference/desk/listItemHandoffs) | [`listForgeItemHandoffs`](/reference/forge/listForgeItemHandoffs) | read |
| Hand off | [`createItemHandoff`](/reference/desk/createItemHandoff) | [`createForgeItemHandoff`](/reference/forge/createForgeItemHandoff) | `desk:write` (agent in the space) / `tenant:forge:write` (developer) |
| Hand back | [`returnItemHandoff`](/reference/desk/returnItemHandoff) | [`returnForgeItemHandoff`](/reference/forge/returnForgeItemHandoff) | as hand off, on the receiving item |
| Convert | [`convertItem`](/reference/desk/convertItem) | [`convertForgeItem`](/reference/forge/convertForgeItem) | as hand off |
| Targets for a picker | desk spaces from [`GET /bootstrap`](/reference/desk/getBootstrap) | [`listHandoffTargets`](/reference/forge/listHandoffTargets) | read |
| Reactions to a hand back | space settings (`settings.handoff`) | [`putProjectHandoffSettings`](/reference/forge/putProjectHandoffSettings) | `desk:admin` / project maintainer |

The receiving module checks the **caller's own permissions** there: a token that may write desk tickets but holds no
forge permission cannot hand a ticket to forge (`tenant:forge:intake` is enough for projects that accept intake).

## Hand off

```bash
curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/1234/handoffs' \
  -H "Authorization: Bearer $TOKEN" -H 'Idempotency-Key: 6c1d…' -H 'Content-Type: application/json' \
  -d '{"target": {"module": "forge", "container": "APP", "typeKey": "fehler"}}'
```

`Idempotency-Key` is required: the handoff id is derived from the item and the key, so a retry with the same key
answers the same handoff instead of creating a second item. `target.container` is the space key (desk) or the project
key (forge); type and status are matched by key, otherwise the target's defaults apply. Empty `title`, `description`
and `priority` are the item's.

- **201** – the other side created its item; `handoff.counterpartRef` names it (`APP-12`, `#123`).
- **202** – the other module could not be reached; the handoff stays `syncState: pending` and is retried every 30
  seconds (backing off to an hour). After 24 hours, or when the receiver refuses, it ends `failed` with a system
  comment on the item. A refusal during the request is **422** `handoff_refused`.
- **503** `forge_unavailable` / `desk_unavailable` – the other module is not configured for the tenant's
  installation.

Desk removes customer data from text it sends to forge (customer name and number, contact and requester names,
e-mail addresses become `[Kunde]`, `[Kontakt]`, `[E-Mail]`). A confidential ticket goes with its full content and
creates a confidential forge item, which only forge admins, project maintainers, its reporter and assignees see.

## Hand back

The **receiving** item hands back with a note (at most 2000 characters). The receiver's settings decide what happens to
it (default: it is closed with the resolution *returned*), the origin's settings what happens to the original (default:
nothing but a system comment with the note). A handoff can be handed back while it is open or closed, otherwise
**409** `handoff_state`.

## Convert

```bash
curl -X POST 'https://api.mbcom.cloud/api/forge/v1/projects/APP/items/12/convert' \
  -H "Authorization: Bearer $TOKEN" -H 'Idempotency-Key: 9a0e…' -H 'Content-Type: application/json' \
  -d '{"target": {"module": "desk", "container": "SUP", "typeKey": "serviceanfrage"}, "version": 7}'
```

The new item takes title, description, type, status, custom fields (by key), labels (by name), dates, assignees,
watchers, the comments with their authors and times, and the attachments (the same documents, not copies). What does
not fit is listed in one system comment on the new item and in the answer's `notes`. Converting within one module is a
move (same item, new space or project, **200**).

The original becomes a **tombstone**: read-only (every write **409** `converted`; while the conversion is being
delivered **409** `conversion_pending`), left out of lists and searches (forge: `includeConverted=true` shows them),
and `GET` answers it with `convertedTo {module, id, ref, path, at}`. A desk ticket with requesters stays as a
**forwarding stub**: customers see it as *Weitergeleitet* and cannot reply there (`409 forwarded`); a new mail creates
a new linked ticket. Items with sub-items are not converted (**409** `has_children`). A forge item moved to another
project answers its old reference with **404** `moved` and `details.redirect`.

## Following the other side

`GET …/handoffs` returns both roles of an item (`origin`, `receiver`) with the cached state of the counterpart:
`counterpartRef`, `counterpartStage` (`new`, `active`, `waiting`, `done`, `cancelled`, `gone`), `counterpartStatusName`,
`state` (`open`, `handed_back`, `closed`, `converted`), `syncState` and the hand-back note. The modules keep each other
up to date through their event feeds within seconds.

For [webhooks](/guides/webhooks), subscribe to `desk.item.handed_off`, `desk.item.handoff_received`,
`desk.item.handed_back`, `desk.item.handback_received` and `desk.item.converted`, or to forge's
`forge.item.handoff_received`, `forge.item.handback_received`, `forge.item.handoff_notice` and
`forge.item.converted_from`. Like every event they carry ids, keys and states only: read the item through the API for
its content.
