> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/administration-guide/reports/output-file-names.md).

# Name the output files

How a report names each file it produces — the File name pattern, its placeholders, the default, the "type an example" helper, the limits, and the folder the files land in.

## What this is, and when you need it

Every run of a report produces a file, and the report's **File name** pattern decides what the file is called: a template of literal text and placeholders, rendered with the run's date and time. Set it once, on the wizard's [Name step](/administration-guide/reports/create-a-report.md#wizard-name) or the designer's [Naming tab](/administration-guide/reports/design-a-report.md#designer-naming), and every run, export and scheduled delivery uses it. You need this page when the default name, the report name followed by a timestamp, is not what the people receiving the files want: a fixed date format, a shorter name, or a name that matches a file they already process.

You do not need it for the extension (`.csv` or `.xlsx`), which comes from the report's file format, or for the folder the file is stored in, which follows the report name and is not configurable.

## The File name field <a href="#naming-pattern" id="naming-pattern"></a>

The field holds the pattern. Under it:

| Element            | Description                                                                                                                                                                                                                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Hint               | *The name of each exported file. Dates and times are those of the server when the report runs.*                                                                                                                                                                     |
| Insert buttons     | One per placeholder, under *File name parts*: **Report name**, **Date**, **Time**, **Year**, **Month**, **Day**, **Hour**, **Minute**, **Second**. Each inserts its placeholder at the cursor.                                                                      |
| Example            | *Example: Contractor\_role\_access\_2026-10-09.xlsx* — the pattern rendered with the current date and time and the report's extension, refreshed as you type. With an empty field it reads *The default file name is used: the report name, the date and the time.* |
| Reset to default   | Restores the [default pattern](#naming-default).                                                                                                                                                                                                                    |
| Or type an example | Opens the [example helper](#naming-example).                                                                                                                                                                                                                        |

The field is validated as you type; a broken pattern shows its error under the field and disables the wizard's **Next** or the designer's **Save**.

## Placeholders <a href="#naming-placeholders" id="naming-placeholders"></a>

Placeholders are written between braces and are case-sensitive: `{MM}` is the month, `{mm}` the minute.

| Placeholder | Renders as                                                                            | Example on 12 October 2026 at 08:00:07 |
| ----------- | ------------------------------------------------------------------------------------- | -------------------------------------- |
| `{report}`  | The report name, made safe for a file system (see [Rules and limits](#naming-limits)) | `Contractor_role_access`               |
| `{date}`    | `{yyyy}-{MM}-{dd}`                                                                    | `2026-10-12`                           |
| `{time}`    | `{HH}-{mm}`                                                                           | `08-00`                                |
| `{yyyy}`    | Four-digit year                                                                       | `2026`                                 |
| `{yy}`      | Two-digit year                                                                        | `26`                                   |
| `{MM}`      | Two-digit month                                                                       | `10`                                   |
| `{dd}`      | Two-digit day of month                                                                | `12`                                   |
| `{HH}`      | Two-digit hour, 00 to 23                                                              | `08`                                   |
| `{mm}`      | Two-digit minute                                                                      | `00`                                   |
| `{ss}`      | Two-digit second                                                                      | `07`                                   |

Everything outside braces is literal text and is kept as typed, apart from the characters the file system cannot take. There is no insert button for `{yy}`; type it.

Dates and times are the **server's** at the moment the run starts, in the server's time zone, not the schedule's. A report scheduled for 08:00 Europe/Rome on a server running in UTC renders `{HH}` as `06`. For a date that never straddles midnight across zones, schedule the run away from the server's midnight or use `{date}` alone.

## The default <a href="#naming-default" id="naming-default"></a>

A report without a pattern of its own uses:

{% code overflow="wrap" %}

```
{report}_{yyyy}{MM}{dd}_{HH}{mm}{ss}
```

{% endcode %}

which gives `Contractor_role_access_20261012_080007.xlsx`. The field shows it as its placeholder text, and **Reset to default** clears whatever you typed so that the default applies again. An empty field and the default pattern are the same thing: the report stores no pattern.

Ad hoc runs, queries sent through the API without a saved report, use `report_{yyyy}{MM}{dd}_{HH}{mm}{ss}` and are stored apart from any report's files.

## Or type an example <a href="#naming-example" id="naming-example"></a>

If you know what the file should look like but not the placeholders, open **Or type an example** and work from the name instead of the pattern:

{% stepper %}
{% step %}
Type the file name as it would look if the report ran now, in **Example file name**, for example `Contractor_role_access_2026-10-12.xlsx`. Use today's date and the current time where the name needs them; those are the digits the helper recognises.
{% endstep %}

{% step %}
Choose **Use this example**. The helper shows *Pattern:* with what it inferred, `{report}_{date}` here, and a preview of that pattern rendered now.
{% endstep %}

{% step %}
Choose **Use this pattern** to put it in the File name field, then adjust it with the insert buttons if needed.
{% endstep %}
{% endstepper %}

The helper recognises the report name, a date written as year-month-day or day-month-year with any separator, and a time written as hour-minute-second or hour-minute, in that order of preference; the extension is ignored. Digits that could be read more than one way stop it: *Could not tell which date or time part 10 is. Use the pattern, then adjust it with the Insert buttons.* appears, with the parts it could place. An example typed on 10 October with the day and the month both `10` is the usual cause; try again on another day, or type the pattern.

## Rules and limits <a href="#naming-limits" id="naming-limits"></a>

| Rule                      | Value and what breaks it                                                                                                                                  |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Pattern length            | At most 200 characters. *The file name pattern is longer than 200 characters.*                                                                            |
| Known placeholders only   | Any other word in braces: *Unknown placeholder {week} in the file name pattern.*                                                                          |
| Matched braces            | A `{` without `}` or the reverse: *Unmatched { at position 12 of the file name pattern.*                                                                  |
| Not empty after rendering | A pattern of only literal characters the file system rejects: *The file name pattern is empty.* A name that normalises to nothing falls back to `report`. |
| Rendered name             | At most 150 characters and 200 bytes before the extension; longer names are cut, never split inside a character.                                          |
| Folder name               | At most 100 characters.                                                                                                                                   |

Rendering makes the name safe for the file system: runs of spaces and other blanks become one underscore, the characters `/ \ : * ? " < > |` and control characters are removed, repeated underscores collapse into one, and underscores, dots and hyphens are trimmed from both ends. That is why `{report}` gives `Contractor_role_access`, not `Contractor role access`. The extension, `.csv` or `.xlsx`, is added from the report's file format and cannot be put in the pattern.

The pattern is stored on the report and copied when the report is [cloned](/administration-guide/reports/manage-reports.md#clone-a-report). It is not part of a view: two reports on the same view can name their files differently.

## Where the files land <a href="#naming-folder" id="naming-folder"></a>

The report service writes every file under one root, the artifact store, in a folder per report:

{% code overflow="wrap" %}

```
<store>/<tenant>/<normalized report name>/<rendered name>.<csv|xlsx>
```

{% endcode %}

* `<store>` is the service's artifact path and `<tenant>` is `default`; both are operator settings, see [Operate the report service](/administration-guide/reports/operate-the-report-service.md#operate-artifact-store).
* The folder is the report name normalised as above and cut to 100 characters. The designer's Naming tab shows it read-only as *Folder: Contractor\_role\_access*. Renaming the report starts a new folder for later runs; earlier files stay where they were and remain downloadable.
* Two runs that render the same name, for instance a pattern without time placeholders run twice in a day, do not overwrite each other: the second file gets `_2`, the third `_3`, and so on.
* Ad hoc runs go under `_adhoc/`.

You never need the path to collect a file: the [Run history](/administration-guide/reports/run-and-download.md#history) and the [Download center](/administration-guide/reports/run-and-download.md#downloads) serve it. The path matters when an operator sizes the store or copies files out of it.

## The running example

Dana's weekly **Contractor role access** report uses `{report}_{date}`. Its files, as Run history lists them:

| Run                              | File                                       |
| -------------------------------- | ------------------------------------------ |
| Monday 12 October, scheduled     | `Contractor_role_access_2026-10-12.xlsx`   |
| Wednesday 14 October, Run        | `Contractor_role_access_2026-10-14.xlsx`   |
| Wednesday 14 October, Export CSV | `Contractor_role_access_2026-10-14.csv`    |
| Wednesday 14 October, Run again  | `Contractor_role_access_2026-10-14_2.xlsx` |

The export took the pattern and the `.csv` extension; the second run of the day took the `_2` suffix.

## Verification

* The **Example** line under the field shows the name you expect, with the right extension.
* After a run, the **Output file** column of [Run history](/administration-guide/reports/run-and-download.md#history-output-file) and the **File** column of the Download center show the rendered name.
* On the details page, the **General** card lists the pattern under **File name**, or the default's description when none is set.

## Related

* [Create a report](/administration-guide/reports/create-a-report.md#wizard-name) — the pattern on the Name step
* [Design a report](/administration-guide/reports/design-a-report.md#designer-naming) — the Naming tab, file type and folder
* [Run a report and download the file](/administration-guide/reports/run-and-download.md) — where the files appear
* [Operate the report service](/administration-guide/reports/operate-the-report-service.md#operate-artifact-store) — the store, its path and its size cap


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openiam.com/administration-guide/reports/output-file-names.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.