Skip to content

Insights rollout — completion plan & tracker

This is the execution plan for finishing the Insights rollout (owned by Imran). Read insights-piece.md first for the anatomy and the data-load gate. The rollout is form-by-form, keyed on how each form is launched — that determines whether it's a quick copy-paste or needs a data-push.

✅ Update 2026-06-05 (VERIFIED IN-APP) — the route→loader map is now the source of truth; the A/B/C table below is superseded. We built importable packages and tested them in the Dev app. Key results: - RWO sub-tasks (Unvented Hot Water Storage, NIBE, Damp & Mould) INHERIT insights from the Repair Works Order task — they need DISPLAY-ONLY, no loader. Adding a self-loader duplicates the rows (the handler appends; RWO copy + self-trigger copy). This replaces the old "Category B data-push" assumption for these forms. - Unvented Hot Water Storage v9 is Active in Dev (display + switch, Add disabled, click-in to view) — first form completed end-to-end. - The injector was missing the on-screen Show/Hide switch control; now fixed. - Insights grid must be showAdd=False (no Add) + showEdit=True (tap to view). - Self-trigger (AppendPropertyInsights) is needed only for forms whose task is NOT already loaded (e.g. Void Survey via Create Jobs). Tap Flushing likely loads via Estate Search. - Management Studio assigns its own sequential version on import (manifest version is cosmetic).

The one rule that decides everything: launch route

A form's insights grid only populates if something loads [Versaa].[usp_all_insights] into its GenBPInsight group at runtime. What loads it depends on how the form is launched:

Launch route Who pushes the data What you must do
Property Search / PCA generic path Property+Search_57.workflow loads insights into the launched form's group, gated by the Insights_OnSwitch workflow variable (currently true, global — generic for any form it launches). Category A — copy-paste only. Add the display group to the form. Data flows automatically.
Sub-task that runs inside a loaded master task (RWO sub-tasks: UvHWS, NIBE, Damp & Mould) The master (RWO) already loaded insights into the shared task; the sub-task inherits them. Display + switch ONLY. ✅ Verified in-app — see the route→loader map. Do NOT add a self-loader: it duplicates rows.
Form launched as its own task with no insight loader (e.g. Void Survey via Create Jobs) Nothing loads insights for that task. Display + switch + self-loader (RequestPropertyInsights + autoSend button).
Inline sub-form loaded by a parent via <X> Subform Load (e.g. Client → Client Visit) The parent already shows insights; the child inherits it at render. Do NOT add the piece — a duplicate GenBPInsight breaks the device merge (Client v69).
No property/tenancy context (area/stock/vehicle: EAI, Van Check, Relinquishment) n/a — there's no property to load insights for. Category C — skip. Point users at the standalone Insights form.

