Diagnostic Toolkit Repository

19.4. Digital Assessment-Portal Setup Guide

A digital assessment portal is the backbone of a repeatable, audit‑ready diagnostic. It gives every stakeholder one place to work from: checklists to run, evidence to click, scores to trust, actions to approve, and progress to review—without downloading a single file. Set it up once, run it every wave, and treat it like product: versioned, instrumented, and improved on a cadence. This guide walks you through the complete build—architecture, roles, information design, integrations, security, and the step‑by‑step launch plan—aligned to the web‑only standards defined in this toolkit.

What the portal must accomplish

The portal’s job is to shorten the distance from evidence to decision. It must make capped truth visible by default, keep evidence one click away, and wire acceptance tests and dates to every action. All artifacts are web‑native pages, boards, or embedded dashboards; viewer exports are disabled. If any item fails a mandatory gate, the related readiness score is capped and the portal shows the cap reason and the acceptance test to remove it. When people ask “how do we know?”, the portal answers with links, not attachments.

Reference architecture (vendor‑neutral)

Design the portal as a thin web layer that sits over your systems of record and exposes decision‑ready views:

• Portal layer (wiki/knowledge hub): hosts pages for checklists, templates, decision logs, waiver register, change calendar, action boards, learning cards, and narrative readouts. Supports page metadata, roles, and version history.
• Embedded analytics: heat maps, operating scorecards, value waterfalls, RAG quality panels, and unit‑cost dashboards embedded as web views with export disabled for viewers.
• Data & compute: a warehouse/lakehouse holding telemetry and evaluator outputs; a scoring service or script that applies thresholds, weights, and caps and stamps snapshots; a lightweight API or view for BI.
• Pipelines & controls: CI/CD with policy‑as‑code gates (privacy, model risk, safety); logs that show failing‑gate examples; waiver register with expiries.
• Identity & security: SSO/RBAC with least‑privilege roles, and audit logs across portal, BI, and pipelines.
• Evidence index: a single page that links to CI logs, evaluator runs, contracts, corpus registry, drill records, and budget views.

Roles and permissions (keep it simple and strict)

Use four roles, mapped to SSO groups, and apply them consistently across portal, BI, and pipelines:

• Viewer: can see portfolio pages, embedded dashboards, and evidence links; cannot export or edit; cannot view restricted ERC content unless granted.
• Contributor: can create and edit pages in assigned spaces (checklists, action cards, learning cards); can move cards on the roadmap board.
• Reviewer (ERC/Finance/Platform/Legal): can annotate, approve, and set gate status; owns the waiver register entries and expiries.
• Owner/Admin: controls spaces, page templates, embed settings, and SSO group mapping; maintains the snapshot stamp banner.

Acceptance test: a user added to a role in SSO reflects the correct permissions across the portal and embeds within 15 minutes, and the Export/Download control is not visible to Viewers anywhere.

Information architecture and URL taxonomy

Create a small number of top‑level spaces that mirror the lifecycle. Keep slugs short and predictable so links remain human‑readable.

• Admin: README & governance, Evidence Index, Decision Log, Waiver Register, Change Calendar.
• Prepare: governance charter, data‑access requirements, workplan, framework customization.
• Evidence: surveys, interview guides, intake tracker, baseline analytics.
• Assess: value cases, governance model, data platform, architecture, talent, change, risk & compliance, operating model, investment business case, partnership strategy, corpus registry, evaluator spec.
• Synthesis: scoring workbook view, heat map, readiness narrative, executive readout, visualization library, stakeholder comms plan, change‑messaging.
• Planning: prioritization view, roadmap board, action cards, quick wins, investment sequence, price ladder, portability drills.
• Ops: metric specs, performance pack, reassessment agendas, learning cards, PIRs, reconstruction and DSAR drills, red‑team pack.

Use consistent page metadata (front‑matter rendered at the top of each page): id, name, version, owner, applies_to, inputs, outputs, acceptance_test, last_reviewed, next_review, snapshot_stamp. Require tags for dimension, value_case, and gate_family to power search.

Page blueprints you should standardize

Build opinionated page templates so every artifact looks and works the same. Each blueprint includes a place for the acceptance test and “evidence on click.”

