Set what handed-back items do in a project (tenant:forge:write and maintainer, or tenant:forge:admin)
PUT /api/forge/v1/projects/{key}/handoff-settings
Module: Forge · operationId: putProjectHandoffSettings · Tag: Handoffs · Auth: access token (Authorization: Bearer <accessToken>)
Requires tenant:forge:admin, or tenant:forge:write and project role maintainer or admin. Stores settings.handoff of the project (the project's settings answer it): receiverOnReturn – what an item this project received does when it is handed back (close: status if given, a done or cancelled status, else the first done status of its workflow (a cancelled one without a done status; an item that is closed already stays), resolution returned; or keep); originOnReturn – what an item this project handed off does when it comes back (none, or status: stage new|active|waiting and optionally a status of that stage, else the first status of the stage; nothing when the item is in the stage already). Both reactions are system moves that ignore workflow transitions. Defaults: close / none. Writes forge.config.updated.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
key |
path | string | yes | Project key (e.g. APP) |
Request body
application/json (required)
originOnReturn(object): What the origin item does when its handoff comes backaction(string):none: nothing;status: move it to a status ofstage(one ofnone,status)stage(string): The stage to move the origin item to (one ofnew,active,waiting)status(string): status: a status key of the stage
receiverOnReturn(object): What a received item does when it is handed backaction(string):close: move it tostatus;keep: leave it as it is (one ofclose,keep)status(string): close: a done or cancelled status key of the project
Example:
{
"originOnReturn": {
"action": "status",
"stage": "active",
"status": "in_arbeit"
},
"receiverOnReturn": {
"action": "close",
"status": "erledigt"
}
}
Responses
- 200 Saved (with defaults filled) (
application/json) - 400 Error (
application/json) - 403 Error (
application/json) - 404 Error (
application/json) - 409 Error (
application/json)
Fields of the 200 answer:
originOnReturn(object): What the origin item does when its handoff comes backaction(string):none: nothing;status: move it to a status ofstage(one ofnone,status)stage(string): The stage to move the origin item to (one ofnew,active,waiting)status(string): status: a status key of the stage
receiverOnReturn(object): What a received item does when it is handed backaction(string):close: move it tostatus;keep: leave it as it is (one ofclose,keep)status(string): close: a done or cancelled status key of the project
Example 200 answer:
{
"originOnReturn": {
"action": "status",
"stage": "active",
"status": "in_arbeit"
},
"receiverOnReturn": {
"action": "close",
"status": "erledigt"
}
}
Example request
curl -X PUT 'https://api.mbcom.cloud/api/forge/v1/projects/string/handoff-settings' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"originOnReturn":{"action":"status","stage":"active","status":"in_arbeit"},"receiverOnReturn":{"action":"close","status":"erledigt"}}'