Skip to main content

Build Custom Reports

This tutorial guides you through creating custom reports in Digital.ai Agility Analytics using the Report Builder interface.

Prerequisites​

Before building custom reports, ensure:

  • You have access to Digital.ai Agility Analytics
  • The Data Mart database is configured and updated with your project data
  • You understand your reporting requirements and data sources

Access the Report Builder​

The Report Builder provides a comprehensive interface for creating full-featured reports.

note

The Report Builder is designed specifically for reports. To build or modify dashboards, use the Dashboard Builder instead.

To access the Report Builder:

  1. Hover over the Add button in Analytics
  2. Select Report from the dropdown list

The template selection dialog appears with six pre-built templates plus a Blank template option.

Template Selection Dialog

  1. Choose a template or select Blank to start from scratch
  2. Click OK to proceed

Understand the Report Builder Interface​

The Report Builder interface consists of several key components:

At the top of the page, a breadcrumb trail shows your navigation path through recently visited pages and folders.

Breadcrumb Trail

Function Ribbon Tabs​

Below the breadcrumb trail, three tabbed ribbons provide core functionality:

File Tab

File Tab

The File options manage report definitions:

  • Create new reports
  • Open existing reports
  • Save report definitions
  • Save with a new name
  • Preview the current report

Insert Tab

Insert Tab

The Insert options add display elements to your report:

  • Tables and crosstabs
  • Charts and graphs
  • Labels and images
  • Headers and footers

Display elements can be added by clicking or using drag-and-drop to the Report Layout panel.

Settings Tab

Settings Tab

The Settings options control report appearance:

  • Page layout and size
  • Paging options
  • Stylesheet selection

Side Panels​

Report Layout Panel

Report Layout and Data Source

The Report Layout panel displays thumbnails of display elements in sequence. You can:

  • Remove elements by clicking the red delete icon icon
  • Rearrange elements using drag-and-drop
  • Open element configuration by clicking the thumbnail

Data Source Panel

The Data Source panel lists:

  • Selected data objects
  • Calculated columns
  • Statistical columns

Click Modify Data Source to adjust your data selections.

Configuration Panel​

The center Configuration panel provides tabs for configuring display elements. Each element has at least one configuration tab.

Configuration Tabs

Use the Previous Step and Next Step buttons to navigate between configuration tabs.

tip

Save your work frequently to avoid losing changes due to session timeout.

Select Data Sources​

Selecting the appropriate data source is the foundation of effective custom reporting.

Access Data Source Selection​

After selecting a template, the Select or Modify Data Source dialog appears automatically. You can also access it anytime by clicking Modify Data Source in the Data Source panel.

Modify Data Source Dialog

Understand Data Object Categories​

If data objects are categorized, use the Data Objects dropdown filter to narrow the list:

  • All: Shows all available data objects
  • A Report On: Trending and historical data objects
  • Detail Data Objects: Current attribute values from the latest ETL load
  • Quick Reports: Predefined queries for common reporting needs
  • Value Data Objects: Drop-down list values from Agility

Select Data Objects​

To select data objects for your report:

  1. From the Data Objects dropdown, choose a category or select (All)
  2. Click the checkbox next to each data object you want to include
  3. As you select objects, the tree refreshes to show related objects
  4. Expand data objects to view their available columns
  5. Click the magnifying glass icon icon next to an object to view sample data
  6. Review the Information panel for descriptions of data objects and columns

The Exclude duplicate rows checkbox ensures only distinct rows are returned (rows with identical values for all selected columns are excluded).

To save your data source selection:

  1. Click OK to save selected items
  2. The Data Source panel updates to reflect your selections

Data Source Panel

note

Most reports use a single data source shared by all display elements.

note

If you select only one data object, column references appear as Column Name. With multiple data objects, references use Data Object.Column Name notation.

Key Data Source Objects​

Review the complete list of available data sources in Data Source Objects. Key objects include:

Trend Data (A Report On category):

  • Effort Trends - Time spent working on features and defects
  • Workitem Trends - Daily changes to workitems with semi-additive columns
  • Epic Trends - Epic data over time
  • Issue Trends - Daily changes to issues

Detail Data (Detail Data Objects category):

  • Workitem Details - Current workitem attributes (Dim.PrimaryWorkitem)
  • Project Details - Current project attributes (Dim.MyProject)
  • Epic Details - Current epic attributes (Dim.EpicView)
  • Member Details - Team member information (Dim.Member)

Quick Reports:

  • Workitem Trend Report - Predefined query for workitem trends
  • Member Effort Report - Effort by team member
  • Blocked Workitem Report - Workitems and blocking issues

Filter and Sort Data​

