OpsLog/wiki/Awards.md

Awards

OpsLog has a flexible awards engine. Award definitions and reference lists are shared globally across profiles.

Built-in awards

DXCC, WAS / WAZ / WAC, WPX, IOTA / POTA / SOTA / WWFF, DDFM (French departments), and more — tracked worked / confirmed / validated by band and mode.

How matching works

An award scans a QSO field (state, QTH, address, notes, …) for a reference, using one Match by mode:

• code — the field value is the reference (e.g. state = NY).
• description — the reference's name appears in the field (substring, space-sensitive — "Hongkong" won't match "Hong Kong").
• pattern — the field is tested against a regex.

Plus a leading/trailing strip, a prefix prepended to found references, a dynamic mode (any value counts, like POTA), and the fallback searches described below.

One QSO can count for several references. A contact always yields every reference its field holds — the value is split on commas and semicolons, so an n-fer POTA activation logged as US-6544,US-0680 credits both parks, and a grid-line VUCC contact credits each grid. There is no "one reference per QSO" switch — it was never useful.

Match by code looks up each token of the field in the reference list (so a partial or multi-value field still resolves), while exact match requires the whole field to equal the reference. Use exact match when a substring would cause false hits.

The five rules to remember

1. Every regex is case-insensitive. Award and per-reference patterns match regardless of case (log fields are typed however the operator felt) — so \bTok[iy]o\b catches TOKYO, Tokyo and even TOKIO. Set your own flag group (e.g. (?s)) to override.

2. A reference's own Pattern is opt-in extra recognition. On the References tab each reference has a Pattern (regex) field. Fill it to recognise a reference by more than its name — spelling variants, or the cities/terms that imply it. Leave it empty and the reference is matched by name only. Example — Jiangsu (China) carries the cities in its own regex: \b(Jiangyin|Wuxi|Suzhou|Nanjing|Changzhou)\b.

3. description also runs the per-reference regexes (on the same field). A description search looks for the reference name OR fires each reference's own Pattern — so a description award over the QTH/address will auto-match your city regexes with no extra rule. (A reference with an empty Pattern stays name-only.)

4. OR rules are ordered fallbacks (first hit wins). The Fallback searches section adds extra searches tried in order, only while nothing has matched yet — the first that finds a reference wins and the rest are skipped (short-circuit, like a chain of else-if). So a province already resolved by name isn't also re-tagged, possibly differently, by a later city regex.

5. Scope is checked first — a manual reference does not bypass it. DXCC filter, valid bands / modes / emission and the valid-from/to dates gate every QSO before any reference is looked at. A 17 m QSO can't count for an award whose valid bands are 80/40/20/15/10 m, even if you assign the reference by hand. Widen the award's bands if it should count.

Tip — Hong Kong / Macau style mismatches: if the log says "Hong Kong" but the reference name is "Hongkong", either fix the name, or give that reference a Pattern like \bHong ?Kong\b. Thanks to rule 3 the pattern now works even for a description award — no separate rule needed.

Worked example — Worked All Provinces of China (WAPC)

A custom province award where the log rarely spells the province out (it names a city). The clean setup:

• Primary: Search in QTH, Match by description.
• Fallback search: Search in address, Match by description.
• On the References tab, give each province a Pattern listing its cities.

Now a QSO is resolved by the province name if present, else by a city regex — first in the QTH, then in the address. First hit wins.

Why doesn't a QSO count? — Test & Missing refs

An award that matches nothing is the hardest thing to debug: the column is just empty, and you can't tell whether the QSO was out of scope, the field was empty, the rule looked in the wrong place, or the reference isn't on the list. Two tools answer that.

Test a callsign (award editor)

In the award editor there's a Test box: type a callsign and OpsLog replays that award's rules against every QSO you have with that station and shows what happened, step by step — the exact same code path the real matcher uses, so what you see is what actually runs. For each contact it reports:

• whether the QSO is in scope (and, if not, why — wrong DXCC, band, mode, emission, or outside the valid-from/to dates);
• each rule in turn (primary, then Fallback 1, 2, …), the field value it scanned, the candidates it produced, which ones were kept, and which were rejected (with the reason — e.g. "not on the reference list");
• rules that were skipped because an earlier one already matched;
• any manual reference you assigned by hand;
• the final result — what the QSO counts for.

This is the fastest way to fix a rule: if the primary scanned the wrong field, or a candidate was rejected as unlisted, the trace says so directly.

Missing refs (awards panel)

For an award scoped to a DXCC entity (DDFM, WAS, RAC, WAJA…), the Missing refs view lists contacts that ARE in scope (right DXCC / band / mode / dates) but where no reference was found — so they don't count yet. Sort by a column, tick the matching contacts, and assign the reference to all of them at once (or click a row to open the QSO and fix the field). Recompute and the fixed contacts drop off the list. This is how you close the gaps a matcher can't fill on its own (a French QSO logged without its department, say).

Live detection & manual refs

• References are detected live as you enter a callsign.
• You can manually assign a reference to a QSO (the Award Refs tab of the QSO editor). It's stored in an ADIF extra (APP_OPSLOG_AWARDREFS) so it survives export/import — see Import and Export ADIF — and is honoured everywhere (award panel, grid columns, totals). For a list-backed award the assigned reference must still be a valid, listed reference, and the QSO must be in scope (rule 5) for it to count.

Reference lists & display

• Import reference lists for totals and names.
• Per award, choose what the Recent-QSOs column shows: reference, name, or both. Award columns are opt-in per the Columns picker (Recent QSOs and Filters).

Built-in updates vs your edits

Built-in awards ship with the app, definition and reference list. When a newer version fixes a shipped award (a better fallback chain, a corrected reference list), OpsLog offers to apply that update — unless you've edited that award yourself, in which case your version is left alone (your work outranks ours). Awards you created are never touched by updates. So you can freely tune a built-in award without fear of a future release overwriting it.

Rescan

Rescan re-pulls the logbook and recomputes — it picks up fresh LoTW / QRZ / eQSL confirmations (see QSL Management).