# Build an assessment template

## Purpose

Author the questionnaire itself: the questions, their routing, and the metadata
that makes them scoreable.

## Who this is for

Anyone who writes the content of an assessment. You need the
`survey_templates.create` and `survey_templates.modify` permissions; the Account
Administration policy carries them, and the Campaign Management policy carries only
`survey_templates.view`, because authoring one is account configuration rather
than campaign operations.

## Where a template sits in the work

A **template** is the questionnaire. An **assessment** is a template attached to
a campaign with a deployment key, a status and a window. The two are separate on
purpose: one template can serve several campaigns, and a campaign can carry
several assessments.

This page covers the template. Attaching one to a campaign, previewing it and
publishing it is
[Publish and preview an assessment](/operate/tenant-admin/publish-and-preview-an-assessment);
moving one between accounts as a file is
[Import and export templates as JSON](/operate/tenant-admin/template-json-import-export).

## Open the library

**Assessments** in the sidebar, at `/<accountId>/dashboard/assessments`. The page
is headed **Assessment templates**.

The table lists the account's own templates plus any **global** templates that
have been distributed to the account. Filter by **Scope** (All scopes / Local /
Global) and **Lifecycle status** (All statuses / Draft / Active / Archived), or
search by name. Each row shows the scope, status, version, how many statement
bindings and custom fields it carries, and when it was created and last touched.

Row actions, left to right: edit (a pencil), **Clone template**, **Export JSON**,
**Replace from file…**, **Lock template**, **Delete template**. The last three are
hidden on a global row, because a tenant cannot change one.

To start something new, choose **New template** in the page header or, from an
empty library, **Build your first template**.

## The builder

Both **New template** and the pencil open the Assessment Template Builder at
`/<accountId>/dashboard/assessments/build` (or `…/build/<id>`).

The Studio puts the template name, **Check**, downloads and **Save Template**
above six workspaces:

| Workspace | Use it for |
| --- | --- |
| **Questions** | Add and arrange questions in the SurveyJS designer; edit their properties. Open **Item library** to reuse an existing item, **Action Statements** to link sources, or **AI Assistant** for reviewable suggestions. |
| **Preview** | Try the questionnaire and its branching without saving responses. |
| **Logic** | Set conditions and routing between questions and pages. |
| **Traceability** | See live coverage: how many questions score, why others were dropped, the Domain x Tier heatmap, and which Action Statements each question measures. |
| **JSON** | Edit a staged copy of the questionnaire source, then apply it to the designer. |
| **Details** | Set the description, lifecycle, version, team fields and template-level statement bindings. |

The header shows lifecycle, version, question count and whether changes are
unsaved. **Autosave is off**: applying JSON, accepting an AI suggestion or editing
a field changes your working copy only. Choose **Save Template** to store it.

The Studio and SurveyJS controls follow the app's light/dark theme and English or
French interface language. This does not translate question content. Use the
[translation workspace](/operate/tenant-admin/translator-workflow) for that.

### Details and team fields

Change the template name in the header. In **Details**:

- **Description** explains what the questionnaire is for.
- **Lifecycle status** is Draft, Active or Archived. Active means ready for use;
  it does not publish an assessment.
- **Version** is a positive whole number maintained by the author. It cannot be
  decreased on an existing template, and saving does not automatically increase
  it or replace an active assessment's pinned version.
- **Team fields** are administrative metadata, not respondent questions. Add a
  label, key, type and required flag; choice fields also take one option per
  line. Supported types are Text, Number, Date, Single choice, Multiple choice
  and Yes / No.
