Report operations

CodeBeamer reporting functionality

CodeBeamer has a rich reporting section where users can list, group and accumulate different tracker item fields from various projects and trackers.

This page will walk you through how to create a simple report like this:

However to read more about the possibilities of the codeBeamer reporting engine please read the detailed documentation.

Creating a report

The POST /v3/reports endpoint accepts a SimpleReportSetting model to create reports in codeBeamer.

Example SimpleReportSettingmodel: { "cbQl": "project.id IN (8) AND tracker.id IN (2764)", "name": "Simple report", "description": "Simple description", "columns": [ { "field": { "id": 3, "name": "Summary", "type": "FieldReference", "trackerId": 2764 }, "columnIndex": 0, "columnWidthPercentage": null }, { "field": { "id": 7, "name": "Status", "type": "FieldReference", "trackerId": 2764 }, "columnIndex": 1, "columnWidthPercentage": null }, { "field": { "id": 2, "name": "Business Value", "type": "FieldReference", "trackerId": 2764 }, "columnIndex": 2, "columnWidthPercentage": null }, { "field": { "id": 5, "name": "Assigned to", "type": "FieldReference", "trackerId": 2764 }, "columnIndex": 3, "columnWidthPercentage": null }, { "field": { "id": 75, "name": "Modified by", "type": "FieldReference", "trackerId": 2764 }, "columnIndex": 4, "columnWidthPercentage": null }, { "field": { "id": 74, "name": "Modified at", "type": "FieldReference", "trackerId": 2764 }, "columnIndex": 5, "columnWidthPercentage": null }, { "field": { "id": 6, "name": "Submitted by", "type": "FieldReference", "trackerId": 2764 }, "columnIndex": 6, "columnWidthPercentage": null }, { "field": { "id": 19, "name": "Story Points", "type": "FieldReference", "trackerId": 2764 }, "columnIndex": 7, "columnWidthPercentage": null } ], "addedPermissions": [ { "project": { "id": 8, "type": "ProjectReference" }, "role": { "id": 4, "type": "RoleReference" }, "access": "READ" }, { "project": { "id": 8, "type": "ProjectReference" }, "role": { "id": 1, "type": "RoleReference" }, "access": "READ" } ], "showAncestors": true, "showDescendants": true, "showAllChildren": false }

Model definition:

SimpleReportSetting model attributes

cbQL

The cbQL query which defines the set of items as the base of the report.

name

The name of the newly created query.

description

The description of the query.

columns

This property will define the list of columns which are made of specific tracker fields.

From the example above:

To get hold on the reference of a tracker field the GET /v3/trackers/{trackerId}/fields can be queried. In our example we will need the Summary, Status, Business Value, Assigned to, Modified by, Modified at, Submitted by and Story Points fields to be our columns.

[
  ...
  {
    "id": 2,
    "name": "Business Value",
    "type": "FieldReference",
    "trackerId": 2764
  },
  {
    "id": 3,
    "name": "Summary",
    "type": "FieldReference",
    "trackerId": 2764
  },
  ...
  {
    "id": 5,
    "name": "Assigned to",
    "type": "FieldReference",
    "trackerId": 2764
  },
  {
    "id": 6,
    "name": "Submitted by",
    "type": "FieldReference",
    "trackerId": 2764
  },
  {
    "id": 7,
    "name": "Status",
    "type": "FieldReference",
    "trackerId": 2764
  },
  ...
  {
    "id": 19,
    "name": "Story Points",
    "type": "FieldReference",
    "trackerId": 2764
  },
  ...
  {
    "id": 74,
    "name": "Modified at",
    "type": "FieldReference",
    "trackerId": 2764
  },
  {
    "id": 75,
    "name": "Modified by",
    "type": "FieldReference",
    "trackerId": 2764
  },
  ...
]

ResizableReportColumnSettings model can be used to define a column.

For example our first column will refer to the Summary field. Using the FieldReference from the previous query, we will need to construct an item like this:

{
  "field": {
    "id": 3,
    "name": "Summary",
    "type": "FieldReference",
    "trackerId": 2764
  },
  "columnIndex": 0
}

Please note: each column must define its index explicitly as the columns are rearrangeable.

A list of these ResizableReportColumnSettings models will define the layout of our report.

addedPermissions

By default only the creator will be able to see the report itself, using this property read and write permissions can be added for different roles in projects:

To add a specific read/write permission for a role a ReportPermission model can be used:

To acquire the project reference we need to call the GET /v3/projects API:

[
  {
    "id": 8,
    "name": "Intland Software's Scrum Template",
    "type": "ProjectReference"
  }
]

To find out what kind of roles are defined in our project we can call the GET /v3/roles endpoint:

[
  {
    "id": 1,
    "name": "Project Admin",
    "type": "RoleReference"
  },
  ...
  {
    "id": 5,
    "name": "Developer",
    "type": "RoleReference"
  },
  ...
]

With these information we can construct our ReportPermission model for Project Admins:

{
  "project": {
    "id": 8,
    "name": "Intland Software's Scrum Template",
    "type": "ProjectReference"
  },
  "role": {
    "id": 1,
    "name": "Project Admin",
    "type": "RoleReference"
  },
  "access": "READ"
}

A list of these ReportPermission models will define the access permissions for the report.

showAncestors

A flag on enable the Show Ancestor functionality. More details here: Reports

showDescendants

A flag on enable the Show Descendant functionality. More details here: Reports

showAllChildren

A flag to enable the lookup for all children for a tracker item.

Updating the report settings

PUT /v3/reports/{reportId} will update an existing report.

Getting the report results

GET /v3/reports/{reportId}/results will return a report result in a table like format.

Response example:

