Skip to content

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
[[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.

[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 filters

A 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(...).

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].
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.
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 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.

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.

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 orders
FROM accounts AS a
JOIN orders AS o ON o.account_id = a.id
GROUP 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.

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_level and validity_period use an allowed value.
  • Every scope entry names a datasource and lists at least one dataset, and every dataset has source.kind, source.name and a non-empty columns list.
  • Every virtual_table has a valid name and a single SELECT that reads only that scope entry’s datasets, and its datasets value is all, report_rows or hidden.
  • 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 kind suits the datasource, every filter parses, and every REF(...) 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.

Each template in the file is matched to an existing one:

  1. First, a template the organization already shares under the same name, whoever owns it.
  2. 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.