Swagger documented Rest API examples

This page will provide you some examples about the usage of our Swagger documented API.

The general documentation can be found here.

The detailed documentation of the Rest API endpoints can be found on your codeBeamer instance under the /v2/swagger/editor.spr path.

How to query tracker items with cbQL

Examples of this end point are going to use the Task tracker of Intland Software's Scrum

Query a tracker item with a specific cbQL query

The API can be called with a complex cbQL string to find tracker items.

GET http://localhost:8080/cb/api/v2/item?page=1&pageSize=25&queryString=project.id%20IN%20%282%29%20AND%20tracker.id%20IN%20%282284%29%20AND%20%28modifiedAt%20%3E%3D%20-1m%20AND%20modifiedAt%20%3C%3D%20%2B0q%29

The queryString parameter:

project.id IN (2) AND tracker.id IN (2284) AND (modifiedAt >= -1m AND modifiedAt <= +0m)

An example result:

{
  "page": 1,
  "pageSize": 25,
  "total": 1,
  "items": [
    {
      "id": 1670,
      "name": "My first tracker item",
      "type": "Bug",
      "version": 1,
      "description": "__My description__",
      "descriptionFormat": "Wiki",
      "submittedAt": "2018-12-21T13:32:49",
      "submitter": {
        "id": 1,
        "uri": "/user/1",
        "name": "bond",
        "type": "UserReference"
      },
      "modifiedAt": "2018-12-21T13:32:49",
      "modifier": {
        "id": 1,
        "uri": "/user/1",
        "name": "bond",
        "type": "UserReference"
      },
      "assignedTo": [
        {
          "id": 1,
          "uri": "/user/1",
          "name": "bond",
          "type": "UserReferenceField"
        }
      ],
      "storyPoints": 42,
      "tracker": {
        "id": 2284,
        "uri": "/tracker/2284",
        "name": "Bugs",
        "type": "TrackerReference"
      },
      "priority": {
        "uri": "/tracker/2284/field/2",
        "values": [
          {
            "id": 2,
            "uri": "/tracker/2284/field/2/option/2",
            "name": "High",
            "type": "ChoiceOptionReference"
          }
        ],
        "fieldId": 2,
        "trackerId": 2284,
        "type": "ChoiceFieldReference"
      },
      "status": {
        "uri": "/tracker/2284/field/7",
        "values": [
          {
            "id": 1,
            "uri": "/tracker/2284/field/7/option/1",
            "name": "New",
            "type": "ChoiceOptionReference"
          }
        ],
        "fieldId": 7,
        "trackerId": 2284,
        "type": "ChoiceFieldReference"
      },
      "ordinal": 0
    }
  ]
}

Date related queryString examples

Submitted this week:

project.id IN ('current project',2) AND tracker.id IN (2284) AND (submittedAt >= -0w AND submittedAt <= +0w)

Submitted this month:

project.id IN ('current project',2) AND tracker.id IN (2284) AND (submittedAt >= -0m AND submittedAt <= +0m)

Submitted between two dates:

project.id IN ('current project',2) AND tracker.id IN (2284) AND (submittedAt >= '2019-01-20 00:00:00' AND submittedAt <= '2019-01-26 23:59:59')

Submitted in the last 7 days:

project.id IN ('current project',2) AND tracker.id IN (2284) AND (submittedAt >= -7d AND submittedAt <= +0d)

Modified in this quarter:

project.id IN ('current project',2) AND tracker.id IN (2284) AND (modifiedAt >= -0q AND modifiedAt <= +0q)

Assigned in the last 30 days:

project.id IN ('current project',2) AND tracker.id IN (2284) AND (assignedAt >= -30d AND assignedAt <= +0d)

You can find more examples in our Swagger API wiki documentation page.

How to create a tracker item with basic information

Examples of this end point are going to use the Task tracker of Intland Software's Scrum

Create a tracker item with commonly used fields

Please use the following JSON request

{
  "name": "My first tracker item",
  "description": "I love this API",
  "storyPoints": 42,
  "startDate": "2018-11-19T15:13:34.223Z",
  "endDate": "2018-11-19T15:13:34.223Z",
  "estimatedMillis": 42000,
  "status": {
    "fieldId": 7,
    "type": "SingleOptionChoiceFieldValue",
    "value": 1
  },
  "priority": {
    "fieldId": 2,
    "type": "SingleOptionChoiceFieldValue",
    "value": 2
  },
  "severities": {
    "fieldId": 14,
    "type": "OptionChoiceFieldValue",
    "values": [3]
  },
  "assignees": [
    {
      "fieldId": 5,
      "type": "UserFieldValue",
      "value": 1
    }
  ]
}

Status / priority field only handles one option, because of that we need to use the SingleOptionChoiceFieldValue as a type of the field, value of the field is one of the ID of the available options, please check the '/v2/tracker/{trackerId}/field' API end point to see all values. In this case we want to set the status to New, which is ID 1, and set the priority to High, which is ID 2.