Filtering focuses your report on specific data, while sorting controls the order of results.

Set Report Filters​

Filters restrict the data included in your report using criteria you define.

To create a filter:

  1. Click Modify Data Source to open the dialog
  2. Select the Filter tab

Filter Tab

  1. Click Add a Parameter to open the Parameter Details dialog

Parameter Details Dialog

  1. Select a Column from the dropdown

  2. Choose a comparison Operator:

    • Equal to / Not equal to
    • Less than / Greater than
    • Less than or equal to / Greater than or equal to
    • Starts with / Does not start with (text only)
    • Ends with / Does not end with (text only)
    • Contains / Does not contain (text only)
    • Is null / Is not null
    • Between / Not between
    • In list / Not in list
    • In cascading list

  3. Select a Value type:

    • Specific Value: Enter a threshold value or click magnifying glass to select from database values
    • Pre-defined Date: For date columns, use tokens like Today, This Year End, Last Fiscal Quarter Start

  4. Enter the Value threshold

  5. Click OK to add the parameter

tip

Use the magnifying glass icon icon to view valid values from the database and populate the Value field automatically.

Create Ask Parameters​

Ask parameters allow report viewers to modify filter values when running the report.

To create an ask parameter:

  1. In the Parameter Details dialog, enable Ask in Report

Ask Parameter Dialog

  1. Enter a Parameter Caption (auto-generated if left blank)

  2. Select a Control Type based on the operator and column data type:

    • Text / Text (multi line)
    • Dropdown
    • List (single select / multi select)
    • Date picker
    • Checkbox

  3. Choose Display this parameter:

    • Next to previous - Shows parameter inline
    • On new line - Shows parameter on its own line

  4. Click OK to save the ask parameter

When the report runs, users can modify these values before rendering.

Combine Multiple Filters​

When you add multiple parameters, combine them using logical operators:

To combine filters:

  1. Add your first parameter as described above

  2. When adding the next parameter, choose the logical operator:

    • And - Both conditions must be true
    • Or - Either condition can be true

  3. Use the directional pad directional pad to create levels and control evaluation order

Multiple Parameters

Sort Report Data​

Sorting determines the initial order of data when the report runs.

To sort report data:

  1. In the Select or Modify Data Source dialog, select the Sort tab
  2. Choose columns to sort by
  3. Select sort direction (ascending or descending)
  4. Specify sort priority for multiple columns
  5. Click OK to save

Create Calculated Columns​

Calculated columns create new columns based on formulas applied to existing column data.

Access Calculated Columns​

To create a calculated column:

  1. Click Modify Data Source
  2. Select the Calculated Columns tab

Calculated Columns Tab

Build Column Definitions​

Create formulas using:

  • Data source columns: Click columns in the tree to insert references
  • Operators: +, -, *, /, %
  • Functions: Predefined date, text, and numeric functions
  • Constants: Literal values

Available function categories:

  • Date functions: Date manipulation and formatting
  • Text functions: String operations (CONCAT, SUBSTRING, UPPER, LOWER)
  • Numeric functions: Mathematical calculations (SUM, AVG, ABS, ROUND)

To define a calculated column:

  1. Enter or build the formula in the Definition textbox
  2. Use the function buttons to insert common functions
  3. Click columns in the tree to add column references
  4. Click operator buttons to add +, -, *, / symbols
  5. Click Test to verify syntax against the database
  6. Select the Type (or use Auto for automatic detection)
  7. Click Determine Type to auto-detect from formula
  8. Enter a Name for the calculated column
  9. Click Save to store the column definition

The column appears in the data objects tree and becomes available for use in display elements.

tip

Use the Preview Selected Data button to see all columns including calculated columns before saving.

note

Calculated columns must be used in the report to be saved in the definition. Unused calculated columns are automatically removed.

Create Statistical Columns​

Statistical columns perform analytical calculations on existing column data.

Available Statistical Functions​

  • Rank - Ranks data from lowest to highest value
  • Reverse Rank - Ranks data from highest to lowest value
  • Percentile - Classifies data by percentage distribution
  • Running Total - Maintains cumulative total
  • Difference from Previous - Shows change from previous row value

Create a Statistical Column​

To add a statistical column:

  1. Click Modify Data Source
  2. Select the Statistical Columns tab