• Checklist page: purpose, when to run, owner, pass standard, items with Yes/No toggles, evidence links inline, auto‑create action cards for “No” items.
• Template page: instructions at top, copy‑paste sections, mandatory fields marked, small examples, and an acceptance test that describes “what good looks like.”
• Evidence Index page: organized by source (CI logs, evaluator runs, contracts, drills, dashboards), with stable URLs and access notes.
• Decision Log page: meeting, date, decision, conditions, owner, due date, link to impacted pages; render latest first.
• Waiver Register page: gate, scope, waiver owner, expiry, mitigation, review date; highlight expired in red.
• Change Calendar page: month view of releases, drills, QBR/JBRs, training, office hours; each entry links to its page.
• Action Card page: owner, acceptance test, date, dependencies, effort, reversibility, evidence links, rollback plan.
• Learning Card page: hypothesis, lever, offline plan, guardrails, sample/power, outcome, standardization; links to dashboards and logs.
• PIR page: timeline, root cause, changes to tests/gates/runbooks, linked KPI movement.

Acceptance test: creating any of the pages above takes ≤ five minutes from a blueprint, and all include a visible acceptance test and a place for links.

Embedded analytics setup (export‑proof)

Embed dashboards with these controls:

• Default to capped views; show hatched caps and bold borders for scale‑blocked cells; display confidence badges and snapshot stamps.
• Disable Export/Download for viewer roles and hide the UI button.
• Enforce row‑level security tied to SSO groups where needed (e.g., BU‑scoped views).
• Include tooltips that link to evidence (CI run, evaluator report, contract clause, corpus registry entry).

Acceptance test: an executive can approve scale/hold/stop decisions using only embedded views and pages, and a skeptic can reach the raw artifact in two clicks.

Data and scoring connections

Keep the computer close to the data; expose read‑only snapshots to the portal.

• Ingest events with canonical IDs (vc_id, sys_id, rel_id, corpus_id, ven_id, hashed person_id).
• Compute sub‑dimensions and dimensions in the warehouse or service; apply thresholds, weights, and caps; stamp the snapshot (timestamp, weight_set, thresholds_version).
• Publish a read‑only view for BI to visualize the snapshot; never load extracts into the portal.
• Refresh cadence: weekly for operating review; monthly for portfolio; quarterly for threshold/weight resets.

Acceptance test: changing the weight set regenerates the same scores from raw inputs, and the heat map shows the new stamp within 15 minutes of publish.

Security, privacy, and compliance guardrails

Bake guardrails into the portal so compliance is the default, not a scramble.

• SSO/RBAC everywhere: portal, BI, pipelines, and evidence sources.
• No downloads: disable exports; block file attachments in portal spaces; keep everything as pages, boards, or embeds.
• Logging & reconstruction: link prompts/outputs logs to safety ops; store a quarterly 60‑minute reconstruction drill with stopwatch proof.
• Data disclosure: keep plain‑language data‑handling and transparency text on hub pages; show retention windows; link DPIA/TRA status on relevant pages.
• Purge drills: publish DSAR purge drill scripts and results on Ops pages; record stopwatch times and sample sizes.
• Secrets management: no secrets stored in pages; link to your vault entries by reference only.
• Review SLAs: ERC and Security review lanes with visible SLAs; waivers recorded with expiries.

Acceptance test: a random auditor can validate lawful data use and control effectiveness from portal pages without requesting a file.

Accessibility and localization

Make the portal usable for everyone.

• Follow WCAG 2.1 AA: clear headings, keyboard navigation, alt text for images, and proper contrast.
• Provide page variants or toggleable content for key languages; avoid embedding text in images.
• Offer low‑bandwidth alternatives (lightweight pages, minimal animation) and printer‑friendly views where floor staff need them.

Acceptance test: a screen‑reader passes on your most visited pages and spot‑checks in two target languages.

Performance and reliability

Plan for the predictable load spikes around readouts and launches.

• Set SLOs for the portal (e.g., 99.9% availability) and for embed latency (e.g., first contentful paint under three seconds on corporate VPN).
• Cache read‑only snapshots on the BI side; avoid live queries for executive heat maps.
• Keep a “degraded mode” that shows the last good snapshot if the warehouse is under maintenance.
• Back up page history per your retention policy; maintain a warm standby for the portal if it is business‑critical.

Acceptance test: during a dry run, the executive readout loads completely in less than three seconds on a standard laptop over VPN.

Build sequence — step‑by‑step

Day 0–1: Foundation

• Create the Admin, Prepare, Evidence, Assess, Synthesis, Planning, and Ops spaces.
• Map SSO groups to Viewer/Contributor/Reviewer/Owner roles and test with a non‑admin account.
• Turn off file attachments and disable export functions for viewers across spaces and embeds.

Day 2–3: Blueprints and metadata

• Implement page blueprints for Checklist, Template, Action Card, Learning Card, PIR, and Decision Log.
• Add mandatory front‑matter metadata and snapshot stamp banner to each blueprint.

