Export Template Reports

Overview

Template Reports allow you to generate fully customised Word documents directly from your application. These exports are configurable and can be applied at different levels within your site., offering flexible document generation based on specific needs

Template Reports are available at three levels:

• App – Export data at Report Level within a specific Application.

• Record – Export data at the Record Level within an Application.

• Global – Export from any Homepage for data across the Site.

We will look at how to define and then upload a Word Doc with Keyword references. Then we will break down what the Keyword options available are and a variety of scenarios to give examples of the outputs that can be generated.

• Adding the Templated Report
• Uploading the Word Doc to a Template Report
• Supported Keyword References
  • Chart Report Key Word
  • Table Reports Key Word with Options
  • Record Key Word
  • Field Key Word
  • Exporting Child Templates
• Report Upload Validation

Adding the Templated Report

Before we upload the Export Template, we need to create an entry in the Templated Report Folder stating what the Export is going to be and which App and/or Level it is relevant to.

1. Navigate to the Templated Reports folder from App Studio Home.
2. Click on an existing Report to modify or either '+' or 'Add' to create a new template
3. Complete the required Fields as described below

Uploading the Word Doc to a Template Report

Once the Template Report entry has been saved, the Document Upload section becomes available.

1. Fill in all required properties for the new Template Report.

2. Click Save.

3. Scroll down to the Document Upload section.

4. Click the Upload icon to add your Word template (.doc or .docx format).

After upload, additional options appear to download or remove the existing document.

The Word Template that we upload is constructed using Keyword References. We will now look at all the different options that are available to use and how these can be used in combination to build elegant export packs from your Applications.

Note: Only a single file upload is supported. Uploading a new document replaces the existing one. Previous versions are lost unless saved manually elsewhere.

Supported Keyword References 

The Word Template uses Keyword References to dynamically insert data. Keywords must appear in their own paragraph or within a table cell and must reside in the main body of the document (not in headers or footers).

Important: Key Words must be placed be the only content within a line or within a table cell in a Word Template.

In addition to the following Key Words we can also use @PageBreak() to make sure the exported document starts a new page where we would like it to.

The first two Key Words for Chart Report and Table Report can be used in the context of a Record Template as well as App and Global level Templates. In the scenario where the Report is a child App of the App that the Record Template is being generated from, the Records in the Child Report will be filtered to only those that have been linked to the record being exported. This is with any additional filters that have been used within the Key Word reference. 

Chart Reports Key Word

@Report(AppIdentifier, ReportIdentifier, filter (optional), ChartWidth (optional), ChartHeight (optional))

• AppIdentifier – The identifier of the App that contains the Table Report to export
• ReportIdentifier – The Identifier of the specific Report within the  App that is being exported.
• filter – This is a filter string to narrow in on a subset of records relevant to the context the Report will appear in the Export Template. It could be Actions that are Status Red. It is constructed in OData query language.
• ChartWidth – Often a chart will need to scale down to fit into a set space in the Export. Enter the pixel width to scale down the chart image.
• ChartHeight – In addition to the chart width, a chart pixel height can be set but be sure to avoid scale ratio issues as the height will already auto-scale based on the set width and so this property not often used.

The following image shows how a Chart Report Key Word reference can be used to inject an image of the chart between text in the Word Template.

This Report used the keyword @Report(StakeholderAuditV2, RAGbyType, , 450) which broken down into its components is:

1. StakeholderAuditV2 - This is the Identifier of the App that the Report being referenced comes from.
2. RAGbyType - This is the Identifier of the Specific Report within the Stakeholder App.
3. filter=%5BActive%5D%20eq%20true - This filters the Records that contribute to the chart, in this case it is the Records where 'Active equals true'.
4. 450 - This is the number of pixels to set as the width of the chart. We have only set this parameter and not a height after as the fifth parameter because the chart height will automatically scale to keep the chart image ratio.

Table Reports Key Word (with Options)

@ListReport(AppIdentifier, ReportIdentifier, filter (optional), IgnoreWhenNoRecords (optional), RepeatHeaderAcrossPages (optional), UseFixedColumnWidths (optional))

• AppIdentifier – The identifier of the App that contains the Table Report to export
• ReportIdentifier – The Identifier of the specific Report within the  App that is being exported.
• filter – This is a filter string to narrow in on a subset of records relevant to the context the Report will appear in the Export Template. It could be Actions that are Status Red. It is constructed in OData query language. It can also optionally include a sort order.
• IgnoreWhenNoRecords – If there are no records, this parameter can be used to give a blank output instead of column headers with no record rows.
• RepeatHeaderAcrossPages – When there are enough rows that the Report splits across multiple pages, it will show the Field names again as a row header when the table continues on the new page.
• UseFixedColumnWidths – The Table Report selected will have column widths set in App Studio. If this parameter is included in the keyword reference and set to true then the column widths are respected.

