Skip to content

Import & Export Request Templates

If you’re only creating one or two request templates, the New Template button on the Request Templates page is the fastest way to do it by hand. This guide covers the other case: you already have (or want to build) a whole set of templates as a single file, and you want to load all of them into Alien Giraffe at once — or pull the current set out so it can be reviewed, versioned, or copied to another organization.

This is done entirely through the dashboard. No API calls are needed.

The import and export controls are only shown to organization admins (the admin or super_admin role for the active organization). If you don’t see them, you’re signed in as a regular user — ask an admin in your organization, or see Users And Roles.

  1. Open Data Requests from the main navigation.
  2. Click From Template. This opens the Request Templates page (you’ll see the breadcrumb Data Requests > Request Templates at the top).

Admins see three buttons above the template list: New Template, Import TOML, and Export TOML. Everyone else only sees New Template.

The file is a single TOML document. At the top level it has an optional [defaults] table and a list of [[templates]] entries:

[defaults]
organization = "acme-corp"
owner = "data-team@acme.example"
[[templates]]
name = "support-account-lookup"
title = "Support: account lookup by customer ID"
description = "Account details and recent orders for a single customer, scoped to what support needs to answer a billing question."
business_justification = "Support investigates billing tickets without direct database access."
risk_level = "low"
validity_period = "1d"
owner = "support-lead@acme.example"
[[templates.scope]]
datasource = "production-postgres"
[[templates.scope.datasets]]
columns = ["id", "email", "status", "created_at"]
[templates.scope.datasets.source]
kind = "table"
name = "accounts"
[templates.scope.datasets.filters]
logic = "AND"
[[templates.scope.datasets.filters.conditions]]
raw = "id = TEXT [account_id]"
[[templates.scope.datasets]]
columns = ["account_id", "order_id", "amount", "created_at"]
[templates.scope.datasets.source]
kind = "table"
name = "orders"
[[templates.scope.datasets.joins]]
type = "inner"
on = "orders.account_id = accounts.id"
[templates.scope.datasets.joins.source]
kind = "table"
name = "accounts"
[templates.scope.datasets.filters]
logic = "AND"
[[templates.scope.datasets.filters.conditions]]
raw = "created_at >= DATE [from_date] AND created_at <= DATE [to_date]"

A template can also compose its datasets through a hand-written virtual table instead of (or alongside) plain per-table scoping — useful when the useful shape of the data is a join or aggregation, not a raw table:

[[templates]]
name = "monthly-signups-by-plan"
title = "Monthly signups by plan"
description = "Signup counts by plan and month for the requested date window."
business_justification = "Recurring growth reporting."
risk_level = "low"
validity_period = "7d"
[[templates.scope]]
datasource = "production-postgres"
[templates.scope.virtual_table]
name = "SIGNUPS_BY_PLAN_MONTH"
sql = """
select date_trunc('month', created_at) AS signup_month, plan, count(*) AS signups
from accounts
group by 1, 2
"""
[[templates.scope.datasets]]
columns = ["id", "plan", "created_at"]
[templates.scope.datasets.source]
kind = "table"
name = "accounts"
[templates.scope.datasets.filters]
logic = "AND"
[[templates.scope.datasets.filters.conditions]]
raw = "created_at >= DATE [from_date] AND created_at <= DATE [to_date]"

The date window sits on the dataset’s filter, not in the SQL: request parameters are only filled in inside dataset filters, and the report reads whatever rows loaded.

For the full file format (every field, the filter grammar, request parameters, REF(...), virtual tables, and hiding the source tables behind a report), see Request Template TOML.

A template can load the files of an SSH datasource’s accepted schemas, such as dated log files (see Dated Files). Name the schema, not a file pattern, with kind = "path_list" and, optionally, the days to load with dates. The name is the schema’s Table name on the datasource (a template that uses an earlier name keeps working after the table is renamed) (see Schemas In The Catalog):

[[templates]]
name = "app-logs-by-day"
title = "Application logs for the requested days"
description = "Application and access logs for the days the requester enters."
business_justification = "Incident investigation."
risk_level = "medium"
validity_period = "1d"
[[templates.scope]]
datasource = "log-host"
[[templates.scope.datasets]]
source = { kind = "path_list", name = "APP_LOGS" }
columns = ["timestamp", "level", "message", "source_path", "file_date"]
dates = { from = "DATE [date_from]", to = "DATE [date_to]" }
[[templates.scope.datasets]]
source = { kind = "path_list", name = "ACCESS_LOGS" }
columns = ["remote_addr", "timestamp", "path", "status", "source_path", "file_date"]
dates = { from = "2026-11-01", to = "2026-11-07" }