- **Bound Action Statements** lists governed template-level bindings. Saving
  derives them: every statement a question names as its primary
  (`asrStatement`) is bound, as is one a matrix row or a choice names (each
  action in SS-ADM's plan is a choice naming its statement), plus any bound
  directly. A primary is marked
  **Question primary** and cannot be unbound while a question still names it.
  Clearing a primary does not unbind it, so remove it here if needed.

### Check before saving

**Check** reports errors and warnings with their location in the source. It
checks question names and structure, expression syntax, and known metadata
formats. Duplicate question names, malformed expressions and an empty
questionnaire are examples of errors. Unknown question extensions, scales and
unresolved expression references are warnings because they may belong to a
custom or legacy questionnaire. Checks also warn about unknown BIMMaS scoring
labels and choice values that do not match the declared scale.

A Draft can retain incomplete content. Saving a questionnaire as **Active**
requires its authoring errors to be resolved. Warnings do not block saving, and
a clean check is not proof that routing, scoring, uploads or a campaign journey
work. Check every branch in Preview and use a test assessment before publication.

### Edit JSON safely

The **JSON** workspace is a staged editor with **Format**, line wrapping, copy
and download controls. **Apply JSON** copies valid source into the designer; it
does not save the template. The Studio refuses an application that would drop
unsupported elements during the editor's load/serialization step.

While JSON edits are unapplied, saving is disabled. Apply them or choose
**Discard JSON edits**. After applying, inspect the checks and Preview. **Undo
last applied change** can restore the previous questionnaire after an applied
JSON or source/AI change; this is not a complete version-history browser.

### Downloads and sharing

Open **Downloads and sharing** in the header:

- **Questionnaire JSON** downloads the current designer questionnaire, including
  applied unsaved changes. It does not include template details or separately
  stored translations. The JSON workspace's own download instead uses the valid
  text currently in that editor, including unapplied edits.
- **Saved template package** downloads the stored template, details, and
  available questionnaire and team-field translation overlays. It excludes
  unsaved work and is available only after the first save. Use this package for
  the [JSON import/export workflow](/operate/tenant-admin/template-json-import-export).
- **Copy account link** shares the saved template's editor address. It does not
  grant access, publish a respondent link or share unsaved changes; colleagues
  still need the appropriate account access.
- **Translations** opens the account translation workspace.
- **Export PDF** uses the current designer questionnaire and the selected
  orientation and paper size, set in the same type and cards a respondent sees.
  PDF is an export, not an interactive assessment or a publication action.

### Leaving with unsaved changes

Nothing on this page saves itself, so every way out of it asks first. Clicking
away in the sidebar, reloading the tab, closing it, and **the browser's own back
and forward buttons** all raise **Leave without saving?**, with **Leave and
discard** and **Stay on this page**. Staying keeps the work exactly as it is and
the back button still works afterwards: you are not stuck on the page. Leaving
discards the edits and takes you where you were going, in the one press; a
reload or a close falls to the browser's own confirmation, which looks different
because it belongs to the browser rather than to Assessor.io. The back gesture
was the exception until September 2026: it used to discard unsaved authoring
with no prompt at all.

### Action Statements

In **Questions**, open **Action Statements** to search the statements
available to your account. The list shows 20 results at a time; **Show 20 more**
reveals the next batch. Choose a **Working question** and use **Link** to record
a source on it. **Linked to this question** filters the list to its sources.

A question source and its primary statement are different. Every linked source
is recorded on the question (`sourceStatementIds`) as a free list of sources.
The first statement you link to a scored question (role `item` or no role) also
becomes its **Primary**: the one statement its answer measures (`asrStatement`).
**Make primary** switches it to another linked statement. Unlinking the primary
clears it.

Saving binds the template to each question's primary. In an account, only
statements from locked, distributed statement sets can be bound. A primary
outside those sets stays on its question and is still reported against, but the
save reports it as not bound instead of failing. Global templates can bind any
global statement. Neither sources nor primaries change how a question is scored.

### The BIMei AI Assistant

In **Questions**, open **AI Assistant** for a sidebar that helps while you
author. It never changes the template on its own: each request comes back as a
**proposal card** showing what would change, and nothing happens until you
choose **Accept**. **Edit** lets you adjust the proposal first; **Discard**
drops it. Proposals stay in the sidebar's history, oldest first, for the rest of
the session.

Pick what you want from the action chips. The line under them says what the
assistant is working on, for example "3 selected question(s) · page Planning".
Select questions in the designer, or tick several in the sidebar's
**Questions** list.

| Action | What you give it | What it proposes |
| --- | --- | --- |
| **Draft a section** | Action Statements you search for and tick (up to 12), an optional page title | One page with one question per statement. A library item or earlier template question that already measures the statement is reused as it is, with its origin shown; a reused library item also keeps its registered scale, and the proposal says so when its scale is not registered, or when the item's options are not that scale's codes, so you can choose one. The rest are drafted with a question type, a registered scale (its choices come from the scale, not the AI) and Domain/Tier/Thread labels, and each question measures its statement. Add it as a new page or to the current one, and untick any question you do not want. |
| **Assign metadata** | Up to 10 selected questions | Labels, a registered scale and the Action Statement each question measures, each shown before and after. Tick the parts to apply. Replacing a question's answer choices with the scale's own options is a separate tick: it starts ticked when the question's current choices are not the scale's, and the card says why: either some current choices are not on the scale, so answers to them could not be read on it, or every current choice is on the scale but the scale adds options the question lacks, such as N/A. It starts unticked when they already match. You can change it either way. **Edit** shows the statement alternatives with the assistant's confidence. |
| **Delivery rule** | A sentence such as "only for information managers in the design phase", for the selected questions or the current page | A SurveyJS visibility condition and a plain-language restatement. Rules use what the platform already knows about a respondent (discipline, lifecycle phase, organisation size, province) where it can, or the answers to your existing questions. Anything the sentence asks for that the template cannot express is listed rather than guessed. Tick **Keep the current rule too** to require both. |
| **Explain coverage gaps** | Nothing: it reads the numbers the **Traceability** tab shows | A short explanation of what is covered and what is not, with buttons that open **Assign metadata** for the questions that need it or start **Draft a section** with a search for an empty area. |
| **Improve wording** | One selected question, optional instructions | Clearer wording for the question and its choices. The type, the number and order of choices, their values, logic, metadata and translations are kept. |

When a respondent's discipline, lifecycle phase, organisation size or province
is not known to the platform, a delivery rule built on it still shows the
question to them, and the card says so. Add a qualifier question that asks for
it and the rule uses the answer instead. The rule is written so it never hides a
question from everyone whose value is unknown.

An accepted proposal is one step in the designer's own undo and redo, and the
header also offers **Undo last applied change**. If you change a question after
the assistant proposed something for it, the card is marked as changed and
cannot be applied; ask again. Accepting never saves: check, preview and
**Save Template** as usual. Any Action Statement a question comes to measure is
bound to the template on save when your account's statement sets allow it, and
recorded on the question otherwise.

The assistant needs account authoring access (`survey_templates.modify`) and
configured AI service access. It can only use the statements, items, templates,
scales and labels available to your account, and a suggestion that refers to
anything else is refused and shown as an error instead. AI does not validate
factual accuracy, evidence, routing or scoring. Review each suggestion and test
the result before saving it as ready for use.

### Item library

In **Questions**, open **Item library** to reuse a question instead of building
it from scratch. **Search** looks across the reusable item catalogue (bank
imports, and items authored directly in an account or the console) by text,
scale and label; **From prior templates** searches the account's other
templates, when that search is available. **Insert** adds the chosen item to
the current page with a unique question name (it never overwrites an existing
one) and keeps its type, choices and Metadata properties as authored. When
the item has a scale your account can use (a built-in scale, a global scale or
one of your own) and every option the item offers is one of that scale's codes,
the inserted question declares it as its `asrScale`. When the item's scale is
not registered, its card says **Scale not registered**; when its options don't
match the scale's codes (the bank can update an item's options without changing
its scale), the card says the options don't match. Either way the question is
inserted without a scale: choose one in the property grid, and **Check**
reminds you until you do. Any
Action Statement the item names becomes a linked source
(`sourceStatementIds`), and the first one becomes the question's primary
(`asrStatement`) when the question is scored and does not already declare a
primary. Nothing is bound to the template until you save. The header's
**Undo last applied change** covers an insert the same way it covers an AI
suggestion.

