Project templates: a working setup you install in one step
Templates bundle components, workflows, integrations and apps into a project you install in one step, with declared permissions, a locked identity per installation and secrets that carry declarations only.
Most projects start the same way. You need a handful of components, a few workflows, maybe an integration or an app, all wired together for a common use case. Building that from scratch each time is slow and easy to get wrong.
A template is a predefined project configuration that bundles components, workflows, integrations and apps together. You install it into a workspace and get a project that already works, then customise it from there. This post covers what happens when you search for a template, install it, upgrade it and remove it, and what the template does and does not carry with it.
You find templates in the dashboard under Developer › Templates, and from the command line with ptkl template.
What a template packages
A template gives you a starting point for a business use case. It can contain:
- components;
- workflows;
- integrations;
- apps.
A template can also declare permissions, and it can hold secret declarations. Both get their own section below, because they decide what the template's code is allowed to do and what you still have to supply.
Finding and installing a template
The CLI has three commands for discovery and installation. Every subcommand accepts the standard output flags (-f/--format, -o/--output) and --env <dev|live>.
| Command | What it does |
|---|---|
ptkl template search |
Search the template catalog |
ptkl template available |
List templates available to the current project |
ptkl template install |
Install a template into a workspace |
Search takes a JSON query:
ptkl template search --query '{"category":"ecommerce"}'
List what your project can use, as a table:
ptkl template available --format table
Install by template UUID and workspace UUID. Use --data to pass extra install options as a JSON object:
ptkl template install \
--template-id <template-uuid> \
--workspace-uuid <workspace-uuid>
Installing runs the template's code in your project, so the dashboard shows what the install needs and what it touches before you confirm.
Declared permissions
Some template code needs access outside its own components, for example to read an existing component or run a function. A template lists this as permissions, written as <action> <resource> strings:
{
"permissions": ["read orders", "run function::notify_customer"]
}
Publishing checks that every entry has the <action> <resource> form.
The person installing must hold every declared permission. The install dialog lists each one and marks it "You hold it" or "You lack it". If you lack any, the API refuses with 403 permissions_not_held, names what is missing, and installs nothing:
{
"error": "permissions_not_held",
"message": "the installer does not hold the template's declared permissions",
"missing": ["read orders"]
}
The fix is to ask the Owner or a Maintainer to grant you those permissions, or to install the template for you. The server checks again when you install.
If a declared permission names a resource your project doesn't have, the install fails before anything is written, with 422 resources_missing listing what is absent. Create or install those components first, then install again.
Everything the template creates needs only manage base_templates, because those resources didn't exist before.
Writing into components that already exist
A template can write into a component you already have. That component keeps the run identity it has today. The installation's role gets no access to it unless the template declares it and you hold it.
The dialog lists these components, each marked "keeps {identity}". The install response lists the same components in adopted, each with its component and run_as, and ptkl template install prints that response.
Each installation gets its own identity
A template can't name your project's roles. Instead, each installation gets its own role and its own API user, and everything the template creates runs as that API user. This is the same run identity mechanism described in our post on run identities.
The role holds:
- access to each component the installation created;
run function::<name>for its functions;- trigger permissions for its workflows;
- the template's declared
permissions.
These identities are locked. They can't be edited, deleted, assigned or chosen as a run identity, and trying to choose one gives 403 identity_locked. The dashboard shows them as belonging to a template installation.
When you uninstall the template, the role and API user go with it. Code still running as them is then refused with 409 identity_gone. Open that code's editor and give it another identity.
Secrets carry declarations, not values
Installing a template, or copying a component into another project, carries secret declarations only (see our post on secrets):
- generated secrets are created fresh in the new project;
- supplied secrets start as missing, and you provide them.
A template's secrets may hold only secretgen::<generator>, secret:: and secretref:: entries. A template that carries an actual value (secret::<value>) is refused when it is published.
Upgrading and uninstalling
Upgrade and uninstall take the same arguments as install:
ptkl template upgrade \
--template-id <template-uuid> \
--workspace-uuid <workspace-uuid>
ptkl template uninstall \
--template-id <template-uuid> \
--workspace-uuid <workspace-uuid>
Both accept --data for extra options as a JSON object. Uninstalling removes the installation's locked role and API user, as described above.
Install refusals
Two other situations stop an install without changing anything:
| Situation | Response |
|---|---|
| Another install or uninstall of this template is running | 409: wait a few seconds and try again |
| A service the check needs is unavailable | 503 with Retry-After: nothing was installed, try again |
Activation codes
ptkl template activation-code redeem <code> redeems an account-level activation code for the current user and project. It is a different command family from install: install installs a template you already have access to.
A worked example
Say you want an e-commerce starting point.
- Run
ptkl template search --query '{"category":"ecommerce"}'and pick a template. - Open the install dialog or read the template's declared permissions. Suppose they include
read orders. If you lack it, ask the Owner or a Maintainer, or have them install it. - Run
ptkl template install --template-id <template-uuid> --workspace-uuid <workspace-uuid>. - Read the install response. The
adoptedlist shows any existing components the template wrote into and the identity each keeps. - Supply any secrets that came in as missing. Generated ones already exist.
- Customise the components, functions and workflows. The functions run as the installation's own API user, with only the access listed above.
Learn more
- Templates and the
ptkl templatecommands: https://docs.protokol.io/toolkit/templates/ - Secrets, including templates and copies: https://docs.protokol.io/components/secrets/
- Run identity, including locked template identities: https://docs.protokol.io/platform/run-identity/