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.