# Import and export templates as JSON

## Purpose
Move an assessment template between accounts or environments, keep a copy outside the
system, or replace a template's contents from a file.

## Who this is for
Account administrators and anyone who maintains the template library.

## Where this lives
Sidebar **Assessments**: the page is titled **Assessment templates**. Everything below
is on that one page.

## Read the list first

Each row tells you what you are allowed to do with it:

- **Scope**: **Global** (supplied by the platform, carrying a **Global** badge) or
  **Local** (yours).
- **Status** and **Version**: Draft / Active / Archived, and the version number. A
  locked template carries a padlock beside its status; an unlocked one carries
  nothing, so the absence of the padlock is the "unlocked" signal.
- **Bindings**: how many statements the template binds.
- **Fields**: how many extra custom fields it declares.

Global templates can be exported and cloned but not edited, locked, replaced or deleted.
Locked local templates cannot be edited, replaced or deleted until you unlock them.

## Export one template

Choose the **download** icon on the row. The file downloads as
`template-<id>.json`.

The export is a portable envelope: the template body plus the metadata needed to
recreate it elsewhere. It is the same shape the import accepts, so an export from one
account can be imported into another without editing, as long as the statements it binds
are also available in that account and no template there already has its name. An
imported template always starts as Draft, version 1.

## Import a template as a new one

1. Choose **Import JSON** in the page header.
2. Pick a `.json` file.

The template is created in your account as a new local template. If a template in this
account already carries the same name (compared with case and surrounding whitespace
ignored), the import is refused as a name conflict rather than silently overwriting.
Use **Replace from file…** below when overwriting is what you want.

Import failures are reported as an error toast carrying the server's reason, which is
usually a schema problem in the file.

## Replace one template's contents

Use this to update an existing template in place: the id, and anything pointing at it,
stay as they are.

1. Find the local template's row.
2. Choose the **file-upload** icon (**Replace from file…**).
3. Pick the JSON file.

The control is not offered at all on a global template, and is disabled on a locked
one: the tooltip then reads "Unlock before replacing". Unlock with the padlock button
first.

Replacing rewrites the template's name, description, questions and custom fields; its
status and version stay as they are. It is refused while an **Active** assessment is
using the template, and the message names those assessments: close them first, or import
the file as a new template. Assessments that have already been activated keep the
questionnaire they were activated with; Draft assessments pick up the new contents when
they are activated. Export the current version first if you might want it back.

## Other row actions

- **Edit / View** (pencil): opens the template builder. On a global template it is
  read-only.
- **Clone**: copies the template into your account under a new name you choose. This is
  how you get an editable version of a global template.
- **Lock / Unlock** (padlock): protects a local template from being edited, replaced or
  deleted.
- **Delete**: permanent. It is refused while the template is locked, and while any
  assessment or registration form in the account uses it.

## Find things in a large library

The filter bar carries a search box (press Enter or the **Search** button to apply),
**Scope** and **Lifecycle status**. **Reset filters** clears all three,
and also puts the sort back to most recently updated and the page size back to 12. Sorting is not in
the bar: it is on the column headers themselves (Template, Status, Version, Updated,
Created). Applied filters are echoed as a one-line summary beside the buttons, the total
count sits above the table on the right, and page size is 12, 24 or 48.

## From the assessment bank

Some templates are not authored here at all: they are composed in the **assessment bank**
(the BIMMaS content repository) and pushed in. A pushed template looks like any other in
the list, with one extra marker: a custom field named `bank_recipe` holding the recipe it
came from, next to `bank_version` and `bank_commit`. Those three fields are the record of
where the content came from; leave them alone.

Maintainers push with `npm run bank:push -- --envelope <file>` (add `--account <id>` to
push into one account instead of the global pool). The push is idempotent: it looks the
library up by `bank_recipe` first, creates the template if nothing carries that recipe,
and otherwise replaces that one template in place: same id, same lifecycle, same
assessments pointing at it. `--dry-run` reports which of the two it would do without
writing.

**A push will not overwrite a template people are answering.** Before a replace, the push
asks the server how many **Active** assessments are pointing at the matched template (in
every account, because a global template is distributed to many), and stops if the answer
is not zero, naming the counts and the accounts. It stops the same way if it cannot get an
answer at all. `--force` overrides it and says in the log exactly what it overrode. Only a platform
administrator can use it: the server refuses it from anyone else, including any push into
an account. A forced replace is recorded in the activity log of every account whose
assessments it changed. Use it only when you know the answers already collected can move. Closing the assessments (or
pushing the new content under a new recipe id) is the ordinary way through.

Two consequences for you:

- **Do not clone-and-edit a bank template if you want the edits to survive.** The next
  push replaces the original in place; your clone is a separate template and simply drifts
  from the bank. Content changes belong in the bank. A clone also carries the
  `bank_recipe` field: in an account that receives bank pushes, that makes two templates
  with one recipe, and the next push into that account stops until you remove the field
  from the clone or delete it.
- **Locking a bank template blocks the next push.** The push stops with the server's own
  refusal ("Template is locked. Unlock before replacing.") and writes nothing. That is a reasonable way to freeze a template mid-campaign, as long as someone
  knows to unlock it afterwards.

If two templates ever end up carrying the same `bank_recipe`, the push refuses to guess
between them and stops. Delete or re-tag the duplicate.

**SS-ADM is pushed the same way, but its content does not live in the bank.** The
Adaptive Maturity Specialised Set's questionnaire is written beside the code that runs it,
in `src/lib/adaptiveMaturity/content/`, and `npm run adm:envelope` builds its envelope
(`tmp/ss-adm.envelope.json`) for `bank:push`. Its template carries `bank_recipe` set to
`ss-adm` but no `bank_version` or `bank_commit`: the content's version and the commit it was
built from are in the questionnaire's own provenance. For SS-ADM, content changes belong in
that folder, not the bank; each released envelope is also filed in the bank as an archive
copy. Its dictionary definitions are read from a named BIM Dictionary release
(`npm run adm:glossary` refreshes them), and its statements are bound by their ONT IRIs, which
bind only once the ONT statement sync has brought them into Assessor.io: run the sync before the
push. Push it as a global template, then distribute it: in an account, a statement binds only if it
is in one of that account's locked statement sets, and SS-ADM's are in none. Everything else in this section applies unchanged.

## Limits and gotchas
- The export contains the template, not its submissions. Answers never travel with a
  template.
- Import and replace both accept a single JSON file at a time. Bulk pushes are an API
  concern, not a UI one.
- Changing the questions or custom fields of a template that live assessments are
  answering is refused: in the builder, by **Replace from file…**, and on the bank push. The message names what is answering it. Editing
  its NAME, description or lifecycle stays allowed while a wave runs.
- That refusal counts **Active** assessments only. A Draft has no respondents and a
  Completed one has no live cohort, so neither freezes a template.
- A bank push replaces the body and the custom fields, not the lifecycle: a template
  already **Active** stays Active, When an assessment goes Active it takes a
  snapshot of the template's questionnaire, and its participants keep answering that
  snapshot. A change that is allowed through therefore reaches Draft assessments, and any
  assessment activated later, but not one already pinned.

## Related pages
- [Publish and preview an assessment](/operate/tenant-admin/publish-and-preview-an-assessment)
- [Translate statements and templates](/operate/tenant-admin/translator-workflow)
- [Glossary](/build/reference/GLOSSARY)