### Traceability

Open the **Traceability** workspace to see, live, how the current questions
add up, including unsaved changes. It shows scored items, qualifiers,
questions excluded on purpose (`asrRole: ignore`) and questions dropped for
another reason (an unrecognised Domain, a missing qualifier value, and so on);
selecting a dropped question opens it in the designer. The Domain x Tier grid
counts scored items into each cell (a dashed cell has none) and rolls up to
Theme A-D. The statement list shows each measured Action Statement with its
questions, and the reverse: questions that name no statement at all. Nothing
on this tab is saved by looking at it: it is a coverage view, not an edit.

## The question metadata properties

Select a question in the Designer and its property grid gains a **Metadata**
category. These properties are what turn a question into something the maturity
reporting can read; without them a question is just text on a page.

Since 17 September 2026 there are four scoring properties, not nine. Everything
DESCRIPTIVE travels in one list of label references, and only the three things
a report cannot compute without keep properties of their own. A fifth,
`asrStatement`, records which Action Statement the item measures and does not
affect scoring.

| Property | Values | What it does |
| --- | --- | --- |
| `lbls` | a list of `group:label` references | What the question is ABOUT. One entry per axis: `domain:d2`, `theme:b`, `tier:mop`, `thread:mt_po_10`, `qualifier:province`. |
| `asrRole` | `item`, `qualifier`, `ignore` | Whether the question is scored, segments the respondent, or is skipped. |
| `asrScale` | a scale id | Which answer scale this question uses. Defaults to `maturity-5`. |
| `asrWeight` | number, default `1` | Relative weight within its domain. |
| `asrStatement` | a statement id or a BIMei Ontology (ONT) statement IRI | The primary Action Statement the item measures. Carried into reports as lineage. It does not change the score and binds the template on save. |

### Governed pickers

`lbls`, `asrScale` and `asrStatement` are pickers in the property grid, not
free text:

- **`lbls`** offers every label your account can see, grouped by label group
  and shown by its human name (for example "Domain: D2 (BIM Uses)"). You can
  still type a reference the list does not carry: Check flags an unrecognised
  group or label afterwards, it does not block you.
- **`asrScale`** offers every scale your account can use: the built-in scales
  first, then the custom ones, global and your account's own, each marked as
  such and shown with a one-line preview of its kind and level count. Retired
  and merged scales are not offered. A deprecated scale is still offered, marked
  as deprecated and with the scale to use instead when one is named. Picking a scale on
  a question with **no choices yet** applies its levels immediately: the
  radiogroup, checkbox, dropdown, ranking, matrix or rating fills in. Picking
  one on a question that **already has choices** asks first, with a note when
  the existing values do not match the scale, since replacing keeps nothing of
  what was there. A deprecated scale is still offered, marked as such and with
  the scale to use instead; a retired one is not offered. Nor is the Level of
  Evidence, except on a question that already uses it, where it stays in the
  list marked retired.
