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 |
listForgeItemHandoffs |
read |
| Hand off | createItemHandoff |
createForgeItemHandoff |
desk:write (agent in the space) / tenant:forge:write (developer) |
| Hand back | returnItemHandoff |
returnForgeItemHandoff |
as hand off, on the receiving item |
| Convert | convertItem |
convertForgeItem |
as hand off |
| Targets for a picker | desk spaces from GET /bootstrap |
listHandoffTargets |
read |
| Reactions to a hand back | space settings (settings.handoff) |
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
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.counterpartRefnames it (APP-12,#123). - 202 – the other module could not be reached; the handoff stays
syncState: pendingand is retried every 30 seconds (backing off to an hour). After 24 hours, or when the receiver refuses, it endsfailedwith a system comment on the item. A refusal during the request is 422handoff_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
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, 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.