Skip to content

Appointment Polling

How Versaa appointment polling works — how orders flow from QL into the Aareon Mobile app, what tables are involved, and how to troubleshoot when orders are not appearing on devices.

How Polling Works

Polling is done by Versaa scheduled workflows — Appointment Early Polling, Appointment Main Polling, Appointment Late Polling — which look at QL and pull appointments into Versaa to populate the Diary.

⭐ The rule (Peter Steele, 15/07/2026): at all times ONE of Early / Main / Late Polling should be in the Running state. If none is Running, Versaa is not looking at QL at all and no appointments will be pulled. Each runs for its part of the day (Main is scheduled daily ~08:15, Occurs every 1440 minutes), then ends.

  • Table the poller uses: hpm1stua (appointments) — an appointment against an order writes hpm1stua, and that is what the Main Appointment Poller reads to create diary Tasks.
  • Interval: ~5 seconds — start a poller and within ~5s it walks the appointments that are in QL but not yet in Versaa.
  • Server: AAREON-TCH01 (Live), AAREON-TCH02 (Dev/Test)

⚠ An order alone is not enough. An action creates an order (hpm1stoa). The diary Task only follows if an appointment exists against that order (hpm1stua). hpm1stoa ≠ the poller's source — see the correction below.

⚠ You cannot tell from instance history whether a poller ran

A scheduled poller that completes normally leaves NO history — it just ends. "The only time you see history of it is if it is cancelled or errored" (Peter). So "I can't see it ran" does not mean it didn't run, and an empty instance list is not evidence of a fault.

The check that actually works: is one of the pollers in the Running state right now?

# nothing Running = the poller is not polling
versaa-rag\.venv\Scripts\python.exe versaa-rag\ms_workflow_errors.py --env test list --status Running --since 7d

✅ The fix — start the poller (no service restart needed)

Management Studio → Workflows → View Workflows → Appointment Main Polling → Start Instance. Wait ~5 seconds; it picks up everything queued in QL that isn't yet in Versaa. Queued appointments flow through without re-issuing them.

The workflow page also shows the schedule — check Last run at vs Next run at. On 15/07/2026 (Test) it read Last run at 14/07/2026 08:15, Next run at 16/07/2026 08:15 despite Occurs every 1440 minutes — i.e. the schedule had skipped a whole day, which is why nothing polled on the 15th.

Key Tables

Table Purpose
hpm1stua Appointments — what the Main Appointment Poller reads to create diary Tasks
hpm1stoa Order records (an action creates an order here). Not the poller's source
hpm1stnt Notes attached to orders
hgm1stup Property data referenced by orders

Correction (15/07/2026): this page previously said hpm1stoa was "the primary polling source", and a diagnosis was made on its processed_yn column. That was wrong — per Peter, the poller uses hpm1stua. Don't diagnose polling health from hpm1stoa.processed_yn; use the Running-state check above.

Troubleshooting: Orders Not Going to Device

When an operative reports a job is not appearing on their device:

Step 1 — Is a poller in the Running state? ← do this first

This is the cheapest and most decisive check, and it was the answer on 15/07/2026.

versaa-rag\.venv\Scripts\python.exe versaa-rag\ms_workflow_errors.py --env test list --status Running --since 7d

Nothing Running → start it: MS → Workflows → View Workflows → Appointment Main Polling → Start Instance. Remember: a normal completion leaves no history, so absence of history proves nothing — only the Running state does.

Worked example (15/07/2026, Test). "Void survey tasks not appearing in Diary Portal to drag onto myself." Evidence: Dev had Appointment Main Polling Running since 08:15; Test had nothing Running at all. The workflow's schedule showed Last run 14/07 08:15 → Next run 16/07 08:15 — it had skipped the 15th. Fix: Start Instance → "came through straight away". No service restart was needed (an AAREON-TCH02 Installer restart was suggested first and would have been overkill). QL, the form and the workflow were all blameless.

Step 2 — Does an APPOINTMENT exist for the order?

If a poller is Running and the job still doesn't land, check the appointment actually exists — an order on its own will never produce a diary Task.

-- Test = t_qlfdat, Dev = a_qlfdat, Live = QLFDAT
SELECT * FROM t_qlfdat.dbo.hpm1stua WHERE order_no IN (381183, 381184, 381185);  -- appointments
SELECT TOP 10 * FROM t_qlfdat.dbo.hpm1stoa ORDER BY order_no DESC;               -- orders (context only)
Result Meaning
No hpm1stua row No appointment was created → the Create 1st Touch Appointment step didn't take. Starting the poller will not help
hpm1stua row exists, no task Poller wasn't Running (Step 1), or work-team mismatch (Step 4)

Query file: scratch/diary_portal_task_check.sql.

Getting a Void Survey onto your own device (Jo Blackburn's test recipe)

How to self-dispatch a test task — undocumented before 15/07/2026:

  1. QL → Contact Management → search the property
  2. Contact Actions → Add Action → action code VDR234 (Void Survey)
  3. Create 1st Touch Appointment ← this is the step that writes hpm1stua; without it there is no diary Task
  4. Register and Issue
  5. Diary Portal → search the order number → drag the task onto yourself
  6. Right-click → Dispatch Task → it appears in the Aareon Mobile task tray

If step 5 finds nothing, work Step 1 above (is a poller Running?) before re-issuing anything.

Step 2 — Check polling service is running

  1. RDP to AAREON-TCH01 (for live)
  2. Check Versaa services are running (via Versaa Installer / Admin Console)
  3. Look for polling service errors in Windows Event Log

Step 3 — Check the operative is assigned correctly

  • Verify the order in QL has the correct operative/work team assigned
  • If the operative's user properties don't match the work team on the order, polling will not push the job

Step 4 — Restart polling if stuck

If polling has stalled, restart the relevant Versaa service (see it/restart-services.md).

Work Team / Operative Configuration

Orders are allocated to operatives via Work Teams in Versaa. If an order is visible in QL but not on a device:

  • Check the operative's Work Team user property in Management Studio
  • Verify it matches the work team code on the QL order in hpm1stoa
  • Reference: [Versaa_IT_DMC_md/Versaa - Change Operatives Work Team.md] for the change procedure

Gas and Electrical User Properties

Gas and electrical repair forms use specific User Properties to control which operatives receive which types of jobs. These are configured per-user in Management Studio → User Properties.

Reference: Versaa_IT_DMC_md/Repair Works Order Form Gas and Elec User Properties.md