- **`asrStatement`** offers a searchable list of Action Statements with a
  vetting chip (`ONT·candidate`, `ONT·canonical` or `Local`) and, for an ONT
  mirror, its IRI, so you can tell an ONT-governed statement from a locally
  authored one without leaving the property grid.

If you set `asrRole` to `item` (or leave it unset, which behaves the same way)
and declare no `asrScale`, a banner nudges you to declare one (see the trap
below).

### Reading and writing a label reference

A reference has two halves and **both are folded**: lower case, punctuation and
separators dropped, the group half camelCased and the label half joined with
underscores. So the Domain `D2` is `domain:d2` and the Thread `MT-Po-10` is
`thread:mt_po_10`, **not** `thread:MT-Po-10`. If you are typing one by hand,
type the fold, or copy an existing reference from a question that already has
one.

The groups the built-in report reads are:

| Group | Labels | Was |
| --- | --- | --- |
| `domain` | `d1`–`d9` | `bimmaasDomain` |
| `theme` | `a`–`d` | `bimmaasTheme` |
| `tier` | `mop`, `moe`, `moo` | `bimmaasTier` |
| `thread` | `mt_po_10` and the rest | `bimmaasThread` |
| `qualifier` | `province`, `org_size`, … | `bimmaasQualifier` |
| `topic` | **reserved** | `bimmaasTopic` |

A Theme is derivable from a Domain, so `theme:` is a cross-check rather than a
second source: a value that contradicts the Domain's Theme is reported instead of
scored. `topic:` is **reserved**: nothing reads it and no report groups on it.
It is held for the day the programme owner publishes topic codes of their own,
and adopting them is a content change: they arrive as a label group, and no
property is minted for them.

**Your account may add groups of its own.** A group you create on the Labels
screen can be referenced here the same way (`capability:information_management`),
and a report definition you author can name it as its roll-up axis. Nothing in
the platform has to learn about it first. The five above are seeded globally
because their codes belong to the programme owner, and they are locked for that
reason.

Three things about all this that are easy to get wrong:

- **Authoring checks are not a complete taxonomy review.** For example,
  `domain:d12` has the right shape but triggers a warning because it is not a
  known BIMMaS domain. Account-defined labels and their meaning still need
  review. The reporting layer resolves references and drops an invalid item
  with a reason rather than scoring it. Run a report against a test submission
  before you trust a new template.
- **A value equal to its default disappears from the saved body.** Setting
  `asrWeight` to `1` explicitly, then reloading, shows it absent. That is
  SurveyJS omitting defaults, and it is harmless: the reader re-applies them.
- **A template authored before 17 September 2026 still works, and is still readable.** The
  app accepts the old `bimmaas*` spellings for one release, so nothing broke the
  day this changed. Ask an administrator to run
  `scripts/migrate/relabel-question-meta.ts` to move your account's templates
  onto the new property panel; reports computed from a CLOSED wave keep reading
  the body that wave ran on, untouched.

Matrix rows can override their question's references **per group**: a row that
names a `tier:` keeps the question's `domain:`. A row may also set its own
`asrRole` and its own `asrStatement`. `asrScale` and `asrWeight` stay question-level: a scale belongs to
the question's column set and a weight to the question's place in the
instrument.

The roll-up these properties feed is **item to domain to theme**. There is no
topic level between the item and the domain, which is why `topic:` above is
reserved rather than used.

## Qualifier questions and routing

A **qualifier** is a question that places the respondent in a segment rather than
scoring them. Make one by setting `asrRole` to `qualifier` and adding a
`qualifier:<axis>` reference to `lbls`. A qualifier with no such reference is
dropped.

The axes the engagement and reporting surfaces understand are `province`,
`org-size`, `sector`, `discipline`, `lifecycle-phase` and `participant-class`;
the wider qualifier vocabulary also carries `project-types`, `asset-portfolio`,
`practitioner-role`, `milestone`, `jurisdiction-level` and `technology`.

### Routing on what the platform already knows

A qualifier question asks the respondent something. Often the platform already
knows the answer: from campaign intake (a registration question mapped to a
label group), from a label already on the participant's roster row, or from
their organisation's own record. Asking again is a tax on every respondent
for the platform's convenience, not theirs.

Before the questionnaire loads, the taker resolves what is already known into a
fixed set of `asr.*` runtime variables and applies them with survey-core's own
`setVariable` API, the same mechanism a calculated value or a `visibleIf`
already reads, just supplied by the platform instead of an answer. Nothing about
this is a fork: it is public SurveyJS API, so it survives an upgrade the way a
custom widget would not.

The variables a template can reference:

| Variable | Type | What it is |
| --- | --- | --- |
| `asr.participant.labels` | string[] | Every `group:label` chip on the respondent's roster row |
| `asr.participant.<axis>` | string | The respondent's own value for one axis, when known |
| `asr.org.name` | string | The respondent's organisation's display name, when resolved |
| `asr.org.labels` | string[] | Organisation-scoped label chips (currently always empty, see below) |
| `asr.org.<axis>` | string | The organisation's own value for one axis, when known |
| `asr.campaign.labels` | string[] | Label chips this campaign applies to the assessment |
| `asr.assessment.labels` | string[] | Label chips on the assessment itself |
| `asr.known.<axis>` | boolean | `true` when EITHER the participant or the organisation carries that axis |

`<axis>` is one of `province`, `orgSize`, `sector`, `discipline`,
`lifecyclePhase` or `participantClass`, the camelCase spelling a label
group's own key already uses (`labelGroupKey('org-size') === 'orgSize'`). This
is a smaller list than the qualifier vocabulary above: the axes left out
(`practitioner-role`, `milestone`, `technology`, `jurisdiction-level`,
`asset-portfolio`, `project-types`, and the three `project-*` qualifiers) are
facts about the PROJECT a respondent is answering about, not about the person
or their employer, so nothing can know them before the questionnaire asks.

**The pattern: page-level `visibleIf` on the known variable first, a qualifier
question as the fallback.**

```json
{ "name": "specialistIntro", "visibleIf": "{asr.known.discipline} = true and {asr.participant.discipline} = 'architect'" }
{ "name": "disciplineFallback", "visibleIf": "{asr.known.discipline} <> true", "elements": [ /* the ordinary qualifier question */ ] }
```

Use `<> true`, not `= false`, for the fallback condition. A runtime variable
that was never set at all (a surface that resolves no participant: the
registration form, a very old cached payload) reads as `undefined` to
survey-core, and `{asr.known.discipline} = false` is FALSE for `undefined`:
the fallback would never show and the respondent would see neither branch.
`<> true` is true for both "explicitly false" and "never set", so the fallback
always has somewhere to land.

A reference to `asr.participant.discipline` or `asr.known.province` is checked
at authoring time exactly like a question name: an unrecognised `asr.*` name
warns `UNKNOWN_RUNTIME_VARIABLE` rather than the generic "not a question here"
warning, so a typo in the axis name is easy to tell apart from a typo in a
question's own name. **Preview as…**, on the Studio Preview workspace, lets you
set discipline, lifecycle phase, organisation size and free-text participant
labels before running the preview, so a routing branch that depends on one of
these variables can be exercised without a real participant.

Two axes are honest gaps today, not oversights: `asr.org.labels` and
`asr.org.<axis>` are always empty, because `organisations` carries no `labels`
column and no label group's applicability includes an organisation scope. An
account cannot yet label an organisation directly, only a participant. Until
that changes, routing on an organisation-level fact works only when every
participant of that organisation carries the same participant-level label.

**Routing is authored in Logic or JSON.** Authoring checks flag malformed
expressions and warn about unresolved question references, but they do not prove
that a condition matches your intent. A misspelled question name can hide a page.
Use Preview and answer through every branch before saving.

For a campaign that has **Campaign consent** enabled, do not add a second consent
page to the template. The campaign inserts its approved English or French wording,
records the campaign's version invisibly, and removes the template's legacy consent
gate after a participant has agreed. The assessment editor's **Ask for consent again
inside this assessment** switch is available only when the campaign allows consent
per assessment.

An existing campaign with campaign consent off keeps the legacy template-owned flow.
For that legacy case, the shipped BIMMaS Core Set is worth copying as a shape:

- Consent is the first page and is never gated.
- Every later page carries a page-level `visibleIf` on the consent answer, e.g.
  `{consentToParticipate} = 'granted'`.
- Eligibility is a survey-level calculated value over a qualifier answer, and the
  content pages add it to their condition.
- A survey-level `complete` trigger ends the run when consent is declined.
- Question-level `visibleIf` is used sparingly, only to hang a follow-up off an
  answered item, for example `{CS-06} notempty`.

In other words: **page-level gating for consent and eligibility, question-level
conditions only for follow-ups.**

## Maturity ladders and the other scales

A maturity ladder is an ordinary question (usually a `radiogroup` with numeric
choice values 1–5) carrying `asrScale: 'bimmas-maturity-5'`. The five
levels are Initial (ad hoc), Defined, Managed, Integrated, Optimised.

The platform has 32 built-in scales: 29 from the BIMMaS pack, and three
platform scales for compliance (met, partly met, not met), extent as a
percentage of scope, and proficiency. Every scale has a kind: maturity ladder,
band, closed list, frequency, trend, yes/no, free text, not-scored, or Level of
Evidence. **Only maturity ladders are averaged into a maturity mean,** and a
ladder of your own joins it only if it has five levels, like the BIMe ladder.
The others are reported, not averaged. The Level of Evidence appears with the
built-ins, but it supplies the review levels auditors use on answer reviews:
don't use it as a question's scale.

The repeated authoring pattern is a **tier triplet**: one thread answered three
times (`MoP` on the maturity ladder, `MoE` on a frequency scale, `MoO` on a trend
scale), where only the first contributes to the mean.