Day 4–5: Evidence wiring

• Stand up the Evidence Index page and populate the first links to CI runs, evaluator packs, contracts, corpus registry, and drill records.
• Create the Waiver Register and Change Calendar pages.

Day 6–7: Scoring and embeds

• Connect BI to the scoring snapshot view; build the embedded heat map (capped by default) and an operating scorecard page.
• Add tooltips with links to evidence and confidence badges; test row‑level security.

Day 8–9: Workflows and boards

• Create the Road‑Map board with lanes for Uncap & Control, Scale Winners, and Explore & Enable; add reviewer lanes and a hard cutline.
• Link “No” answers on checklists to auto‑create Action Cards on the board.

Day 10–11: Controls & drills

• Publish CI policy‑as‑code gates and show a failing‑gate example on the Governance Model page.
• Run and publish a portability drill or reconstruction drill; record stopwatch time and defects.

Day 12–13: Content and training

• Load the Manager Kit, Change‑Messaging hub page, and first‑week rituals for one cohort.
• Draft the Executive Readout page and Readiness Narrative page for a pilot value case.

Day 14: Dry run and go‑live

• Freeze a snapshot 24 hours prior; run a simulated operating review and executive readout entirely from the portal.
• Fix any broken links, permissions, or slow embeds; publish the Decision Log entries from the dry run.

Acceptance test: leaders can make scale/hold/stop and top‑three action decisions from the portal in a single meeting; a skeptic can reach the raw artifact in two clicks; no download option appears anywhere.

Operating model and governance

Keep the portal healthy with light, regular care.

• Weekly: publish the snapshot, update the heat map, close decisions in the log, and rotate the “What changed this week” banner on the home page.
• Monthly: re‑score PI, redraw the cutline, and archive stale action cards; audit viewer export settings; spot‑check evidence links.
• Quarterly: version thresholds and weights; retire low‑signal pages; refresh “golden path” guidance; run reconstruction and portability drills.
• Semiannual: run a portal access review; re‑validate SSO group memberships and page permissions.

Acceptance test: no stale snapshot stamps, no expired waivers, and no orphan pages (each page has an owner and a next review date).

Go‑live checklist (must be all Yes)

• SSO/RBAC enforced; viewer export disabled portal‑wide and in embeds.
• Heat map defaults to capped with hatched caps and scale‑blocked borders; confidence badges visible.
• Evidence Index complete enough to reproduce five random numbers in under two clicks each.
• Decision Log and Waiver Register live and linked on the home page.
• Road‑Map board live with a hard cutline and reviewer lanes; at least one scale‑blocking gate scheduled to green within 30 days.
• One failing‑gate example visible that blocked a release in the last 30 days.
• A reconstruction or portability drill result posted with stopwatch time.
• Executive Readout and Readiness Narrative pages ready for the first forum.
• Manager Kit and Change‑Messaging hub page live; office hours listed.

30/60/90‑day portal maturation plan

• 30 days: two value cases fully instrumented; weekly operating review run from the portal; first CFO‑signed benefits method linked; first adoption and time‑to‑competence cohort panels live.
• 60 days: three additional checklists standardized; two manual reviews converted to CI gates; at least one unit‑cost lever change attributed to an anomaly tracked on the portal; drill freshness KPI added to Ops.
• 90 days: thresholds and weights versioned; at least two caps removed with acceptance‑test proof; benefits realization entries posted for each scaled case; pattern updates (prompts or router policy) documented via Learning Cards and reflected in the paved road.

Common pitfalls—and the fix

• Attachment creep. Someone uploads a slide as a file. Fix by disabling attachments in the space and recreating the content as a page with live embeds.
• Broken “two‑click rule.” Numbers point to screenshots. Fix by replacing images with embeds and deep‑linking to the underlying artifact.
• Export leaks. BI still shows a download button to viewers. Fix by applying viewer roles and disabling export in the embed settings; test with a non‑admin account.
• Definition drift. KPI definitions change silently. Fix by versioning metric specs in front‑matter and announcing changes in the weekly banner.
• Reviewer bottlenecks. ERC reviews become a queue. Fix by adding reviewer lanes with SLAs on the board and limiting concurrent review‑bound cards.
• Portal sprawl. Pages multiply without owners. Fix by requiring owner and next_review metadata and archiving pages past due.

Build the portal as a web‑native product with clear roles, clean information architecture, live evidence links, and export‑proof embeds. When you couple that foundation with the scoring snapshot, gates in CI, and a disciplined operating cadence, you create a system where readiness improves every week—and decisions are fast, auditable, and safe.