> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melonly.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Record Mappings

> How matchers connect record templates so Search fill, Run, Record Search, charge totals and unique fields work.

***

## What are Record Mappings?

Matchers tell the CAD that two fields hold the same kind of data, even when their labels differ. A "First Name" field and a "Given Name" field only link if both use the matcher `first_name`. You set matchers on fields in the [Template Editor](/CAD/Admin/template-editor#matchers).

Matchers power Search fill, Run, Record Search, unique checks and charge totals. Leave the matcher blank on fields that don't need any of these.

There are two kinds:

| Kind | Set on | Example |
| - | - | - |
| Field matcher | The field itself | `first_name`, `veh_plate`, `sex` |
| Option matcher | Each choice on a Select, Multiple Choice or Checkboxes field | `male`, `female` and `other` on a Sex field |

A matcher can only use lowercase letters and underscores, up to 64 characters. Searches and unique checks ignore letter case.

***

## Search Fill

Search fill on a Standard section finds a record, then copies its data into the section.

<Steps>
  <Step title="Find the record">
    Officers search using the sources you turned on for that section. You can turn on more than one.
  </Step>

  <Step title="Copy every shared matcher">
    The CAD copies every field on the found record whose matcher also exists in this section. Searching a civilian by name can fill sex, phone number and address too, not just the name.
  </Step>
</Steps>

| Source | Officers search by |
| - | - |
| Civilian | First name, last name and date of birth (plus middle initial and alias, if the template has them) |
| Vehicle | Plate |
| Licence | Licence number |
| Custom search | The fields on one of your [search indices](/CAD/Admin/recordsreports/search-indices) |
| Record ID | The record's number |

Copying skips fields with no matcher, read-only fields, and supervisor-only fields unless the author is a supervisor. Values are fitted to the destination's input mask, and can move between field types, for example a date into a text field.

### Matching choices

When the destination is a choice field, the CAD first picks the option with the same option matcher. If none match, it falls back to the option with the same label, ignoring case.

<Expandable title="Example: copying Sex onto an arrest report">
  The civilian template has a `sex` field with Male (`male`) and Female (`female`). The arrest report has a `sex` field with M (`male`) and F (`female`). Search fill selects M or F because the option matchers match, even though the labels don't. Without option matchers, Male would only copy onto an option also labelled Male.
</Expandable>

<Note>
  Changing a matcher doesn't update existing records. Run and Record Search keep using the old matcher on a record until it's saved again.
</Note>

***

## Built-in Matchers

The CAD recognises these matchers. You can make up your own, like `phone_number` or `case_number`, for anything else. Some types need certain matchers before they'll save. See [Required fields](/CAD/Admin/template-editor#required-fields).

<AccordionGroup>
  <Accordion title="Identity">
    | Matcher | Meaning |
    | - | - |
    | `first_name`, `last_name` | Name. Used by Run name searches. |
    | `middle_initial`, `alias` | Included in Run name searches and Search fill. |
    | `dob` | Date of birth. Used to work out age. |
    | `age` | Worked out from `dob` in the same section. |
    | `contact_number`, `residence` | Phone number and address on character and licence cards. |
    | `photo`, `identity_image`, `identity_photo` | Portrait on Run results. An image field labelled with "photo" works too. |
    | `sex` | Pair with the option matchers `male`, `female` and `other`. |
    | `roblox_username` | Links a civilian to a Roblox user for auto-created civilians and the licence scanner. |
  </Accordion>

  <Accordion title="Vehicle">
    | Matcher | Meaning |
    | - | - |
    | `veh_plate` | Plate. Used by Run plate searches and traffic stops. |
    | `veh_iss` | Registration issue date. Expiry is worked out from it. |
    | `veh_exp` | Registration expiry, filled in by the CAD. |
    | `veh_make`, `veh_model`, `veh_year`, `veh_col`, `veh_type` | Shown on Run results. |
  </Accordion>

  <Accordion title="Licence">
    | Matcher | Meaning |
    | - | - |
    | `licence_number` | Licence number. Used by Run licence searches, and by charges on the same record to apply points and suspensions. |
    | `licence_iss` | Issue date. |
    | `licence_exp` | Expiry, worked out from the issue date and the template's expiration. |
    | `licence_points` | Current demerit total. |
    | `licence_class`, `licence_conditions` | Shown side by side on a licence Run. |
    | `licence_status` | Set by the CAD, not officers. See [Option Matchers](#option-matchers). |
  </Accordion>

  <Accordion title="Creating unit">
    These fill from the unit that creates the record, when the field is empty.

    | Matcher | Fills with |
    | - | - |
    | `unit_number` (or `unit_num`) | Callsign |
    | `unit_name`, `unit_rank`, `unit_platoon`, `unit_id` | Name, rank, platoon and unit ID |
    | `unit_agency` | Agency abbreviation |
    | `unit_division` (or `unit_subdivision`) | Subdivision |
    | `unit_location` (or `unit_loc`) | Last known location |
    | `unit_street`, `unit_building`, `unit_postal` | Parts of the location |
  </Accordion>

  <Accordion title="Time">
    | Matcher | Meaning |
    | - | - |
    | `now` | Fills a date or time field with the current date or time when the record is created, even if it's read-only. |
  </Accordion>
</AccordionGroup>

***

## Option Matchers

Each choice on a choice field has its own matcher box next to its label. Use option matchers when two templates word the same choice differently, or when the CAD needs to pick a choice for you.

| Field matcher | Option matchers | Selected when |
| - | - | - |
| `sex` | `male`, `female`, `other` | Search fill copies sex between records |
| `licence_status` | `valid`, `suspended`, `expired` | The licence is in that state |
| `charges_held_for_bond` | `yes`, `no` | Any charge on the record holds for bond, or none do |

### Flags

Tick the flag box on a choice to show its label as a red alert whenever that choice is picked. Runs play the flag tone, and on the Police panel the alert is sent to dispatch. A common setup is a Flags field with options like Armed or Violent marked as flags. See [Alerts and Warnings](/CAD/User/lookups#alerts-and-warnings).

***

## Charge Matchers

Put these on fields in a Standard section to show totals from the charges on the same record. The CAD fills them in and locks them. The record still needs a Charges section.

| Matcher | Shows |
| - | - |
| `charges_fine_subtotal` | Fines before surcharges |
| `charges_fine_total` | Fines including surcharges |
| `charges_points` | Total licence points |
| `charges_jail_total` | Total jail days |
| `charges_bond` | Bond owed |
| `charges_held_for_bond` | Whether any charge holds for bond: Yes or No as text, 1 or 0 as a number, or a choice with `yes` and `no` option matchers |
| `charges_surcharge_` + name | One surcharge's amount. Add the surcharge's abbreviation, name or ID in lowercase, like `charges_surcharge_cc`. |

Text fields show money with your currency symbol and jail as days.

Traffic and speeding charges also apply their points and suspensions to the licence whose number is in a `licence_number` field on the same record.

***

## Unique Fields

Text, text area, number, date, time and random fields can be unique.

| Unique type | Rule |
| - | - |
| Not Unique | No check |
| Local | No other record can reuse the value in this field |
| Global | No other record can reuse the value in any field with the same matcher |

Use Global on `licence_number` and `veh_plate` so plates and licence numbers stay unique across your CAD. Only Random fields can be both unique and read-only.

***

## Search Indices and Dependencies

[Search indices](/CAD/Admin/recordsreports/search-indices) search records by your own matchers, like `phone_number`. Each one adds a Record Search tab and a Search fill source. Run doesn't use them. A match still copies every shared matcher, not just the ones you searched by.

Fields hidden by a dependency don't count toward required matchers, so keep identity fields like `first_name` and `veh_plate` in sections that are always visible.

***

<Card title="Need help?" icon="headset" href="https://melonly.xyz/discord">
  Still have questions? Join our Discord server for support from the Melonly Team.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.