In ZAP's automation report job, what does the template parameter actually refer to?

juniorshould knowfreq 50%

answer

one folder per template
the folder's name is the id
the pretty title lives inside template.yaml
blank means risk-confidence-html

basics

~10 s

The template's own directory name under ZAP's reports folder - its id, not the display title written inside template.yaml and not the output file name. Leave it empty and the job uses risk-confidence-html.

solid answer

~40 s

Every report template is a directory, and the report job's template parameter is that directory's name - what the shipped help page calls the template ID. The name: key inside the directory's template.yaml is a different thing: it is the human-readable title the desktop report dialog lists, and the job never matches on it. Leave template empty and the job substitutes risk-confidence-html. Name an id that no loaded template has and you get no report at all - the job records an error that lists every id it can see, and returns without writing a file. Because the directory is the identity, dropping a copied directory into the templates folder is the whole of installing a template.

Every report template is a directory, and the `report` job's `template` parameter is that directory's name - what the shipped help page calls the template ID. The `name:` key inside the directory's `template.yaml` is a different thing: it is the human-readable title the desktop report dialog lists, and the job never matches on it. Leave `template` empty and the job substitutes `risk-confidence-html`. Name an id that no loaded template has and you get no report at all - the job records an error that lists every id it can see, and returns without writing a file. Because the directory *is* the identity, dropping a copied directory into the templates folder is the whole of installing a template.

code

yaml · 5 lines

yaml

- type: report
  parameters:
    template: traditional-html     # the directory's name, not its title
    reportDir: /zap/wrk
    reportFile: nightly-example-com

go deeper

for a junior

Remember that a report template is a folder and that the folder's name is what you write in the plan. If you leave the value out, you get the risk-confidence-html template.

for a middle

Be able to explain the split: the directory name is the id the job matches on, while the name key inside template.yaml is only the title a human sees in the desktop dialog.

for a senior

Talk about what a wrong id costs in an unattended run - no file is written at all - and about the template folder being machine state that has to be provisioned onto every runner.

for a principal

Own where template folders come from across a fleet: baked into an image, mounted, or fetched at start-up. The plan is portable, the template is not, and that asymmetry is what you are designing around.

Reporting is an add-on, and templates are folders

Reporting is not part of ZAP's core program. It is the reports add-on, which registers the automation report job, the desktop report dialog and the shipped template set. (The same add-on registers the outputSummary job, which is why a plan generated for you by a packaged scan script needs reports present at all.)

The add-on keeps its templates as directories, one per template, inside a single templates folder. That folder defaults to reports/ under ZAP's home directory and is itself configurable, through the reports.templateDir configuration key. At load time the add-on lists the immediate subdirectories of that folder and, for each one holding a readable template.yaml, builds a template object. A subdirectory with no template.yaml is skipped silently - it is not an error, it simply is not a template.

Two names, and only one of them is the id

Every loaded template carries two names, and confusing them is the classic mistake:

name	where it comes from	what consumes it
the config name, i.e. the id	the directory's own name on disk	the plan's `template:` value, and the ID column of the shipped help page
the display name	the `name:` key inside `template.yaml`	the desktop report dialog's picker

So template: risk-confidence-html resolves because a directory of exactly that name exists - not because any file inside it contains that string. That same template's name: key reads Risk and Confidence HTML, and putting that into a plan does not work. The lookup the job performs walks the loaded templates comparing directory names, and nothing else. The display name has one other property worth knowing: the add-on keys its loaded templates by it internally, so two template directories that declare the same name: collide even though their folders differ.

What each outcome looks like

template omitted, or present but empty. The job substitutes risk-confidence-html, the add-on's default, and carries on. That default is a themed HTML document, so an unconfigured report job produces HTML.
template set to a real id. The template is found, and its declared file extension is then forced onto the output name: if your reportFile does not already end in it, the extension is appended.
template set to something nothing matches. No report is written. The job raises an error - not a warning - quoting the value you supplied and listing every template id it could see, which is the fastest way to discover what a given install actually has.

Why this bites in a pipeline

The id is a filesystem fact, so it is environment-specific. A plan that names a custom template runs on a machine where that directory exists and fails on one where it does not. The plan file travels; the template does not travel with it.
The job has no way to point elsewhere. There is no per-job template path. The only lever is the add-on's own reports.templateDir setting, which is ZAP configuration rather than plan data, so it is set outside the plan or not at all.
Installing a template is a copy, not a registration. Nothing indexes templates centrally; the directory's presence is the installation, and its name is the id.
The output extension follows the template, not your file name. Choosing a JSON template while asking for report.html yields report.html.json, because the extension is appended whenever the name does not already end in it.
An unknown id is silent in the artefact store and loud in the run's own error output. You get no file, so a later pipeline step that copies *.html finds nothing and may not fail on its own account.
The set of ids differs per install. Which templates a machine has depends on which add-on version is installed there and on whatever was copied in beside it, so the error listing valid ids is worth reading rather than guessing from memory.

Getting the two names straight in review

When you read someone's plan, the check is mechanical: does the template: value look like a directory name - lowercase, hyphenated, matching something under the templates folder - or does it look like prose? traditional-html, traditional-md, sarif-json and risk-confidence-html are ids. Traditional HTML Report is a title, and a title in a plan is a defect waiting for the next run.

