ConnectCloud Developers

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.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

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.

View as Markdown