# 📋 Forms

Totum Forms is where educators and content authors build assessment frameworks — the structured criteria used when someone scores a surgical video in Totum Assess.

Forms uses your Totum platform account and organisations. It is a separate product from Totum itself.

# What it is

In Forms you can:

• 🧱 Create frameworks with phases, steps, and optional Global Rating Scale (GRS) items
• 🎚️ Configure scoring and field types (Likert scales, text, numeric, time, toggles, checklists, dates)
• 📑 Save reusable Likert score-descriptor templates while you edit
• 📦 Publish immutable version snapshots for live assessment
• 🔒 Keep frameworks private to your organisation or list them in the public library
• 🍴 Fork (duplicate) public frameworks into your organisation as a starting draft
• 📥📤 Import and export frameworks (JSON / CSV) where your role allows
• 📨 Submit a framework for platform review when you want it publicly listed (non–platform-admin path)

⚠️ Assess scores against a published version, not against the live draft you are still editing. Changing a draft after publish does not rewrite assessments that already used an older version.

# Who it’s for

Access also requires a Forms product seat in your organisation. See Roles and permissions.

# ⚡ Quick start

1. Sign in to Forms and confirm the correct organisation in the header.
2. On My Frameworks (Dashboard), click New Framework.
3. Enter a title, procedure type, framework type (for example OSATS / OSALS / Custom), and score scale. Save to open the editor.
4. Add phases, then steps under each phase. Fill in titles, scoring types, and Likert descriptors where needed.
5. Use Preview to check how the framework reads.
6. Click Publish, enter a version number and short change summary, and confirm.
7. Tell your Assess administrator which published version to select in Assess Settings.

flowchart LR
  Create["Create draft"]
  Edit["Edit phases and steps"]
  Preview["Preview"]
  Publish["Publish version"]
  Assess["Used in Totum Assess"]

  Create --> Edit --> Preview --> Publish --> Assess

For a full cross-product journey, see Example workflow 1.

# 🖥️ Screens

Navigation appears in the header menu / burger menu. Platform admins also see Submissions in admin areas of the product.

# 🧩 Framework structure

flowchart TB
  FW["Framework"]
  FW --> PH["Phases"]
  PH --> ST["Steps"]
  ST --> SD["Score descriptors for Likert"]
  FW --> GRS["Optional GRS items"]
  FW --> VER["Published versions"]

# 🔄 Status and visibility

# Status lifecycle

stateDiagram-v2
  [*] --> Draft
  Draft --> Published: Publish
  Draft --> Submitted: Submit for review
  Submitted --> Published: Platform approve
  Draft --> Archived: Archive
  Published --> Archived: Archive

Typical paths:

• Draft → Publish (for organisational use)
• Draft → Submit for review → Platform approve → Published (often with public visibility)
• Published / Draft → Archive

# Visibility

Platform admins can mark a framework public when publishing. Other authors typically use Submit so a platform admin can approve public listing.

# 🛠️ How-tos

# Create a framework

1. Open My Frameworks.
2. Click New Framework (editors and above).
3. Complete the dialog: title, procedure type, framework type, description, score scale, and any GRS option offered.
4. Confirm — you are taken to the editor with a new draft.

# Edit phases and steps

1. Open a framework with Edit.
2. In the left panel, add or reorder phases and steps (drag where supported).
3. Select a step to edit its fields on the right: title, scoring type, critical flags, N/A, notes, video prompts, Likert descriptors, and so on.
4. Changes typically auto-save as you leave fields; watch the header save status.

# Use score descriptors and Likert templates

1. For Likert steps, add a short description for each score on the scale.
2. Where the editor offers templates, save or apply a reusable descriptor set so you do not retype the same anchors on every step.

# Preview

Open Preview from the editor or from a framework card to review the framework as a read-only document before publishing.

# Publish a version

1. From the editor, click Publish.
2. Enter a version string (for example 1.0.0) and a short change summary.
3. Platform admins may also choose to make the framework publicly visible.
4. Confirm. A frozen snapshot is stored and appears under Version History.

⚠️ Important: In-flight Assess cases keep the snapshot they were given. Publishing again creates a new version; it does not rewrite old assessments.

# Submit for platform review

If you are not acting as a platform admin and you want the framework considered for the public library:

1. Ensure the framework is in a suitable draft state and you can edit it.
2. Click Submit and confirm.
3. Status becomes Submitted. A platform admin reviews it on Submissions.

# Import a framework

1. On My Frameworks, use Import (organisation admins and platform admins).
2. Provide a JSON or CSV file in the expected format.
3. Validate and confirm. A new framework structure is created in your organisation.

# Export

From the editor (where available for your role), export the framework as JSON or CSV for backup, sharing, or use in other systems.

# Fork from the public library

1. Open Library.
2. Find a published public framework.
3. Use Duplicate / fork.
4. A private draft copy is created in your current organisation (often with “(Copy)” in the title), ready to customise.

# Duplicate, archive, or delete from My Frameworks

From a framework card’s actions menu:

• Duplicate — copy within the org (editors+)
• Archive / Unarchive — retire or restore (editors+)
• Delete — permanent removal (organisation admins+), with confirmation

# Manage organisation settings

On Settings (org admin+):

• View organisation details
• Manage members and their Forms roles
• Create and manage API keys for programmatic access where your programme uses them

# 👤 Roles in Forms (plain language)

Exact UI buttons follow these rules (for example Import is admin-gated even if you can edit). Full matrix: Roles and permissions.

# 💡 Tips and common gotchas

• Wrong organisation → empty My Frameworks or “someone else’s” list. Check the header switcher.
• Assess still using old criteria → you published a new version but Assess Settings still point at the previous version. Ask the Assess admin to update the default / routing.
• Cannot Import → you need organisation admin (or platform admin), not only editor.
• Submit vs Publish — Submit is the public-review queue path; Publish creates a version for use (and platform admins can also make it public in one step).
• GRS may appear in imported or legacy frameworks and in Assess scoring even when your authoring UI for GRS is limited — ask your programme lead if you need holistic scales.

# Related chapters

• Getting started
• Assess — consumes published versions
• Example workflows
• Roles and permissions
• Glossary