Tracker Item Operations

Getting a List of Tracker Items in a Tracker

GET /v3/trackers/{trackerId}/items will return a list of tracker item references in a specific tracker.

Response example:

{
  "page": 1,
  "pageSize": 25,
  "total": 9,
  "itemRefs": [
    {
      "id": 1042,
      "name": "Bug for \"Weight transfer Test\"",
      "type": "TrackerItemReference"
    },
    {
      "id": 1041,
      "name": "Bug for \"Suspension Test\"",
      "type": "TrackerItemReference"
    },
    {
      "id": 1040,
      "name": "Bug for \"Driving range must be 1000km or more Test\"",
      "type": "TrackerItemReference"
    },
    ...
  ]
}

Getting a List of Tracker Items Based on CbQL Query

GET /v3/items/query or POST /v3/items/query will accept a CbQL query to determine a filtering criteria for the retrieved tracker items.

For example if we are looking for all the tracker items with High priority we can use the following query: priority='High'

Request body:

{
  "page": 1,
  "pageSize": 25,
  "queryString": "priority='High'"
}

Response:

{
  "page": 1,
  "pageSize": 25,
  "total": 1,
  "items": [
    {
      "id": 1046,
      "name": "Implement car software",
      "descriptionFormat": "Wiki",
      ...
      "priority": {
        "id": 2,
        "name": "High",
        "type": "ChoiceOptionReference"
      },
      ...
    }
  ]
}

Getting the Details of a Tracker Item

GET /v3/items/{itemId} will return detailed information about a tracker item.

Response example:

{
  "id": 1046,
  "name": "Implement car software",
  "descriptionFormat": "Wiki",
  "createdAt": "2020-08-04T10:53:49.963",
  "createdBy": {
    "id": 1,
    "name": "bond",
    "type": "UserReference"
  },
  "modifiedAt": "2020-08-04T10:53:49.963",
  "modifiedBy": {
    "id": 1,
    "name": "bond",
    "type": "UserReference"
  },
  "version": 1,
  "assignedTo": [
    {
      "id": 2,
      "name": "Developer",
      "type": "RoleReference"
    }
  ],
  "storyPoints": 5,
  "tracker": {
    "id": 4308,
    "name": "Tasks",
    "type": "TrackerReference"
  },
  "children": [],
  "customFields": [
    {
      "fieldId": 1006,
      "name": "Occurrence",
      "values": [
        {
          "id": 2,
          "name": "Often",
          "type": "ChoiceOptionReference"
        }
      ],
      "type": "ChoiceFieldValue"
    },
    {
      "fieldId": 10001,
      "name": "Detected On Date",
      "value": "2020-08-10T09:00:00.000",
      "type": "DateFieldValue"
    }
  ],
  "priority": {
    "id": 2,
    "name": "High",
    "type": "ChoiceOptionReference"
  },
  "status": {
    "id": 3,
    "name": "In progress",
    "type": "ChoiceOptionReference"
  },
  "subjects": [
    {
      "id": 1007,
      "name": "As User, I want to have a software in my car, which is easy to use",
      "type": "TrackerItemReference"
    }
  ],
  "resolutions": [],
  "severities": [],
  "teams": [
    {
      "id": 1127,
      "name": "Developer Team",
      "type": "TrackerItemReference"
    }
  ],
  "tags": [
    {
      "createdAt": "2022-08-04T13:53:40.796Z",
      "createdBy": {
        "id": 0,
        "name": "string",
        "type": "string",
        "email": "string"
      },
      "hidden": true,
      "id": 0,
      "name": "string",
      "privateLabel": true
    }
  ],
  "versions": [
    {
      "id": 1001,
      "name": "Sprint 1.1",
      "type": "TrackerItemReference"
    }
  ],
  "ordinal": 6,
  "typeName": "Task",
  "comments": []
    }

}

Creating a Tracker Item

POST /v3/trackers/{trackerId}/items will create a tracker item on a specific tracker.

Each mandatory field must be provided.

