Skip to content

How to Build a Form

This covers creating a new PCA (Property Create and Access) form — the standard pattern for forms that work against a property in QL.

Forms vs. Workflows

  • Form = front-end: data capture, display, visibility rules, JavaScript calculations. Lives on the mobile device.
  • Workflow = back-end: triggered when the form completes. Handles decision trees, data writes, CRM classifications, raising repairs, generating documents, sending emails.
  • A PCA form fires [FormName].PCACompletion on completion — this triggers both the form-specific workflow and the Generic Task Completion Workflow.

Forms as a Presentation Layer

A form is fundamentally a presentation layer — the underlying data is stored as XML.

  • A form can be opened without any XML behind it (e.g. a blank task launched directly).
  • Without backing XML, form items can still be pre-populated using defaults, calculations, and conditions.
  • However, without XML backing, Group Items cannot be auto-populated — they require workflow-appended data.
  • If a form is used without XML, the workflow must explicitly strip out unwanted data during a Send Message event before processing.

Form Access via Active Directory

Access to a form is controlled through Active Directory (AD) group membership.

The correct pattern

Assign a user to a role (group), and assign form access to the role — not directly to the user. This prevents repetition when multiple users need the same access.

Form-specific AD group naming

Form permissions use groups named: 

1TPG_PRTY[ENVIRONMENT]_[FORM_NAME]

Examples (as seen in Management Studio user permissions): - 1TPG_PrtyLive_Access_System - 1TPG_PrtyLive_Administer_System - 1TPG_PrtyLive_Run_AllWorkflows - 1TPG_PrtyLive_Access_Form-Non_Productive_Time

Form-specific groups follow the same 1TPG_PRTY[ENV]_ prefix with the form name appended.

Adding a user to a form group (AD Administrative Center)

  1. Open Active Directory Administrative Center on the relevant server.
  2. Use Global Search — search for the username (e.g. wrightm).
  3. Open the user record → Member Of tab → click Add...
  4. In the object name field, type the group prefix (e.g. 1tpg_prtylive) — this shows all matching groups.
  5. Select the required group(s) → OK.

When searching by partial group name, AD may return a "Multiple Names Found" dialog — scroll to find the correct group for the specific form.

See also: it/environments.md for system-level AD group requirements.

Standard Blocks

Copy these from an existing working form rather than creating from scratch:

Block Purpose
Contact CRM contact creation — client ID, property ID, CRM classification
PK Primary Key — unique identifiers for the record
Email Email delivery settings
DocEx Document export settings (EDRMS/SharePoint)
PCA Type Form First visible page — shows property info, insights, alerts
Safeguarding Standard safeguarding questions page
Insights Property insights data grid (Mark Wright's consolidated QL queries)
GenBPI General Business Process Information group

Step-by-Step: Building a PCA Form

1. Create the form

  1. Forms Designer → Create Form
  2. Give it a clear name (e.g., Component Replacement Request)
  3. Save

2. Copy blocks from an existing form

  1. Open a similar existing form
  2. Select all standard blocks (Contact, PK, Email, DocEx, PCA Type Form, Safeguarding, Insights)
  3. Copy them to the new form

If cross-form copy fails ("could not run the block, cannot read properties of null"), create the block manually.

3. Configure the Main block

Setting Value
Form document name The form name
Form document template name Same as form name
Form do NOT save to info portal No (meaning it WILL save — label is confusingly worded)
Platforms Enable Mobile, Self-Serve, and 360

For Name Fields (appears in the task list on device): - QLPRT_AddressLine1 - QLPRT_AddressLine2 - Gen.BPKey_PropertyID (or QL_PropertyID)

4. Add form_form_name hidden item

In Main → Form Items: - Name: form_form_name - Type: Text - Default value: Formula → Form Item → select Form Document Name

Populates the task list header. No need to place on a visible page.

5. Define page navigation

Page Navigates to
Main PCA Type Form
PCA Type Form Insights
Insights Safeguarding
Safeguarding (end / finish)

⚠️ Never copy an existing button. Copying copies all underlying parts by reference — editing the copy also edits the original. Always create a brand new Form Item of type Request.

  1. Open Property Search form → edit current version
  2. In Form Items, click Add Form Item:
  3. Name: e.g., ComponentReplacementRequest
  4. Type: Request
  5. Drag the new item onto the layout
  6. Configure:
Setting Value
Caption Add [form name] to your task list
Visible Yes
Message name Same as the form item name
Send to Select the new form
  1. In Define form item mappings, map these fields from Property Search to the new form:
Source (Property Search) Target (new form)
Form Workflow ID Suffix Form Workflow ID Suffix
QL Property ID QL Property ID
QL Address Line 1 QL Address Line 1
QL Address Line 2 QL Address Line 2
QL Tenancy Sequence Number QL Tenancy Sequence Number
QL Rent Account Number QL Rent Account Number
QL User ID (capital version) QL User ID

Tenancy/rent account is mapped because CRM contacts can only be raised against people, not properties.

  1. Save and add a version comment. Activate the form.

7. Test on mobile

  1. Aareon Mobile app → hamburger ☰ → Resources → Forms Update
  2. Property Search for D6621 (7 Abbey Rd / Dorothy Stocks in Dev — pre-loaded with test data)
  3. Tap the new button. Tap Finish.
  4. Management Studio → Workflows → Search Instances to verify workflow triggered.

Quick Tips

  • Always wait for the middle panel to fully load before clicking any form element.
  • Use the light touch principle — don't touch working fields.
  • Test property: D6621 = 7 Abbey Rd / Dorothy Stocks in Dev.