ConnectCloud Developers

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 back
    • action (string): none: nothing; status: move it to a status of stage (one of none, status)
    • stage (string): The stage to move the origin item to (one of new, active, waiting)
    • status (string): status: a status key of the stage
  • receiverOnReturn (object): What a received item does when it is handed back
    • action (string): close: move it to status; keep: leave it as it is (one of close, 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 back
    • action (string): none: nothing; status: move it to a status of stage (one of none, status)
    • stage (string): The stage to move the origin item to (one of new, active, waiting)
    • status (string): status: a status key of the stage
  • receiverOnReturn (object): What a received item does when it is handed back
    • action (string): close: move it to status; keep: leave it as it is (one of close, 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"}}'

View as Markdown · Interactive reference · OpenAPI