Skip to main content

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 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.

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 contents. Assessments already deployed from it keep pointing at the same template, so a replace changes what future participants see. 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 replaced or deleted.
  • Delete — permanent, and refused while the template is locked.

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. 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 BIMmaas 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; 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.
  • 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.

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.
  • Editing the questions of a template that live assessments are answering is refused — in the builder, 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, so a change that IS allowed through reaches every assessment pointing at the template immediately. There are no version snapshots — one template is one row, and the version recorded on an assessment is a label, not a frozen copy.