{
  "report": {
    "id": 3731,
    "name": "Simple report 2",
    "type": "ReportReference"
  },
  "cbQL": "project.id IN (8) AND tracker.id IN (2764)",
  "columns": [
    {
      "columnRef": "0-3",
      "field": {
        "id": 3,
        "name": "Summary",
        "type": "FieldReference",
        "trackerId": 2764
      },
      "name": "Summary",
      "type": "text",
      "columnIndex": 0
    },
    {
      "columnRef": "0-7",
      "field": {
        "id": 7,
        "name": "Status",
        "type": "FieldReference",
        "trackerId": 2764
      },
      "name": "Status",
      "type": "choice",
      "columnIndex": 1
    },
    ...
  ],
  "pagingInformation": {
    "page": 1,
    "pageSize": 25,
    "pageCount": 2
  },
  "data": {
    "type": "ReportGroupWithRows",
    "header": "Grand Total",
    "count": 25,
    "rows": [
      {
        "itemRef": {
          "itemId": 1094,
          "trackerId": 2764
        },
        "cells": [
          {
            "columnRef": "0-3",
            "value": "[REQ-1094] Navigation system"
          },
          {
            "columnRef": "0-7",
            "value": "Draft"
          },
          ...
        ],
        "outlineLevel": 0,
        "isRealResult": true
      },
      {
        "itemRef": {
          "itemId": 1097,
          "trackerId": 2764
        },
        "cells": [
          {
            "columnRef": "0-3",
            "value": "[REQ-1097] Navigation storage support"
          },
          {
            "columnRef": "0-7",
            "value": "Waiting for approval"
          },
          ...
        ],
        "outlineLevel": 1,
        "isRealResult": true
      },
      ...
    ]
  },
  "showAllChildren": false
}

Structure of the report result

cbQL

The underlying cbQL query.

columns

It contains the defined columns in the report with their column references.

Example definition of the Summary column:

{
  "columnRef": "0-3",
  "field": {
    "id": 3,
    "name": "Summary",
    "type": "FieldReference",
    "trackerId": 2764
  },
  "name": "Summary",
  "type": "text",
  "columnIndex": 0
}

The columnRef will be used to connect the value attributes with their column definition. It consist of the trackerId and the fieldId separated by a dash sign.

Reports can be created from multiple trackers therefore the built-in fields can be referenced with 0 trackerId creating tracker independent column definitions.

pagingInformation

Contains the basic paging information attributes.

data

It contains the groups and rows of the table.

The root element is always a ReportGroupWithRows or ReportGroupWithGroups containing the Grand Total summary.

Inside the Grand Total element there can be additional groups if the cbQL attribute defines so, but the leaf elements are ReportGroupWithRows models:

{
  "type": "ReportGroupWithRows",
  "header": "Grand Total",
  "count": 25,
  "rows": [
    {
      "itemRef": {
        "itemId": 1094,
        "trackerId": 2764
      },
      "cells": [
        {
          "columnRef": "0-3",
          "value": "[REQ-1094] Navigation system"
        },
        {
           "columnRef": "0-7",
           "value": "Draft"
        },
        ...
      ],
      "outlineLevel": 0,
      "isRealResult": true
    },
    ...
  ]
}

Getting the tracker items related to a report

GET /v3/reports/{reportId}/items will return a report result as TrackerItem models.

Example result:

{
  "page": 1,
  "pageSize": 25,
  "total": 28,
  "items": [
    {
      "item": {
        "id": 1094,
        "name": "Navigation system",
        "description": "Navigation system\r\n\r\n\r\n[{Image wiki='[!7230a1f747037e4b72708d7b3687e4f1.png!]' width='381' height='256' }]\r\n\r\n\r\nThis has to be smaller.\r\n\r\n\r\n\\\\\r\n\\\\",
        "descriptionFormat": "Wiki",
        "createdAt": "2020-08-06T09:57:19.639",
        "createdBy": {
          "id": 1,
          "name": "bond",
          "type": "UserReference"
        },
        "modifiedAt": "2020-08-06T09:57:19.639",
        "modifiedBy": {
          "id": 1,
          "name": "bond",
          "type": "UserReference"
        },
        "version": 1,
        "assignedTo": [],
        "tracker": {
          "id": 2764,
          "name": "Requirements",
          "type": "TrackerReference"
        },
        "children": [
          {
            "id": 1097,
            "name": "Navigation storage support",
            "type": "TrackerItemReference"
          },
          {
            "id": 1095,
            "name": "Enable satellite navigation",
            "type": "TrackerItemReference"
          },
          {
            "id": 1096,
            "name": "Provide Points of interest (waypoints)",
            "type": "TrackerItemReference"
          },
          {
            "id": 1098,
            "name": "Integrations and other functions",
            "type": "TrackerItemReference"
          }
        ],
        "customFields": [],
        "priority": {
          "id": 0,
          "name": "Unset",
          "type": "ChoiceOptionReference"
        },
        "status": {
          "id": 2,
          "name": "Draft",
          "type": "ChoiceOptionReference"
        },
        "categories": [],
        "subjects": [
          {
            "id": 1011,
            "name": "As User, I want to have a navigation system in my car",
            "type": "TrackerItemReference"
          }
        ],
        "resolutions": [],
        "severities": [],
        "teams": [],
        "versions": [],
        "ordinal": 1,
        "typeName": "Requirement",
        "comments": [
          {
            "id": 2724,
            "name": "7230a1f747037e4b72708d7b3687e4f1.png",
            "type": "CommentReference"
          },
          {
            "id": 2727,
            "name": "Comment by Sales on 18.11.2015 16:31",
            "type": "CommentReference"
          }
        ]
      },
      "outlineLevel": 0,
      "isRealResult": true
    },
    ...
  ]
}