Assessment Instruments

Assessment Instruments

An assessment instrument is a scored question set, such as a risk or needs assessment, whose total score falls into named bands like "Low", "Standard" or "Enhanced". You build and publish the instrument once, attach it to a datastore, and each record then shows the assessments recorded against it with the band each one reached.

Where to find it

Architect Panel → Forms:

• Assessment Instruments — scored question sets, their versions, and the bands a score falls into

The console belongs to the Casework & Records platform module. If that module is switched off the console shows an amber notice instead; see Platform Modules.

Before you start: what works today

The console lets you build, version and publish instruments, and records show an Assessments tab listing assessments with their band. There is not yet a built-in screen for staff to fill an assessment in: responses are recorded through the platform's assessment interface, which needs a custom page or integration built by a developer. Plan for that before promising an assessment to users.

Creating an instrument

1. Open Assessment Instruments. In the New instrument card enter a Name and a Key, and optionally a Description.
2. Choose the Datastore whose records it applies to. Choose a specific datastore rather than "any".
3. Tick Enabled (it starts unticked) and click Save.
4. Click New version to create draft version 1.

Adding questions

In Add a question, enter the Question, a Key, the Answer type ("a choice", "yes or no", "a number" or "free text"), a Weight (1 unless one question should count more), an optional Score key for a sub-score, and whether it is Required. Click Add question.

For "a choice", type the options in Options as a list, each with a value, a label and the score it contributes, for example [{"value":"0","label":"Never","score":0},{"value":"3","label":"Often","score":3}]. Include "value" on every option: the placeholder in the box leaves it out, but an option without one cannot be chosen.

Questions cannot be edited. To change one, Remove it and add it again with a new key.

Adding bands

In Add a band, enter a Name (what people see, such as "Enhanced"), a Key, and the From and To scores. A band runs from its start up to but not including its end, except the highest band, which includes its end. Leave Score key blank for bands on the total.

The console checks the bands as you go and shows red warnings for overlaps, gaps, bands that run backwards, and a top band that stops below the highest possible score. The Questions heading shows the highest possible score, which is the ceiling the bands must reach.

Publishing

When the questions and bands are right, click Publish this version. Publishing is refused while a red warning remains or if there are no questions. Once published, the version's questions and bands are fixed for good. See Versions and Scoring.

What records show

Records in the chosen datastore gain an Assessments tab listing each assessment's name, version ("v2"), state (draft or complete), band and completion date. It is read-only, and shows bands rather than numeric scores.

What goes wrong and how to tell

• Nothing happens when you click a button: the console reloads without showing error messages. The action was refused; check required fields, and for a choice question check the Options list.
• A question will not add with a reused key: a removed question's key cannot be reused in the same version.
• Clicks act immediately: Remove, Publish and Retire have no confirmation.
• Bands with a score key are not listed on the console; keep bands on the total unless a developer is managing sub-scores.

Worked example

A housing team builds "Tenancy support needs" on its Tenancies datastore: eight choice questions scored 0 to 3, so the heading shows a highest possible score of 24. It adds three bands: Standard 0 to 8, Enhanced 8 to 16 and Intensive 16 to 24, with no gaps and no warnings, and publishes version 1. Its developer adds a short assessment page for officers; completed assessments then appear on each tenancy's Assessments tab with their band.

Recommendations

• Agree the scoring on paper first; published versions cannot be changed.
• Clear every red warning before publishing.
• Always include a value on each option.
• Plan how assessments will be filled in before rolling out an instrument.

Versions and Scoring

An assessment instrument changes over time, but an assessment completed last year must still mean what it meant then. Instruments are therefore versioned: a published version is fixed, each assessment records the version it was answered against, and its scores and band are frozen when it is completed.

Where to find it

Architect Panel → Forms:

• Assessment Instruments — the Version selector, New version, Publish this version and Retire this version

Draft, published, retired

The Version selector lists each version with its number, its state (draft, published or retired) and how many responses it has.

• Draft: questions and bands can be added and removed. Drafts cannot be used for real assessments.
• Published: fixed. The console shows "This version is published." and offers no editing.
• Retired: no longer given to new assessments. Assessments already started on it keep it.

New assessments get the newest published version that is not retired. Publishing version 2 therefore takes over from version 1 straight away, without retiring it.

Changing an instrument

1. Select the current published version and click New version from this one. This copies its questions and its bands on the total into a new draft.
2. Make the changes: Remove questions or bands and add new ones.
3. Clear any red warnings and click Publish this version.
4. Optionally select the old version and click Retire this version. Retiring the newest version makes the previous published one current again.

Versions cannot be labelled or deleted from the console, and a retired version cannot be un-retired. Keep a note elsewhere of why each version changed.

How a score is worked out

• Each answer scores: a choice scores its option's score; yes scores 1 and no scores 0; a number scores itself; free text scores 0.
• Weights multiply: each answer's score is multiplied by its question's weight and added to the total. Questions with a score key also add to that sub-score.
• Unanswered questions are left out of both the score and the highest possible score.
• The highest possible score is the sum of each choice question's highest option score, plus 1 for each yes-or-no question. Number questions have no ceiling, which the heading points out.
• Bands: the total is placed in the band whose range contains it. If no band matches, the band is left blank.
• Required questions must be answered before completion: "These questions must be answered first:" followed by their keys.

There is no reverse-scoring switch: give the options reversed scores instead. Answer scores are stored when answered, and the totals and band are stored when the assessment is completed, so publishing a new version never changes a completed result. A completed assessment cannot be changed or reopened.

What goes wrong and how to tell

• Publish does nothing: a red warning remains, the version has no questions, or it is already published. The console does not display refusal messages, so read the warnings on the page.
• Scores look low against the bands: options that could not be read count as 0, which lowers the highest possible score. Check every choice question's options.
• Sub-score bands vanished from a new version: only bands on the total are copied.
• Fixed data edited elsewhere: the Instrument Items and Instrument Bands datastores are visible under Data → Datastores, and editing them there bypasses the protection on published versions. Do not.

Worked example

A tenancy support instrument at version 1 bands 0 to 8 as Standard. After a review, the team wants 0 to 6. The architect selects v1, clicks New version from this one, removes the Standard and Enhanced bands, adds Standard 0 to 6 and Enhanced 6 to 16, and publishes v2. New assessments use v2 from that moment. A tenancy assessed last spring still shows v1 and Standard on its Assessments tab, because its band was frozen when it was completed.

Recommendations

• Change by new version, never by editing data directly.
• Retire deliberately, only when you want the previous version back or nothing at all.
• Record the reason for each version outside the platform.
• Check the highest possible score after every change to the questions.