Report Generator: automation with YAML script

A YAML script tells Report Generator which slides to create and for which control options. For example: one set of slides per region, all in one PowerPoint file.

Do you need a script?

No script: every slide of the template is exported once, with the filters currently selected on the dashboard.
With a script: you choose which slides are exported, in which order, and for which control options.

Step 1. Create the file

Use any text editor. An editor with YAML highlighting (for example, Notepad++) makes mistakes easier to see. Create a new file and set the language to YAML.

Indent with spaces, never with tab characters. A script indented with tabs fails with the message cannot parse YAML script.

In Notepad++, go to Settings → Preferences → Language → Tab Settings and tick Replace by space. The Tab key then types spaces.

Save the file with the extension .yml (not .yaml), for example report.yml.

Step 2. Write the script

Here is a complete example. Copy it and change the slide numbers, control IDs and options.

YAML

# Slides 1 and 2: once, as they are
- slides: [1, 2]

# Slides 3 and 4: once for each region
- forcontrol:
    alias: Region
    items: ["North", "South"]
    subiterations:
      - slides: [3, 4]

# Slide 5: always for Brand A
- set:
    Brand: "Brand A"
- slides: 5

The exported report has these slides: 1, 2, 3 (North), 4 (North), 3 (South), 4 (South), 5 (Brand A).

Slide numbers are the slide numbers in the template (the first slide is 1). The exported report usually has more slides, in a different order.

Commands

Command	What it does
`slides`	Adds template slides, in the order listed. Write one number (`- slides: 5`) or a list (`- slides: [1, 2]`). Slides not listed anywhere are not exported.
`forcontrol`	Repeats the commands under `subiterations` once for each option of a control. It has three parts: `alias` (required): the control ID. `items` (optional): the options to use. Leave it out to use all options. `subiterations` (required): the commands to repeat, usually `slides`. Without it, the loop is skipped.
`set`	Selects one or more options in a control for all slides that follow. Write `ControlID: "Option"` or `ControlID: ["Option 1", "Option 2"]`.

Command

What it does

slides

Adds template slides, in the order listed. Write one number (- slides: 5) or a list (- slides: [1, 2]). Slides not listed anywhere are not exported.

forcontrol

Repeats the commands under subiterations once for each option of a control. It has three parts:

alias (required): the control ID.
items (optional): the options to use. Leave it out to use all options.
subiterations (required): the commands to repeat, usually slides. Without it, the loop is skipped.

set

Selects one or more options in a control for all slides that follow. Write ControlID: "Option" or ControlID: ["Option 1", "Option 2"].

Where to find the control ID

The control ID is shown under the control, and at the top of the left panel when the control is selected.

Writing rules

Every command starts with a dash and a space: - slides, not -slides.
Put a space after every colon: alias: Region.
Indent the parts of a command with spaces, as in the example. Parts of the same command line up exactly.
Put option labels in straight double quotes "North". Curly quotes “North” (often added by Word or Outlook) do not work.
In items, the spelling must match the control. Capital letters don't matter.
In set, write options exactly as in the control, including capital letters. A control ID or option that doesn't match is ignored without a message: the slides then use the dashboard's current selection. Check the result.
Lines starting with # are comments and are ignored.

Combine several controls

To create slides for each combination of options, for example each gender in each age group, put one forcontrol inside the subiterations of another:

YAML

- forcontrol:
    alias: Gender
    subiterations:
      - forcontrol:
          alias: Age
          items: ["30-40", "41-50"]
          subiterations:
            - slides: [3]

This creates slide 3 once for each combination, in this order: first gender with "30-40", first gender with "41-50", second gender with "30-40", second gender with "41-50", and so on.

Keep reports small. The number of slides multiplies: 2 genders × 5 age groups × 3 slides = 30 slides. We recommend no more than 3 nested controls and about 100 slides per report. Use items to limit the options. Very large reports take long to create and can fail.

When a loop ends, its control keeps the last option of the loop. If later slides need a different option, add a set before them.

The script doesn't work with Proxy controls.

Step 3. Upload the script

Upload the .yml file in the same window as the PowerPoint template (dashboard in EDIT mode → left menu → Reports → open the report).

A script can be up to 32,768 characters long.
To change the script, upload a new .yml file in the same window.
To get the current template and script back, click Download files in the same window. You get a ZIP file with template.pptx and script.yml.

If the export fails

Message	What to do
cannot parse YAML script: …	Syntax error. Replace tab characters with spaces, and check dashes, colons and quotes against the writing rules above.
… control "…" not found	A control ID in `alias` is wrong, or the control is on another tab. Copy the ID from the dashboard again.
Report generator: Mentioned in script option "…" was not found in dashboard control "…"	An option in `items` does not exist. The report is created without it. Fix the spelling.
… is not allowed at the top level	Unknown command or typo. Use only `slides`, `forcontrol` and `set`.

More problems and fixes: Report Generator: troubleshooting.