DATE [date_from] and DATE [date_to] ask the requester for the dates, shown as one Dates row under Request parameters (see Request Parameters For Dated Files). A plain YYYY-MM-DD fixes the date in the template. Leave dates out to load every file of the schema. The datasource’s Target and its date tokens aren’t part of the template: only the schemas the datasource accepts are loaded, so if the datasource doesn’t accept a schema of that name, the dashboard shows a notice and a request can’t be created from the template until the template is updated (editing the template stays possible, and saving it removes that dataset), and creating the request through the API fails with schema "APP_LOGS" not found in datasource "log-host". A path source on an SSH datasource fails with datasource "log-host" loads files through its schemas: use kind "path_list" with a schema name.

Field Where Required Notes
organization [defaults] or per template one of the two Which organization the template belongs to. A value on the template overrides the default.
owner [defaults] or per template one of the two The email of the person the template is attributed to.
name [[templates]] yes Stable identifier used to match templates on re-import (see How Import Behaves).
title [[templates]] yes Short, human-readable label shown in the dashboard.
description [[templates]] yes Longer explanation of what the template returns and why. Supports multi-line TOML strings ("""...""").
business_justification [[templates]] yes Why this access exists — shown to approvers.
risk_level [[templates]] yes e.g. low, medium, high — informs the approval review.
validity_period [[templates]] yes How long a request created from this template stays valid, e.g. "1d", "7d".
scope [[templates]] yes One or more [[templates.scope]] blocks, each naming a datasource and what to pull from it.
datasource [[templates.scope]] yes The name of an already-registered datasource (see Configure Data Sources).
virtual_table.name / virtual_table.sql [templates.scope.virtual_table] no An optional hand-written SQL view over the datasets below it, given a name so it can be queried directly once the request is active.
datasets[].columns [[templates.scope.datasets]] yes The exact columns to expose from this table or path.
datasets[].source.kind / .name [templates.scope.datasets.source] yes kind = "table" for a database table, kind = "path" for one object-storage path, kind = "path_list" for an SSH schema loaded as one table from its files. name is the table name, the path, or the schema’s Table name on the datasource.
datasets[].dates [[templates.scope.datasets]] no path_list only. { from = "...", to = "..." }, both included; each bound is a YYYY-MM-DD date or a DATE [name] parameter. Omitted: every file of the schema.
datasets[].joins[] [[templates.scope.datasets.joins]] no Each join has a type (e.g. "inner"), an on expression, and its own source.{kind,name}.
datasets[].filters [templates.scope.datasets.filters] no A logic ("AND"/"OR") plus one or more conditions. A condition is either structured (column, op, value) or a raw SQL expression.

Filter conditions can reference a value the requester supplies at request time, using the [param_name] placeholder syntax (DATE [from_date], TEXT [account_id], TIMESTAMP [incident_at] - 30m), and can reference another dataset in the same scope with REF(Table.column) to join without repeating a value. See Create Request From Template for how those parameters are filled in when someone actually uses the template.

Matching Data Sources And Fields Correctly

Section titled “Matching Data Sources And Fields Correctly”

Every datasource value in the file has to be the exact name of a data source that’s already registered in Configure Data Sources — matching is an exact, case-sensitive text match, not a fuzzy or case-insensitive lookup. Get this wrong and that template will fail, but it’s important to understand when it fails and what else can go wrong later without being caught at all.

Two separate things happen when a file is imported, and only one of them touches the datasources you’ve configured:

  1. The file is checked for structure first — every template needs its required fields (name, title, description, business_justification, risk_level, validity_period, at least one scope with at least one dataset), and any virtual_table.sql is checked so that every table it selects from is actually declared as one of that scope’s datasets. A template that fails this check is malformed, not just mismatched.
  2. Then each template’s datasource is looked up against your organization’s configured data sources. If the name doesn’t match anything registered, that specific template is skipped — the rest of the file still imports normally, and the result panel’s skipped-templates list names it and says the datasource wasn’t found.

What’s not checked — and only fails later, at activation

Section titled “What’s not checked — and only fails later, at activation”

