Region Mappings — Naming Regions Consistently
This screen lets you see and adjust how region names arriving from accounts are matched to regions in the Routy geo catalog. It lives under Account Integration → Region Mappings.
What this screen is for
When Routy reads an account's report, the region arrives as free text — exactly
as the source writes it (California, Calif., CA, Ontario). Those strings
mean nothing on their own, so each one has to be mapped to a region in the
geo catalog. Once mapped, every event and every report row carrying that name is
attributed to the right region.
Each row on this screen is one mapping: a source name pointing at one geo region code. A source name with no region yet is shown as Unmapped — Routy has seen the name but doesn't know where it is.
Unlike brand mappings, region mappings are global: one name, one meaning, across every account and program.
How to read the screen
Each row shows:
- Source name — the region string exactly as the source reports it. This is what Routy matches on, so spelling and spacing matter.
- Mapped region — the geo region the name points at, as a green badge, or Unmapped.
- Country — the country that region belongs to, derived from the region code.
- Code — the stored region code itself.
- Updated — when the mapping last changed.
The count under the title shows how many mappings exist, and how many are still unmapped. Click the unmapped chip to show only those, and click it again to clear the filter.
Warning triangles
A ⚠ next to a code means the code is stored but the catalog can't resolve it to exactly one region:
- The code matches more than one region. Region codes are subdivision codes,
not globally unique —
CAis both California and Catalonia. Hover the triangle to see every candidate. Reports will attribute the name to whichever region the pipeline resolves; if that's wrong, the fix is on the catalog side. - The code isn't in the catalog at all. It was mapped to something that has since been removed or was never a real region. Re-map the row.
Mapping a region
You can map a region straight from the table:
- Click the Mapped region cell on the row you want to fix.
- Pick the region from the dropdown, then click Save. To remove a mapping without losing the row, click Unmap — the source name stays and goes back to Unmapped.
The same popup is available on the Events screens, so you can fix a mapping at the moment you notice a wrong region.
Adding a mapping by hand
Use Add Mapping when you already know a name is coming and want it mapped before the first report arrives.
- Type the Source name exactly as the source will report it.
- Optionally pick a Country to narrow the region list — this is only a filter, it isn't stored on the mapping.
- Choose a Geo region, or leave it empty to record the name as unmapped.
If a region in the catalog is named exactly like the source name, it's offered as a suggestion — click Use it to accept.
The source name identifies the mapping and can't be changed afterwards; editing an existing mapping only changes the region it points at. Adding a name that already exists edits that row rather than creating a second one.
Bulk update
When several source names need the same treatment — a handful of spellings of one region, or a batch of unmapped rows — handle them in one go instead of row by row.
- Tick the rows you want. On a phone, use the checkbox on each card; on a desktop, use the checkboxes in the table, or the one in the header to take everything currently loaded.
- Click Bulk update in the top-right.
- Choose what to do:
- Map to one region — point every selected name at the same region.
- Auto-map by name — map each selected name to the region whose catalog name matches it exactly. Names with no match, or with more than one, are skipped and reported as such. The option tells you up front how many of your selection it can actually resolve.
- Unmap — keep the names, clear the region they point at.
- Confirm. The drawer shows progress row by row, then a summary.
Rows are updated one at a time, so a failure part-way through doesn't undo the ones that already succeeded. Anything that failed is listed at the end with the reason, and Retry failed re-runs just those. Stop after current halts the run without touching the rows it hasn't reached.
Changing a filter or the search clears your selection — the rows it referred to may no longer be in the list.
Finding what you need
- Search matches the source name and the region code.
- Mapping filter shows only Mapped or only Unmapped rows — start with Unmapped to find the names still waiting for attention.
- Country filter narrows to mappings pointing at regions in one country. It only lists countries the current rows actually reach.
- The funnel button clears every filter at once.
Common tasks
"A region shows up twice in reports." The source is sending two spellings of the same region. Search for the region, select every spelling, and bulk-map them to the same geo region.
"I mapped a region but the report still shows the old one." Mappings apply when a report is next processed. Re-run the account's task, or wait for the next scheduled run.
"The region I need isn't in the dropdown." The dropdown lists the geo catalog. Add the region under Global → Regions first, then come back and map it.
"I want to delete a mapping, not just unmap it." Mappings can't be deleted from here — unmapping is the equivalent. The row stays so you can see the name has been seen and deliberately left unmapped.
When to escalate to engineering
- The source name in reports doesn't match any row here, and no new row appears after a report run.
- A mapping is saved but events keep arriving unmapped for the same name.
- A code shows the ambiguity warning and reports are attributing it to the wrong country.
- Saving a mapping returns an error every time.