Two traps already hit this rollout: importing packages built from a stale snapshot (reverted Mark's Dev versions) and injecting an inline sub-form (Client v69 broke task sync). Both are avoided by the route table above plus: always work from a fresh Dev pull, and test in-app that the grid populates before activating — structural validity never proves population.

The three "switches" — don't confuse them

There is no single Management Studio on/off toggle for insights. Three separate things, in three different places:

Name Type / location Role State
z_Insights_Switch form item (Option List "Show Insights;Hide Insights;") the user's show/hide choice on the form per task
z_Insights form item = GetConfigurationValue("Insights") form-side config gate feeding z_Insights_Visible's default config value
Insights_OnSwitch workflow variable (workflow_variables/…/Insights_OnSwitch.variable) gates whether the workflow loads the insights data ("1 = On, 0 = Off") true (global, already on)

Implication for the rollout: the data plumbing is global and already on — you do not flip anything per form. You only (a) put the display + toggle items on the form, and (b) for sub-tasks, pass the group down from the master.

Exclusions (in the PCA loader ignore list)

Property+Check+Appoint+LoadDat_30.workflow skips these from its data load, so they are not auto-populated even via PCA: Building Safety Check, Fire Risk Assessment, Estate Assessment Inspection, Asbestos Survey, Mutual Exchange Inspection, Warden Resident Seen Check, Fire Door Check, Stock Condition Survey, Block Survey, HHSRS Survey, Pre Leaving Visit, Damp and Mould Inspection, Red Flag Reporting, Component Replacement Request, Family Survey 2 MW, Asbestos Data. (Many of these are launched another way and handle insights themselves; flagged here so you don't assume PCA covers them.)

Worklist (regularly-used forms still lacking the display)

Status as of the 040626 fresh pull. "Started" = switch present but no grid.

Form May use Launch route Category Status / owner
Void Survey 181 Property Search / void process A switch present — Mark started; confirm before touching
Tap Flushing Check 101 PCA / scheduled A switch present — Mark started; confirm
Damp & Mould Inspection 58 sub-task of Repair Works Order (+ PCA-ignored) B not started — needs data-push
Unvented Hot Water Storage 57 sub-task of Repair Works Order (UvHWSV) B not started — needs data-push
NIBE 3 sub-task of Repair Works Order B not started — needs data-push
Succession Inspection 3 sub-task of Client Visit B not started — client-insights push
Relinquishment Inspection 1 sub-task of Client Visit, no property/tenancy keys C likely skip — no context
Complaint 1 own start/complete flow A?/C? switch present; verify route + context
EAI ×5 (Cars/Tipping/Graffiti/Trees/Team) 5–7 ea area/estate, no property C skip — standalone Insights form

Confirmed done (display present): Stock Condition Survey v48 (verify it populates — it's PCA-ignored), Client Visit, Building Safety Check, Repair Works Order, Routine Tenancy Visit, Asbestos forms, Red Flag Reporting, Pre-Leaving Visit, and others (see insights_audit.csv).

Recipe A — copy-paste (Property-Search/PCA forms)

Per Mark's method, all in Dev (Management Studio):

  1. Open the source form with the full piece (FRA Review, or Routine Tenancy Visit / Property Search) in Form Designer.
  2. Select the insights group + display section (shift-select the block; ctrl to deselect anything extra), copy, exit the form (don't press Back).
  3. Open the target form, paste the group and the display run (the grid + gate SectionBreakElements) onto the Main page after the header.
  4. Inverse-hide the legacy alerts: set the old "Property Alerts" section's Visible to z_Insights_Visible != "Show Insights" (don't delete it — keeps the fallback when insights are toggled off). Tidy any other warning sections.
  5. Save as a new version with a clear comment. Do not activate yet.
  6. Test in Dev (app): launch via Property Search, toggle Show Insights, confirm the grid populates with the property's insights, and that legacy alerts hide. If empty → the form isn't on the property-search path; treat as Category B.
  7. Activate → migrate Dev→Test→Live (dev-to-live.md).
  8. Update the form's control document (CLAUDE.md §12).

Recipe B — data-push (sub-task forms)

These are spawned by a master (RWO / Client Visit) via ExtractSubTaskCreateWorkflow, so the insight data must be passed from the master to the sub-task. Use Peter's Void First Person / Pre-Leaving Visit wiring as the reference implementation (same RWO sub-task pattern) — copy it.

  1. Do Recipe A steps 1–4 first (the sub-task form still needs the display group).
  2. In the master's flow, where the sub-task is created, add a group mapping that passes the master's GenBPInsight group into the sub-task's GenBPInsight group ("Define Format and Mappings"). The master (RWO / Client Visit) already has insights loaded, so this hands the data down without re-querying. The reusable Append+Property+Insights_15.workflow (*.AppendPropertyInsights → usp_all_insights, keyed on GenBP_Key_PropertyId) is the alternative if the master's group isn't available at that point.
  3. For Client Visit sub-tasks (Succession), the parent carries client insights — pass that group through; confirm the sub-task has a tenancy/property key to key on.
  4. Test in Dev (app): complete the master, open the spawned sub-task, toggle Show Insights, confirm the grid populates. This is the step that catches a bad mapping — do not skip it.
  5. New version, activate, migrate, control doc — as Recipe A.

Recipe B touches a master workflow and only verifies in the app. Coordinate with Peter (who owns this pattern) and re-pull Dev before editing so you build on the current master version.

  1. Agree the split with Mark & Peter. Mark: Category-A forms he's started (Void Survey, Tap Flushing). Peter: the data-push pattern (Void First Person / Pre-Leaving). You: the rest, using their work as templates.
  2. The global plumbing is already on — the Insights_OnSwitch workflow variable is true and the query variables ($QL_Property_Insights$ etc.) exist. This is NOT a form item and NOT an MS form-designer toggle; nothing to switch on per form. (The form-side z_Insights = GetConfigurationValue("Insights") is a separate config gate; z_Insights_Switch is the user's Show/Hide toggle on the form.)
  3. Finish Category A first (fast wins) for any property-search forms not already taken.
  4. Category B once Peter's reference wiring exists to copy: Damp & Mould → Unvented HW → NIBE (all RWO), then Succession (Client Visit).
  5. Category C: leave EAI / Relinquishment on the standalone Insights form.
  6. One form at a time, end-to-end, tested in-app, control doc updated, then Dev→Test→Live.

Per-form pre-flight checklist

  • [ ] Re-pulled Dev (snapshot current) — see snapshot-lag gotcha.
  • [ ] Confirmed nobody else (Mark) is mid-edit on this form.
  • [ ] Category confirmed (A / B / C) from the launch route.
  • [ ] Not an inline sub-form (<X> Subform Load) — if it is, do nothing.
  • [ ] Display added + legacy alerts inverse-hidden.
  • [ ] (B only) master→sub-task GenBPInsight mapping added.
  • [ ] In-app Dev test: grid populates + toggle works.
  • [ ] New version comment; activated only after passing.
  • [ ] Control document updated (CLAUDE.md §12).
  • [ ] Migrated Dev→Test→Live.