Statistical Columns Tab

  1. Choose a Function Type from the dropdown
  2. Select a Column from the list (function applies to this column's values)
  3. (Optional) Modify the default Name
  4. Click OK to create the column

The statistical column becomes available for selection in the Report Builder.

note

Statistical columns not used in the report are automatically deleted when exiting the Report Builder.

Statistical Function Examples​

Rank Example:

Ranks Agility drop-down values from lowest to highest (e.g., Low, Medium, High):

Ranking Stories

Reverse Rank Example:

Ranks from highest to lowest value:

Reverse Rank

Running Total Example:

Maintains cumulative total:

Running Total

Percentile Example:

Classifies by percentage distribution:

Percentile Function

Difference from Previous Example:

Shows row-to-row changes:

Difference from Previous

Add Display Elements​

Display elements present your data visually in the report.

Insert Tables and Crosstabs​

Tables display data in rows and columns, while crosstabs summarize data across two dimensions.

To add a table:

  1. From the Insert tab, click Table or drag it to the Report Layout panel
  2. A new configuration tab appears for the table
  3. Configure table columns, grouping, and settings (see detailed table configuration below)

To add a crosstab:

  1. From the Insert tab, click Crosstab
  2. Configure row fields, column fields, and data cells

Insert Charts and Graphs​

Visual charts help identify trends and patterns in your data.

Supported chart types:

  • Bar charts (vertical and horizontal)
  • Line charts
  • Pie charts
  • Area charts
  • Scatter plots
  • Tree maps

To add a chart:

  1. From the Insert tab, select a chart type
  2. Configure the chart data source
  3. Set X-axis and Y-axis fields
  4. Configure chart appearance and style

Add Labels and Images​

Enhance reports with descriptive text and branding images.

To add labels:

  1. From the Insert tab, click Label
  2. Enter label text
  3. Configure font, size, color, and alignment

To add images:

  1. From the Insert tab, click Image
  2. Specify the image source:
    • Upload from file
    • Reference URL
    • Use embedded image
  3. Set image size and alignment

Configure Tables​

Tables are the most common display element in custom reports.

Configure Table Columns​

Select which data columns appear in your table and how they display.

To configure columns:

  1. Select the table in the Report Layout panel
  2. In the Configuration panel, use the Tabular Columns tab
  3. Drag columns from the Data Source panel to the table configuration
  4. For each column, set:
    • Label: Display name
    • Width: Column width in pixels or percentage
    • Alignment: Left, center, or right
    • Format: Number format, date format, or custom format

Group Table Data​

Grouping organizes rows into logical sections with optional subtotals.

To add grouping:

  1. In the table configuration, select the Grouping tab
  2. Drag a column to the grouping area
  3. Configure group settings:
    • Group header: Text to display for the group
    • Show subtotal: Calculate subtotals for numeric columns
    • Page break: Start each group on a new page

Configure Crosstabs​

Crosstabs summarize data across two dimensions with calculated intersections.

To configure a crosstab:

  1. Drag columns to Row Fields (vertical dimension)
  2. Drag columns to Column Fields (horizontal dimension)
  3. Drag numeric columns to Data Cells (values to summarize)
  4. Select aggregation function: Sum, Average, Count, Min, Max

Crosstab settings:

  • Show row totals: Display total for each row
  • Show column totals: Display total for each column
  • Show grand total: Display overall total
  • Suppress empty rows/columns: Hide rows or columns with no data

Format and Style Reports​

Apply formatting to improve report readability and visual appeal.

Apply Report Headers​

Report headers appear at the top of each page.

To add a header:

  1. From the Insert tab, click Header

  2. Enter header content:

    • Static text
    • Report title
    • Company name or logo
    • Page numbers
    • Date/time tokens

  3. Configure header appearance:

    • Font and size
    • Background color
    • Border style

Configure Report Settings​

Control overall report layout and behavior.

To configure report settings:

  1. From the Settings tab, click Report Settings
  2. Set options:
    • Page size: Letter, Legal, A4, or custom
    • Orientation: Portrait or landscape
    • Margins: Top, bottom, left, right
    • Columns: Multi-column layout
    • Background: Background color or image

Apply Stylesheets​

Stylesheets provide consistent formatting across multiple reports.

To select a stylesheet:

  1. From the Settings tab, choose a stylesheet from the dropdown
  2. Available styles:
    • Default
    • Classic
    • Modern
    • Professional
    • Custom (if configured by administrator)

Preview and Save Reports​

Test your report and save the definition for future use.

Preview the Report​

To preview:

  1. Click the magnifying glass icon magnify icon in the toolbar
  2. Or click Preview from the File tab

The report renders with actual data from the Data Mart database.

Save Report Definitions​

To save a report:

  1. Click the save icon save icon in the toolbar

  2. Or select Save or Save As from the File tab

  3. Enter a report name

  4. Choose a folder location:

    • My Personal Reports: Private to your account
    • Shared Reports: Available to other users (requires permissions)

  5. (Optional) Add a description

  6. Click Save

tip

Save frequently to preserve your work and avoid session timeout data loss.

Next Steps​

After building your custom report: