Template Manager
Templates define the shape of a rate file and everything that happens to it: the expected columns, the validation rules, who can use it, who approves it, who is emailed, and how each OTM table is loaded. You pick one every time you upload.
Admin screen. Most uploaders only come here to export a template.
Download a template before you start
Prepare your file from the template rather than from a previous file - column names and order matter.
- Go to Template Manager.
- Open the template you want.
- Click CSV or Excel in the toolbar.
Open your template and export it as CSV or Excel.
Keep the required columns and format unchanged.
The toolbar
| Button | What it opens |
|---|---|
| Preview | The file as an uploader will see it |
| CSV / Excel | Download the template |
| Settings | How the template behaves: delimiter and the OTM tables to load |
| Access | Who uses it, who signs off and who is emailed |
| Validations | Which business validations run on upload |
| Save | Saves the template - nothing in the panels is stored until you do |
Editing a panel safely
Settings and Access open as side panels made of sections. Every section is read-only until you click its Edit button, so a stray click cannot change something you did not mean to touch.
- Click Edit on the section you want. Only one section can be open at a time.
- Make your changes, then click Apply - or Cancel to put the section back exactly as it was.
- Closing the panel with a section still open discards that edit.
- Reset to defaults in the footer asks before it does anything, and resets only the panel you are in - resetting Settings never touches Access, and the other way round.
Then click Save in the toolbar.
Settings panel
How this template behaves.
| Section | What it controls |
|---|---|
| Upload | The default delimiter used to read uploaded CSV files - comma, semicolon, tab or pipe |
| Tables to Upload | The OTM tables loaded for this template type, in dependency order, and the action for each |
| Lookup tables | Value conversions this template's fields can use - see below |
The action per table:
| Action | Meaning |
|---|---|
| Create if not found | Insert only (OTM II) - fails if the record already exists |
| Create / update | Upsert (OTM IU) - creates if new, updates if found |
| Expire & process | Rate Geo only (OTM EP) - expires the matching rates already in OTM, then inserts the new one. See Publishing |
| Fail if not found | Not uploaded - the record must already exist in OTM |
Set to Expire & process, loading modifies rates already in OTM rather than only adding to them.
Lookup tables
Converts a field's value on its way to OTM. The file says HEAT, OTM wants
H; the conversion is defined once here and named on every field that needs
it.
Each row is:
| Column | Meaning |
|---|---|
| id | The name fields use to refer to this conversion, e.g. serviceLevel |
| Lookup table | A lookup table from the project's Lookup Tables screen |
| From | The column holding the value as the file writes it |
| To | The column holding the value OTM should receive |
On a field, open its settings and pick the lookup by id. One conversion can serve several fields.
When it runs. The conversion is applied when the canonical file is built, after validation. Pre-validation checks the uploader's file exactly as they wrote it, so a validation message always quotes the value the uploader can see in their own file.
Record ids carry the converted value. A field that feeds a record id - the
service level, most often - is converted before the id is built, so the id
carries what the lookup produced, not what the file said. This is how one OTM
domain gets DRY as D and another gets it as DL, from the same file shape.
Set such a lookup to fail the record on a missing value: passing the file's
own word through would put it into the id, and a record whose rate offering
does not exist in OTM is refused there.
When a value is not in the table. Each lookup decides:
- (default) the value passes through unchanged - the right behaviour when the file already speaks OTM's vocabulary for some rows;
- fail the record - the record is reported like any other bad record, with the field, the value and the lookup named, and counts towards the failure threshold.
The panel warns about a lookup that has no id or no columns chosen, two lookups sharing an id, and a field naming a lookup that is not defined - each of these would otherwise convert nothing, silently.
Built id parts
A lane whose geo type is CITY builds its token from two pieces - the city (the low value) and the district or state (the high value). The standard rule takes the first 10 characters of the city and the high value whole.
Where that is not what the ids should look like, shape the two pieces here. Turkey, for instance, wants five characters of the city and five of the district, giving ten in total rather than ten plus a whole district.
Leave both empty and the standard rule applies, which is what every template did before this setting existed.
Rate and lane ids are keys. Records already in OTM were built with the previous lengths, so an upload meant to update them will no longer match - it will load alongside them instead. Change this before a domain's first load, or plan the migration.
Transforms
Where a lookup swaps one whole value for another, a transform reshapes the one the file already has - taking the first four characters of a code, cutting a value on a dash, padding a number to a fixed width.
A transform is an ordered chain of steps, each fed what the last one produced. Chaining two or three covers most needs.
| Step | What it does |
|---|---|
| Substring | Characters from a fixed position, e.g. ODFL1234 to ODFL |
| Split and take | Cut on a delimiter and keep one part, e.g. NA-EAST-01 to EAST |
| Extract | The first capture group of a pattern |
| Trim | Remove surrounding spaces, optionally collapse inner ones |
| Change case | UPPER, lower or Title |
| Pad | Grow to a fixed width, e.g. 88 to 088 |
| Prefix / suffix | Wrap the value in fixed text |
| Replace | Swap one piece of text for another |
Positions count from 1, so "from 1, length 4" is the first four characters.
Try it in the editor: type a value you recognise and the panel shows what the chain does to it. This is the quickest way to settle an off-by-one, and faster than uploading a file to find out.
Where a transform can be set. This is the part worth getting right.
| Set it on | What it shapes |
|---|---|
| A field | That field's value, everywhere it is used |
| One segment of a built id | That segment only |
The second is usually what you want when a value appears twice. A city, for instance, belongs in the City field at full length while the rate id wants only the first five characters of it. A field-level transform cannot say that - there is one field and it needs two shapes. So open the field's ID Source → Custom builder and press shape on that segment. The column keeps its full value in its own field; only the id is shortened.
The preview shows the shaping, so {City | substring 1-5} reads differently
from {City} and a shortened id cannot be mistaken for a full one.
Two ways to set up a field-level one.
- Named - defined here in Settings, then picked on a field from its Transform dropdown. One transform can serve many fields, and changing it changes all of them.
- This field only - choose Custom... on the field and build the chain there. Save as named transform promotes it the moment a second field needs it.
A field uses one or the other, never both.
Applying it to many fields at once. Each named transform lists the template's CSV-backed fields under Applies to; tick the ones it should reshape. A field already using a different transform is marked, so you can see what you are about to replace rather than discovering it later.
Order matters, and it is fixed. A transform runs before the lookup: the value is reshaped first, then mapped. So a field can cut a carrier code out of a longer string and then convert that code to OTM's vocabulary.
Blank stays blank. A transform never turns an empty cell into a value, so a required field that is empty is still reported as empty.
Pre-validation judges the transformed value, because that is what reaches OTM - so what the screen passes is what OTM receives. The uploaded file itself is never rewritten: the grid keeps showing what you uploaded.
The list above is the whole vocabulary. There is deliberately no free-form script: a template is edited by people, not developers, and code in one would run inside the platform with its database and OTM access.
The panel warns about a transform with no name, two sharing a name, a step with missing settings, and a field naming a transform that is not defined.
Access panel
Who uses this template, who signs off, who is told. Kept apart from Settings so access and approvals are never changed by accident while editing table setup.
| Section | What it controls |
|---|---|
| Assignees | Project members who can see this template and upload against it |
| Approvals | The approvers - each mandatory or optional - and the policy: All mandatory or Any one. No approvers means files are auto-approved. See Approvals |
| Notification Emails | Extra addresses copied on this template's emails, and who gets which email |
Who gets which email
A grid with one row per email and a column each for Approvers, Uploader and This list (the extra addresses above). Tick or untick a box to change who receives that email.
- By default every box matches the routing GoRate has always used, so nothing changes until you change it. Reset to default puts it back.
- No box is locked. Approval pending used to force the approvers' copy on; a team that watches approvals from a shared mailbox can switch it off and be told there instead.
- Auto-approved has no approvers column - it is only sent when the template has no approvers.
- A row that would reach nobody shows Nobody will be told.
- Whoever needs to act is on the To line; everyone else is copied.
The full list of emails is in Emails.
Validations panel
Business Validations lists each pre-validation rule with a switch, and shows how many are enabled. Turning one off stops that check running in Data Upload for this template:
| Rule | What it checks |
|---|---|
| Length checks | Minimum, maximum or exact character count |
| Conditional required | A field is required when another has a given value |
| Auto-fix corrections | Silent normalisation, e.g. ZIP zero-padding; fixed cells turn amber |
| Master-data lookups | Carriers, locations, regions, lanes and contracts exist in the OTM snapshot |
| Real US ZIP codes | USZIP3 / USZIP5 values are real US ZIP codes |
| Unique Rate IDs | No Rate ID appears twice in the upload |
| Cross-row totals | Totals across related rows add up, e.g. allocations to 100% |
| Period-aligned validity | Effective / expiration dates line up with the time period type |
| Required value groups | At least one field in a group carries a value |
| Conditional formats | A value's shape, when a related field has a given value |
| Date ordering | Expiration falls after effective |
| Numeric bounds | Numbers stay inside their allowed range |
| Overlapping validity windows | Rows on the same lane and carrier with intersecting dates |
| Duplicate detection | Fuzzy and exact duplicates |
| Domain-specific rules | The naming and pricing conventions this template's OTM domain carries - its record id shapes, its currency rules and its route handling. Turn it off for a child domain that inherits the name but not the conventions |
See Validation for how these show up on the grid.
Lane geo types
Every template models its lane the same way: a Source Type and a Dest Type, and the one value field that type needs. The type decides which OTM lane column the value lands in, so it also decides what validation asks for.
| Type | The value it needs |
|---|---|
| COUNTRY | Country code |
| STATE/PROVINCE | Province code, plus the country |
| CITY | City, plus the province in the High Value column |
| CITY/COUNTRY | City, plus the country |
| USZIP3 / USZIP5 | US ZIP - 3 or 5 digits, checked against the real USPS list |
| CAN_POST2 / CAN_POST3 | Canadian prefix - K1 or K1A |
| POSTAL_CODE | Postal code, plus the country |
| LOCATION | An OTM location id |
| REGION | An OTM region |
| ZONE1 - ZONE4 | A zone name, at that zone level |
City names are cut to 10 characters wherever they appear in a record id, so the id and the lane it points at agree.
Zone lanes
OTM keeps four zone levels side by side on a lane, so the type names the level
and a single Source Zone / Dest Zone field carries the value - ZONE3
puts it in the third, and the other three stay empty.
Zone names are free text, unlike a ZIP or a postal prefix, so nothing checks their shape - only that a zone lane carries one and that it fits OTM's 30-character column.
A Lane ID is built from both ends, and OTM stores it in 50 characters. Two long zone names together can exceed that, so keep them to roughly 24 characters each.
What is not set on the template
The OTM adapter, the failure threshold and business hours are set once per project, on the GoRate Setting page.
One template per file shape
Templates are per rate-file shape - typically per geography or per carrier. If your file does not match any template's columns, that is a template question for your administrator, not something to fix by renaming columns in the workbook.