Export Template Reports

Overview

Export Template Reports allow App Builders to generate customised Word documents from Softools. A Word template controls the document layout, branding and static text, while keyword references insert current Record data, Report content, images and linked child information when the export is run.

Template Reports can be made available at three levels:

• App: export Report data from a specified App.
• Record: export information for the Record currently open in the Workspace.
• Global: export information across the Site from a Homepage.

This article explains how to configure a Template Report, create and upload the Word template, use the supported keywords, and control which Records appear in Record-level exports.

Contents

• Choosing the Template Report level
• Adding a Template Report
  • Setting a system default
• Creating the Word template
• Uploading and validating the template
• Managing the uploaded document
• Supported keywords
• Adding Reports to an App-level template
  • Adding a chart Report
  • Adding a table Report
• Creating a customised Record-level export
  • Adding individual Field values
  • Adding images and In-App Charts
  • Using Report keywords in a Record-level template
  • Adding child Record templates
  • Adding page breaks
• Adding the full standard Record export with @Default()
• Creating a consistent baseline export with @Record()
• Testing a Template Report
• Viewing configured Template Reports
• Troubleshooting

Choosing the Template Report level

Choose the subtype according to where Users need to run the export and what the document should contain.

App

An App-level Template Report is available from the selected App. Use it for documents built from App Reports, such as a stakeholder directory containing a chart and several filtered tables.

Record

A Record-level Template Report is available while viewing a Record in the selected App. It can include values from the current Record, linked child Records, Reports and child Record templates.

Record-level exports apply the exporting User's security. Report keywords return only Records that User is permitted to access.

Global

A Global Template Report is available from Homepages. It can combine Reports from different Apps into a single Site-wide document, such as an executive portfolio pack containing Projects, Actions and Benefits.

Adding a Template Report

Template Reports are configured centrally in App Studio.

1. Open App Studio.
2. Select Templated Reports.
3. Select an existing Template Report to edit, or select + to create one.
4. Complete the configuration properties.
5. Select Save.

Setting a system default

Enable Use As System Default For SubType to make the Template Report the default export at App, Record or Global level.

The App property is not required when a Template Report is the system default because the default applies across the selected subtype.

Creating the Word template

Create the document in Microsoft Word and add branding, headings, explanatory text, tables, page headers and page footers as required. Insert Softools keyword references in the main body where dynamic content should appear.

Keyword references must:

• be the only content in their paragraph or table cell;
• appear in the main body of the document;
• not be placed in a page header or footer; and
• use valid App, Report, Form, Field and Template Report identifiers.

Static content, Word styles and document formatting surrounding a keyword remain part of the generated document.

Important: Keyword references are identifiers, not display labels. Changing the label shown to Users does not change the identifier used in the Word template.

Uploading and validating the template

After saving the Template Report configuration:

1. Scroll to the Document section.
2. Select the upload icon.
3. Upload the Word template.
4. Review any validation messages.
5. Select Save.

Only one Word document can be attached to a Template Report. Uploading a replacement removes the previous document, so retain a separate copy if earlier versions may be needed.

App Studio validates supported keyword references during upload. If a referenced identifier cannot be found, the document is not accepted and the validation summary identifies the affected reference.

Managing the uploaded document

Once a Word template has been uploaded, the Document section shows the filename and three controls:

• Upload: select another Word document. This overwrites the document currently attached to the Template Report.
• Download: download a copy of the attached Word template.
• Remove: remove the attached document from the Template Report.

Only one document can be attached at a time. Download and retain a copy before overwriting or removing a template if it may be needed again.

Supported keywords

The following keywords can be used in Word templates:

Optional parameters are positional. Retain the commas for any skipped parameters before a later value.

Adding Reports to an App-level template

App-level Template Reports can use Report keywords to insert chart and table Reports for the Records selected before the export is run. The same keywords can also be used in Global and Record-level templates. Their general syntax and options are introduced here, before the additional hierarchy and filtering behaviour for Record-level templates is explained later.

Adding a chart Report

Use @Report() to insert a chart Report as an image.

@Report(AppIdentifier,ReportIdentifier,FilterString,ChartWidth,ChartHeight,IgnoreHierarchy)

For example:

@Report(StakeholderAudit,RAGbyType,,450)

This inserts the RAGbyType Report from the StakeholderAudit App at a width of 450 pixels.

Set a width only where possible. The height then scales automatically and preserves the chart's proportions. Set both dimensions only when the output must fit a fixed area.

A chart keyword may be placed inside a styled single-cell Word table. The table styling then provides a background or border behind the generated chart.

Adding a table Report

Use @ListReport() to insert a table Report.

@ListReport(AppIdentifier,ReportIdentifier,FilterString,IgnoreWhenNoRecords,RepeatHeaderAcrossPages,UseFixedColumnWidths,IgnoreHierarchy)

