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

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

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

## Rescan

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