Severities is a multiple option field, it can handle multiple options, because of the we need to use the OptionChoiceFieldValue as a type of the field, values of the field is one or more of the IDs of the available options. In this case we want to set the Severities to "Minor", which is ID 3

Tracker item can be assigned to multiple users, in this case use only on user with ID 1. Please note that user must be assigned to the project.

Create a tracker item with custom fields

Please create a 2 new custom fields in your tracker, one of them should be a integer custom field with 0 min and 10 max value, other one should be a choice field with option1, option2, and option3 choice options

Use the following JSON request to create a tracker item

{
  "name": "My first tracker item with custom field",
  "description": "I love this API",
  "customFieldValues": [
    {
      "fieldId": 10001,
      "type": "IntegerFieldValue",
      "value": 5
    },
    {
      "fieldId": 1000,
      "type": "OptionChoiceFieldValue",
      "values": [ 1, 3 ]
    }
  ]
}

Field ID is depends on your tracker layout, it might be differ from the example above, please check the '/v2/tracker/{trackerId}/field' API end point to get the valid ID.

Because of the 10001 field is a integer field, type is set to to IntegerFieldValue, value is set to 5. In case you want to trigger a validation message, please set the value 11 or more.

We want to set the option1 and option3 values for 1000 choice field, to do that we need to use OptionChoiceFieldValue type, and ID of option1 and option3

Create a tracker item with custom table field

Please create a table field with 2 new column in your tracker, one of them should be a integer custom field with 0 min and 10 max value, other one should be a choice field with option1, option2, and option3 choice options

Use the following JSON request to create a tracker item

{
  "name": "My first tracker item with table field",
  "description": "I love this API",
  "tableValues": [
    {
      "fieldId": 1000000,
      "type": "TrackerItemTableFieldValue",
      "rows": [
        {
          "fieldValues": [
            {
              "fieldId": 1000001,
              "value": 5,
              "type": "IntegerFieldValue"
            },
            {
              "fieldId": 1000002,
              "type": "OptionChoiceFieldValue",
              "values": [ 1, 2 ]
            }
          ]
        },
        {
          "fieldValues": [
            {
              "fieldId": 1000001,
              "value": 6,
              "type": "IntegerFieldValue"
            },
            {
              "fieldId": 1000002,
              "type": "OptionChoiceFieldValue",
              "values": [ 3 ]
            }
          ]
        }
      ]
    }
  ]
}

Field ID is depends on your tracker layout, it might be differ from the example above, please check the '/v2/tracker/{trackerId}/field' API end point to get the valid ID.

Because of the table can handle multiple rows we need to create a TrackerItemTableFieldValue container with rows. First column is a integer field with 1000001, type is set to to IntegerFieldValue, value is set to 5. In case you want to trigger a validation message, please set the value 11 or more. Second column is a choice option column, type is set to optionChoiceFieldValue, value is set to IDs of option1 and option3.

Create a tracker item with custom positioning

Since codeBeamer 9.3.0 two optional parameters were introduced: referenceItemId and position. Using these parameters you can define the relative position of and item against a reference item. When you create an item you can send a POST request to '/v2/tracker/{trackerId}/item?referenceItemId=1&position=AFTER'. This will position your newly created item right after the reference item having id: 1.

How to update multiple fields of a tracker item

Examples of this end point are going to use the Task tracker of Intland Software's Scrum

Please create a 2 new custom fields in your tracker, one of them should be a integer custom field with 0 min and 10 max value, other one should be a choice field with option1, option2, and option3 choice options and also create a table field with 2 new column in your tracker, one of them should be a integer custom field with 0 min and 10 max value, other one should be a choice field with option1, option2, and option3 choice options

Use the following JSON request

{
  "fieldValues": [
    {
      "fieldId": 10001,
      "type": "IntegerFieldValue",
      "value": 4
    },
    {
      "fieldId": 1000,
      "type": "OptionChoiceFieldValue",
      "values": [ 2 ]
    }
  ],
  "tableValues": [
    {
      "fieldId": 1000000,
      "type": "TrackerItemTableFieldValue",
      "rows": [
        {
          "fieldValues": [
            {
              "fieldId": 1000001,
              "value": 4,
              "type": "IntegerFieldValue"
            },
            {
              "fieldId": 1000002,
              "type": "OptionChoiceFieldValue",
              "values": [ 1 ]
            }
          ]
        },
        {
          "fieldValues": [
            {
              "fieldId": 1000001,
              "value": 7,
              "type": "IntegerFieldValue"
            },
            {
              "fieldId": 1000002,
              "type": "OptionChoiceFieldValue",
              "values": [ 2 ]
            }
          ]
        }
      ]
    }
  ]
}