For example:

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

This returns Stakeholders whose Type is Channel, orders them by Name, hides the table if there are no matching Records, repeats the headings across pages and uses the configured column widths.

Place a table Report keyword in its own paragraph when the generated table needs to flow across pages. Wrapping it in a single-cell table can prevent Word's repeating-header behaviour and constrain the generated content.

Creating a customised Record-level export

A customised Record-level export uses individual keywords to control the labels, layout and position of each item in the generated document. Start with Fields from the current Record, then add images, In-App Charts, linked Reports or child Record templates as required.

Adding individual Field values

Use @Field() in a Record-level template to insert one value from the current Record.

@Field(FieldIdentifier)

For example:

@Field(ProjectReference)
@Field(RAGStatus)

Some Field types provide related backing values:

• For a Person Field, @Field(ProjectManager) returns the stored User identifier and @Field(ProjectManager_Text) returns the User's name.
• For a Selection Field, @Field(Status) returns the stored option value and @Field(Status_Text) returns the displayed option text.
• For a Date Field, @Field(TargetDate_Formatted) returns the formatted date.

Number formatting

For Money, Number, Integer and Long Fields, @Field() applies the Field's Number Formatting configured in App Studio. This includes currency, digit grouping, percentage settings and decimal places.

For example, if PillarBudget is configured as British Pound currency with digit grouping and two decimal places:

@Field(PillarBudget)

returns:

£1,250,000.00

Use the appropriate _Formatted value when the exported presentation needs to differ from the standard Field output.

Adding images and In-App Charts

Use @ImageField() to insert an image stored in an Image Field:

@ImageField(FieldIdentifier,Width,Height)

Use @InAppChart() to insert an In-App Chart:

@InAppChart(FieldIdentifier,ChartWidth,ChartHeight)

Width and height are optional. Set the width only where possible so Softools can preserve the original proportions automatically.

Using Report keywords in a Record-level template

The same @Report() and @ListReport() keywords can be used in a Record-level template. At this level, Softools can use the current Record hierarchy to limit which Records are returned.

Using hierarchy

Record-level Report keywords use the current Record hierarchy by default.

If the referenced Report belongs to a directly linked child App, Softools returns the child Records linked to the Record being exported. The keyword filter is then applied to that linked set.

For example, a Pillar Record can include its directly linked Projects using:

@ListReport(Projects,ProjectExport,,true,true,true)

If the referenced App is not a direct child of the current App, hierarchy does not provide a matching set of Records. For example, Actions linked beneath Projects are grandchildren of a Pillar. Set the final IgnoreHierarchy parameter to true when the Report filter should determine which Records are returned.

Existing templates retain their hierarchy behaviour because IgnoreHierarchy is optional and defaults to false.

Using dynamic filter values

A Record-level filter can take a value from the Record being exported. Place the current Record Field identifier inside double braces:

{{FieldIdentifier}}

There are two common reasons to use a dynamic filter with IgnoreHierarchy.

Collecting grandchildren across child Records

In this example, Projects are children of a Pillar and Actions are children of those Projects. Actions are therefore grandchildren of the Pillar rather than direct children.

The following keyword ignores the direct hierarchy relationship and returns Actions whose PillarReference matches the current Pillar:

@ListReport(Actions,ActionExport,filter=[PillarReference] eq {{PillarReference}},true,true,true,true)

This produces one combined Actions table across all child Projects belonging to that Pillar. IgnoreHierarchy does not itself traverse the grandchildren. It allows the PillarReference filter to establish the required set.

The same approach can be used with a chart:

@Report(Actions,ActionsByStatus,filter=[PillarReference] eq {{PillarReference}},500,,true)

Retrieving Records from a standalone App

Benefits are held in a standalone App rather than beneath Pillars in the hierarchy. There is therefore no hierarchy path from the current Pillar to its Benefits.

The following keyword ignores hierarchy and uses the matching PillarReference value to return the relevant Benefits:

@ListReport(Benefits,BenefitExport,filter=[PillarReference] eq {{PillarReference}},true,true,true,true)

In both cases, the final true means that the filter supplies the relationship instead of the current Record hierarchy.

Security: @Report(), @ListReport() and @ChildAppTemplatedReport() apply the exporting User's security. Ignoring hierarchy does not grant access to additional Records.

Adding child Record templates

Use @ChildAppTemplatedReport() in a parent Record template to generate another Record-level Template Report for each linked child Record.

@ChildAppTemplatedReport(ChildAppIdentifier,ChildTemplateReportIdentifier,FilterString)

For example, a Pillar export can insert the ProjectOnePage template for every linked Project:

@ChildAppTemplatedReport(Projects,ProjectOnePage)

The exporting User's security is applied to the child Records.

Starting each child Record on a new page

