Customizing report style and layout is now available in IBM Cognos Adaptive Analytics version 10.1 Fix Pack 1

Resolving The Problem

IBM Cognos Adaptive Analytics version 10.1 Fix Pack 1 enables report managers to customize the look and feel of generated reports using a template file. This feature is only available starting with Cognos Adaptive Analytics version 10.1 Fix Pack 1.

1 Cognos Adaptive Analytics reports

All reports that are generated by Cognos Adaptive Analytics follow a common layout structure:

• Report header
  The header contains the analytic type icon, a report title, the company logo, the prompt filters (HTML), and the selected filter values (PDF).
• Chart section
  This section can be turned off for all analytic types, and it is not supported for detailed listing reports.
• Detail data section
  This data can be either a list or a crosstab for reports that use the Summary Analysis analytic type. For reports that use other analytic types, this data is always a list or always a crosstab depending on the analytic type.
• Report footer
  This section contains text that shows selected filters values subsection, as well as the report execution date and page number. Note that the selected filters values section is only generated for reports that are intended to be deployed in IBM Cognos Connection, via the “Generate Deployment Archive” action.

Figure 1 shows a typical report layout, including the four parts defined in the previous list.

Figure 1 - Report layout



2 Customizing the report template

Cognos Adaptive Analytics comes with a report template that your Cognos Adaptive Analytics administrator can edit to customize your reports. The template contains an extensive set of classes which control the style of the various layout elements of the report. The Cognos Adaptive Analytics engine will read these classes from the template and apply them to any generated reports.

The template is a V5 report specification and can edited using IBM Cognos Report Studio or directly using an XML editor. The only aspects of the template which should be edited are the set of local classes.

Steps for the Cognos Adaptive Analytics administrator

1. Find the ATTemplate_custom.xml file in the following folder:
   IBM_BI_Server_Installation_Location\data\AA\templates\.
2. Save the original ATTemplate_custom.xml file in a location where you can find it later in case you need to revert your changes.
3. Copy the file to the clipboard.
4. Open Cognos Report Studio.
5. From the Tools menu, click Open Report from Clipboard.
6. From the View menu, click Classes. The list of local classes contains includes all the elements you are able to change using the template. Figure 2 shows the Cognos Report Studio interface, including the Local Classes pane, Preview pane, and Properties pane.
   
   Figure 2 – Classes in Cognos Report Studio user interface
   
7. From the Local Classes pane, click a class, and then change its settings in the Properties pane. A preview of the class is shown in the Preview pane. You can click the Page view icon to see the template with the styles applied. Figure 3 shows the Cognos Report Studio user interface, including the page view of the template with the styles applied.
   
   Figure 3 – Template in Cognos Report Studio user interface
   
8. When you are finished editing the template, from the Tools menu, click Copy Report to Clipboard.
9. Open a text editor, and paste the report into the text pane.
10. From the text editor, save the file as ATTemplate_custom.xml in the following folder:
    IBM_BI_Server_Installation_Location\data\AA\templates\.
11. To apply the template to your Cognos Adaptive Analytics reports:
• Edit the Cognos Adaptive Analytics configuration file called aaConfig.xml to add the following text to the Settings section:
  <EditATTemplate>on</EditATTemplate>
• Open Cognos Adaptive Analytics.
• Click the projects icon, and click Reload Analytic Type Template.

3 Class reference

The following sections describe the classes that are defined in the template.

3.1 Page header

Figure 4 shows organizational layout elements within the page header and the local classes for these.

Figure 4 – Page header layout elements


Table 1 shows the full list of the classes that are used in the page header area.

Table 1 – Page header classes

Class name	What the class applies to
aa_static_block_header	The block that contains static text items. This block can be used for a copyright notice or disclaimer.
aa_report_title_block	The block that contains the report title table. This block is not rendered in the Cognos Adaptive Analytics interactive report environment.
aa_report_title_table	The report title table, which has three columns: analytic type icon, report title, and company icon.
aa_report_title_at_icon_cell	The analytic type icon within the report title table.
aa_report_title_cell	The title cell within the report title table.
aa_report_title_logo_cell	The company logo in the report title table. The company logo can be changed by selecting a different file using the Background Image property.
aa_prompt_block	The block that contains prompts on the report page. This block is not rendered in the Cognos Adaptive Analytics interactive report environment.
aa_prompt_label_cell	In an HTML report, the table cell within a prompt that contains the prompt name.
aa_prompt_button_cell	In an HTML report, the table cell within a prompt that contains the Run button.
aa_prompt_button	In an HTML report, the Run button within a prompt.
aa_prompt_label_cell_pdf	In a PDF report, the table cell within a prompt that contains the prompt name.
aa_prompt_cell_pdf	In a PDF report, the table cell within a prompt that contains the display text of the prompt.
aa_prompt_text_pdf	In a PDF report, the table cell within a prompt that contains the prompt value.

3.2 Page body

Figure 5 shows organizational layout elements within the page body and the local classes for these.

Figure 5 – Page body layout elements


Table 2 shows the full list of the classes that are used in the page body area.

Table 2 – Page body classes

Class name	What the class applies to
aa_chart_table	The table that contains the chart.
aa_chart_cell	The table cell that contains the chart (for a report with a single chart).
aa_chart_cell_multiple	The table cell that contains the chart (for a report with multiple charts).
aa_chart_single	The chart object (for a report with a single chart).
aa_chart_multiple	The chart object (for a report with multiple charts).
aa_chart_title	The blocks that contains the chart title.
aa_chart_axis_title	The blocks that contains the axis titles.
aa_chart_to_details_separator_block	The block that separates the charts from the details sections.
aa_details_block	The block that contains the details sections. The details could appear as a list or crosstab, or as one of the specialized formats that are used, for example, in period on period or balance walkthrough reports. This class also applies to the block that separates the charts from the details sections as described in the previous row of this table.
aa_topic_block_detailed_listing	The block that contains the topic name in a detailed listing. This block appears above the list section of each topic.

