Writing Request Template TOML
A request template TOML file describes one or more request templates as text: which datasource each one reads, which tables or files, which columns and rows, which values the requester fills in, and an optional report built from the loaded data. Writing templates as a file lets you review them, keep them in version control and load a whole set at once.
The same file format is used in two places:
- Dashboard import. An organization admin uploads the file with Import TOML on the Request Templates page. See Import & Export Request Templates.
- Startup file. The Connector reads
request_templates.toml(path set by--request-templates-config/A10E_REQUEST_TEMPLATES_PATH) every time it starts. A missing file is ignored.
This section is the reference for writing the file:
| Page | What it covers |
|---|---|
| This page | File layout, template fields, TOML syntax, validation |
| Datasets, Joins & Filters | Choosing tables or files, columns, load-time joins, row filters |
| Request Parameters & References | Values the requester fills in (DATE [from_date]), and filtering one dataset by another (REF(...)) |
| Virtual Tables | A SQL report over the loaded data, and hiding or trimming the source tables behind it |
| Worked Examples | Three complete templates: a support investigation, a periodic report and dated log files |
A Minimal Template
Section titled “A Minimal Template”[[templates]]name = "support-account-lookup"title = "Support: account lookup"description = "Account details for one customer, for answering a billing ticket."business_justification = "Support investigates billing tickets without direct database access."risk_level = "low"validity_period = "1d"
[[templates.scope]] datasource = "production-postgres"
[[templates.scope.datasets]] source = { kind = "table", name = "accounts" } columns = ["id", "email", "status", "created_at"] filters.logic = "AND" filters.conditions = [{ raw = "id = TEXT [account_id]" }]A requester who picks this template is asked for an Account id. Once the request is approved and activated, the accounts rows for that id are loaded into the request’s isolated environment and can be queried in the Explorer.
File Layout
Section titled “File Layout”[defaults] optional: owner and organization for every template[[templates]] one entry per template [[templates.scope]] one entry per datasource the template reads virtual_table optional: a SQL report over this datasource's datasets [[templates.scope.datasets]] one entry per table or file source which table or file columns which columns joins optional: load-time joins that narrow the rows filters optional: row filtersA template can read several datasources. Give each its own [[templates.scope]] entry. Datasets in different scope entries of the same template can reference each other with REF(...).
[defaults]
Section titled “[defaults]”| Field | Notes |
|---|---|
owner |
Email of the user who owns templates that don’t set their own owner. |
organization |
Slug of the organization for templates that don’t set their own organization. |
What happens when owner and organization are missing depends on how the file is loaded:
- Dashboard import: a missing organization becomes the active organization, and a missing owner becomes the admin doing the import. A file that names a different organization is rejected. Leave both out if the file should import unchanged into any organization.
- Startup file: there is no signed-in user to fall back on, so every template must get both values, either from its own keys or from
[defaults].
[[templates]] Fields
Section titled “[[templates]] Fields”| Field | Required | Allowed values |
|---|---|---|
name |
yes | A stable identifier, such as support-account-lookup. Used to find the existing template when the file is loaded again. |
title |
yes | Short label shown on the template card. |
description |
yes | What the template returns and how to use it. Shown to requesters, and used by AI template matching. |
business_justification |
yes | Why this access exists. Shown to approvers, and pre-filled on the request. |
risk_level |
yes | low, medium or high. |
validity_period |
yes | 1h, 3h, 5h, 1d, 3d or 7d: how long an activated request stays available. |
owner |
see above | Overrides [defaults] owner. |
organization |
see above | Overrides [defaults] organization. |
scope |
yes | At least one [[templates.scope]] entry. |
[[templates.scope]] Fields
Section titled “[[templates.scope]] Fields”| Field | Required | Notes |
|---|---|---|
datasource |
yes | Exact, case-sensitive name of a datasource already configured in the organization (see Configure Data Sources). |
datasets |
yes | At least one [[templates.scope.datasets]] entry. See Datasets, Joins & Filters. |
virtual_table |
no | name, sql and datasets. See Virtual Tables. |
TOML Syntax Tips
Section titled “TOML Syntax Tips”Two equivalent spellings
Section titled “Two equivalent spellings”TOML lets you write a nested table either inline or as its own section. These two datasets are identical:
[[templates.scope.datasets]] source = { kind = "table", name = "accounts" } columns = ["id", "email"] filters.logic = "AND" filters.conditions = [ { raw = "status = 'active'" }, { raw = "created_at >= DATE [from_date]" }, ] [[templates.scope.datasets]] columns = ["id", "email"] [templates.scope.datasets.source] kind = "table" name = "accounts" [templates.scope.datasets.filters] logic = "AND" [[templates.scope.datasets.filters.conditions]] raw = "status = 'active'" [[templates.scope.datasets.filters.conditions]] raw = "created_at >= DATE [from_date]"The compact inline form is easier to read in long files, and the rest of this section uses it. Indentation is only for readability; TOML ignores it.
Keys belong to the last header above them
Section titled “Keys belong to the last header above them”A plain key such as datasource = ... or virtual_table.name = ... belongs to the closest [[...]] header above it. Write a scope entry’s own keys (datasource, virtual_table.*) before its first [[templates.scope.datasets]] header. Placed after it, they would belong to that dataset and the file would fail to load.
Multi-line strings
Section titled “Multi-line strings”Use triple quotes for SQL and long descriptions:
description = """\Approved refunds for the requested window. \Group them by week in the Explorer."""
virtual_table.sql = """SELECT a.id, a.plan, count(*) AS ordersFROM accounts AS aJOIN orders AS o ON o.account_id = a.idGROUP BY a.id, a.plan"""A backslash at the end of a line inside """ joins it to the next line without a line break. Without it, the newline is kept as part of the text.
Validation
Section titled “Validation”When the file is loaded, it is checked in two stages.
Whole-file checks. If any of these fail, nothing is written. The dashboard import returns the reason, and at startup the Connector refuses to start.
- The file is valid TOML.
- Every required field is present, and
risk_levelandvalidity_perioduse an allowed value. - Every scope entry names a datasource and lists at least one dataset, and every dataset has
source.kind,source.nameand a non-emptycolumnslist. - Every
virtual_tablehas a valid name and a singleSELECTthat reads only that scope entry’s datasets, and itsdatasetsvalue isall,report_rowsorhidden. - No two templates resolve to the same organization, owner and name.
Per-template checks. A template that fails one of these is skipped, and the other templates still load. The import result (or the startup log) names each skipped template and the reason.
- The owner exists. This is checked whenever the organization has no shared template with the same
name. - The datasource exists in the organization.
- The scope compiles: each source
kindsuits the datasource, every filter parses, and everyREF(...)points at a dataset and a listed column.
Nothing checks the datasource’s real schema when the file is loaded. A misspelled table, file or column passes both stages. When a request is then created from the template in the dashboard, a dataset whose table or file isn’t in the catalog gets a notice that names it (<dataset> was not found in <datasource>. Ask an administrator to update the template.) and no request can be created from the template until it is updated (editing the template stays possible, and saving it removes that dataset), and any column the catalog doesn’t list is left out without a message. A REF(...) or virtual table that needed it fails later. A path_list source that names a schema the datasource doesn’t accept is refused when the request is created through the API: schema "APP_LOGS" not found in datasource "log-host". Copy names from Catalog Scanning, and test a new template once end to end: create a request from it, check that every dataset and column appears on the request form, then approve, activate, and query it in the Explorer.
How Loading Matches Existing Templates
Section titled “How Loading Matches Existing Templates”Each template in the file is matched to an existing one:
- First, a template the organization already shares under the same
name, whoever owns it. - Otherwise, the owner’s own template with the same
name.
A template with no match is created and shared with the whole organization. A changed match is updated in place, keeping its id and owner. A matched private template also becomes shared. An identical match is left unchanged. Templates that are not in the file are never deleted or made private.