Neither the import step nor creating a request from the template looks at the datasource’s real schema, with two exceptions: importing a template that names an SSH datasource with kind = "path" is refused (SSH datasources load files through their schemas: use path_list), and when a request is created, a path_list source’s schema name must be one the datasource accepts (in the dashboard, Create Request shows a notice for a schema that isn’t and a request can’t be created from the template until the template is updated). That means none of the following are validated until someone actually activates a request built from the template:

  • Whether datasets[].source.name (a table name, or a path for object storage) actually exists in that data source. For an SSH datasource it must be the Table name its administrator gave the schema in the wizard, not the name the wizard suggested (see Table names and request templates).
  • Whether every column listed in datasets[].columns actually exists on that table or path.
  • Whether a joins[].on condition or a filter’s raw SQL expression refers to a real, correctly-spelled column.
  • Whether a virtual_table.sql query’s columns exist on the tables it selects from (its tables are checked at import — see above — but not its columns).

The one partial exception is REF(Table.column): that’s checked against the other dataset’s declared columns list in the same file, so a typo’d REF() target is caught at import — but that check only confirms the column is listed in the template, not that it’s real in the actual database.

In practice, this means a template can import cleanly, and a request can be created and approved from it, and still fail to produce useful data — because the table/column names simply don’t match what’s really in the data source. When that happens, activation itself still succeeds (the environment comes up), but the specific dataset that references a bad table or column fails to load in the background while everything else in the request loads normally. You’ll see this on the request’s status once it finishes provisioning, or as missing/empty data for that dataset in the Explorer — not as an error on the request itself.

  • Use the catalog scanner as your source of truth for names. Scan Your Catalog discovers the real table and column names for a data source exactly as the database reports them — copy names from there rather than typing them from memory.
  • Watch case conventions per data source type. Oracle identifiers are conventionally written upper-case (matching what the scanner discovers there); Postgres tables and columns created without quotes are lower-case, and a quoted mixed-case column in a template won’t match an unquoted lower-case column in the real table. When in doubt, match the catalog scanner’s casing for that source exactly.
  • Export before you edit. Starting from Export TOML on a working set of templates and modifying that, rather than writing a new file from scratch, means the datasource names and identifier casing are already correct.
  • Treat “it imported successfully” as passing the first check only, not the last one. The only way to confirm a template’s tables and columns genuinely line up with the real data is to create a request from it, approve and activate it, and check that its data loads without error.
  1. On the Request Templates page, click Import TOML.
  2. Choose a .toml file from your computer in the picker that opens. There’s no drag-and-drop area — it’s a standard file picker.
  3. The import runs immediately. There is no preview or confirmation step, so double-check the file before choosing it.

An alert on the page spells out exactly what happens:

Importing writes to the database immediately. Templates are matched on organization, owner and name: new ones are created, changed ones updated in place, and nothing is ever deleted. Imported templates become shared with the whole organization.

  • Each template in the file is matched against existing templates by organization + owner + name. A match updates that template in place; no match creates a new one.
  • Nothing is ever deleted by an import — templates that exist in the dashboard but aren’t in the file are left untouched.
  • Every imported template becomes a shared, organization-wide template (not a private one), regardless of who imports it.
  • If your deployment also loads a request_templates.toml file at server startup, that startup file will overwrite any templates it also defines the next time the service restarts. If you rely on both, keep them in sync — export from the dashboard, update the deployed file, and redeploy.

A result panel appears summarizing what happened, for example:

  • Complete — every template in the file was imported cleanly, with a count of how many were created, updated, unchanged, or skipped.
  • Partial — some templates imported and some were skipped; a list shows each skipped template’s name, owner, and the reason it was skipped.
  • Nothing imported — none of the templates could be applied.
  • Empty file — the file didn’t contain any templates.

If the file isn’t recognized as TOML (by its filename), or the whole import fails outright (malformed TOML, a required field missing, or the file exceeds the platform’s size limit), you’ll see a notification explaining that nothing was written — a failed import never partially applies.

Click Export TOML to download the current organization’s templates as a .toml file, ready to hand to another admin, check into version control, or re-import elsewhere.

A few things worth knowing about what’s in the export:

  • Only shared, organization-wide templates are included — anyone’s private/personal templates are left out.
  • Templates are sorted by owner, then name, so re-exporting the same set produces a stable, diff-friendly file.
  • Only configuration fields are exported — no internal IDs, timestamps, or credentials.