Create your own report template

Report templates are Microsoft Excel workbooks that contain definitions of what to include in the report. That is, they define the layout of the report (where information is placed on sheets, in rows, and in columns) and what should be reported (the actual solution results that should be included).

The information to be included in the report is defined in the template using a specific syntax. During report generation, this syntax is converted to output that matches solution values from your results. The output is saved in Excel file format in the designated report output folder.

The standard templates provided with Plan are generally usable without any need for editing. You don't need to create your own template files to create a report.

If you need to create your own report template, the easiest way is to customize one of the standard templates provided, since they contain all possible syntax and demonstrate their correct usage. The following workflow shows you how to do that:

1. Copy a template, then open it

   Open the folder where the templates are stored. This is likely to be C:\Program Files\Spiral Software\SpiralSuite\bin\Templates.

   Make a copy of the most suitable template, then open it in Excel.

2. Delete and rename worksheets

   Delete the worksheets you don't need from the workbook. However, do not delete the Contents worksheet. This must stay as the first worksheet as it is used to determine the template type.

   You can rename any of the worksheets, since all output data is generated from syntax that does not use the worksheet names.

3. Re-organize sections, add new rows and columns

   As well as re-ordering most of the sections of the report, you can do the following:

   • Add new rows and columns.

   • Filter sections to show specific information. This can increase the speed of report generation, while improving the readability of the report.

     Example: To have a section of rows listing all utility purchases except electricity, you could use the syntax {START-ROWS-UTILITY_PURCHASES,EXCLUDE="Electricity"}. The Output Specific Data section explains this syntax in more detail.

4. Save template

   Save the template to the desired location. If a template file has been used to create a report definition, and is then edited and saved, the report definition will not automatically update. To use the edited template, either recreate the report definition or update the template file then use the load template feature in the Report Definition dialog.

5. Open the Report Manager

   In Plan, click Manage in the Reporting ribbon tab:

   

6. Copy an existing report definition, as a basis for your own version

   Select an existing template, then click Copy. If no report templates are listed, add a report template.

   

7. Edit report definitions

   On the new copy, click Edit. The Report Definition dialog opens. Choose the Report Type if necessary.

   Warning: Be extremely careful about changing the report type. The template must match the correct report type, and should only be changed if the template file (which you will load in this step) is of a different type.
   It is best to create the report definition you require by clicking the Add button (which ensures that all options are automatically chosen), making a copy of it (as in the previous step), then leaving the Report Type as is.

   

8. Enter details

   Enter a Name and Description for the report and choose where to share it.

   

9. Load template

   Browse to the file location where your custom report template is saved.

   

   Select the required template and click Open.

   

   Once you're done, click OK.

10. Export template

    Select the report to export and click Export Template.

    

    The template is saved to a Microsoft Excel file.

Output specific data

Plan uses specific syntax to define the values to output in your reports. When this syntax is included, all the relevant items of data are looped over and are included in the report. For example, a Process Units section loops through your process units. All process unit assets are included in the report output, with the information requested for that asset.

Each section is defined as a series of rows and columns. The syntax for each is described in the next two sections.

Warning: Some report sections (such as Process Units and Blending) are only allowed once on a worksheet.

Define specific rows

Sections of the report tagged by {START-ROWS-[KEYWORD]} and {END-ROWS-[KEYWORD]} loop through keywords of the selected type.

For example, if you want a section of your report to have a row for each inventory name, use {START-ROWS-INVENTORIES} and {END-ROWS-INVENTORIES} to tell Plan to loop through all inventories. Then place the {INVENTORY-NAME} tag in between those tags to insert a row for each inventory name:

The following table shows the categories of rows you can define:

Define specific columns

Sections of the report tagged by {START-COLS-[KEYWORD]} and {END-COLS-[KEYWORD]} produce sections which loop through keywords of the selected type.

For example, if you want a section of your report to have a column for each property name, use {START-COLS-PROPERTY_NAMES} and {END-COLS-PROPERTY_NAMES} to tell Plan to loop through all inventories. Then place the {PROPERTY-NAME} tag in between those tags to insert a column for each property name:

The following table shows the categories of columns you can define:

A more complete list of syntax is also available.