Request body example:

{
  "name": "Implement car software",
  "storyPoints": 5,
  "priority": {
    "id": 2,
    "name": "High",
    "type": "ChoiceOptionReference"
  },
  "subjects": [
    {
      "id": 1007,
      "name": "As User, I want to have a software in my car, which is easy to use",
      "type": "TrackerItemReference"
    }
  ]
}

Response example:

{
  "id": 1335,
  "name": "Implement car software",
  "descriptionFormat": "PlainText",
  "createdAt": "2020-08-05T13:54:43.941",
  "createdBy": {
    "id": 1,
    "name": "bond",
    "type": "UserReference"
  },
  "modifiedAt": "2020-08-05T13:54:43.941",
  "modifiedBy": {
    "id": 1,
    "name": "bond",
    "type": "UserReference"
  },
  "version": 1,
  "assignedTo": [],
  "storyPoints": 5,
  "tracker": {
    "id": 4308,
    "name": "Tasks",
    "type": "TrackerReference"
  },
  "children": [],
  "customFields": [],
  "priority": {
    "id": 2,
    "name": "High",
    "type": "ChoiceOptionReference"
  },
  "status": {
    "id": 1,
    "name": "New",
    "type": "ChoiceOptionReference"
  },
  "subjects": [
    {
      "id": 1007,
      "name": "As User, I want to have a software in my car, which is easy to use",
      "type": "TrackerItemReference"
    }
  ],
  "resolutions": [],
  "severities": [],
  "teams": [],
  "versions": [],
  "ordinal": 15,
  "typeName": "Task",
  "comments": []
}

TrackerItem Model Structure

TrackerItem model is used to acquire or modify all information about a tracker item in any tracker therefore it should be flexible enough to represent anything from a Requirement to a Test Case item.

In Codebeamer we have built-in fields (Status, Priority, Summary, etc.) and custom fields which are tracker specific (Test Steps on a Test Case or any custom field defined by the users).

Basic Explicit Fields

The most used built-in fields are extracted explicitly (name, storyPoints, description, etc.) so if you are about to modify only those there is no need to use any special model like in the following request body:

{
  "name": "Implement car software",
  "storyPoints": 5
}

Choice Option Explicit Fields

When the explicitly defined field is a choice field (like status, priority or subjects) a Reference model must be provided.

{
  "name": "Implement car software",
  "priority": {
    "id": 2,
    "name": "High",
    "type": "ChoiceOptionReference"
  },
  "status": {
    "id": 1,
    "name": "New",
    "type": "ChoiceOptionReference"
  },
  "subjects": [
    {
      "id": 1007,
      "name": "As User, I want to have a software in my car, which is easy to use",
      "type": "TrackerItemReference"
    }
  ]
}

Custom Fields

For tracker specific fields there aren't any explicit fields provided as the Swagger definition requires a fixed model structure. These field values are presented in the customFields attribute like in the following Test Case example:

{
  "name": "Test Case 2",
  "customFields": [
    {
      "fieldId": 10003,
      "name": "Reusable",
      "value": false,
      "type": "BoolFieldValue"
    },
    {
      "fieldId": 1001,
      "name": "User custom choice",
      "values": [
        {
          "id": 2,
          "name": "Second option",
          "type": "ChoiceOptionReference"
        }
      ],
      "type": "ChoiceFieldValue"
    },
    {
      "fieldId": 1000000,
      "name": "Test Steps",
      "values": [
        [
          {
            "fieldId": 1000001,
            "name": "Action",
            "value": "Enter an invalid username and an invalid password.Click login button",
            "type": "WikiTextFieldValue"
          },
          {
            "fieldId": 1000002,
            "name": "Expected result",
            "value": "The application should display an error message and re-open the login page.",
            "type": "WikiTextFieldValue"
          },
          {
            "fieldId": 1000003,
            "name": "Critical",
            "value": false,
            "type": "BoolFieldValue"
          }
        ]
      ],
      "type": "TableFieldValue"
    }
  ]
}

