Component Replacement Request Form¶
Live dependencies & version history: see the auto-generated catalog page — its Dependencies & Related section lists the sub-forms, sub-tasks, and workflows that use this form, refreshed on every dev pull.
Key reference for the CRR form — the most-developed form in this workspace.
Version History¶
| Version | Notes |
|---|---|
| v61 | Last version modified by direct XML patching in this workspace. Baseline for "Other" button work. |
| v78 | Added new fields. Word Connector template updated (date/lifecycle rows removed). |
| v80 | Added QLPrtyCy_cost (Decimal) and z_ComponentToUpdate_Manual via Management Studio. |
| v85 | XML-patched: added z_*_Fmt date String fields + set availableForDocumentRendering=True on 10 fields. Deployed as v94/v95 after version increments on each import into Dev. |
| v97 | Added: Get Component Request Data button, z_component_count calculated Integer field (hides button when data already loaded). Version increments reflect imports through Dev→Test→Live environments. |
| v100 | Current version as of 27/05/2026 full export. Document rendering expansion: ActualLifecycle, ComponentToUpdate, Component_In_Place, and several other previously-False fields now have availableForDocumentRendering=True. Form_FormName added to nameFields. KeyFields updated to include "Red Flags". Incremental refinements across v98–v100. |
| v102 | Ticket 11469 (02/06/2026 demo feedback). Removed the duplicate Last_date column from the component-selection grid (QLPrtyCm_Components GroupDataGridElement) — it duplicated the installation date (inst_date). Grid-column-only change: the underlying QLPrtyCy_last_date FormItem and the row-tap detail field are untouched, and the grid loader (Comp Request App Data v12) is unaffected. Grid now shows 7 columns: new_cmpnt, Desn, inst_date, next_date, next_pdt, Duration, QLPrtyCy_cost. Package Component+Replacement+Request_102_remove_lastdate_11469.ftpackage. |
Current file: extracted/forms/Forms/Component+Replacement+Request_102.form
v80 Behaviour Summary¶
- Tap a table row → fields auto-populate from
GetSelectedItemValue("QLPrtyCm_Components", ...)value formulas → remain read-only. - Tap "Other" (
Other_Component = "Other") → fields become editable (ReadOnly formula evaluatesFalse). - In "Other" mode,
ComponentToUpdateno longer auto-overwrites from the table row — manual text entry is preserved. - All 6 target fields are
isMandatory=False. Other_Componentoptions:Other;Use table value;— allows user to explicitly switch back out of Other mode.
v61 Field Reference (XML-patched baseline)¶
All 6 target fields are in the ComponentToUpdate section (lines ~16245–16720 of the v61 form file):
| Field | Type | Element UUID | Formula ID |
|---|---|---|---|
ComponentToUpdate |
TextBox | 8956d90a-2406-4273-8a7a-859f91951bcc |
c0b1a2d3e4f5678901234567890abc01 |
InstallDate |
DatePicker | 57d4bbbb-9c45-49fd-8719-f4a5c5425d35 |
c0b1a2d3e4f5678901234567890abc02 |
LastDate |
DatePicker | f3e6bfdb-3312-41bc-92fd-3ba709f55af6 |
c0b1a2d3e4f5678901234567890abc03 |
NextPlannedDate |
DatePicker | 397a4813-121f-457b-9dfc-dd7a5836c7f7 |
c0b1a2d3e4f5678901234567890abc04 |
NextDate |
DatePicker | 89360339-f4e8-48c8-9549-afc1eb9f64b0 |
c0b1a2d3e4f5678901234567890abc05 |
LifeSpan |
IntegerBox | fdf6577d-a65b-4efb-90a7-d235b69b7262 |
c0b1a2d3e4f5678901234567890abc06 |
Other_Component |
OptionsListRadioButton | 98480e2c-0c34-4bd1-ac38-9739c594a6d1 |
none |
PercentthroughLife |
IntegerBox | 7e7d8d76-d031-4877-8ff5-b11c7dcee8ee |
45864549c44a44999d51fef3b7649abf |
For v78/v80 work, inspect the extracted form file directly — element IDs may differ.
v85 z_*_Fmt Date Formatting Fields¶
Three z_* String FormItems were added in v85 to provide clean DD/MM/YYYY date values for the Word Connector document template. The original dateTime fields showed 00:00:00 in the PDF because they were rendered as raw datetime strings.
| Field | Type | archivable |
availableForDocumentRendering |
Formula |
|---|---|---|---|---|
z_InstallDate_Fmt |
String | True | True | $formItem.InstallDate?$formItem.InstallDate.getDate()+"/"+($formItem.InstallDate.getMonth()+1)+"/"+$formItem.InstallDate.getFullYear():"" |
z_NextDate_Fmt |
String | True | True | $formItem.NextDate?$formItem.NextDate.getDate()+"/"+($formItem.NextDate.getMonth()+1)+"/"+$formItem.NextDate.getFullYear():"" |
z_NextPlannedDate_Fmt |
String | True | True | $formItem.NextPlannedDate?$formItem.NextPlannedDate.getDate()+"/"+($formItem.NextPlannedDate.getMonth()+1)+"/"+$formItem.NextPlannedDate.getFullYear():"" |
Both
archivable=TrueandavailableForDocumentRendering=Trueare required —archivable=Truepersists the computed value to task XML so the server-side renderer can read it;availableForDocumentRendering=Trueallows the field to appear in the Word Connector template without triggering the "N invalid display items" failure.
10 fields set to availableForDocumentRendering=True in v85¶
These fields were False by default and were fixed in v85 to allow the Word Connector template to save without invalid items:
ComponentToUpdate, ActualLifecycle, LifeSpan, PercentthroughLife, Detail_Description, Recharge, Make_Safe, Component_In_Place, Photo_Description, Photo
PercentthroughLife Calculation¶
Calculates directly from InstallDate + LifeSpan, bypassing the ActualLifecycle field. This is intentional — Versaa doesn't propagate reactive changes through two levels of value formulas.
Word Connector Template (v78)¶
Source: alldocumenttemplates22040206.ftpackage → DocumentTemplates/Component+Replacement+Request.template
Working copy: versaa-rag/_tmp_component_v78.docx
Builder script: versaa-rag/build_redesigned.py
Verifier: versaa-rag/verify_redesigned_v78.py
Critical: rId collision in v78 template¶
rId11 and rId13 each appear for two different drawings in the v78 template. The drawings dict in build_redesigned.py is keyed by GUID from the descr attribute of <pic:cNvPr> (format: FieldName:GUID), not by rId. Helper: drawing_run(guid). Any edits to the script must preserve this pattern.
Merge Field GUID Map (all 17 fields)¶
| GUID | Field | Section |
|---|---|---|
a7bb487f-5be0-4982-bbbc-531f68199390 |
Form Started | Submission Details |
4d40dc59-9fb2-420f-8a82-34e8b8d9bdbf |
Form Completed | Submission Details |
ab6679ed-130a-45ef-aa53-008d40da0413 |
User Name | Submission Details |
263cd434-9f3f-4061-a162-00326588f889 |
Component | Component Details |
bc03c196-4d64-4168-ba45-7c25a1e0763d |
condition0 (Other start) | Component Details |
b37497ab-43fc-4365-842c-2c15d80dc4a4 |
Other (manual entry) | Component Details |
40ee7492-e7c4-4695-ab7e-3ac7e5fd654c |
condition0 (Other end) | Component Details |
ddbc365d-9d7e-4dc8-8734-72789cfcca93 |
Detail_Description | Reason for Replacement |
810bee26-3579-4849-b933-2525d19db5f1 |
Recharge | Assessment |
1d10505e-0131-4e77-b341-64eef8916ff0 |
Make_Safe | Assessment |
49e85165-c49a-45cb-8774-97f882d886c2 |
condition0 (In_Place start) | Assessment |
f3de01a9-f1eb-453b-9138-311dae187645 |
In_Place | Assessment |
8212fc13-ce65-4e66-b121-191d8121a0ee |
condition0 (In_Place end) | Assessment |
c35fa0d7-5e96-43ba-91d3-d01dfd22d683 |
Photos group start | Photographic Evidence |
bc593e3b-3309-4888-890c-639c41b38e8b |
Photo_Description | Photographic Evidence |
d758ce7b-076b-482f-a0a7-bb1c00db82d4 |
Photo | Photographic Evidence |
76300b16-f9c7-42cf-806c-25479b88015c |
Photos group end | Photographic Evidence |
Rebuilding after template changes¶
- Re-extract:
versaa-rag/extract_template.py→ updates_tmp_component_v78.docx - Inspect:
versaa-rag/inspect_template_v78.py - Update GUID constants in
build_redesigned.py - Run
build_redesigned.py, verify withverify_redesigned_v78.py
Get Component Request Data Button¶
A button was added to the CRR form (during/after session 10, May 2026) that triggers a workflow to fetch all component data for the property on demand.
How it works¶
- The button sends a message event with name:
getComponentRequestData - A workflow triggered by
any *.getComponentRequestData(wildcard — fires for any form that sends this message) runs a SQL query to fetch all component data for the property and populates the data items in the form. - The workflow was originally triggered by
componentReplacementRequest.appendPCAData. The newany *wildcard trigger means any future form can also use this workflow just by sending the same message name. - The workflow applies SQL to the property, including roofs — windows and doors were added to the SQL group table in session 10 (Peter updated the group table live by formatting Lorna's list in Notepad++ and pasting it in).
Checksum: z_component_count¶
To prevent the button from running again if data is already loaded:
- A FormItem
z_component_count(type: Integer, calculated) counts the number of property components using a formula ("get calculate as an integer — number of properties components; if none return zero"). - A Visibility rule on the button: button is not visible if
z_component_count > 0(i.e., components already loaded). - The
z_prefix means the field is temporary — not saved to the Data Warehouse.
Launching CRR as a sub-task — you MUST map the property id into the loader keys¶
The "Request Component Data" button keys the SQL on the CRR form's own GenBP_Key_PropertyId / QLPrtyCm_PropertyId. When a parent form spawns CRR as a SubTask, its <ItemMappings> must map the property id into those items — not into the generic SubTask Property ID header field. If it only maps the header, the button fires with no property and the list comes back empty.
- Working reference: the Repair Works Order form — maps
…PropertyId → GenBP_Key_PropertyId,… → QL_Property ID, and the address intoQLPrty_AddressLine1..5/QLPrty_PostCode. - Void Survey fix (17/07/2026, ticket 21617): its CRR SubTask mapping originally targeted
SubTask Property ID(copy-pasted from the Safeguarding sub-task) → empty components. Changed to mapGenBP_Key_PropertyId → GenBP_Key_PropertyId + QLPrtyCm_PropertyId + QL_Property IDandGenBP_AddressLine1..5/GenBP_AddressPostcode → QLPrty_AddressLine1..5/QLPrty_PostCode. Components + address now pull through. (Property Type has no clean parent source and RWO doesn't map it either — left blank.)
✅ RESOLVED (21/07/2026) — CRR completion email not sending as a sub-form¶
Symptom: the CRR completion email (to ComponentReplacementRequest@lincolnshirehp.com) fires when CRR is completed standalone, but never arrives when CRR is completed as a sub-task of Repair Works Order or Void Survey.
The earlier diagnosis on this page — "a shared CRR document-template / recipient issue, not specific to any parent form" — was wrong. The form and the mailbox are fine. The defect is in the parent completion workflows, and it is a different defect in each parent.
Root cause. CRR has no completion workflow of its own — its email is sent by the shared Generic Task Completion workflow. Every XPath in that workflow is anchored to //Task[not(ancestor::Task)] — the outermost Task only, nested Tasks explicitly excluded (~60 occurrences, including the gate that skips the email when Form_EmailRecipient is empty).
A sub-task lives as a nested <Task> inside the parent's TaskXml until the parent's completion workflow extracts it into its own root Task. Standalone CRR works precisely because it is the root task.
| Parent | Defect |
|---|---|
| Repair Works Order | The Process Component Replacement Request step used Toolkit.Workflow.CreateWorkflowInstanceForSubtasks, which starts a workflow instance but does not extract the sub-task. All 6 working sub-tasks in the same workflow (Gas Servicing, Commercial Gas, Solid Fuel, UvHWS, Other Gas Forms, Damp & Mould) use Toolkit.ExtractSubTaskCreateWorkflow. CRR was the only outlier. Because CRR stayed nested, //Task[not(ancestor::Task)] resolved to the RWO task, Form_EmailRecipient was never found, and the email gate evaluated false — skipped silently, no error. |
| Void Survey | No extraction step at all. All 29 Void*.workflow files contain zero sub-task steps — the CRR sub-task is created on device and then orphaned inside the parent TaskXml. |
Repo-wide the correct class dominates: 128 Toolkit.ExtractSubTaskCreateWorkflow vs 5 Aareon.Toolkit. variant vs the 2 uses of the wrong CreateWorkflowInstanceForSubtasks.
Fix (RWO) — Dev v8, 21/07/2026. Swapped the step class and parameters to match the Damp & Mould step verbatim; step id, name, transition and editor layout untouched:
- type="FirstTouch.Workflow.Steps.Toolkit.Workflow.CreateWorkflowInstanceForSubtasks">
+ type="FirstTouch.Workflow.Steps.Toolkit.ExtractSubTaskCreateWorkflow">
<ConstParameter name="sourceStep" value="Unpack Data" />
- <ConstParameter name="subtaskNames" value="ComponentReplacementRequest" />
- <ConstParameter name="parentTaskIdDataItemName" value="" />
+ <ConstParameter name="formItemNameList" value="ComponentReplacementRequest" />
+ <ConstParameter name="formItemNameStatusOverride" value="" />
+ <ConstParameter name="parentGuidDataItemName" value="" />
<ConstParameter name="workflowName" value="Generic Task Completion" />
formItemNameList takes the parent's FormItem name (ComponentReplacementRequest, per Repair+Works+Order_97.form l.736) — not the form display name.
Scripts: versaa-rag/transform_rwo_comp_crr_extract.py + build_rwo_comp_crr_package.py. Imported to Dev as v8, inactive (v7 remains active — activate deliberately before device testing).
Status (22/07/2026):
- Repair Works Order — VERIFIED in Dev AND Test. RWO Comp activated (Dev v8 / Test v16 — different lineages, same fix content, both server-verified); a CRR completed from inside a Repair Works Order produced the email at ComponentReplacementRequest@lincolnshirehp.com in both. Note the whole RWO must be completed (not just the CRR sub-form filled) — the completion workflow fires on the order completion. Test → awaiting business sign-off → Live.
- Void Survey — VERIFIED in Test. Added the equivalent ExtractSubTaskCreateWorkflow step (formItemNameList=ComponentReplacementRequest → Generic Task Completion) to Void Pre Inspection QL Updates (trigger Void Survey.UpdateHMSData = the post-completion QL-sync workflow). Inserted on the common path just before the terminal End step, so it runs on every void completion (harmless no-op when no CRR was filled). Built on live Dev v11 → Dev v12 (inactive); then imported + activated in Test as v13 (record f10cfe5c; Dev v11 == Test v12 base content confirmed identical, so the port was safe). A CRR completed inside a Void Survey in Test produced the email at ComponentReplacementRequest@lincolnshirehp.com. Test first, because Dev QL was down at the time — Dev's v12 remains inactive/unverified pending QL recovery. Scripts versaa-rag/transform_void_qlupdates_crr_extract.py + build_void_qlupdates_crr_package.py.
- Status: both RWO (Comp v8 Dev / v16 Test) and Void (v13 Test) verified in Test → awaiting business sign-off → Live. Loose end: reconcile Dev Void (activate v12) once Dev QL is back.
Email content (confirmed from the live Test email, 22/07/2026): although Form_EmailSubject / Form_EmailBody / Form_DocumentEmailAttachmentName are blank on the form, the Generic Task Completion workflow supplies them at runtime — the delivered email has a subject ("Component Replacement Request For: B21106"), a populated body (property + address + date), and the rendered CRR document attached (~83 KB, from Form_DocumentTemplateName). So the earlier concern that the mail would be subject-less / unattached was wrong — it is fully formed. No additive form change needed for subject/attachment.
Repair Works Order → CRR: Insights data passing¶
When CRR is launched from the Repair Works Order form (via the "Starting Work" button), Insights data needs to be passed across to the CRR form. The fix:
- On the "Starting Work" button in the Repair Works Order form, "Defined Format and Mappings" was used to map the Insights data group across.
- Because Mark Wright copied all the Insights items with the same names, the entire group could be mapped at once (one group mapping rather than individual field-by-field mappings).
- This passes all Insights data from the Repair Works Order to the CRR form when the button is clicked.
Repair Works Order Completion — CRR processing step (RESOLVED 21/07/2026)¶
Peter added a step in the Repair Works Order Completion workflow to "process component replacement requests". As of session 10 "the step runs and completes but does nothing."
It did nothing because it extracted nothing — it used CreateWorkflowInstanceForSubtasks instead of ExtractSubTaskCreateWorkflow, so the CRR sub-task was never lifted out of the parent's TaskXml. Session 10's hunch that "generic task completion needs its own completion workflow for CRR" was close but not quite right: Generic Task Completion is the correct target — it just has to be handed a CRR that is its own root task. See the resolved-issue section above for the fix.
Photo/image aspect ratio in Word template¶
Imran increased photo sizes in the CRR Word document template to improve visible detail in the PDF. When tested, photos were displaying but with incorrect aspect ratio (images stretching). Fix: adjust the image placeholder shape/dimensions directly in the Word template. This is an easy change — fix the proportions in the template itself.
QL contact routing (how the Asset-team case is raised)¶
The QL case/contact is not raised by a bespoke workflow — it is raised by the CRR form's
built-in QLcrm_* FormItems, fired by QLcrm_Requested=Yes on submit and processed by the
generic completion / QLWorktrayRequestCn pipeline. Key routing fields (in the v101/v102 form):
| Field | Value | Effect |
|---|---|---|
QLcrm_Requested |
formula → Yes when Submit == "Submit Request" |
Fires the QL contact on submit |
QLcrm_Class Level 1 |
ASSET |
Routes to the Asset team work tray (the single field that sets the destination) |
QLcrm_Class Level 2–4 |
COMPONENT > REPLACE > REQUEST |
Classification path |
QLcrm_Classification |
S |
Contact classification code |
QLcrm_Contact Type |
I |
Contact type |
QLcrm_CreateDefaultAction |
Yes |
Creates the default action / call-log entry (the case) |
QLcrm_DefaultAction_Action Outcome |
mandatory, from QL datalist | Sets the QL status ("awaiting a decision" is a QL-side outcome label, not in the XML) |
QLcrm_FormTypeName |
Contact |
Raises a QL Contact (not a repair) |
Form_EmailRecipient |
ComponentReplacementRequest@lincolnshirehp.com |
Asset-team notification email |
The only CRR-specific workflow is Comp Request App Data v12 — the on-demand component-data loader behind the "Get Component Request Data" button (it does not raise the case).
Ticket 11469 — 02/06/2026 demo feedback (Lorna Holdcroft)¶
Two asks from the Sally V + Repair Team Leaders demo:
- Remove the "Last Date" grid column — DONE in v102 (see version history above).
- Line-manager approval step before triage — operatives' CRR requests should first go to the
Repairs Team Leaders (line manager) to filter (some are repairable, not for replacement);
only approved ones proceed to the CRR triage meeting via a call-log action to AssetMan.
This is a QL classification/work-tray routing change, not a form rebuild — today
QLcrm_Class Level 1 = ASSETsends the contact straight to the Asset team. PENDING: the QL team (with Pete) must define which classification lands the contact in the Repairs Team Leaders' tray and how the onward "approve → AssetMan" action is configured; the Versaa change is then a small repoint ofQLcrm_Class Level *. Related to the pending "QL contact classification routing" decision (see [../../memory/STATE.md]).
Completed Work Log (CRR changes)¶
| Date | Change | Package |
|---|---|---|
| 08/07/2026 | v102: removed duplicate Last_date column from the component-selection grid (ticket 11469) |
Component+Replacement+Request_102_remove_lastdate_11469.ftpackage |
| 27/04/2026 | v61: "Other" button makes 6 fields editable | component_replacement_request_other_button_27042026.ftpackage |
| 27/04/2026 | v61 fixes: PercentthroughLife direct calculation; Other_Component auto-clear | component_replacement_request_fixes_27042026.ftpackage |
| 27/04/2026 | v61 hotfix: removed auto-clear (prevented re-selecting "Other") | component_replacement_request_click_fix_27042026.ftpackage |
| 27/04/2026 | v61 deselect: changed to Other;Use table value; options |
component_replacement_request_other_deselect_27042026.ftpackage |
| 27/04/2026 | v61 manual entry: ComponentToUpdate no longer auto-fills in Other mode | component_replacement_request_component_manual_27042026.ftpackage |
| 27/04/2026 | v61 display fix: empty string fallback instead of null (---) |
component_replacement_request_component_manual_display_fix_27042026.ftpackage |
| 27/04/2026 | v61 keep-value: preserves user-entered text in Other mode | component_replacement_request_component_manual_keepvalue_27042026.ftpackage |
| 27/04/2026 | v61 textbox split: added z_ComponentToUpdate_Manual dedicated field |
component_replacement_request_component_textbox_split_27042026.ftpackage |
| 29/04/2026 | v80: added QLPrtyCy_cost (Decimal) field and grid column |
componentreplacementrequestversion80.ftpackage |
| 29/04/2026 | v78: redesigned Word Connector DOCX (5-section layout, 17 GUIDs verified) | Component_Replacement_Request_Redesigned.docx |