Template placeholders

A placeholder is a blank in a template that is filled in each time the template is used. Write the template once, for example “Find idle EC2 instances in {{region}}”, and whoever turns it into a task is asked for the region first. The value replaces the token everywhere it appears, so the task that gets created reads exactly as if it had been written by hand.

Writing a placeholder

A placeholder is a key wrapped in double braces:

Rotate the access keys of {{service_name}} in {{region}}.
Keep the old key for {{grace_days}} days before deleting it.

• The key can use letters, digits and underscores, up to 64 characters: region, idle_days, account_id_2.
• Spaces just inside the braces are ignored, so {{ region }} and {{region}} are the same placeholder.
• Keys are case sensitive: {{Region}} and {{region}} are two different placeholders.
• Tokens can go in the template’s name, description, agent instructions and verification criteria. A key used in several places is asked for once and filled in everywhere.
• Anything that does not follow these rules, such as {{bucket-name}}, is not a placeholder. It is left in the text exactly as written.

Adding placeholders to a template

1. On your workspace’s Templates page, create a template with +, or choose Edit on an existing one.
2. Type a token such as {{region}} into any of the text fields. It is highlighted as you type, so you can see at a glance which parts of the text will be filled in.
3. Open the Placeholders step. Every token in the text has its own entry, already labelled from its key (idle_days becomes “Idle days”). Adjust its settings, then save the template.

Deleting a token from the text removes its placeholder. If you type it again before saving, its settings come back.

Placeholder settings

Setting	What it does
Label	The question shown next to the input, for example “Region to scan”. Required, up to 200 characters.
Type	The kind of value asked for, which decides the input shown. See Available types.
Default value	The value the input starts with. It must fit the type, for example a number for a Number placeholder.
Required	When on, the task cannot be created until a value is given. When off, a blank value simply removes the token from the text.
Help text	An optional hint shown under the input, up to 1000 characters.

A template can declare up to 25 placeholders.

Available types

Type	Input shown	Inserted into the text as	Example
Text	A text box	The text exactly as typed	payments-api
Number	A number input	The number	30
Yes / No	A toggle	true or false	true
AWS region	A searchable list of AWS regions	The region code	us-east-1
AWS account ID	A text box that only accepts 12 digits	The account ID	123456789012

Choose the most specific type that fits. An AWS region placeholder cannot be filled in with a typo, and an AWS account ID placeholder rejects anything that is not a valid account ID, so the agent never receives a task built on a bad value.

Using a template with placeholders

When you choose Create task or Schedule job on a template that has placeholders, you are asked for their values first. Each input starts at its default value. Once you continue, every token is replaced and the usual wizard opens with the finished text, so you can still review or change anything before the task or job is created.

The template itself never changes. The next person to use it is asked for the values again.

Tip

Placeholders work well for anything that changes between runs while the task stays the same: the region or account to look at, a threshold, a time window, or a resource name.

Placeholders in gallery template files

Templates in the template gallery declare the same placeholders in their YAML file, under placeholders.variables. The types use these names:

Type in the app	type in a template file
Text	string
Number	number
Yes / No	boolean
AWS region	aws-region
AWS account ID	aws-account-id

Each entry takes a key, a label and a type, plus an optional description (the help text), default and required (on unless set to false):

task:
  name: Clean up orphaned EC2 instances
  description: Identify EC2 instances in {{region}} that are no longer in use.
  instructions: List instances idle for {{idle_days}} days and propose which to terminate.
placeholders:
  variables:
    - key: region
      label: Region
      type: aws-region
      default: us-east-1
    - key: idle_days
      label: Idle threshold (days)
      type: number
      default: 14
      description: Instances with no activity for this many days are reported.

Gallery variables are filled in when you import the template, alongside the environment it should run against, so the template saved in your workspace already contains your values.