Validation Rules

What this does

Validation Rules make a Reference Number required on a stop when an actual arrival or departure time meets a condition you define, such as arriving outside the appointment window. Until the user fills it in, Edit Stop and Check Call won't save.

Capture late and early reasons at the source. The reason is recorded when dispatch enters the time, not after your shipper's EDI rejects the update.
Send the exact code your trading partner expects. Users pick from your approved list, and the code's Value goes out with your shipment status updates.
Go beyond late reasons. Any Back Office Reference Number can be required: a detention approval, a reschedule reference, or any code a shipper asks for.
Target the right freight. Scope each rule to an organization and to specific shipment types.

User Guide

Before you start: what you need first

The TMS Site Admin role. Only users with this role can see and use the Validation Rules page.
The Reference Number the rule will require. A rule can only require a Reference Number that already exists. Set it up first on the Shipment Reference Numbers page (see the next section).
Stop times to compare against. Rules compare the actual time with the stop's Scheduled or Appointment Ready and Close times. If a stop has none of the times your rule uses, the rule can't fire on that stop.

How a validation rule works

Every rule has three parts, shown as a card on the Validation Rules page:

Trigger: "When a Stop is added or changed." Rules are checked whenever a user enters or changes a stop's times.
Condition: one or more rows of Field, Operator, and Target. When there are several rows, choose And (all conditions must be true) or Or (any condition must be true).
Action: "Require [Reference Number] before save."

Condition options:

Field: Actual Arrival Time or Actual Departure Time.
is within / is outside compare against a window: the Scheduled Ready / Close window or the Appointment Ready / Close window.
is at or after / is at or before compare against one time: Scheduled Ready, Scheduled Close, Appointment Ready, or Appointment Close.
On the edge counts as inside. A time exactly on Ready or Close is inside the window, so "is outside" doesn't fire. If one side of the window is blank, only the other side is checked.

Each rule also has a scope:

Organization: your organization, or a customer organization under it. A rule applies to shipments for that organization and the organizations beneath it.
Shipment Types: All, or one or more of Small Package, LTL, Truckload, Domestic Freight, Cartage, and Drayage.

How to set up a Reference Number for reason codes

Where to go: Back Office → LSP → Shipment Reference Numbers → Add. For every setting on this page, see Custom Shipment Reference Numbers. For a reason code, these settings matter most:

Display Name: what users see on the stop, for example Late Reason.
Data Type: String.
Reference Type → Stop: choose Optional if users may also add it by hand, or Off if it should only appear when a rule asks for it. Don't choose Required for a reason code: Required makes the Reference Number mandatory on every stop, every time, whether or not a rule fires. With Optional or Off, the rule makes it required when the condition is met.
Free-Form Allowed: set to No so users can only pick from your list.
Predefined Values: enter each code. Value is the code saved on the stop and sent to your integrations. Display Text (Optional) is the friendly label users see in the dropdown; it isn't sent.
Default: leave this unchecked for reason codes. When a rule makes the Reference Number required, a Default fills the field automatically, so users can save without choosing a reason.

Example Late Reason values, using X12 AT7 shipment status reason codes. Always confirm the codes in your trading partner's 214 guide.

AO: Weather or Natural Disaster Related
AF: Accident
AI: Mechanical Breakdown
AH: Driver Related
AJ: Other Carrier Related
AL: Previous Stop
AM: Shipper Related
AG: Consignee Related
B1: Consignee Closed

How to create a validation rule

Where to go: Back Office → LSP → Validation Rules.

Pick the scope. Type to search for the Organization, then click All or one or more Shipment Type chips.
Click Add Rule. A new card opens with Trigger, Condition, and Action.
Turn the rule on with the Active toggle.
Add conditions. Choose a Field, Operator, and Target for each row. Click Add condition for more rows, and choose And or Or between them.
Choose the Action. Pick the Reference Number to require.
Name the rule (optional). Click the pencil next to the card's title. Otherwise the name is built for you, for example "Stop Rule | Requires Reference Number - Late Reason."
Click Save.

Add more rules for the same organization and shipment types with Add Rule. Use the copy icon to start from an existing card, and the trash icon to delete one.
Turn a rule off any time with its Active toggle, without deleting it.
A card missing a Field, Operator, Target, or Reference Number shows an Incomplete tag, and the rule won't save until you finish it.

Example: require a late reason on arrivals and departures

Where to go: Back Office → LSP → Validation Rules → Add Rule.

