Import and export templates as JSON
Move an assessment template between accounts or environments, keep a copy outside the system, or replace a template's contents from a file.
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
- Choose Import JSON in the page header.
- Pick a
.jsonfile.
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.
- Find the local template's row.
- Choose the file-upload icon (Replace from file…).
- 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_recipefield: 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.