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