Tradespersons and KPIs

These jobs keep the tradesperson records current and calculate staff KPIs. All times are Brisbane time. For the full timetable see the Scheduled Tasks Overview.

Capabilities are the licences, tickets and insurances recorded against tradespersons and team members (see Capabilities). Some are mandatory; a tradesperson with an expired mandatory capability cannot be assigned to a job from the Planning Board or job view (ROCH-1382).

Tradesperson records

Clear expired tradesperson availability dates (update:user:available:date)

• Runs: daily at 01:00.
• Selects: head tradespersons (users with the tradesperson role) whose Available from date is in the past.
• Changes: clears the date, so the tradesperson shows as available again on the Planning Board.

Delete capabilities expiring today (delete:expired:capabilities)

• Runs: daily at 07:05.
• Selects: team member capability records (the older staff capability list) whose expiry date is today.
• Changes: deletes them, so the person no longer shows that capability.
• Note: this acts on the legacy staff capability records only. Head tradesperson capabilities recorded against user accounts are not deleted; they are flagged expired and chased by the weekly reminder below.

Expiring capabilities warning (notify:expiring:capabilities)

• Runs: daily at 09:00.
• Selects: legacy staff capability records that expire in exactly 30 days or exactly 7 days, for active staff whose head tradesperson is also active.
• Sends: “You have some capabilities expiring!” to the team member’s email, copied to the Capabilities expiring group in CC Emails (ROCH-1223 added the office to this email), listing the capabilities and dates.
• Changes: nothing.
• Note: like the deletion job above, this reads the legacy staff capability records. Since team member data was migrated to user accounts (ROCH-754, ROCH-1102) the number of records it finds may be small. The weekly reminder below is the one that covers current user-account capabilities.

Weekly expired capabilities reminder (send:reminder:expired-capabilities)

• Runs: Mondays at 09:00.
• Step 1: first runs a check that marks a capability as renewed when the same person has a newer record for the same capability with a future expiry date, so renewed items stop being chased.
• Selects: active users who have at least one capability that has an expiry date, is past that date and has not been renewed.
• Sends: “You have expired capabilities” (or “You have missing capabilities” if nothing is expired but mandatory items are missing) to the tradesperson, listing the items to update in the trades app.
• Changes: the renewed flags from step 1.
• Background: ROCH-1708 asked for a weekly reminder to active trades only, plus the “Send trade capabilities reminder” button on the jobs board for on-demand nudges. See Tradesperson app for how trades upload documents.

KPIs

KPI settings (targets and commission rules per person) are managed under KPI Settings; results are shown under KPI. Both jobs use the same calculation, which totals accepted quotes, accepted variations, public reviews by job size, leads and the PM visit measures (total visits, first day visits, final visits with the client present, customer confirmed visits and pre-start inspections), then applies each person’s commission rules and any manual adjustments.

Daily KPI recalculation (kpi:user:daily)

• Runs: daily at 01:30.
• Selects: every user with active, current (non-historical) KPI settings. Settings belonging to terminated users are deleted first, and KPI results for the current quarter belonging to anyone who no longer has settings are removed (ROCH-1554, ROCH-1833).
• Changes: recalculates each user’s breakdown, commission and adjustments for the current quarter (from the first day of the quarter to its last day) and saves it as the live, non-historical result.
• Where to see it: KPI. Figures on that screen are as of 01:30 each morning.

Quarterly KPI close-off (kpi:user:quarterly)

• Runs: at midnight at the start of 1 January, 1 April, 1 July and 1 October. It uses “yesterday” to identify the quarter that just ended. The code carries a note that it must not be run manually, because doing so on another date would freeze the wrong quarter.
• Selects: every user with active, current KPI settings.
• Changes: calculates the finished quarter for each user and saves it as a historical result; deletes the previous historical copy of the KPI settings and replaces it with a snapshot of the settings as they stood at quarter end, so past quarters are always read against the rules that applied at the time (ROCH-1838).
• Where to see it: the past-quarter selector on KPI.

Quality reporting

Improvement request report (report:improvement:request)

• Runs: monthly, midnight at the start of the 1st, covering the previous calendar month.
• Selects: workmanship improvement request items raised on PM reports last month.
• Sends: “Improvement Request Report” to the Improvement Request Report CC Emails group with the items, jobs and tradespersons involved. Nothing is sent if there were none.
• Where to see it: Improvement Requests and the workmanship improvement stats under Dashboard metrics. Background in ROCH-324 (recipients) and ROCH-112 (image sizes).

Tips and gotchas

• A tradesperson who says they were reminded about a capability they have already renewed probably uploaded the renewal without an expiry date, or the reminder ran before the renewal was uploaded; the renewed check only recognises a newer record with a future expiry.
• Capabilities marked no expiry are never chased.
• If a person is missing from the KPI screen, check they still have active KPI settings; the daily job removes results for anyone without them.
• Never run the quarterly KPI job by hand. If a quarter needs recalculating, ask a developer.