**The trap worth remembering:** if you leave `asrScale` off, it defaults to
the maturity ladder. That is right for a five-point radio group and nonsense for
a comment box. The reader rescues the obvious cases: `text`/`comment` become
free text, `checkbox`/`tagbox` become a closed list, and `asrRole: ignore`
becomes not-scored. But a bare `radiogroup` with no scale is still read as a
ladder. Declare the scale.

### Your account's own scales

Anyone with `survey_templates.modify` (an Account Manager, by default) can add
scales for the account on the **Scales** tab of the Labels screen. The tab lists the built-in scales and the global custom scales,
which you can use but not change, and your account's own scales under
**Account scales**. Add a scale of your own only when no built-in or global
scale fits, for example a list of your organisation's sites or departments.

Each scale carries badges: its **status**, a **lock** with the date it locked,
where it came from (the bank, the platform console, your account or a
blueprint), its **wording version**, and its **metric** if it has one. The list
shows active and deprecated scales; choose **All statuses** under **Show** to
see retired and merged ones too.

**Creating one.** Choose **New scale** and give it:

- a **key**, which is what a question records in `asrScale`. You cannot change
  it later, and it cannot reuse the key of a built-in or global scale;
- a **name**, a **French name** if you want French readers to see one, and, if
  you like, a description. On the Scales tab, in the Studio's scale picker and in
  the merge wizard, a scale with a French name shows it when the interface is in
  French;
- a **metric**, if the scale is a rating. A metric says what the scale measures
  (frequency, extent, proficiency and so on) and how it is scored, its Type.
  The picker shows both for every metric. Choosing one sets the scale's kind
  for you. Checklist metrics and the evidence index are listed but cannot be
  chosen: the evidence index is never a question scale, and checklist scoring
  for custom scales comes in a later release. A list of options that is not a
  rating, such as your sites, has no metric. A metric can also say what kind of
  unit its bands are in. Percentages, counts and time spans are the same
  everywhere, but for a currency, an area, a length, a temperature, a mass or a
  volume the metric names only the kind of unit: your account chooses the
  actual one, such as CAD or square metres, on its **Units** page. Reports do
  not show these units yet;
- a **kind**, only when there is no metric: Maturity ladder, Ordinal band,
  Closed list, Frequency, Direction of travel or Yes / no. Free text,
  not-scored and the Level of Evidence are not offered for new scales;
- its **levels**, each with its own value and an English label, and optionally
  a French label. How many depends on what the scale is. A **list** (a Closed
  list or Yes / no with no metric) takes from 1 to 500 options, so a single
  "I confirm" step and a long list of options are both fine. An **ordered
  scale** (Maturity ladder, Ordinal band, Frequency, Direction of travel) and
  any scale with a metric take from 2 to 20 levels, and a scale with a metric
  must also fit its Type. **Add level** stops at the limit. A scale with no
  metric can give each level a score; a scale with a metric cannot, because its
  Type decides each level's number. A maturity ladder's values must be 1, 2, 3
  and so on, in order;
- a **rank** for each level, when the order matters: an ordered kind, or a
  metric whose Type scores by rank (every Type except a checklist). Ranks run
  from 0 for the lowest level, each used once, and answers are read by rank.
  **Rank by position** ranks the levels in the order listed. If the order you
  list them in and their ranks differ, the tab says so, because respondents see
  the order and the scoring reads the rank;
- optionally, the values that mean **not applicable** or **not sure**,
  separated by commas. Answers with those values are left out of averages. A
  not-applicable or not-sure value cannot be the same as a level's value;
- optionally, a **label** for each of those values, in English and French, such
  as "Not sure" / "Pas certain". A question that uses the scale shows these
  words for those answers. A value you leave blank shows the default, "Not
  applicable" / "Sans objet" or "Not sure" / "Je ne sais pas". A French label
  needs an English one beside it. Removing a value from its list removes its
  label too.

A level missing its value or its English label, a rank that is missing,
repeated or out of range, or too few or too many levels for the scale, stops the
save and is marked so you can fix it. It is
never dropped without telling you. If the levels do not fit the metric, for
example five levels on a three-point Type, the save is refused and the problem
is shown against the level it concerns.

**Before a scale locks, you can still change what it measures.** When you open
one of your scales, the tab shows where it is used: templates of any status,
pinned template versions, assessments, your account's items and blueprints.
Being used does not freeze it. Until it locks you can change its metric, its
kind (when it has no metric), its ranks and its not-applicable and not-sure
values, and add levels. What you cannot do is remove or rename a level value
that a template, item or blueprint has copied: the save is refused and says
which values and where they are used.

**When a scale locks.** A scale locks for good the first time an assessment
that uses it goes Active, whether it is published, created straight into
Active or copied into Active, or when test answers are added to one. It does
not wait for the first real answer: the lock is in place before anyone can
answer. From then on its level values, ranks, metric, kind, scores and
not-applicable and not-sure values are fixed, because answers are read with
them. To measure something differently, create a new scale.

