Tags: not added yet

1Report operations

1.1CodeBeamer 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:

[!1596700974247.png!]

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

1.2Creating 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:

[!1596701936974.png!]

1.2.1SimpleReportSetting model attributes

1.2.1.1cbQL

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

1.2.1.2name

The name of the newly created query.

1.2.1.3description

The description of the query.

1.2.1.4columns

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

From the example above:

[!1596702432647.png!]

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.

[!1596702947221.png!]

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.

1.2.1.5addedPermissions

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:

[!1596702164409.png!]

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

[!1596703597862.png!]

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.

1.2.1.6showAncestors

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

1.2.1.7showDescendants

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

1.2.1.8showAllChildren

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

1.3Updating the report settings

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

1.4Getting 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
}

1.4.1Structure of the report result

1.4.1.1cbQL

The underlying cbQL query.

1.4.1.2columns

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.

1.4.1.3pagingInformation

Contains the basic paging information attributes.

1.4.1.4data

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
    },
    ...
  ]
}

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
    },
    ...
  ]
}

Table of Contents