Writing Custom Reports for SpiraTeam v2.3+

1) The report database tables

Each individual report is made up of the following items:

†  Report definition – name and description of the report, as well as what category it belongs to

†  Report formats – a list of the formats that the report can be created in

†  Report sections – each report is made up of one or more sections. Each section can have a set of filter/sort options associated with it by linking the section to an artifact type (requirement, test case, etc.). Sections that are not filterable (e.g. project overview) don’t need to be linked to an artifact type

†  Report elements – each report section can optionally contain child elements that display associated information for each record in the section (e.g. if the section was a list of requirements, then the elements could be the test cases linked to each requirement). Unlike sections, elements don’t have their own filter options.

In the database, we have the following tables defined:

So when creating a new report, you have two options:

1)     Simply find a report that is close to the one you want, i.e. it has the appropriate sections (with filters/sorts) and contains the necessary secondary elements. Then you can just modify the XSLT and XML report definition files (see sections 2 and 3 below) and not touch the database. This is easier than the next option, but means that you lose an existing standard report in the system.

2)     Create an entirely new report by populating new rows in each of the tables in the database. In future versions of SpiraTeam there will be a web-based GUI that will make this process much easier.

To add a completely new report as defined in option 2, you’d need to populate the following tables:

†  TST_REPORT – contains the name/description of the new report

†  TST_REPORT_AVAILABLE_FORMAT – maps the report to the list of possible output formats defined in the TST_REPORT_FORMAT table

†  TST_REPORT_SECTION – contains the sections that make up the report. You would need to create at least one new section for the new report

†  TST_REPORT_AVAILABLE_SECTION – you’d use this to map the new report to the new section created, and also to any required pre-existing sections

†  TST_REPORT_SECTION_ELEMENT – if the new section uses any of the standard (existing) secondary elements from the TST_REPORT_ELEMENT table, they’d need to be added to this table.

(Note that green tables can have data added to them, whereas the blue ones should NOT).

Many of the tables (TST_REPORT, TST_REPORT_SECTION, TST_REPORT_ELEMENT, TST_REPORT_FORMAT) have a special column called “TOKEN”. This is used when the reporting system looks for the matching report definition files (.XSLT and .XML) to actually generate the report. If you create new reports, make sure that these TOKEN values match the files you will be adding in section 2 and 3 below:

2) The Report Template (XML) Files

Inside the C:\Program Files\SpiraTeam\Reports folder on the server, there will be a folder called Templates. In this folder will be a series of XML files that contain the templates used to display the various reports in the system. Their filename consists of the following items concatenated:

            [Report Token]_[Report Format Token].xml

So a Microsoft Word 2003 Incident Detailed report would be named IncidentDetailed_MsWord2003.xml.

Each of these XML files should be capable of being opened in its native application (MS-Word, MS-Excel, MS-Project and an HTML editor) so you can use the application to modify the “look and feel” of the report: add colors, logos, etc. and in general change the theme used by the report. Be careful however as there are some XML comments included in the templates that need to be preserved as they demarcate where the various Report Sections will get inserted.

The XML comments will be in the form:

<!-- [Report Section Token]  -->

If you inadvertently modify or delete these special comments, you will need to open up the XML template in a text editor such as Notepad and insert them back in. Also for a new report, make sure that the comment name matches the name of the new report section you defined earlier.

3) The Report Transformation (XSLT) Files

Inside the C:\Program Files\SpiraTeam\Reports folder on the server, there will be a folder called Transforms. In this folder will be a series of XML Stylesheet Transform (XSLT) files that contain the transformations used to convert the raw data from the application into the displayable form used in each section of a report. Their filename consists of the following items concatenated:

            [Report Section Token]_[Report Format Token].xslt

Unlike the templates described in section (2) there will be one file for each section that makes up the report. The contents of each transform file will be specific to the type of data being transformed and the desired output format. It is beyond the scope of this document to explain how XSLT works and what the appropriate syntax is. However to help you create the appropriate report transformation, it is helpful to run the raw XML format report in SpiraTest as this will show you the different data elements that make up the data-stream that is available for transformation.