An example of this being used on a report level export is to look at Exporting a Stakeholder List across multiple pages.

This uses @ListReport() references in the form

@ListReport(StakeholderAuditV2,ContactListExport,filter=%5BType%5D%20eq%20%27Channel%27&orderby=%5BName%5D%20asc,true,true,true)

Breaking this down into the individual parameters:

1. StakeholderAuditV2 - This is the Identifier of the App that the Report being referenced comes from.
2. ContactListExport - This is the Identifier of the Specific Report within the Stakeholder App.
3. filter=%5BType%5D%20eq%20%27Channel%27&orderby=%5BName%5D%20asc - This filters the Records to appear in each table, in this case it is the Records where 'Type equals Channel'. It then also orders that subset of Records by Name ascending.
4. true - The first true means that if there are no Stakeholders then the table will not show, if this was false we would have the column headings in a table row with no row entries for Stakeholders when there are none to display.
5. true - The second true means the Column headings repeat as can be seen at the top of the second page.
6. true - The final true is to respect the column widths set out in App Studio. This is how we can have narrow columns for Advocacy and Importance but still maintain wider columns for Name and Role. Without this set to trye, each column is equally distributed.

Record Key Word

@Record(Forms[], Fields[], LinkedAppReports[], ShowComments?(optional), ShowAttachmentsList?(optional))

     - e.g. @Record()

     - e.g. @Record([], [], [], false, true)

     - e.g. @Record([FormA, FormB], [FieldA, FieldB], [{ChildAppA, ListReport},{ChildAppB, BarChart}], true, false)

Fields Key Word

A Record Level Export can reference all of the values that are held in Fields in the Record that is being exported. This is done using the @Field(FieldIdentifier) with the Identifier of the Field in the brackets.

• @Field(Name) returns the value that the Name Field has in the record such as 
• @Field(Cost) returns the value in the Cost Field in the record such as 

Depending on the Field type it may also hold backing values that can be used in an Export. Take a Person Field, this stores the User GUID as the value and the User's name as Text so we can use:

• @Field(PersonField) returns 64fe1f3e-8074-4566-a14c-274dd9f6b21b
• @Field(PersonField_Text) returns Mark Johnson

Or suppose we have an Selection Field that has options of High, Medium and Low but with associated values of 1, 2 and 3. In this case

• @Field(SelectionField) returns 1
• @Field(SelectionField_Text) returns High

Other Fields like Number and Date Fields can have a format string added. The format string presents a friendlier option to read in the Report so we could use

• @Field(Budget) returns 20000
• @Field(Budget_Formatted) returns £20,000

There are also Fields which contain extra parameters and so they have their own Key Word references. An Image Field contains and image which we can set the width and height on @ImageField(FieldIdentifier, Width (optional), Height (optional)). Normally this would only have the width set as the height will auto-scale in ratio and so setting a height can distort the image

• @ImageField(ImageField, 300) returns the image added to ImageField with a pixel width of 300 and the height adjusted to maintain the width to height ratio of the originally uploaded image

Similarly, an In App Chart can also be exported as an image that can have the width and height set using @InAppChart(FieldIdentifier, ChartWidth (optional), ChartHeight (optional))

The following is an example of using the @Field() Key Word reference with a variety of different Field Types

Exporting Child Record Templates

For a templated report produced from a parent record, you can include the below keyword where you need child record level templates inserted for child records matching the filter criteria.

@ChildAppTemplatedReport(ChildAppIdentifier, ChildAppTemplatedReportIdentifier, FilterString)

Suppose that we have our Stakeholder Record Level Report as in this support article but we also have a linked Actions App.

We could use the following structure:

Here we have a template produced at the Stakeholder Record Level. 

• The first section references Fields from the Parent Stakeholder App
• Next we have an @PageBreak() reference to insert a page break and ensuring the Child Template Keyword starts on a new page
• Then we loop through the Child Action Records and produce for each the content that comes from the ActionOnePage Record Level Templated Report created for the Action App. Each Record will be on a new page.
• Again we add another @PageBreak() to split the rest of the content after the child records onto a new page
• Lastly we can continue adding information from the Parent Stakeholder Record

Report Upload Validation

When uploading documents to the export template, app studio will validate the field names being referenced in the export, if any don't match then it will not upload the document and show an error message in the bottom left-hand of the screen under a red triangle saying which references are wrong. 

For any issue where the document has been uploaded and the export is still failing please check export summaries - Export Summaries – Softools. This will contain a summary reason the Export failed.

View Available Exports

The Templated Exports Settings App displays a comprehensive list of all exportable Word template-based exports available on the site. In addition to in App Studio, it offers a centralised view of every template that can be used to generate Word or PDF documents, making it easy for users to find, access, and manage the exports relevant to the site.