Skip to content

Multi-Form Workflows

Some forms act as a menu that routes users into different sub-forms based on selection. The navigation logic lives in the form's Identify tab via Send Message Events.

Client Visit — Reference Structure

The "Client Visit" form is the primary example:

  1. Main "Client Visit" form loads → presents a radio button (Z_VisitType_UserPick) with visit type options.
  2. Based on selection, a Send Message Event fires and loads the appropriate sub-form.
  3. Sub-form (e.g., "Tenancy Check Two") runs as an independent form.

Branching logic is in the Identify tab of the main form — not in the workflow BPMN.

Client Visit visit types (v100)

The z_Visit Type User Pick field (radio button on the main screen) drives which path is taken:

Visit Type Notes
Arrears Arrears-related visit
ASB Anti-social behaviour visit
CRM General CRM contact visit
Routine/Starter Tenancy Visit Routes into Tenancy Check Two sub-form
Relinquishment Inspection Property relinquishment
Telecare Telecare-related visit
EDI EDI data collection

Tenancy Check Two — sections

  • Primary count, Relationship / turn, Gender, Phone numbers, Ethnic origin, Nationality, Proof of name, Employment (hidden April 2026 following Pat's request)

Rent Statement Request

Client Visit includes a "Request a rent statement" button controlled by z_Param_Show Rent Statement Request (Yes/No option list). When triggered: - Creates a CRM contact in QL using QLRRS_* fields (brief description defaults to "Rent statement request") - Tested in Dev (May 2026, session 10) — successfully created a CRM contact in QL - Status as of 13/05/2026: working in Dev, ready to migrate to Test

How to Locate a Field You Can't Find

  1. Reproduce in the mobile app — navigate through the form until you see the field. Note the path taken.
  2. Open Form Designer → search for the main form name.
  3. Go to the Identify tab → review branching options to identify which sub-form name corresponds to the path.
  4. Open the sub-form that matches your path.
  5. Scroll through sub-form items to find the element.

Tracing Execution via Workflow Search Instances

To confirm which forms fired during a completed run:

  1. Management Studio → Workflows → Search Instances → filter status: Completed
  2. Filter by date or workflow name
  3. Open an instance → inspect steps — each shows which form, message, or event was processed

Making Changes to a Sub-Form

Edit the sub-form directly — you don't need to edit the main menu form (unless changing navigation/routing logic).

  1. Edit the sub-form in Dev.
  2. Add a version comment.
  3. Activate.
  4. Export only the sub-form as a package.
  5. Import to Test, verify, then import to Live.

Sub-Workflow Data Passing — Critical Gotcha

Sub-workflows called by a parent workflow do NOT automatically inherit all data from the parent's initial context. Only data explicitly passed via Append Data Item steps (or equivalent) will be available.

Pattern: Append Data Item to pass missing data

If a sub-workflow is erroring because a data item (e.g., GenBP_key) is missing from its initial context:

  1. Identify which parent workflow calls the sub-workflow
  2. In the parent workflow, find the earliest step that has the needed data item in its context
  3. Add an "Append Data Item" step before the sub-workflow call, mapping: source field → target field name
  4. Source options: "Previous Workflow Step", "Workflow Subform Loaded", "Task Data" — pick whichever step in the chain has the value populated

Key principle from Mark Wright: "As long as the previous steps actually populated with XML. If it's not, then you have to keep going back through the chain to find one that is, otherwise it will error."

When retrying won't fix a missing-data error

When you retry an errored workflow step, it retries FROM that step — it does NOT replay the whole workflow from the beginning. If the data item was never in that step's context, retrying will not help. You must add the Append Data Item step to the workflow and re-run from a new instance.

Real example: Client Visit Basic Load (May 2026)

  • GenBP_key was missing from Client Visit Basic Load and all related sub-workflows
  • Fix: added Append Data Item step copying QLCL_PropertyID → GenBP_key in five workflows: Client Visit Basic Load, Schedule Preload Client Visit, Search Areas, Search Contact, Client Load Basic Details
  • Source step used: "Previous Workflow Step" / property search step (which always has the property ID)

Quick Tips

  • Multi-form flows are connected by message events in the form's Identify tab, not in the workflow BPMN.
  • When a ticket shows a screenshot from a mobile device, trace the exact navigation path before searching Form Designer.
  • If a form name search returns too many results, filter by category or search for a distinctive field name.
  • Always check Search Instances (filtered to "completed") after a change to confirm the correct path is taken.