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), DLD (DARC DOK), H26 (Helvetia 26 cantons), the US counties (USA-CA), and more — tracked worked / confirmed / validated by band and mode.

The awards panel has a mode filter (All / CW / Phone / Digital) that applies to the whole award — bands, counts, confirmations and the contacts behind a cell — and stacks with the worked/confirmed filter, so "worked on CW but not confirmed on CW" is one click. Reference lists sort by reference or by description.

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 — from the looked-up address and from the QTH, name, country, comment, note or grid you typed.
• An award can be marked one reference per QSO (used by DLD). When several references then match the same contact, none is assigned silently — the candidates are offered at log time and you pick. Off by default, so an n-fer POTA activation still counts every park.
• 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. A hand-assigned reference replaces what the matcher found, so a correction survives the next recompute.

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).

---

US counties (CQ USA-CA)

A county award needs a county on every US QSO, and most logs do not have one: neither the callsign nor the prefix carries it, and few operators send it.

Settings → US counties downloads the FCC ULS database — every US amateur licence with its address — and builds a local index of callsign → county + grid. It is a few hundred megabytes to fetch and takes a few minutes; once built it works offline and needs no key.

With it downloaded:

• A new US QSO gets its county (and grid, if you have none) filled in automatically — only where the field is empty. A value you or QRZ supplied is never overwritten: the ZIP-derived county is about 98 % right and the one you logged is usually better.
• Right-click → Update US county from the ULS database re-derives the county of the selected contacts and replaces what is stored. That is the deliberate opposite of the automatic pass, and it is the way to correct counties already in the log — see the Connecticut note below. Contacts outside the US, and callsigns the database does not hold, are left alone. The entry only appears once the database is downloaded.

Connecticut

Connecticut abolished its eight counties for statistical purposes in 2022; the Census Bureau replaced them with nine planning regions. CQ USA-CA still uses the old county names, so OpsLog maps a Connecticut address back to its legal county.

If your database was built by an older OpsLog, the Settings panel says so and offers a refresh — a download date alone cannot show it, because a database fetched yesterday by an older version still holds the wrong Connecticut counties. After refreshing, use the right-click update on your CT contacts.