ConnectCloud Developers

Change status, fields and labels of many items, or check first with dryRun (desk:write)

POST /api/desk/v1/items/bulk

Module: Desk · operationId: bulkUpdateItems · Tag: Items · Auth: access token (Authorization: Bearer <accessToken>)

Request body

application/json (required)

  • ids (array of string, required): Ids of the items to change
  • addLabelIds (array of string): Labels to add (ids)
  • dryRun (boolean): Change nothing: updated lists the items the change would apply to, failed and missingFields why the others would stay as they are (agent role, writable item, the transition with its required fields and comment). An item already in the status would not change. No automation, mail or live notice follows.
  • patch (ItemInput)
    • assignees (array of object): People working on the item (the whole list)
      • role (string): Key of an assigneeRole entry (bootstrap enums); omitted = the default role
      • userRef (string): Login (e-mail) of the person
    • categoryId (string, nullable): Category of the item
    • confidential (boolean): Only holders of desk:confidential, the item's creator and its assignees see it
    • contact (Ref | null): Masterdata contact person of the item (null clears)
    • customFields (object): Merged; null removes a value
    • customer (Ref | null): Masterdata customer of the item (null clears)
    • dedupeKey (string): Create only; repeated deliveries return the existing item
    • description (string): Markdown
    • dueAt (string (date-time), nullable): Due date
    • dueHasTime (boolean): dueAt carries a time of day (false: only the date counts)
    • estimateMinutes (integer, nullable): Estimate in minutes
    • followUpAt (string (date-time), nullable): When to follow up
    • impact (string, nullable): Impact key of the priority matrix
    • kbWorthy (boolean): Candidate for the knowledge base once resolved
    • labelIds (array of string): Labels of the item (ids; the whole list)
    • parentId (string, nullable): Parent item; a child takes the parent's project (with its own children), detaching keeps it
    • priority (string, nullable): Priority key
    • projectId (string, nullable): Project of the item (decision 19). A child item always has its parent's project: another one is refused (422, field projectId); changing it on a parent changes it on all its descendants
    • projectMilestoneId (string, nullable): Milestone of the item's project it counts for (ADR 0024); cleared when the item leaves the project
    • rank (string): Board order (base-36 fraction)
    • source (string): Create only; key of a source entry (bootstrap enums). API clients send api: the space's due date on receipt (settings.dueOnReceipt) tells the channels apart by it; without a source a ticket counts as manual.
    • sourceOrigin (string): Create only: the activity of Arbeitsplatz › Aktivitäten the ticket is created from (comms:interaction:<id> or comms:calendar:<id>; 400 otherwise); a free reference the portal links to /activities, never changed afterwards
    • sourceRef (string): Reference of the source (e.g. the sender address of a mail ticket)
    • spaceId (string): Create only
    • startOn (string (date), nullable): Start date
    • status (string): Create only
    • summary (string, nullable): Summary pinned above the description (Markdown, trimmed). A new ticket starts with its description (a mail ticket with the trimmed text of its mail), capped at 2000 characters; null fills it that way again. Only the change is in the history, not the text. Never shown in the customer portal or handed to forge. (max length 20000)
    • teams (array of object): Teams of the item (the whole list)
      • role (string): responsible or collaborating (one of responsible, collaborating)
      • teamId (string): Id of the team
    • title (string): Title of the item (max length 500)
    • typeId (string): Create only
    • urgency (string, nullable): Urgency key of the priority matrix
    • weight (integer, nullable): Weight of the item
  • removeLabelIds (array of string): Labels to remove (ids)
  • status (string): Status key to move every item to

Example:

{
  "addLabelIds": [
    "9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"
  ],
  "dryRun": false,
  "ids": [
    "#37",
    "#41"
  ],
  "patch": {
    "priority": "hoch"
  }
}

Responses

  • 200 Per-item result (application/json)

Fields of the 200 answer:

  • dryRun (boolean): True when the request was a dry run (nothing changed).
  • failed (object): Why an item was not changed, in German, per item id
  • missingFields (object): Required fields the status change needs, per failed item id; retry that item with a transition that sends them
  • updated (array of string): The items changed – with dryRun the items the change would apply to

Example 200 answer:

{
  "dryRun": false,
  "failed": {
    "#41": "Der Status „Gelöst“ verlangt die Felder Ursache, Lösung und Abschlussgrund"
  },
  "missingFields": {
    "#41": [
      "cf.ursache",
      "cf.loesung",
      "cf.abschlussgrund"
    ]
  },
  "updated": [
    "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c37"
  ]
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/desk/v1/items/bulk' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addLabelIds":["9b6c7d8e-0f1a-4b2c-9d4e-6f7a8b9c0d02"],"dryRun":false,"ids":["#37","#41"],"patch":{"priority":"hoch"}}'

View as Markdown · Interactive reference · OpenAPI