**Rewording a locked scale.** The name, the French name, the description and
the English and French labels stay editable, the labels of the not-applicable
and not-sure values included. When you change a name or a label, the tab asks
what the change does:

- **Fixes spelling**: the words mean what they meant before, such as a typo,
  punctuation or capitals. The change is made in place. If it changes a number,
  adds or removes a word such as "not", or swaps a comparison word such as
  "more" for "less", the tab shows those changes beside the labels they touch
  and asks you to check them. Choose **I've checked: it's a spelling fix** to
  keep it as one, or choose **Changes what it means** instead.
- **Changes what it means**: earlier answers were given to different words.
  The change is saved as a new wording version, the old wording is kept, and
  the tab tells you the new version number.

The **Wording versions** list on the scale shows every version, newest first.
A change to the description alone is not asked about.

**Code aliases.** A stored answer sometimes carries a slightly different
spelling of a level value, for example a trailing space or an old typo. Under
**Code aliases** you can add that spelling, choose the value it means and give
a reason, and answers with it are then read as that value. You can add aliases
to any scale, locked or not, except a merged one. They are kept for good: an
alias cannot be changed or removed.

**Status.** From a scale's **More actions** menu:

- **Deprecate**: questions already on it keep working, and pickers still offer
  it, marked deprecated. You can name a scale to use instead, which is shown
  beside it. New blueprint items cannot use a deprecated scale;
- **Retire**: it disappears from every picker. Answers already given with it
  are still read and scored;
- **Reactivate**: a deprecated scale can be made active again. Bringing back a
  retired scale is for platform administrators only, so it is not offered to
  anyone else.

Each change asks for a reason, which is recorded.

**Merging two scales that mean the same thing.** When two scales are duplicates,
for example one with a typo in its codes and one spelled correctly, choose
**Merge…** from the **More actions** menu of the one you no longer want. It is
offered on active and deprecated scales. You can merge one of your scales into
another of yours or into a global one, never the other way round. Pick the scale
to merge into: only active scales of the same kind (and metric) are offered.
Then map each code to a code of that scale. Matching spellings and labels are
filled in for you; check them. Every code needs a target in the same role (a
level to a level, not applicable to not applicable), and on an ordered scale
bound to a metric the order must stay the same. If the codes cannot be mapped
that way, the scales are not duplicates: keep both. **Preview the merge** shows
what will change before anything does: the draft templates that will move to the
other scale, the drafts you must update yourself (their logic refers to an
affected question, or they have a translation), the blueprints you must update
yourself (a delivery rule refers to an affected item), and the blueprints that
will need review again, because their accepted questions go back to pending.
A merge that keeps every code, which only renames the scale, leaves blueprint
approvals as they are.
Published templates, drafts an active assessment is answering, compiled
blueprints and every answer already given stay exactly as they were. After the
merge, a library item or assistant suggestion that names the merged scale is
inserted on the other scale, and **Check** offers **Replace with successor** for
any question still on it. The merged scale leaves the default list. Under **All
statuses** or **Merged only** it is marked **Merged into** followed by the name of
the scale it was merged into. It stays as it was merged: it has no **Edit**, no
**Delete** and no **More actions** menu, and every change or deletion is refused,
so it cannot be edited, take a code alias, have its status changed, be
merged again or be deleted. The scale it was merged into now counts as used, so it
cannot be deleted, and while the merged scale maps one of its codes onto a code of
the scale it was merged into, that code cannot be removed or renamed.

**Metrics.** Metrics are kept by the platform, so you choose from them but do
not create them. The picker on the scale form shows what each one measures
and its Type.

**Deleting.** Only a scale that nothing uses, that has never locked and that has
not been merged can be deleted, and the deletion is permanent. A merged scale is
kept, because the answers given on it are read through it, and a scale that
another scale was merged into counts as used. For a scale that is used or locked, **Delete** shows where
it is used, or since when it has been locked, instead. Retire it to take it out
of the pickers.

**If someone else saved first.** If the scale changed after you opened it, your
save is refused. Choose **Reload** to see the latest version, then make your
change again.

**Rewording a scale does not change questions that already use it.** Applying a
scale copies its levels into the question as choices. A reworded label appears
in questions you apply the scale to from then on, not in the ones that already
have its choices.

## Editing a template that people are answering

Once any assessment built on a template is **Active**, its questions are frozen.
Precisely two fields are blocked (the survey body and the custom fields), and
everything else stays editable: name, description, lifecycle status and version,
statement bindings, the lock toggle.

The Studio opens its questionnaire in read-only mode and offers **Make editable
copy**. An unchanged questionnaire does not prevent a metadata-only save. Team
fields are still structural data: changing them is refused while the template is
in use. Copy first if you need to change questions or team fields.

If a structural save is refused, the Studio names the assessments using the
template and keeps your edits. This can also happen when an assessment becomes
Active after you opened the editor.