3.3 List reports

Table 3 shows the full list of the classes that are used in list reports.

Table 3 – List report classes

Class name	What the class applies to
aa_list	A list.
aa_list_column_heading	The column headings in a list.
aa_list_cell_level	Cells in the list that are used for hierarchy levels or attributes.
aa_list_cell_measure	Cells in the list that are used for measures or calculations.
aa_column_subtotals_label cell	Cells in the list object that are used for the label of a subtotal row.
aa_column_subtotals_value_cell	Cells in the list object that are used for the value of a subtotal.
aa_column_totals_label_cell	Cell that is used for the label of a total for a section.
aa_column_totals_value_cell	Cell that is used for the total value in a section.
aa_section_header_cell	Cell that contains the section header. This cell has no style by default.
aa_section_header_table_cell	When subtotals are enabled, the section header in a table cell.
aa_section_label	Label of the section header.
aa_section_item	An item in a section header.
aa_section_subtotal_label_cell	Cell that is used for the label of a subtotal for a section.
aa_section_subtotal_value_cell	Cell that is used for the subtotal value in a section.
aa_column_totals_label_cell_with_section	When there are sections in the report, column totals are organized in a table. This class applies to the cell that is used for the label of a total in a section.
aa_column_totals_value_cell_with_section	When there are sections in the report, column totals are organized in a table. This class applies to the cell that is used for the value of a total in a section.

3.4 Crosstab reports

Table 4 shows the full list of the classes that are used in crosstab reports.

Table 4 – Crosstab report classes

Class name	What the class applies to
aa_crosstab	A crosstab.
aa_crosstab_row_heading	A row heading in a crosstab.
aa_crosstab_column_heading	A column heading in a crosstab.
aa_crosstab_row_totals_label_cell	The cell that shows the label for a row total.
aa_crosstab_row_totals_cell	The cell that shows a row total.
aa_crosstab_column_totals_label_cell	The cell that shows the label for a column total.
aa_crosstab_column_totals_cell	The cell that shows the total for a column.
aa_crosstab_corner	The measures label.
aa_crosstab_cell	A crosstab cell.
aa_crosstab_subtotals_label_cell	The cell that shows the label for a subtotal.
aa_crosstab_subtotal_values_cell	The cell that shows the subtotal.
aa_croostab_totals_label_cell_with_section	When the crosstab report includes a section, totals are arranged in a table at the foot of the crosstab. This class applies to the labels in that table.
aa_croostab_totals_value_cell_with_section	When the crosstab report includes a section, totals are arranged in a table at the foot of the crosstab. This class applies to the values in that table.

3.5 Classes specific to the Period on Period analytic type

Table 5 shows the full list of the classes that are used only in reports that use the Period on Period analytic type.

Table 5 – Period on Period analytic type report classes

Class name	What the class applies to
aa_period_on_period_total_label	The label for a row total.
aa_period_on_period_corner	The measure in a crosstab.
aa_period_on_period_total_cell	The cells that contain total values.
aa_period_on_period_cell	The cells in a crosstab.
aa_period_on_period_row_heading	The label for a row heading.
aa_period_on_period_time_column_heading	The label for a column heading.
aa_period_on_period_summary_column_heading	The label for a column heading.
aa_period_on_period_subtotals_label_cell	The label for a subtotal.
aa_period_on_period_value_cell	Cells that contain subtotal values.
aa_period_on_period_totals_label_cell_with_section	When the crosstab report includes a section, totals are arranged in a table at the foot of the crosstab. This class applies to the total label cell in that table.
aa_period_on_period_totals_value_cell_with_section	When the crosstab report includes a section, totals are arranged in a table at the foot of the crosstab. This class applies to the total value cells in that table.

3.6 Page footer

Table 6 shows a full list of the classes that are used in the page footer area.

Table 6 – Page footer classes

Class name	What the class applies to
aa_static_block_footer	The block that contains a static text item. These items can be used for a copyright notice or disclaimer.
aa_page_footer	The page footer.
aa_footer_block	The block that contains report parameters and run date.
aa_run_date_cell	The table cell that contains the run date.
aa_run_date_label	The text item for the label Run Date.
aa_run_date_text	The text item that contains the run date.
aa_page_number_cell	The table cell for the page number.
aa_page_number_label	The text item for label the Page.
aa_page_number_text	The text item for the actual page number.
aa_report_parameters_block	The block that contains the report parameters.
aa_report_parameters_label	The label Report Parameters.
aa_report_parameters_text	The text of the report parameter.

4 Configuring static text

You can add static text to the template in the header, footer, or both. This is intended to be used for copyright text or legal disclaimers. The static text appears in both interactive and deployed reports for all analytic types.

The report page of the template includes place holders for these static text items, and you can add the text to any of these areas:

• Add text above the report title by double-clicking or selecting the text Double-click to edit text above the Report Title area and then typing your text. Figure 6 shows these areas on the report page view.

Figure 6 – Report Title area and static text area

• Add text above the report footer by double-clicking or selecting the text Double-click to edit text above the Report Parameters area and then typing your text. Figure 7 shows these areas on the report page view.

Figure 7 – Report Parameters area and static text area


The styles for these two static text items are defined by the classes aa_static_block_header and aa_static_block_footer.