Skip to content

The _Data Items Library Form

_Data Items is a pattern-library form, not an operational one. The leading underscore sorts it to the top of the form list. Its purpose is to hold a catalogue of pre-configured, known-working data-item blocks that you copy into a new form rather than re-authoring from scratch.

  • On disk: extracted/forms/Forms/_Data+Items_3.form
  • Markdown export: Versaa_Exports_md/forms/_Data_Items_3.md

Why it exists (Peter's principle): "most of the time they are just copying things that already work." Versaa config is full of non-obvious mechanics — suffix-matched data-item groups, formula ID format, client-no resolution switches. A block that already runs in Dev/Live is pre-validated against all of them; a hand-built one re-introduces every gotcha. So the right first move on a ticket is to find a working block and clone it.

Blocks it carries (by namespace prefix)

Prefix Block Use for
QLcrm_* CRM / tenancy contact Raising a QL contact from a form (ImportContactCreationRequest)
QLRR1_* QL repair request Raising a repair request into QL
QLRRC1_* Repair request's paired contact The contact that accompanies a repair request
QLPrty_* Property block Property address / type / alerts
QLTen_* Tenant block Tenant names / address
QLCl_* Client block Client address lines
QL_* Core keys QL_Client No, QL_Property ID, QL_Tenancy Sequence No, QL_QL User ID
GenBPInsight (group) + z_* Insights panel, debug selector (z_DebugOptions/z_DebugUsers), Concatenator helper The Insights piece; the three-tier debug visibility pattern
FRA_* FRA component fields (with _original paired fields) FRA change detection
Form_* Generic form behaviour flags Email, document template, abandon processing, permissions

Provider-level equivalents

The same blocks also exist as data providers (invoked in a workflow step rather than copied into a form):

  • Contact: QL Request Generic AdHoc Contact 1/2/3 — prefixes QLAH1/QLAH2/QLAH3 (Versaa_Exports_md/providers/QL_Request_Generic_AdHoc_Contact_1.md)
  • Repair request: QL Request Generic AdHoc Repair Request 1/2

The key reusable mechanic: resolve the client from the property

QL contacts/repair requests normally require a client_no, or ImportContactCreationRequest throws "Unable to create contact as there is no client no provided". The contact/repair blocks expose option-list switches that make QL resolve the client/tenancy from the property, so no explicit client_no is needed:

Switch (<prefix>_…) Effect when Yes
Use Property Void Client No Resolve the property's void client — the fix for voids (no tenant)
Use Property Tenant Client No Resolve the property's current tenant client
Use Property Tenancy Seq No Resolve the tenancy sequence no from the property
Use Tenancy Seq No Property Resolve the property from the tenancy sequence no
Use Tenancy Seq No Tenant Client No Resolve tenant client no from the tenancy sequence no

Requirement: the step must receive propertyId (GenBP_Key_PropertyId). Because the resolution is driven by the form data item, this is a form change, not a workflow change.

Worked example — Void Survey (ticket 21617 item-2)

A Void Survey is always a void (no tenant/client), so the TENANCYMGT/CHANGES/CHECK "property details incorrect" contact errored with "no client no". The fix was a single data item: add QLMV_Use Property Void Client No = Yes (the form's contact prefix is QLMV_). Verified live — hgmcntct.contact_no=1701884, prty_id=10804, client_no=3000384 (the void client, not 0). No workflow change: workflow v4 already passed propertyId. See void-survey.md → Known Issues.

How to apply

Before building a new data-item block, contact, repair request, or QL integration, search copy-from sources in order:

  1. _Data Items library form (this page).
  2. An existing form that already does the same thing (e.g. Family Survey for a working QL contact group; Repair Works Order for button captions).
  3. The AdHoc provider family (QL Request Generic AdHoc Contact/Repair Request).

Clone the working block, re-namespace the prefix, wire the gates — rather than authoring from scratch.