Add Custom Report Templates

Platform uses Docxtemplater for generating reports. Report structure depends on the Issue schemas that are set by default in the Project.

When creating a new report template, you must use technical names of the fields that you add to your Issue schema.

There are several default report templates in the Platform:

template.docx - unique report template for each issue schema;
universal-template.docx - common template for all issue schemas.

Before uploading your report templates to the Platform, we recommend you to download one of the default report templates, change it as you need, and upload it back to the platform.

Note: change the name of the default report templates before uploading them back to the Platform. When loading templates with the same name, the platform will automatically change the file names by adding the date and time to the files, for example [2021-04-06T15: 49: 23.895Z] template.docx.

Upload report templates

Note: only Hive administrators can upload new report templates.

To upload a report template to the Platform:

Log in to the Platform as an administrator;
Go to Administration > Report templates tab;
Click Upload template and add a template from your computer;
A new template appears in the list of templates.

When creating an issue you can select your template for Issue report.

Note: the issue report includes images in the formats that are supported by .docx (png and jpeg). Files in other formats that are attached to the issues will not be exported to the report.

Report template format

All report templates are customizable.

Important! When creating a new report template, you must use technical names of the fields that you add to your Issue schema.

You can include in your report:

any text that will be simply copied to the output file;
headers, footers, table of contents, title page, etc.;
issues with all fields or only with predefined fields.

You can edit style parameters and create your own field filters in .docx templates. The formatting that you use in your report template will be applied to all fields.

In addition, you can use Markdown issue fields in your report templates.

Predefined variables

Report filters and variables are used to insert text that may change in your output when you generate report. Predefined variables make it easy to insert things like the current date, the title of your project and so on.

Variables for outputting information about your project:
- {project.name} - exports project name to the report;
- {project.startDte} - {project.endDate} - exports project start and end dates to the report;
- {project.scope} - exports project scope to the report;
- {project.description} - exports project description to the report.
Variables for exporting Wiki pages:
- {#wiki.tree} - exports wiki-pages considering a tree hierarchy, example:
```
{#wiki.tree}
{name}
{@rendered}
{/}
```
- {#wiki.flat} - exports wiki-pages without considering a tree hierarchy, example:
```
{#wiki.flat}
{name}
{@rendered}
{/}
```
- {wiki.map} - exports wiki-pages by ID, example:
```
{wiki.map[42].name}
{@wiki.map[42].rendered}
```
- {wiki.byName} - exports wiki-pages by Name, example:
```
{wiki.byName["Summary"].name}
{@wiki.byName["Summary"].rendered}
```

Notes:

Wiki page name must be unique.

Entries are case and space sensitive.

Report Filters

With the help of filters, you can create your own data output in the report.

Common filter rules:

Filter without parameters: {myExpression | filter}
Filter with one parameter: {myExpression | filter:"argument1"}
Filter with several parameters: {myExpression | filter:variable:variable2}

List of available filters

lower

Converts the string to a lower case.

{issue.name|lower}

upper

Converts the string to an upper case.

{issue.name | upper}

length

Defines length of collection (list or string).

{issues | length}
{issues | where:'totalScore >= 2' | length}

prop

Defines an arbitrary property of an object.

{issues | prop:'length'}

where

Filters list of elements.

Total score is greater-than or equal to 2 (f.e., 2 - medium or 3 - high risk level):

{#issues | where:'totalScore >= 2'} {name} {/}

Total score is equal to the value 1 - low (f.e. 1 - low):

{#issues | where:'totalScore === 1'} {name} {/}

Probability is lower than 3 (f.e. 1 - low or 2 - medium):

{#issues | where:'probabilityScore < 3'} {name} {/}

Total score is equal to 3 and Criticality is greater-than or equal to 2 (possible values: && AND || OR):

{#issues | where:'totalScore === 3 && criticalityScore >= 2'} {name} {/}

Filter by any custom field with a numeric value:

{#issues | where:'myCustomFieldEstimatedLosses > 9000'} {name} {/}

find

Search by elements.

{(issues | find:'id === 42').name}

sortBy, sortByAsc

List sorting by ascending order. You can add several parameters:

{#issues | sortBy:'totalScore'} {name} {/}
{#issues | sortBy:'totalScore':'name'} {name} {/}

sortByDesc

List sorting by descending order. You can add several parameters:

{#issues | sortByDesc:'totalScore'} {name} {/}
{#issues | sortByDesc:'totalScore':'name'} {name} {/}

sumBy

The sum of the object fields.

{issues | sumBy:'myCustomFieldBusinessExpenses'}

toFixed

Converts a number to a string representation with a fixed number of decimal places;

{myNumber | toFixed:2}

json

Outputs the value of the json variable (can be applied for debugging when writing a template). We recommend using it with this variable to display current scope and all available variables.

{myVariable | json}
{this | json}

displayValue

Displays field values with enums (score, select, radio buttons). Called with the field's system value (f.e. 1 for score). Accepts field description from presetFieldsMap.

Example for Score field:

{#issues}
{totalScore | displayValue:presetFieldsMap.totalScore}
{/issues}

Custom fields example: * single select or radio buttons:

{#issues}
{myCustomField | displayValue:presetFieldsMap.myCustomField} 
{/issues}

multiple select:

{#issues}
{#myCustomListField}
{this | displayValue:presetFieldsMap.myCustomListField}
{/myCustomListField}
{/issues}

Report Styles

Markdown fields styles

Important! Do not change the Style IDs and Style names of the styles in template.docx and universal-template.docx. Currently, the report generator supports only predefined style names and IDs.

You can change styles parameters directly in the .docx report templates or if you create your own template, use the Style IDs and Style names listed below. These styles are applied only for Markdown fields, such as General description, Risk description, Technical description and Recommendations.

Style ID	Style Name	Usage	Comment
H1	H1	Paragraph	Level 1 headers
H2	H2	Paragraph	Level 2 headers
H3	H3	Paragraph	Level 3 headers
H4	H4	Paragraph	Level 4 headers
H5	H5	Paragraph	Level 5 headers
BodyExpRep	Body (Exp_Rep)	Paragraph	All default body paragraphs
BodyExpRepChar	Body (Exp_Rep) Char	Character	Characters inside default body paragraphs
Code	Code	Paragraph	Code block
CodeChar	Code Char	Character	Inline code
InternetLink	Internet Link	Character	Internet links
Emphasis	Emphasis	Character	Emphasis (Italic font)
StrongChar	Strong Char	Character	Strong (Bold font)
PictureCaption	Picture Caption	Paragraph	Caption for figures
TableCaption	Table Caption	Paragraph	Caption for Tables
Table style 1	Table style 1	Table	Table style

Styles for Risk values

Below is default report template styles for risk values. You can change these styles like you want and change the style IDs and names.

Style ID	Style Name	Usage	Comment
vulnrate	vulnrate	Paragraph	Vulnerability rate paragraph
styleRatingLow	styleRatingLow	Character	Characters for low vulnerability rate (green)
styleRatingMedium	styleRatingMedium	Character	Characters for medium vulnerability rate (yellow)
styleRatingHigh	styleRatingHigh	Character	Characters for high vulnerability rate (red)