20.1.1. Concepts and Building Blocks

Before creating your first challenge it helps to understand the five ideas clearPath ties together: metric, scope, threshold, reward, and close.

20.1.1.1. Metric – what you are measuring

The metric decides how a participant is scored. clearPath supports four:

Metric	Value code	Meaning
Observation count	0	Raw number of hand-hygiene observations in scope.
Compliance %	1	Percentage of observations where a rub or wash was recorded.
Improvement delta	2	Current-period compliance minus prior-period compliance (in percentage points). Requires prior-period dates.
Longest streak	3	Length (in days) of the longest consecutive run where daily compliance stayed at or above the configured streak threshold.

20.1.1.2. Scope – who is competing

The scope decides who is eligible. Every challenge resolves its scope to a list of participants at compute time; each participant is scored independently:

Scope	Code	Participants
Facility	0	Every facility in the corporation (or one specific facility, if set).
Unit	1	Every patient-care area (unit) under the corporation’s facilities.
Auditor	2	Every user who has recorded at least one session.
HCP Type	3	Every distinct healthcare-provider type that appears in the data.
Team	4	Every active team defined under Teams.

20.1.1.3. Threshold and comparator – the goal

The threshold is the number a participant must reach; the comparator is the direction.

• Comparator 0 (≥) – participant meets the goal when their metric is at or above the threshold.

• Comparator 1 (≤) – participant meets the goal when their metric is at or below the threshold.

Combined examples:

• “≥ 90% compliance this month” – metric = Compliance %, threshold = 90, comparator = ≥.

• “Record at least 50 observations this quarter” – metric = Count, threshold = 50, comparator = ≥.

• “Improve by at least 5 percentage points” – metric = Improvement delta, threshold = 5, comparator = ≥.

• “Maintain a 14-day streak at 85%” – metric = Longest streak, threshold = 14, streak threshold = 85.

20.1.1.4. Reward – what winners receive

Each challenge can award:

• Points – any non-negative integer. Points accumulate in the Points Ledger.

• Badge – any badge from the catalogue. The badge is granted once per winner, permanently.

Rewards are optional. A challenge with zero points and no badge still records who met the goal – the results can be used for recognition, reporting, or downstream manual rewards.

20.1.1.5. Close – when the awards happen

A challenge moves through three states:

1. Active – within its date window; results can be previewed and recomputed.

2. Closed – the admin (or the auto-close job) has run Close. At close time clearPath:

   • Writes the final results snapshot to challenge_results.

   • Inserts points and badge grants for every winner (met = 1).

   • Evaluates Badge Auto-Award Rules for each winner and grants any tier badges whose thresholds are now satisfied.

   • Queues an email notification in the mail outbox for auditor winners who have an email on file.

3. Inactive – the challenge is disabled but not closed; no awards are ever made from this state.

Close is idempotent. Running it twice has no effect the second time – a unique constraint on the ledger prevents double-awards, and the state check short-circuits immediately.

20.1.1.6. The ledger

Every point grant, redemption, expiry or adjustment lives in challenge_points_ledger. Entries are signed:

• Earned (reason = 0) – positive. Created on challenge close.

• Redeemed (reason = 1) – negative. Created by the redemption endpoint.

• Expired (reason = 2) – negative. Created when points age out.

• Adjusted (reason = 3) – positive or negative. Manual correction by an administrator.

A participant’s current balance is simply SUM(points) across all their ledger rows. The Participant Profile page computes this for you.