Place the keyword in its own paragraph outside a table. Each child Record template begins on a new page. This works well for a portfolio pack where every Project needs a separate Project Overview page.

Flowing child Records continuously

Place the keyword inside a single-cell Word table when the child Record outputs should flow one beneath another. The cell's formatting can also provide a shared background or border around the generated content.

This is an intentional layout choice. Use it for a continuous directory-style output rather than a one-page-per-Record pack.

Adding page breaks

Use the following keyword to start subsequent content on a new page:

@PageBreak()

Place it in its own paragraph where the page should end. For example, it can separate a parent summary from subsequent Report sections.

Adding the full standard Record export with @Default()

Use @Default() when a Template Report that overrides the Record-level system default should still insert the complete standard Record export:

@Default()

@Default() generates the standard Record export, including the configured Forms, Template headings and Field values.

Rules and Form Rules are not evaluated by either approach. Content hidden in the Workspace by those rules will still appear in the export, and Workspace styles are not reproduced.

Creating a consistent baseline export with @Record()

Use @Record() to insert selected content from the current Record. This provides a quicker, automatically generated baseline where precise labels and positioning are not required.

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

Examples:

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

Using a consistent Export Form

For a quick and consistent Record export, create a Form in each App with the same identifier, such as ExportForm. Add the key Fields for that App to the Form, then use:

@Record([ExportForm])

This allows each App Builder to decide which key values are included while using one common Template Report design across Apps.

The output contains the Form heading, Template headings and Field values. It does not add Field labels automatically. For a fully designed document with descriptive labels and precise positioning, use individual keywords such as @Field(), @Report() and @ListReport().

Testing a Template Report

After uploading and saving the Word template, test it from the location where Users will run the configured subtype. This confirms that the Template Report is available, the keywords return the intended content and the generated document has the expected layout.

The available export location depends on the configured subtype:

• Run an App Template Report from the selected App's actions menu. Select the required Records in the Report before opening Export. The Template Report runs across the selected Records.
• Run a Record Template Report while viewing a Record in its configured App.
• Run a Global Template Report from a Homepage.

To test the export:

1. Open the relevant App, Record or Homepage.
2. Open the actions menu and select Export.
3. Select the required export type.
4. Select the Template Report.
5. Enter an optional filename.
6. Select Confirm.
7. Review the resulting Export Job notification.

Reviewing a successful test

When the test finishes successfully, an Export Job notification appears beneath the notification bell.

For a successful export:

• select the arrow in the top-right corner to open its record in Export Summaries;
• select the download arrow to download the generated file; or
• select the bin to remove the notification.

Investigating a failed test

If the test fails, its Export Job notification is marked with a red strip. Select the arrow in the top-right corner to open Export Summaries, where the full error message can be reviewed.

The Export Summaries App keeps a history of exports, subject to the User's permissions. It records information including the status, requesting User, start and finish times, download history and any error details. This makes it the main route for diagnosing a Template Report that uploads successfully but fails when tested. Successfully generated files can also be downloaded again from their Export Summary.

Exported files are retained for 12 months. Download and store a separate copy if the document must remain available for longer. See Export Summaries for more information.

Viewing configured Template Reports

The Export Templates App provides a central view of the Word template-based exports configured across the Site. Use it to review the Template Reports available in addition to managing individual definitions through App Studio.

Troubleshooting

The template will not upload

Review the validation summary in App Studio. Confirm that each App, Report, Field and Template Report identifier exists and is valid for the configured subtype and App.

A Record-level Report is empty

Check the App hierarchy. By default, Record-level Report keywords return Records from the relevant linked child App. If the referenced App is not a direct child, add an appropriate filter and set IgnoreHierarchy to true.

Table headings do not repeat

Confirm that RepeatHeaderAcrossPages is true and place the @ListReport() keyword in its own paragraph rather than inside a single-cell Word table.

A Field value is unexpected

Confirm whether the template should use the stored value, a _Text value or a _Formatted value. For numeric Fields, review the Field's Number Formatting in App Studio. Also check the Field Identifier is correct if there are multiple similar Fields such as statuses or dates.

The document uploaded but the export failed

Open the failed Export Job notification and select the arrow in its top-right corner. Review the full failure reason and supporting details in Export Summaries.

Also confirm that:

• each keyword is the only content in its paragraph or table cell;
• keywords are in the document body rather than a page header or footer;
• positional commas have been retained where optional parameters are skipped; and
• the document is a supported Word file.

Related articles

• Export Templates
• Export Summaries
• How can I see my Exports?
• Exporting a Record and Report
• Filters (OData) - Simple
• Configuring Base Filters in Reports (+Group & Sort)
• Fields, Templates, Forms, Records and Reports
• Field Formatting
• In-App Chart
• Rules
• Form Rules - Form and Template Visibility