The escape hatch is the panel's own button, **Save as a new template**. It saves
the canvas *as it currently stands* (your refused edit included) as a new
template named `{name} (copy)`, then takes you to it. It is not a clone: a clone
would copy the stored body and lose the edit you just made.

Then repin: open the campaign's assessment, and in **Edit Assessment** change
**Based on Assessment Template:** to the copy. There is no bulk repin, and
repinning does not migrate answers already recorded, which is the whole reason
the lock exists.

Draft and Completed assessments do not lock anything. Only Active does.

## Other save safeguards

- **The template has not loaded**: editing and saving are disabled. Use
  **Retry loading**; do not start over on the blank canvas.
- **Someone saved a newer version**: your edits stay in the Studio and are not
  written over the newer save. Choose **Save as a new template**, **Download my
  changes**, or **Reload saved version**. Reload asks before discarding your
  work. The conflict check protects Studio saves against another writer; it is
  not a collaborative merge editor.
- **"Template is locked. Unlock it from the template list before saving."**:
  somebody used the padlock in the library. Unlock it there. Unrelated to the
  Active-assessment lock.
- **"Save refused. Saving would remove N elements the editor never loaded: …"**:
  the stored body contains something the Creator could not render (an unsupported
  widget, usually from a legacy import), and saving would silently drop it.
  Nothing is written. Fix the elements at the source first.
- **"Save refused: A template called "…" already exists …"**: the name is
  another template's. Template names are unique **within a scope**: within your
  account, and separately among the global templates. The comparison ignores case
  and surrounding spaces, so `Core Set` and `core set` are one name. Nothing is
  written, and nothing is ever renamed for you. Choose a different name, or open
  the template that already has it.

  The scopes really are separate: a global template called "Core Set" does not
  stop you calling one of your own templates "Core Set". They appear side by side
  in your library with a scope badge.

## Clone, and what a clone carries

**Clone template** in the library opens a dialog showing the source and a **New
template name**, prefilled `{name} (Clone)`.

Cloning the same template twice needs a name for the second copy: the prefill is
the same both times, and the second one is refused as a name conflict. Type
something that says what the copy is for.

The clone carries the survey body, the custom fields, the statement bindings and
the description. It **resets** the lifecycle to Draft version 1, unlocks it, and
lands it **in your account** even when the source was global.

The clone **does** carry translations. They are keyed to the template id and the
clone mints a new one, so the localized bodies are copied across onto it rather
than followed, and the response reports how many travelled. Which rows travel is
the SOURCE template's own scope: cloning one of your own templates carries your
account's French with it, while cloning a **global** template carries the bank's
canonical rows only: your account's local override of a global template is
deliberately not folded in. (This paragraph said the opposite until 2026-09-07;
the clone has carried translations since the template-clone fix.)

## Global templates, and the bank

A **global** template comes from the platform's assessment bank and is
distributed to accounts. In the library it carries a **Global** badge.

What you can do with one: view it, clone it, run it. What you cannot: edit it,
lock it, replace it or delete it: the API answers *Global templates are
read-only in account scope*.

**Limits and gotchas**

- **The Studio opens global and manually locked templates read-only.**
  **Make editable copy** creates an account-owned Draft copy of the stored
  template. To edit the original of a manually locked local template, first
  unlock it from the library. A global original cannot be unlocked by the account.
- **A clone is independent of the bank.** Later bank updates replace the
  distributed original, not your account copy. If the change belongs in the
  shared bank, ask for it to go there instead of maintaining a divergent copy.
- A bank-pushed template carries `bank_recipe`, `bank_version` and `bank_commit`
  in its custom fields, plus a hidden provenance stamp on the survey itself. Those
  identify where it came from; do not hand-edit them.
- A global edit made by the platform cannot rewrite a questionnaire people are
  answering: the same Active-assessment lock applies estate-wide, and the bank
  push checks before it replaces anything.

## Before you call it done

1. Run **Check**, resolve errors and review warnings.
2. **Preview** the whole thing, answering down every branch you authored.
3. Check every scored question has a `domain:`, a `tier:` and a `thread:`
   reference and a declared `asrScale`.
4. Check every qualifier has a `qualifier:` reference.
5. Attach it to a test campaign, submit once, and run a report. That is the only
   step that proves the metadata is readable rather than merely present.
6. Then set **Lifecycle status** to Active and save. Publish the assessment from
   its campaign when it is ready.

Studio Preview does not save responses or uploaded files and does not exercise
the complete participant journey. Account access, campaign consent, invitations,
campaign rules, evidence storage and reporting still need a deployed test
assessment. There is no **Publish** action in the Studio.

## Related pages

- [Publish and preview an assessment](/operate/tenant-admin/publish-and-preview-an-assessment)
- [Import and export templates as JSON](/operate/tenant-admin/template-json-import-export)
- [Translate statements and templates](/operate/tenant-admin/translator-workflow)
- [Reports and scorecards](/operate/tenant-admin/scorecards)
- [Glossary](/build/reference/GLOSSARY)
