Custom Reports

A custom report is a report you design: a handler runs your JavaScript over each session's data and renders the result through your HTML template, for admins, candidates, PDF exports and the API.

Published 2026/10/15

A custom report replaces the Standard Template — or is embedded above or below it — with a report you design yourself: your layout, branding, wording and calculations. You build it once per test and it renders for every session of that test, including sessions completed before you created it.

The two parts of a custom report

Part	Where you manage it	What it holds
Custom report	Test › Reporting › Template	Title, description, the handler it runs, and which organizations may use it.
Handler	Organization › Snippets › Handlers	The logic: an optional function (JavaScript) that turns the session's data into exactly the values you need, and a template (Nunjucks HTML) that turns those values into the report.

One handler can back several custom reports, and a test can have any number of custom reports. Which one a candidate or reviewer sees is decided by the test's default and, per delivery, by the task step.

Access

Private — only your organization can select it.
All organizations — any organization that uses this test (for example through the Test Library or Marketplace) can select it.
Selected organizations — only the partner organizations you pick.

Where a custom report appears

Admin Report — when the step's report template is the custom report, or Standard extended with it (top or bottom). See Admin Report.
Candidate Report — configured the same way in the step's User Report settings.
Export as PDF and Print — from the report view; split the report into .ti-page blocks for clean A4 output (see Print & PDF Layout).
REST API — the customReport expand on test sessions returns both the function's output object and the rendered HTML.
Result postbacks — the result sent to your webhook includes the custom result.

Where to start

How Custom Reports Work — the pipeline and where your code runs.
Build Your First Custom Report — step by step, from a real session's data to a report in production.
Report Input Reference, Writing the Function and Writing the Template — the reference you will keep open while building.
Recipes and Troubleshooting.

Custom reports are rendered when they are viewed, not stored. Saving a change to the handler changes the report of every session immediately — test against several real sessions before saving.
Good to know

In this section

How Custom Reports Work Each session's data is passed to your JavaScript function, which returns a plain object; your Nunjucks template renders that object to HTML. On servers the function runs in an isolated sandbox limited to 5 seconds and 128 MB. Build Your First Custom Report Download a completed session's Report Input, create a handler with the test's ID, paste the input as sample data, write the function and template, then attach the handler to the test as a custom report and make it the default. Report Input Reference The Report Input holds the candidate, dates, task and step, the scored result with sections, dimensions and answers by Reporting Name, the benchmark comparison, and the test's reporting settings; result, normy and testReporting can be missing. Writing the Function The function must be a single synchronous function named anonymous that returns a plain object; helpers go inside it, and object spread, optional chaining (?.) and nullish coalescing (??) are rejected by the parser. Writing the Template Templates use Nunjucks with HTML escaping on by default — use | safe only for HTML you wrote — and must carry all their own CSS and fonts, because the report is isolated from the app's styles. Print & PDF Layout Wrap each A4 page of a custom report in a div.ti-page of 210 × 297 mm; Print then puts every .ti-page on exactly one sheet, and Export as PDF follows your @media print rules, so each page's content must really fit. Recipes Tested building blocks for custom reports: safe percentages, matching the test's own pass mark and performance levels, parent and child dimensions, band texts, answers by Reporting Name, sten bars and reusable macros. Troubleshooting A handler missing from the Handler list has a different Test ID; "Unexpected token" means object spread, ?. or ??; blank values are misspelled or missing variables; a page that splits in the PDF has content taller than A4.