Reports is a new project independent way (since 8.0) to search/filter work items ad-hoc or for later reuse across multiple projects using cbQL.
By default clicking on Reports menu opens a New Report, you can create simple report via the query condition editor or complex queries in advanced mode using the cbQL syntax.
Save Report, Properties
When first saving your query you need to give it a name and optionally you can add roles from projects that you want to share the query with and a description. Two kind of access level can be assigned: read and write, write also gives read permission.
When assigning permissions you select a project you have access to and then select one or multiple roles from multiselect menu. If the current report contains one project, this project will be preselected and its roles will immediately appear in role selector. Once you select the role(s), the role(s) and its/their project(s) will appear with a default READ permission. You can change the access level row-by-row to WRITE if you want. If you do not have permission to view the roles of the selected project, a warning message will shown and the role selector will be empty.
After the first save you can simply update your query with the Save button the properties window will not popup, if you want to modify other aspects of the query you can use the context menu Properties option.
If you select Save as... from context menu, the Properties popup will also appear and you can change the name/permissions, after saving a new Report will be created with the newly set properties.
View Mode and Edit Mode
There are two modes of the reports: View and Edit Mode. If you have only READ access for the current report, only the View mode is available. If you have WRITE permission also, you can switch between the two modes by clicking the proper items of the action bar (Open in View Mode, Edit).
In View mode, you can see only the name and description of the report and of course the result table.
There is an accordion called My Reports, if you click there, you will ses a list of your starred reports and some predefined reports (Submitted by me, My unresolved items). You can star you reports using the context menu of the report in both View and Edit modes.
From codeBeamer 9.1 you can use in-place edit borh in View and Edit modes. See more information about in-place edit here.
Clicking the arrow next to the Reports tool menu, you will see the recently opened reports at the bottom. Clicking on these report, these will open in View Mode. From the context menu you can create New Report, reach the old report functionality Reports (Vintage) and you can find existing reports. Clicking on Find Reports, an overlay appears in which you can see your own reports and the reports which are shared with you via project roles.
It is able to filter the report list: you can type a text into the filter input or you can switch between own and shared reports using the checkboxes. Once you click on a report, it will be loaded in View Mode.
Find Reports is also available from the action bar of a report both in View and Edit Modes.
Using the context menu of the current report you are able to Delete Report.
Structure of the screen
There are three main sections of the Edit screen:
Field section: on the left panel you can see the available fields in a tree. By default the Default fields (commonly used fields which are available in most of the trackers) and the Common Reference fields appearing. The fields can be drag&dropped to the other parts of the screen: Filter list, Group by/Order by sections, Result table header. The available places where you can drop will be highlighted once you start dragging a field.
In case of custom fields with Per Status permission configuration, only the fields having at least "Read" permission by default are able to be selected.
Report properties and filter section: on the center panel top you can see the name of the report, the context menu, the Save button, the editor section (the Project and Tracker selectors and the Field Filter, Group by and Order by lists), the Go button, and the switch to Advanced mode option.
Result: center bottom after clicking on Go button (or in case of editing an existing report) you can find the filtered Tracker Item list in a table according to the set options.
Project and Tracker selectors
The two most commonly used filter option is by Project and Tracker. Once you select any projects, the trackers of the selected projects will appear under the Trackers dropdown list. Once you select any trackers, the field tree on the left will extend with the custom fields of the selected trackers (the fields which are not under the Default fields and Common Reference fields). Furthermore if you choose only one tracker, the labels of the Default and Common Reference Field will change to the field labels of the selected tracker.
Branch support is only available from codeBeamer 9.0.0.
From codeBeamer 9.0.0 you can select also the branches of the trackers. Within the tracker selector under each tracker you will see the hierarchy of the branches of the tracker if exists. Branches are selectable just the same way as you select trackers.
This is the most important section of the screen. To add a filter by a field either you can use the Add filter button or you can drag the proper field into the filter section. After you select or drop a field, a small control overlay will appear in which you can set the desired options. These controls depend on which type the field has. The following field types are supported:
Choice fields / meaning type selectors
The possible values of these fields depend on which trackers are selected in the Tracker selector, in the list you will see the field values grouped by the selected trackers. Once you select or deselect tackers in Tracker selector, these fields will be refreshed automatically and will show always a consistent state.
Furthermore if you select Status or Resolution, you can filter also by meanings of the field values. The Status and Resolution meanings for values can be set on Tracker customization page. On Query widget the meanings do not depend on selected trackers, have fix values, which are the followings:
Status: Unset, In progress, Resolved, Closed, Obsolete
Resolution: Unsuccessfull, Successfull, Obsolete
You also can use the Filter option inside these selector for filtering meanings / field values.
By selecting these conditions, you will see a list of users depending on which projects are choosen in the Project selector. If you do not select any projects, all of the visible members of the projects assigned to the current user will appear. At the beginning of the values there is a "Me" option which means the current user. The values of these fields are also refreshing automatically if you change projects in the Project selector.
Three properties of the users are appearing in the list: the user name (or user alias configured in general.xml), the real name, and the domain of the user's email address. You can filter by these three properties if you begin to type in the Filter input box inside the selector.
From codeBeamer 8.2 you are able to select users which are not presented in the list by clickin Add Other User(s) link. A dialog opens and you can begin to type to select the desired user(s). If you are ready, click on OK button, and the selected user(s) will appear in the user selector list.
By selecting date conditions, you will see a small control box, in which you can set your date ranges. Three options are available:
Predefined date ranges: e.g Today, Today and Yesterday, This week, etc. Possible values are grouped in the list by day/week/month/quarter/year.
Specific dates: you have to select two dates using the datepicker. If you want, you can skip the "form" or the "to" values, just leave the input empty.
Relative custom date ranges: you can set relative Custom date ranges also, by setting the from and to dates using the selectors: number of days/workdays/weeks/months/quarters/years before/after today. Click on the checkboxes before from/to labels if you would like to skip any of these values.
You can filter by number type field of tracker items. You should set the operator (greater than >, greater than or equals to >=, equals =, less than or equals to <=, less than <) and the integer number.
You can filter by duration type field of tracker items. You should set the operator (greater than >, greater than or equals to >=, equals =, less than or equals to <=, less than <), the integer number and the duration (hour, minute, second).
You can filter by text field of the tracker items. SQL wildcards and negation are allowed to use here. Example: if you would like to see tracker items where the summary not contains "test", you should type here: "%test%" and check the "not" checkbox.
Boolean fields are supported only from codeBeamer 9.2.
You can filter by any custom boolean fields.
Color fields are supported only from codeBeamer 9.2.
If you select color field, you will be able to pick a color using the colorpicker and filter the result by color.
You are able to filter tracker items by references. By clicking a selected reference field, a small overlay opens, in which you can set the desired referring tracker items. Firstly you have to select one ore more project(s) then one or more tracker(s), and then you can use the autocomplete field or the pencil icon to select the tracker items. The projects and trackers could filled out according to the selected trackers and the set field reference (e.g. if Bugs tracker is selected in Tracker selector, and you drag and drop Release reference field, the trackers will be preselected according to the Bugs tracker Release field reference setting). Only valid items will appear, so according to the selected trackers. Between the selected items there will be OR connection. Optionally you can filter by suspected/not suspected references, three possibilites are available:
Do not filter
Not Suspected References
If you leave the work item input empty, and select Suspected / Nor suspected filter, you can filter ont the field level. E.g. if you select Suspected references and leave the work item input empty, all work items will match where Release field contains at least one Suspected reference.
From codeBeamer 9.3.0 you can use Tag filters also. There are several kind of tags within codeBeamer and you can filter work items by any kind of tags:
Work Item Tag
Release / Sprint Tag
From + Add filter menu you can select other filters too. These filters does not represent any field, that is why they are not present in the left tree.
Has Reference to / Has Reference from: similar to the Reference field, but without the field being specified. Optionally filterable by suspected references.
If the "Filter by Work Item(s)" section is closed or the work item input is empty, you can filtler by tracker level. E.g. the following case means that those work items will match which have at lease one reference from the Bugs tracker:
If you open the "Filter by Work Item(s)" section and set some work items, you can specify the references:
Has Downstream Reference / Has Upstream Reference: these are simple boolean options, you can find which Tracker Items has downstream/upstream refrences or not. Optionally filterable by suspected references also.
Has Review / Is under Review: simple boolean options, filter work items by their Review(s).
Suspected References (Has Suspected Link / Has Incoming Suspected Link / Has Outgoing Suspected Link): simple boolean option, filter by suspected links without field, work item specified.
From codeBeamer 9.3.0 you can include other Report into an existing Report. Use Include option of + Add Filter menu, and you will have two options:
Include Report: you can select an other Report by autocomplete or using the pencil icon and the Report Finder.
Include cbQL from Work Item Description: if you have any work item which contains cbQL in its Description field, you can select here the item and the cbQL will be included into the existing Report.
NOT and EMPTY options
Using any type of field types there is ability to negate the condition using the NOT badge on the right top section of the selector. If selected the light gray background of the badge will be darker and the "not" word will appear in the filter stripe before the selected conditions.
You can filter also for emptyness of a field value. A field value of a Tracker Item could be empty if the field is not mandatory, but it is not set. E.g. if you would like to see the items which does not belong to a Release, you can add the Release field to the filter list and set it to empty. If selected the light gray background of the badge will be darker and the "empty" word will appear in the filter stripe.
You are able to combine the NOT and EMPTY badges, so with these two badges you can reach three states:
NOT badge is on: negation of the selected condition.
EMPTY badge is on: filter for empty field value. In this case the selectable elements within the setting container will be disabled (e.g. the choice options of a choice field).
NOT and EMPTY badges are on: filter for not empty field value. Selectable elements are also disabled.
Group by section
You are able to group the result by project, trackers and some fields. If you start dragging from left pane tree, the Group by section will be highlighted if the grouping is available for this field (grouping by custom field is also available). For grouping by project and/or tracker, you have to use the Add button inside the Group by section. Multiple grouping is also supported (maximum 3 levels).
In case of grouping by date type fields, you can also use truncate functions (Day, Week, Month, Quarter, Year). You can switch the truncate function by clicking the darkgrey background truncate funcion badge.
Grouping is neccessary to use the Aggregate functions (see below).
From codeBeamer 9.1 it is able to Group by Custom fields, but only if exactly one tracker is selected in the tracker selector. It means, that custom fields appear under Add Group by context menu only if you selected exactly one tracker in the tracker selector.
If you already have one tracker selected and a custom field of the tracker in the Group by section, and later you select other tracker(s) or set the tracker selector to Any, the selected custom field within the Group by area will be removed.
Order by section
Order by is also supported for most of the fields, you can just easily drag&drop the desired fields. For ordering by Tracker or Item ID, you have to use the Add button inside the Order by section. Multiple ordering is also supported (maximum 3 levels).
You can change the direction of ordering (ASC or DESC) by clicking the dark background direction badge.
Order groups by summarized values
In certain cases you are able to order the groups by the summarize function values. The control badge for that is available only if the following conditions match:
the report is grouped, and grouped by only one field
some of the Summerize function are set for a number type field (SUM, AVG, MIN, MAX)
this number type field is selected in Order by area
The order by aggregate badge will appear after the ASC/DESC badge and will contain the selected summarize functions and the NONE option. If you select NONE, the default ordering will be present, so not the groups but the Tracker Items will be ordered by the field value.
By default there is AND condition between the filters in the Filter list, but you are able to define custom logic (using AND/OR and parentheses) by clicking the + Add AND/OR button next to the + Add filter button inside the Filter list. Once clicking, the Filter list goes to AND/OR Logic mode, the structure changes a bit:
All of the added filters get a number, the numbers will represent the filters.
An AND/OR Logic input field appears top of the area in which you can type the custom logic using the filter numbers, the AND, OR logical operators and parentheses if necessary.
If you begin to type into the AND/OR Logic field, the logic is being validated immediately. If the typed logic is invalid, a red alert appears, and once it became a valid logic, the text colour will be green and the alert disappears. You can run the Report only if the AND/OR Logic is valid.
Valid logic: you can use uncapitalized format too, the logic validation is case insensitive
Please note, that if you switch to Advanced mode while using AND/OR Logic, the cbQL is not editable. If you need to modify it anywy, you have to copy the cbQL and create a nem Report with advanced mode or go back to Simple mode and switch off the AND/OR Logic mode.
To switch off AND/OR Logic mode, click on the X button right inside the stripe.
Current Project functionality
From codeBeamer 9.3.0 there is a new option under Project selector of the Reports page, called Current Project.
Using this option you do not need to define the project of the Report, so if you use later the Report in project context, the current project will be preselected. This is useful if you have Reports which are data sources of Dashboard widgets (e.g. Table Widget or any kind of Chart Widgets), and you want to use them on the Dashboard pages of multiple projects - you do not need to create as many Reports as many projects you have, just save one Report and use the Current Project functionality.
On Report page, if you select Current Project and hit the GO button, a project selector overlay is displaying - after select a project you will see a preview result - this way you can check the result before you use the Report in project context.
The result table contains the Tracker Items which are matched to the set filter options group by and order by according to the set values. The result table appears:
in View mode always during page loading
in Edit mode if you load an existing report during page loading
in case of new report, after clicking on GO button
In Edit mode you can modify the table layout:
you are able to reorder the table columns, by drag&dropping the table headers (a green line will help you during dragging where you can move the field) or by using the Move left and Move right options of the context menu near the column header name
you can remove column by using the Remove column of the context menu near the column header name
you can add more fields (as column) by drag&dropping from the left side tree (light green highlighting and a green line will help you during dragging where you can add the field). It is not possible to add field to the table if it already contains the field.
if the report is a grouped report and you added number type fields to the table, you can add summarize options and set formatting options (see below)
If you save the report, the table layout settings (columns, column order) will be saved also.
Summarize options are available only for grouped reports, using this functionality the number type field values will be aggregated per groups.
Use the context menu near a number type column (field), and choose Summarize, a small overlay will be displayed. You can select which type of aggregation functions you would like to see of the current field: sum, average, min and/or max. After clicking OK, the group headers will contain the aggregated values below the proper field. This functionality is working also by setting multiple group by options.
If you save the report, the set Summarize options will be saved also, after reloading the saved report, these values will also appear.
Formatting options are available only for grouped reports, using this functionality the number type field values will be shown as you set.
Use the context menu near a number type column (field), and choose Formatting options, a small overlay will be displayed. You can select format type (Decimal or Percent) and Decimal places (0-3). After clicking OK, the values of the selected field (also the group headers aggregated values if Summerize options set) will be in the same format which you set.
If you save the report, the set Formatting options will be saved also, after reloading the saved report, the values will appear as you set.
Next to the Go button you can switch to Advanced mode. Using the Advanced mode, you can see only the sytax highlighted cbQL of the report, the project/tracker selector, filter list, group by and order by areas disappear, and an editable textarea appears. Note: if you use AND/OR Logic, the cbQL is not editable!
Advanced mode is for supporting some cbQL functions which are not able to use currently in Simple mode (e.g. escalation type cbQL functions) and for more complex AND/OR/NOT logic, but if you prefer cbQL language instead of drag&drop UI, you are able to create your own cbQL here. You can switch back to Simple mode, only if the Simple mode supports the typed cbQL, the cbQL is not too complex logically, it is valid and syntactically correct, unless you get a warning message, and you remain in Advanced mode.
If you save your report from Advanced mode, the report will be marked as advanced, so after load the report, Advanced mode will be the default mode.
Export Report to Office
Reports can be exported to Excel. Two options are available:
Simple export: export with the columns which you see on screen (saved for the report)
Export via template: in this case you have to select first a project which contains existing template or you can upload one.
From codeBeamer 8.1 you are able to send automatic reports by email on a regular basis.
Every user can create an own Job for an own or shared Report. Open a Report and click on New Job within the action bar.
Settings of the Job:
Name: mandatory field, by default the name of the Job will be the name of the Report.
Recipients: who will recieve the emails
Personal subscription: only you will get the email
Project roles: If the Report is shared with some roles, you can select here these roles too. In this case there is a restriction, the first 10 user/role will get the email.
Threshold: the email will send only if the report contains more item than the number set here.
Daily: once per day or every 4 hours a day starts at a specific time (hour).
Weekly: you can select on which day(s) of week should the email to be sent. The sending time within the day can be set the same way like the Daily option.
Monthly: specific day of every month or specific day of week of every month. The sending time within the day can be set the same way like the Daily option.
Please note, that emails will be sent according to the user's timezone and the exact time of email sending will depend on job queue activity.
Clicking on Manage Jobs on the action bar, you can see a list of your own Jobs. Each Job can be edited, disabled/enabled or deleted. Disabled Jobs are grayed out.
System administrators can manage (edit, disable/enable, delete) all of the Jobs under Job Manager of System Admin pages, furthermore they can see other information of each Job (Status, Last Run, Created at, Owner, etc.).