The same distinction shows up in the desktop dialog, which lists titles while the plan it can generate writes ids. That is not really an inconsistency; it is two audiences. A person picks a report by the title that describes it, and an unattended run addresses it by the folder it lives in, which is the name the directory actually has on disk.

## Reporting is an add-on, and templates are folders Reporting is not part of ZAP's core program. It is the **`reports` add-on**, which registers the automation `report` job, the desktop report dialog and the shipped template set. (The same add-on registers the `outputSummary` job, which is why a plan generated for you by a packaged scan script needs `reports` present at all.) The add-on keeps its templates as **directories, one per template**, inside a single templates folder. That folder defaults to `reports/` under ZAP's home directory and is itself configurable, through the `reports.templateDir` configuration key. At load time the add-on lists the *immediate* subdirectories of that folder and, for each one holding a readable `template.yaml`, builds a template object. A subdirectory with no `template.yaml` is skipped silently - it is not an error, it simply is not a template. ## Two names, and only one of them is the id Every loaded template carries two names, and confusing them is the classic mistake: | name | where it comes from | what consumes it | |---|---|---| | the **config name**, i.e. the id | the **directory's own name** on disk | the plan's `template:` value, and the ID column of the shipped help page | | the **display name** | the `name:` key inside `template.yaml` | the desktop report dialog's picker | So `template: risk-confidence-html` resolves because a directory of exactly that name exists - not because any file inside it contains that string. That same template's `name:` key reads `Risk and Confidence HTML`, and putting *that* into a plan does not work. The lookup the job performs walks the loaded templates comparing directory names, and nothing else. The display name has one other property worth knowing: the add-on keys its loaded templates by it internally, so two template directories that declare the same `name:` collide even though their folders differ. ## What each outcome looks like 1. **`template` omitted, or present but empty.** The job substitutes `risk-confidence-html`, the add-on's default, and carries on. That default is a themed HTML document, so an unconfigured `report` job produces HTML. 2. **`template` set to a real id.** The template is found, and its declared file extension is then forced onto the output name: if your `reportFile` does not already end in it, the extension is appended. 3. **`template` set to something nothing matches.** No report is written. The job raises an **error** - not a warning - quoting the value you supplied and listing every template id it could see, which is the fastest way to discover what a given install actually has. ## Why this bites in a pipeline - **The id is a filesystem fact, so it is environment-specific.** A plan that names a custom template runs on a machine where that directory exists and fails on one where it does not. The plan file travels; the template does not travel with it. - **The job has no way to point elsewhere.** There is no per-job template path. The only lever is the add-on's own `reports.templateDir` setting, which is ZAP configuration rather than plan data, so it is set outside the plan or not at all. - **Installing a template is a copy, not a registration.** Nothing indexes templates centrally; the directory's presence *is* the installation, and its name *is* the id. - **The output extension follows the template, not your file name.** Choosing a JSON template while asking for `report.html` yields `report.html.json`, because the extension is appended whenever the name does not already end in it. - **An unknown id is silent in the artefact store and loud in the run's own error output.** You get no file, so a later pipeline step that copies `*.html` finds nothing and may not fail on its own account. - **The set of ids differs per install.** Which templates a machine has depends on which add-on version is installed there and on whatever was copied in beside it, so the error listing valid ids is worth reading rather than guessing from memory. ## Getting the two names straight in review When you read someone's plan, the check is mechanical: does the `template:` value look like a directory name - lowercase, hyphenated, matching something under the templates folder - or does it look like prose? `traditional-html`, `traditional-md`, `sarif-json` and `risk-confidence-html` are ids. `Traditional HTML Report` is a title, and a title in a plan is a defect waiting for the next run. The same distinction shows up in the desktop dialog, which lists titles while the plan it can generate writes ids. That is not really an inconsistency; it is two audiences. A person picks a report by the title that describes it, and an unattended run addresses it by the folder it lives in, which is the name the directory actually has on disk.

How do you add a report template of your own so that a plan can name it?
Copy an existing template directory to a new name beside it under ZAP's `reports` folder, then edit the copy's `template.yaml` and its `report.<ext>` file. The new directory's name becomes the id a plan uses. Nothing has to be registered, published or rebuilt - the folder's presence is the installation.
Can a report job point at a template directory somewhere else on disk?
No. The job accepts a template id only. Which folder is searched is decided by the add-on's `reports.templateDir` configuration key, which is ZAP configuration rather than plan data. So the plan stays portable while the template it names has to be placed on every machine that runs it.

It is the difference between a folder's name on disk and the title printed on the document inside it. Automation finds the folder; a person recognises the title.

saying these in an interview costs you the question

Thinks the template value names the output file to write
Puts the template's display title into the plan
Believes templates are compiled into the add-on and cannot be added
Assumes an unknown template id quietly falls back to the default
Thinks the plan file carries the template definition with it

In ZAP's automation report job, what does the template parameter actually refer to?

§ answer

basics

solid answer

code

§ go deeper

▾level notes4 levels

▾deep dive~4 min

Reporting is an add-on, and templates are folders

Two names, and only one of them is the id

What each outcome looks like

Why this bites in a pipeline

Getting the two names straight in review

▾common follow-ups2 questions

▾analogy~10 s

▾red flags5 flags

Reporting is an add-on, and templates are folders

Two names, and only one of them is the id

What each outcome looks like

Why this bites in a pipeline

Getting the two names straight in review

answer

go deeper