In order to find out the fieldId-s and model types to use here we need to discover the field configuration of the tracker described in the Discovering the project structure section.

To find the fieldId-s we need to call the GET /v3/trackers/{trackerId}/fields endpoint:

Response:

[
  ...
  {
    "id": 1001,
    "name": "User custom choice",
    "type": "FieldReference",
    "trackerId": 4309
  },
  ...
  {
    "id": 10003,
    "name": "Reusable",
    "type": "FieldReference",
    "trackerId": 4309
  },
  ...
  {
    "id": 1000000,
    "name": "Test Steps",
    "type": "FieldReference",
    "trackerId": 4309
  }
]

Custom Basic Fields

Getting information about Resuable field via calling GET /v3/trackers/{trackerId}/fields/10003:

Response:

{
  "id": 10003,
  "name": "Reusable",
  "type": "BoolField",
  "hidden": false,
  "valueModel": "BoolFieldValue",
  "mandatoryInStatuses": [ ... ]
}

Here we can find that the valueModel of this field is "BoolFieldValue". It means that if want to set a value for this field as custom field we need to add a BoolFieldValue model into the customFields list.

Looking up the model in the Swagger UI of your instance ( https://{codeBeamerUrl}/v3/swagger/editor.spr ):

It will describe the required structure:

Based on this information we can construct our field value model:

"customFields": [
  {
    "fieldId": 10003,
    "name": "Reusable",
    "value": false,
    "type": "BoolFieldValue"
  }
]

Please note: the type parameter is always telling what type of object you are sending.

In this case a BoolFieldValue is provided so "type": "BoolFieldValue" this is needed because of the flexibility of the tracker configuration.

Custom Choice Fields

For User custom choice:

GET /v3/trackers/{trackerId}/fields/1001:

{
  "id": 1001,
  "name": "User custom choice",
  "type": "OptionChoiceField",
  "hidden": false,
  "valueModel": "ChoiceFieldValue<ChoiceOptionReference>",
  "mandatoryInStatuses": [],
  "multipleValues": false,
  "options": [
    {
      "id": 0,
      "name": "Unset",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 1,
      "name": "First option",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 2,
      "name": "Second option",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 3,
      "name": "Third option",
      "type": "ChoiceOptionReference"
    }
  ],
  "referenceType": "ChoiceOptionReference"
}

The valueModel is a ChoiceFieldValue<ChoiceOptionReference> which means that we will need a ChoiceFieldValue which contains ChoiceOptionReference as values.

The field definition defines the available options also:

  "options": [
    {
      "id": 0,
      "name": "Unset",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 1,
      "name": "First option",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 2,
      "name": "Second option",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 3,
      "name": "Third option",
      "type": "ChoiceOptionReference"
    }
  ]

Now we have all information to construct our customFields item:

"customFields": [
    {
      "fieldId": 1001,
      "name": "User custom choice",
      "values": [
        {
          "id": 2,
          "name": "Second option",
          "type": "ChoiceOptionReference"
        }
      ],
      "type": "ChoiceFieldValue"
    }
]

Custom Reference Fields

GET /v3/trackers/{trackerId}/fields/1002

  {
    "id": 1002,
    "name": "System",
    "description": "System which caused the Defect",
    "type": "TrackerItemChoiceField",
    "hidden": false,
    "valueModel": "ChoiceFieldValue<TrackerItemReference>",
    "mandatoryInStatuses": [],
    "multipleValues": false,
    "referenceType": "TrackerItemReference"
  },

This field needs ChoiceFieldValue<TrackerItemReference> valueModel so we will need to put a TrackerItemReference into ChoiceFieldValue:

    {
      "fieldId": 1002,
      "name": "System",
      "type": "ChoiceFieldValue",
      "values": [ <TrackerItemReferences> ]
    },

To get the available options choice fields we can call the GET /v3/items/{itemId}/fields/{fieldId}/options endpoint.

GET /v3/items/{itemId}/fields/1002/options

{
  "page": 1,
  "pageSize": 25,
  "total": 2,
  "references": [
    {
      "id": 2750873,
      "name": "Rocket Science",
      "type": "TrackerItemReference"
    },
    {
      "id": 2750874,
      "name": "Warp System",
      "type": "TrackerItemReference"
    }
  ]
}

The customFields item:

"customFields": [
    {
      "fieldId": 1002,
      "name": "System",
      "values": [
        {
          "id": 2750873,
          "name": "Rocket Science",
          "type": "TrackerItemReference"
        },
      ],
      "type": "ChoiceFieldValue"
    }
]

Custom Table Fields

For Test Steps:

GET /v3/trackers/{trackerId}/fields/100000:

{
  "id": 1000000,
  "name": "Test Steps",
  "type": "TableField",
  "hidden": false,
  "valueModel": "TableFieldValue",
  "mandatoryInStatuses": [],
  "columns": [
    {
      "id": 1000001,
      "name": "Action",
      "type": "WikiTextField",
      "hidden": false,
      "valueModel": "WikiTextFieldValue",
      "mandatoryInStatuses": [ ... ]
    },
    {
      "id": 1000002,
      "name": "Expected result",
      "type": "WikiTextField",
      "hidden": false,
      "valueModel": "WikiTextFieldValue",
      "mandatoryInStatuses": []
    },
    {
      "id": 1000003,
      "name": "Critical",
      "type": "BoolField",
      "hidden": false,
      "valueModel": "BoolFieldValue",
      "mandatoryInStatuses": []
    },
    {
      "id": 1000004,
      "name": "Id",
      "type": "WikiTextField",
      "hidden": true,
      "valueModel": "WikiTextFieldValue",
      "mandatoryInStatuses": []
    }
  ]
}

It needs a TableFieldValue:

The values here are a list of lists representing the rows and columns for the table field and the field definition also defines the columns:

"columns": [
  {
    "id": 1000001,
    "name": "Action",
    "type": "WikiTextField",
    "hidden": false,
    "valueModel": "WikiTextFieldValue",
    "mandatoryInStatuses": [ ... ]
  },
  {
     "id": 1000002,
    "name": "Expected result",
    "type": "WikiTextField",
    "hidden": false,
    "valueModel": "WikiTextFieldValue",
    "mandatoryInStatuses": []
  },
  {
    "id": 1000003,
    "name": "Critical",
    "type": "BoolField",
    "hidden": false,
    "valueModel": "BoolFieldValue",
    "mandatoryInStatuses": []
  },
  {
    "id": 1000004,
    "name": "Id",
    "type": "WikiTextField",
    "hidden": true,
    "valueModel": "WikiTextFieldValue",
    "mandatoryInStatuses": []
  }
]

The Id field is hidden so we need to construct a [WikiTextFieldValue, WikiTextFieldValue, BoolFieldValue] list for each row.

The final custom field value:

"customFields": [
    {
      "fieldId": 1000000,
      "name": "Test Steps",
      "values": [
        [
          {
            "fieldId": 1000001,
            "name": "Action",
            "value": "Action 1",
            "type": "WikiTextFieldValue"
          },
          {
            "fieldId": 1000002,
            "name": "Expected result",
            "value": "Expected result 1",
            "type": "WikiTextFieldValue"
          },
          {
            "fieldId": 1000003,
            "name": "Critical",
            "value": false,
            "type": "BoolFieldValue"
          }
        ],
        [
          {
            "fieldId": 1000001,
            "name": "Action",
            "value": "Action 2",
            "type": "WikiTextFieldValue"
          },
          {
            "fieldId": 1000002,
            "name": "Expected result",
            "value": "Expected result 2",
            "type": "WikiTextFieldValue"
          },
          {
            "fieldId": 1000003,
            "name": "Critical",
            "value": false,
            "type": "BoolFieldValue"
          }
        ]
      ],
      "type": "TableFieldValue"
    }
]

It will create two test steps:

Modifying a Tracker Item

Modifying the Tracker Item as a REST Resource

PUT /v3/items/{itemId} will replace the whole state of the tracker item as it is provided in the request body.

For example there is an existing item:

{
  "id": 1336,
  "name": "Implement car software",
  "descriptionFormat": "PlainText",
  "createdAt": "2020-08-05T14:11:40.517",
  "createdBy": {
    "id": 1,
    "name": "bond",
    "type": "UserReference"
  },
  "modifiedAt": "2020-08-05T14:11:40.517",
  "modifiedBy": {
    "id": 1,
    "name": "bond",
    "type": "UserReference"
  },
  "version": 1,
  "assignedTo": [],
  "storyPoints": 5,
  "tracker": {
    "id": 4308,
    "name": "Tasks",
    "type": "TrackerReference"
  },
  "children": [],
  "customFields": [],
  "priority": {
    "id": 2,
    "name": "High",
    "type": "ChoiceOptionReference"
  },
  "status": {
    "id": 1,
    "name": "New",
    "type": "ChoiceOptionReference"
  },
  "subjects": [
    {
      "id": 1007,
      "name": "As User, I want to have a software in my car, which is easy to use",
      "type": "TrackerItemReference"
    }
  ],
  "resolutions": [],
  "severities": [],
  "teams": [],
  "versions": [],
  "ordinal": 16,
  "typeName": "Task",
  "comments": []
}

To change only the name of the item the whole model must provided with the modified name property.

Request body:

{
  "id": 1336,
  "name": "New name",
  "descriptionFormat": "PlainText",
  "createdAt": "2020-08-05T14:11:40.517",
  "createdBy": {
    "id": 1,
    "name": "bond",
    "type": "UserReference"
  },
  "modifiedAt": "2020-08-05T14:11:40.517",
  "modifiedBy": {
    "id": 1,
    "name": "bond",
    "type": "UserReference"
  },
  "version": 1,
  "assignedTo": [],
  "storyPoints": 5,
  "tracker": {
    "id": 4308,
    "name": "Tasks",
    "type": "TrackerReference"
  },
  "children": [],
  "customFields": [],
  "priority": {
    "id": 2,
    "name": "High",
    "type": "ChoiceOptionReference"
  },
  "status": {
    "id": 1,
    "name": "New",
    "type": "ChoiceOptionReference"
  },
  "subjects": [
    {
      "id": 1007,
      "name": "As User, I want to have a software in my car, which is easy to use",
      "type": "TrackerItemReference"
    }
  ],
  "resolutions": [],
  "severities": [],
  "teams": [],
  "versions": [],
  "ordinal": 16,
  "typeName": "Task",
  "comments": []
}

Please note: if only the name parameter is provided then it will mean that all other fields needs to be cleared.

The following request body will return an error as the status field cannot be cleared:

{
  "name": "New name 2"
}

Error response:

{
  "message": "State transition from New to -- is not defined for [TASK-1336] - New name",
  "resourceUri": "/items/1336"
}

Modifying a Specific Field on a Tracker Item

PUT /v3/items/{itemId}/fields can be used to change a specific field on a tracker item without providing the whole TrackerItem model.

This endpoint requires to handle the built-in fields as custom fields and provide them as FieldValue models.

Modifying the Name of the Item

Finding out the fieldId of name field using GET /v3/trackers/{trackerId}/fields

[
  {
    "id": 0,
    "name": "ID",
    "type": "FieldReference",
    "trackerId": 4308
  },
  ...
  {
    "id": 3,
    "name": "Summary",
    "type": "FieldReference",
    "trackerId": 4308
  },
  ...
]

As next step let's get the field definition via GET /v3/trackers/{trackerId}/fields/3

{
  "id": 3,
  "name": "Summary",
  "type": "TextField",
  "hidden": false,
  "valueModel": "TextFieldValue",
  "mandatoryInStatuses": [ ... ],
  "trackerItemField": "name"
}

As you can see there is a trackerItemField property which means that it has an explicit property on the TrackerItem model, but in this case we need to handle it custom field.

So we'll need to construct a TextFieldValue as valueModel for the update

So the final request body:

{
  "fieldValues": [
    {
      "fieldId": 3,
      "type": "TextFieldValue",
      "name": "Summary",
      "value": "New name 2"
    }
  ]
}

It will update only the provided field values and keep every other field as it is.

Insert HTML Code into Wikitext Field

You may take advantage of the HTML Wiki plugin for this: Wiki Markup and Plugins and then run a:

PUT call @ /v3/items/{itemId}/fields:

{
    "fieldValues": [
      {
        "fieldId": 80,
        "name": "Description",
        "value": "[{Html\r\n\r\n<b> This is some bold text with special charachter @@@###</b> <u> This is some underline text </u> <i> This is some italics text </i> <a href=\\\"https://www.google.com\\\">Visit google!</a> <p>RapidTables ™ </p> <p>RapidTables ® </p> <table style=\\\"width:100%\\\"> <tr> <th>Name:</th> <td>John</td> </tr> <tr> <th rowspan=\\\"2\\\">Telephone:</th> <td>55577854</td> </tr> <tr> <td>55577855</td> </tr> </table> <ul> <li>Coffee</li> <li>Tea</li> <li>Milk</li> </ul>\r\n}]",
        "type": "WikiTextFieldValue"
      }
    ]
}

Change the Value of Description Field and its Type from Plain Text to Wikitext

PUT @ /v3/items/{itemId}/fields:

{
  "fieldValues": [
            {
      "fieldId": 80,
      "name": "Description",
      "value": "[{Html\r\n\r\n<b> This is some bold text with special charachter @@@###</b> <u> This is some underline text </u> <i> This is some italics text </i> <a href=\\\"https://www.google.com\\\">Visit google!</a> <p>RapidTables ™ </p> <p>RapidTables ® </p> <table style=\\\"width:100%\\\"> <tr> <th>Name:</th> <td>John</td> </tr> <tr> <th rowspan=\\\"2\\\">Telephone:</th> <td>55577854</td> </tr> <tr> <td>55577855</td> </tr> </table> <ul> <li>Coffee</li> <li>Tea</li> <li>Milk</li> </ul>\r\n}]",
      "type": "WikiTextFieldValue"
    },
    {
      "fieldId": 84,
      "name": "Description Format",
      "value": "W",
      "type": "TextFieldValue"
    }
  ]
}

Bulk Update Specific Fields on a Large Number of Tracker Items

PUT /v3/items/fields (from Codebeamer Dorothy) can be used to change specific fields on a large number of tracker items without providing the whole TrackerItem models.

Example request body to add a user to the "Assigned to" field of two tracker items.

[
  {
    "itemId": 1000,
    "fieldValues": [
      {
        "values": [
          {
            "id": 714,
            "type": "UserReference"
          }
        ],
        "fieldId": 5,
        "type": "ChoiceFieldValue"
      }
    ]
  },
  {
    "itemId": 1001,
    "fieldValues": [
      {
        "values": [
          {
            "id": 714,
            "type": "UserReference"
          }
        ],
        "fieldId": 5,
        "type": "ChoiceFieldValue"
      }
    ]
  }
]

Atomic parameter

To run the bulk update in an atomic transaction (if one update fails all of the updates is getting rollbacked) please provide atomic=true as a request param like

http://server-name:8080/cb/api/v3/items/fields?atomic=true

The default value for atomic is false.

Response Example responses for the three possible outcomes.

Response when every update is successful:

{
  "successfulOperationsCount": 2
}

The atomic transaction's response with failure (atomic=true):

{
  "message": "At least one update failed",
  "resourceUri": "items/fields",
  "failedOperations": [
    {
      "id": 2147483647,
      "exceptionMessage": "Tracker item is not found."
    }
  ]
}

Non-Atomic transaction's response: success plus failure (atomic=false):

{
  "successfulOperationsCount": 1,
  "failedOperations": [
    {
      "id": 2147483647,
      "exceptionMessage": "Tracker item is not found."
    }
  ]
}

Making a Tracker Item Status Transition

Finding out the fieldId of status field using GET /v3/trackers/{trackerId}/fields

[
  {
    "id": 0,
    "name": "ID",
    "type": "FieldReference",
    "trackerId": 4308
  },
  ...
  {
    "id": 7,
    "name": "Status",
    "type": "FieldReference",
    "trackerId": 4308
  }
  ...
]

As next step let's get the field definition via GET /v3/trackers/{trackerId}/fields/7

{
  "id": 7,
  "name": "Status",
  "type": "OptionChoiceField",
  "hidden": false,
  "valueModel": "ChoiceFieldValue<ChoiceOptionReference>",
  "mandatoryInStatuses": [],
  "multipleValues": false,
  "options": [
    {
      "id": 0,
      "name": "Unset",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 1,
      "name": "New",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 2,
      "name": "Suspended",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 3,
      "name": "In progress",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 4,
      "name": "Partly completed",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 5,
      "name": "Completed",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 6,
      "name": "To Verify",
      "type": "ChoiceOptionReference"
    },
    {
      "id": 7,
      "name": "InQA",
      "type": "ChoiceOptionReference"
    }
  ],
  "trackerItemField": "status",
  "referenceType": "ChoiceOptionReference"
}

As you can see there is a trackerItemField property which provides the connection between the explicit properties and the built-in fields. It means now that the Status field is represented as status in the TrackerItem model.

So we'll need to construct a ChoiceFieldValue<ChoiceOptionReference> as valueModel for the update, check Tracker Item Operations for details.

So the final request body:

{
  "fieldValues": [
    {
      "fieldId": 7,
      "name": "Status",
      "values": [
        {
          "id": 3,
          "name": "In progress",
          "type": "ChoiceOptionReference"
        }
      ],
      "type": "ChoiceFieldValue"
    }
  ]
}

It will update only the provided field values and keep every other field as they are.

Moving a Tracker Item in the Tracker Outline

We have introduced a few endpoints to support this functionality:

• GET /v3/items/{itemId}/children - Retrieve the list of child tracker items of a tracker item
• PUT /v3/items/{itemId}/children - Reorder the child tracker items of a tracker item
• POST /v3/items/{itemId}/children - Add a new child tracker item of a tracker item
• PATCH /v3/items/{itemId}/children - Insert or remove a child tracker item of a tracker item

If you are about to move an item to the tracker root level you can use the following endpoints:

• GET /v3/trackers/{trackerId}/children - Retrieve the list of child tracker items of a tracker
• PUT /v3/trackers/{trackerId}/children - Reorder the child tracker item references of a tracker
• POST /v3/trackers/{trackerId}/children - Add a new child tracker item of a tracker
• PATCH /v3/trackers/{trackerId}/children - Insert or remove a child tracker item of a tracker

These endpoints work the same way, only the outline level difference is present.

Therefore we will look into the tracker item related endpoints:

Retrieve the List of Child Tracker Items

Using the GET /v3/items/{itemId}/children endpoint will retrieve the current list of child items:

{
  "page": 1,
  "pageSize": 25,
  "total": 3,
  "itemRefs": [
    {
      "id": 54220,
      "name": "Find Radio Station Test",
      "type": "TrackerItemReference"
    },
    {
      "id": 54222,
      "name": "Scan Radio Station Test",
      "type": "TrackerItemReference"
    },
    {
      "id": 54223,
      "name": "Select Radio Station Test",
      "type": "TrackerItemReference"
    }
  ]
}

Reorder the Child Tracker Items

Using the PUT /v3/items/{itemId}/children endpoint we can reorder the children.

Request Body for the new child item order (moving 54223 into the second place):

{
  "children": [
    {
      "id": 54220,
      "name": "Find Radio Station Test",
      "type": "TrackerItemReference"
    },
    {
      "id": 54223,
      "name": "Select Radio Station Test",
      "type": "TrackerItemReference"
    },
    {
      "id": 54222,
      "name": "Scan Radio Station Test",
      "type": "TrackerItemReference"
    }
  ]
}

Response:

{
  "page": 1,
  "pageSize": 25,
  "total": 3,
  "itemRefs": [
    {
      "id": 54220,
      "name": "Find Radio Station Test",
      "type": "TrackerItemReference"
    },
    {
      "id": 54223,
      "name": "Select Radio Station Test",
      "type": "TrackerItemReference"
    },
    {
      "id": 54222,
      "name": "Scan Radio Station Test",
      "type": "TrackerItemReference"
    }
  ]
}

Add a New Child Tracker Item

Using the POST /v3/items/{itemId}/children endpoint we can add a new child.

Request Body:

{
  "id": 54206
}

Response:

{
  "itemReference": {
    "id": 54206,
    "name": "Auto Scale on Highway Test",
    "type": "TrackerItemReference"
  },
  "index": 3
}

The new item (Auto Scale on Highway Test #54206) is added into the 3. index of the child list.

Insert a Child Tracker Item

Using the PATCH /v3/items/{itemId}/children endpoint we can insert a new child into a specified position.

Request:

/v3/items/54218/children?mode=INSERT

{
  "itemReference": {
    "id": 54217,
    "name": "Night Mode Test",
    "type": "TrackerItemReference"
  },
  "index": 0
}

Response:

{
  "itemReference": {
    "id": 54217,
    "name": "Night Mode Test",
    "type": "TrackerItemReference"
  },
  "index": 0
}

The new item is inserted into the first place of the child list.

Remove a Child Tracker Item

Using the PATCH /v3/items/{itemId}/children endpoint we can remove a new child.

Request:

/v3/items/54218/children?mode=REMOVE

{
  "itemReference": {
    "id": 54217,
    "name": "Night Mode Test",
    "type": "TrackerItemReference"
  },
  "index": 0
}

Please note: You need to provide the proper index alongside with the tracker item reference.

Response:

{
  "itemReference": {
    "id": 54217,
    "name": "Night Mode Test",
    "type": "TrackerItemReference"
  },
  "index": 0
}

The new item is removed form the first place of the child list and moved one level upper (it will be moved next to the parent item).

Deleting a Tracker Item

DELETE /v3/items/{itemId} will delete a tracker item and return HTTP 200 in case of success.

Deleting Tracker Items Associations

The default procedure implies the combined usage of 2 endpoints:

• GET /v3/items/{itemId}/relations and then,
• DELETE /v3/associations/{associationId}/

1) Gather the Item ID having the association, let's say http://localhost:8080/cb/issue/5850CB:/images/out.png, therefore 5850

2) Use that ID to execute the GET call at /v3/items/{itemId}/relations:

3) cB should return a response similar to this:

{
  "itemId": {
    "id": 5850,
    "version": 4
  },
  "downstreamReferences": [],
  "upstreamReferences": [],
  "incomingAssociations": [],
  "outgoingAssociations": [
    {
      "type": "OutgoingTrackerItemAssociation",
      "id": 21594,
      "itemRevision": {
        "id": 5872,
        "version": 3
      }
    }
  ]
}

4) From the above, take the 21594 ID

5) To remove the association, execute a DELETE call at /v3/associations/{associationId}/ by providing 21594:

Pagination

For the following endpoints:

GET /v3/trackers/:trackerId/baseline

GET /v3/items/:itemId/attachments

and for all all other endpoints where page, pageSize and total parameters are not documented otherwise, the following will apply:

• They are additional pieces of information in the response, however the response will always return the whole result.
• It won't be possible to change which page to return/how many elements on that page.
• The page will always be 1.
• The pageSize will always be equal to the total number of elements.
• It is so by design to aim for a "future-proof" solution. This way, it will be possible to implement the paging later without breaking the API schema.