Condition 1: Actual Arrival Time · is outside · the Appointment Ready / Close window.
Condition 2: Actual Departure Time · is outside · the Appointment Ready / Close window.
Junction: Or. Either a late or early arrival, or a late or early departure, requires a reason.
Action: Require Late Reason before save.
Name: Late Arrival or Departure Reason.

To catch only arrivals, use Condition 1 alone.

More ways to use Validation Rules

Late departures only: Actual Departure Time · is at or after · the Appointment Close time → require a detention or delay reference.
Early arrivals only: Actual Arrival Time · is at or before · the Scheduled Ready time → require an early-arrival code.
One shipper, one freight type: scope a rule to a single customer organization and Truckload only, so other customers aren't prompted.

What users see in Edit Stop and Check Call

Where it happens: the Edit Stop modal on the Shipment Detail page, and the Check Call form.

When an actual time meets a rule's conditions, the required Reference Number appears as an extra field. With Predefined Values, it's a dropdown of your codes.
The field shows "Reference number Late Reason is required." An info icon next to it names the rule that asked for it.
Save stays disabled until a value is picked. On Check Call, Update and the status buttons stay disabled too.
If the user corrects the time so it no longer meets the condition, the requirement goes away.
The value is saved on the stop's Reference Numbers.

How the reason code reaches your trading partner

Stop Reference Numbers, including the code a rule required, are part of the shipment data sent by your Shipment Status Update webhook.
Your EDI mapping picks up the code's Value and sends it to your trading partner, for example on 214 status updates.
If your partner receives the wrong code, check the Value on the Reference Number's Predefined Values. Display Text is never sent.

Which rules apply to a shipment

Rules on your organization and on the customer organizations under it all apply together.
If two rules require the same Reference Number, the user fills it in once and both are satisfied. The dropdown uses the codes set up closest to the customer.
A rule only fires when the shipment's type matches the rule's Shipment Types.

What's not included

Rules prompt users only in the Back Office Edit Stop modal and Check Call form. Times that arrive through the API, carrier tracking integrations, or Front Office aren't checked.
Rules check stop times only: Actual Arrival Time and Actual Departure Time.
Rules don't add reasons to stops that were completed before the rule existed.

Tips & best practices

We recommend leaving Default unchecked on any Reference Number a rule requires, so users make a deliberate choice.
Name rules for what they catch, such as "Late Arrival Reason," so the info icon tells users exactly why they're being asked.
Use is outside to catch both early and late times with one condition.
Put a rule on a single customer organization when only one shipper needs the code.

Frequently asked questions

Can a validation rule require a standard reference number like PO Number?

Yes. A rule can require any Reference Number shown in the Back Office, standard or custom.

Does a validation rule fire for early arrivals too?

Yes, if you use "is outside." It fires when the time is before Ready or after Close. Use "is at or after" to catch only late times.

Why did the reason fill itself in?

The Reference Number has a Default value. Uncheck Default on the Shipment Reference Numbers page so users have to choose.

Why wasn't I prompted when the time came in from tracking?

Validation Rules only prompt in Edit Stop and Check Call in the Back Office. Times from tracking integrations, the API, or Front Office aren't checked.

Who can create or change a validation rule?

Users with the Site Admin role. The Validation Rules page doesn't appear for anyone else.

The rule asks for a Reference Number that's turned Off for stops. Is that right?

Yes. Off only stops users from adding it by hand. When a rule's condition is met, the Reference Number still appears and is required.

If something doesn't work

The required field never appears:
- Check that the actual time has a date and time.
- Check that the stop has the Scheduled or Appointment times your rule compares against.
- Check the rule's Organization, its Shipment Types, and that it's Active.
- New or changed rules can take a few minutes to reach a shipment that's already open. Close and reopen it.
Users can save without picking a reason: the Reference Number has a Default. Uncheck it.
I can't save the rule:
- Every condition needs a Field, Operator, and Target, and every rule needs a Reference Number.
- "is within" and "is outside" only work with a window. "is at or after" and "is at or before" only work with a single time.
- Two identical rules show "Duplicate rule — identical to another rule in this list."
Users can type a reason instead of picking one: set Free-Form Allowed to No on the Reference Number.
My trading partner gets the wrong code: check the Value (not the Display Text) on the Predefined Values, then check your EDI mapping.
I don't see Validation Rules under LSP: you need the Site Admin role.
Still stuck? Contact Tai Support with the shipment number and the rule's name.

To learn more, see Custom Shipment Reference Numbers and Shipment Status.