Skip to content
English
Customer portal
Go to Tai Software
  • There are no suggestions because the search field is empty.

MacroPoint Driver Tracking Integration

How the Tai TMS tracks loads through MacroPoint: credentials, source settings, accepted tracking frequencies, and how updates become statuses and alerts.

This staff-facing article explains how the Tai TMS uses the Descartes MacroPoint integration to track a shipment's location, which credentials and source settings it needs, the exact tracking-frequency values it accepts, and how MacroPoint order-status, schedule, and temperature updates become tracking statuses and shipment alerts.

Overview

MacroPoint (branded in the product as "MacroPoint", and referred to in tracking messages as the Descartes MacroPoint app) is a driver and shipment location-tracking provider. When a broker starts tracking on a shipment, the Tai TMS sends the shipment's stops, carrier, and reference numbers to MacroPoint and asks it to report the vehicle or driver location on a set interval. MacroPoint then posts location, schedule, event, and status updates back to Tai, which update the shipment's current location and history, the tracking record's recent status, the transit-leg status, and shipment alerts.

MacroPoint is configured as an integration source of type "MacroPoint". It is one of several driver-tracking providers the TMS supports (others include Trucker Tools, FourKites, Project 44 Load Tracking, and Open Track), but MacroPoint has its own required credentials and its own set of connection methods (cell phone, ELD, trailer GPS, and telematics).

Tracking can be started manually from the shipment (the load-track panel) or submitted automatically to the carrier through workflow automation. Both paths use the same MacroPoint integration source and the same settings; the only difference is where the frequency comes from.

How it works

To start tracking, staff open the load-track panel on a shipment, pick the MacroPoint integration source, confirm the driver cell phone / truck / trailer numbers, choose a tracking frequency, and start tracking. Behind the scenes Tai builds an order containing the first pickup, any middle stops, and the last delivery (with scheduled ready/close times), the linehaul carrier, the shipment's reference numbers, a track start time, and a tracking interval, and sends it to MacroPoint. MacroPoint reports back on that interval until tracking ends.

Connection methods and "Track by ELD". If the integration source has the setting PartnerStatus set to true, the panel asks MacroPoint which connection methods are available for the shipment's linehaul carrier. The possible methods are Tms, ELD, LTL, Telematics, TrailerGPS, and CellPhone. The panel then decides how the load can be tracked:

  • If ELD or Telematics is available, the shipment can be tracked by the truck / vehicle number.
  • If TrailerGPS or Telematics is available, it can be tracked by the trailer number.
  • Otherwise it falls back to the driver cell phone number (MacroPoint texts the driver / uses the mobile app).

Without PartnerStatus = true the lookup is skipped and the panel offers only the driver's cell phone. "Track by ELD" therefore means letting MacroPoint pull location from the carrier's electronic logging device / telematics feed using the truck or trailer number, instead of texting the driver's phone. Which options are offered depends entirely on what MacroPoint reports as available for that carrier.

What goes into the order.

  • Stops. The first pickup and last delivery are always sent. Middle stops are sent as "Pickup" for first-pickup and pickup stops and as "DropOff" for every other type (drop, both) when the middle-stop feature below is on; when it is off, every middle stop goes as "Pickup".
  • Geofence. The GeofenceInMiles source setting sets the arrival radius, in miles, for each stop. A blank or zero value is not sent, and MacroPoint then applies its own company default. The first and last stops always carry the radius; middle stops carry it only when the middle-stop feature is on.
  • Reference numbers. The driver cell phone number, truck number, and trailer number are sent to MacroPoint as the mobile, vehicle, and trailer identifiers. For automatic submission to the carrier, a driver cell phone number must be present on the shipment or the auto-submission is skipped and logged ("Automatic Driver Track submission to ... failed because no driver cell phone was found on the shipment!").
  • Temperature (cold chain). There is no separate cold-chain switch. Whenever the shipment has a Desired Temperature reference number, Tai sends it together with the Maximum and Minimum Temperature reference numbers if present. The unit comes from the UnitOfTemperature source setting and defaults to Fahrenheit.
  • Optional extras from source settings. Copies of updates can be emailed to the customer contact (EmailCopiesOfUpdatesTo), the customer / bill-to name can be included (SendCustomerName), and the shipper reference number and customer PO number can be passed through as custom fields (ShipperReferenceNumber, CustomerPONumber). A second MacroPoint ID (PartnerMPID) adds a second notification with the same interval and duration.
  • Delivery notes. "Require Delivery Signature" and "Require POD Image" notes are added to the last stop (see RequireSignature and RequirePODImage).
  • Track start and duration. The start time is the first pickup's appointment time (or its scheduled ready time when there is no appointment), shifted by StartTrackHoursOffset, shown in Eastern time and moved forward to the next quarter hour (a time already on a quarter hour moves forward a full 15 minutes). Tracking is requested for the hours remaining until the delivery stop's ready time plus 72 hours.

What updates on the shipment.

  • Location updates change the shipment's current in-transit location (a readable location string plus latitude/longitude history) and the tracking record's recent status, recent event, and last-updated time. Repeated pings are de-duplicated within a 4-minute window so near-identical points are not written twice.
  • Event updates record actual times on the stop and move the transit leg. Arrived-at-pickup sets the stop's actual arrival and adds the "On Hand Origin" alert; departed-pickup sets the actual departure, removes that alert, and moves the active transit leg to In Transit. Arrived-at-delivery sets the actual arrival and adds "On Hand Destination"; departed-delivery sets the actual departure, removes that alert, and moves the active transit leg to Delivered. An actual time that is already filled in is not overwritten.
  • Order-status updates set the tracking status and recent status text and can raise a shipment alert (mapping table below). Routine messages — "Tracking Now", "Requesting App Install", and event updates — are not written to the shipment activity log; other order-status messages are logged as a private "MacroPoint Message".
  • Schedule updates and temperature updates can raise shipment alerts (rules below).
  • Changing the shipment. When a shipment with active MacroPoint tracking is updated, Tai queues a change order that resends the stops, times, and reference numbers using the tracking's stored frequency, and logs either "MacroPoint change order call was successful." or "MacroPoint change order: an error occurred while trying to change the order."
  • Staff can also send a comment to the driver and cancel tracking from the panel. Errors MacroPoint returns appear as "code: [Severity: level] message".

Business rules & limits

  • Required credentials. The MacroPoint integration source needs a Username and Password (issued by MacroPoint, sent as basic authentication) plus a source setting named MacroPointId. If MacroPointId is missing or blank, tracking fails with: MacroPoint Integration requires a valid source setting for "MacroPointId" (the setting name appears in quotes, and there is no trailing period). The same message appears if no tracking frequency was supplied.
  • Bad credentials. When MacroPoint answers with an empty "unauthorized" response, the user sees "Unauthorized to initiate load track with MacroPoint." Fix the username and password on the integration source. The shared driver-tracking flow also has the message "You credentials are not correct, please fix this in the integrationsource!"; each time it occurs it adds to the source's authentication-failure count, and once the count goes above 5 (or above the value of an allowedFailureCount source setting, if one is entered) the source is put into an authentication-error state. Saving the integration source resets the count and clears that state.
  • One tracking per shipment. Only one active tracking can exist per shipment. Starting a second one fails with "Tracking already exists for Shipment ID {id}."

  • Tracking-frequency values (the headline). The frequency is the interval, in minutes, at which MacroPoint reports location. The available options are:

    • 10 Minutes — Setting name to enter: TenMinutes; Minutes value: 10
    • 20 Minutes — Setting name to enter: TwentyMinutes; Minutes value: 20
    • 30 Minutes — Setting name to enter: ThirtyMinutes; Minutes value: 30
    • 45 Minutes — Setting name to enter: FourtyFiveMinutes; Minutes value: 45
    • 1 Hour — Setting name to enter: OneHour; Minutes value: 60
    • 2 Hours — Setting name to enter: TwoHours; Minutes value: 120
    • 4 Hours — Setting name to enter: FourHours; Minutes value: 240
    • 6 Hours — Setting name to enter: SixHours; Minutes value: 360
    • 8 Hours — Setting name to enter: EightHours; Minutes value: 480
    • 12 Hours — Setting name to enter: TwevleHours; Minutes value: 720

    When set as a source setting named DriverTrackFrequency (used for automatic carrier submission), the value can be entered either as the setting name (for example FourHours, typed exactly as shown, including capital letters) or as the minutes number (for example 240) — both are accepted. Two of the names are spelled unusually in the system: the 45-minute option is FourtyFiveMinutes and the 12-hour option is TwevleHours (the "v" and "e" are transposed). Entering TwelveHours or FortyFiveMinutes will not be recognized; use the exact spellings above or the numbers. Use only the ten values listed.

  • Frequency defaults. For automatic carrier submission, if the DriverTrackFrequency setting is missing, blank, or its text does not match a name above, it defaults to 4 Hours (240). The manual panel pre-selects 1 Hour. A MacroPoint order cannot be created without a frequency.

  • Source settings reference. Setting names are matched without regard to case except where noted. True/false values are entered as true or false.

    • MacroPointId — Value: text; What it does: The MacroPoint ID the order is placed under (required); If absent: Tracking will not start
    • PartnerMPID (type exactly) — Value: text; What it does: Second MacroPoint ID; adds a second notification with the same interval, duration, and custom fields; If absent: None
    • PartnerStatus — Value: true/false; What it does: Lets the panel ask MacroPoint for ELD / telematics / trailer GPS availability; If absent: Off; only cell phone is offered
    • DriverTrackFrequency — Value: name or minutes; What it does: Interval for automatic carrier submission; If absent: 4 Hours (240)
    • RequirePODImage — Value: true/false; What it does: Adds a "Require POD Image" note to the delivery stop; If absent: true
    • RequireSignature — Value: true/false; What it does: Adds a "Require Delivery Signature" note to the delivery stop; If absent: true
    • GeofenceInMiles — Value: whole number; What it does: Geofence radius in miles for stops; If absent: Not sent; MacroPoint default applies
    • StartTrackHoursOffset — Value: whole number, -24 to 24; What it does: Hours added to the track start time; If absent: 0
    • StopSequencingRequired (type exactly) — Value: true/false; What it does: Whether stops must be visited in order; only an explicit false turns it off; If absent: Stops must be in order
    • EmailCopiesOfUpdatesTo — Value: true/false; What it does: Copies updates to the customer contact's email on the shipment; If absent: false
    • SendCustomerName — Value: true/false; What it does: Sends the bill-to customer name; If absent: false
    • UnitOfTemperature — Value: text, for example Fahrenheit; What it does: Temperature unit for cold-chain tracking; If absent: Fahrenheit
    • ShipperReferenceNumber — Value: true/false; What it does: Passes the shipper reference number as a custom field; If absent: false
    • CustomerPONumber — Value: true/false; What it does: Passes the PO number as a custom field; If absent: false
    • ignorestatusupdates — Value: true/false; What it does: When true, order-status updates are ignored and event updates no longer change the tracking record or transit-leg status; location and schedule updates still apply; If absent: false
    • allowedFailureCount — Value: whole number; What it does: Authentication failures tolerated before the source goes into an authentication-error state; If absent: 5

  • StartTrackHoursOffset must be between -24 and 24 hours; values outside that range are rejected when the integration source is saved ("StartTrackHoursOffset must be between 24 and -24 hours!", or "StartTrackHoursOffset is invalid!" for non-numbers), and out-of-range or non-numeric values are ignored when building the request.

  • Track duration. Tracking is requested for the number of whole hours from now until the delivery stop's appointment (or scheduled) ready time, plus 72 hours. With no delivery time it is 72 hours, and if the total comes out at zero or less it is set to 72 hours. A delivery time that is already a day or two in the past therefore gives a window shorter than 72 hours.

  • Order-status mapping. Each MacroPoint order-status code sets the tracking status and, for some codes, a shipment alert. The recent status text reads " - ". Any message reading "Tracking completed successfully" also sets Completed.

    • Tracking completed successfully (1022) — Tracking status: Completed; Shipment alert: None
    • Stopped by creator (1050); expired with location hidden by driver (1067); expired with driver phone unresponsive (1069); expired without installation (1070); expired without location (1071) — Tracking status: Canceled; Shipment alert: None
    • Possible fraud detected (1076) — Tracking status: Stays Active; Shipment alert: Possible Fraud Detected
    • Incompatible phone (1061); invalid truck number (1065); invalid trailer number (1066); invalid bill of lading (1072); invalid PRO number (1073); invalid air waybill (1074); carrier not supported (1075); invalid container ID (1077) — Tracking status: Stays Active; Shipment alert: Load Track Exception
    • Everything else, including requesting app install (1002), ready to track (1020), tracking now (1021), location hidden by driver (1053), waiting for update (1060), driver phone unresponsive (1068), retired codes, and unknown codes — Tracking status: Stays Active; Shipment alert: None

  • Schedule rules. A schedule update is acted on only when it fits the shipment's progress: a pickup update while the shipment has not yet reached In Transit (checked against the first pickup), or a drop-off update once it is In Transit or later (checked against the last drop). Acting on it writes a private "MacroPoint Schedule Update" activity note (alert text, miles to stop, ETA) and updates remaining miles. A Shipment Delayed alert is added (once) when the alert text says more than 3 hours BEHIND (the first number in the text must be greater than 3). With the callback-alert-codes feature on, the alert is also added when MacroPoint's schedule code is 3 (cannot make it) or 4 (past appointment time).

  • Temperature rules. Location updates can carry a temperature code. With the callback-alert-codes feature on, code 1 adds or updates the In Temperature Threshold alert, 2 the Above Temperature Threshold alert, and 3 the Below Temperature Threshold alert, and in each case resolves the other two; code 0 (cannot determine) changes nothing. With the feature off, Tai matches the text "in temp threshold", "above temp threshold", or "below temp threshold" instead.

  • Feature switches. Four application feature flags control the newer MacroPoint behavior. When a flag is off, the legacy behavior described in the matching row applies.

    • TMS-24125 - MacroPoint order request middle stop type and geofence — Controls: Middle stops sent as Pickup or DropOff with the geofence radius; off sends every middle stop as Pickup with no radius
    • TMS-24121 - MacroPoint callback temperature and at-risk alert codes — Controls: Numeric temperature codes and the Cannot Make It / Past Appointment Time schedule alerts; off uses the text matching
    • TMS-24124 - MacroPoint fraud code 1076 shipment alert — Controls: The Possible Fraud Detected alert; off raises no alert
    • TMS-24133 - MacroPoint order status not tracking shipment alert — Controls: The Load Track Exception alert for the invalid-input and unsupported codes; off raises no alert

Frequently asked questions

What tracking-frequency values does MacroPoint accept, and are both the label and the number valid?

The valid intervals are 10, 20, 30, and 45 minutes and 1, 2, 4, 6, 8, and 12 hours. In the load-track panel staff pick a label from the dropdown ("4 Hours", etc.). When configuring the frequency as a source setting (DriverTrackFrequency) for automatic submission, you may enter either the setting name (for example FourHours) or the equivalent minutes number (for example 240) — both work. The number represents the reporting interval in minutes.

I set the frequency to "TwelveHours" (or "FortyFiveMinutes") and it didn't take. Why?

Those spellings do not match the system. The 12-hour value is spelled TwevleHours (transposed letters) and the 45-minute value is spelled FourtyFiveMinutes. Use those exact spellings, or just enter the minutes number instead (720 for 12 hours, 45 for 45 minutes). Until it is fixed, automatic submission falls back to 4 Hours.

Tracking won't start and says it requires a valid source setting for "MacroPointId." What's wrong?

The MacroPoint integration source is missing the MacroPointId setting (or it is blank). MacroPointId is required in addition to the username and password. Add the MacroPointId value MacroPoint assigned to the account and retry.

What credentials does the MacroPoint integration need?

A Username and Password on the integration source, plus the MacroPointId source setting. Optional source settings include PartnerMPID, PartnerStatus, GeofenceInMiles, EmailCopiesOfUpdatesTo, SendCustomerName, UnitOfTemperature, StartTrackHoursOffset, StopSequencingRequired, ShipperReferenceNumber, CustomerPONumber, RequirePODImage, RequireSignature, and DriverTrackFrequency.

How do I track by ELD instead of the driver's phone?

You cannot force it; it depends on the carrier. The integration source must have PartnerStatus = true. When you open the panel, Tai then asks MacroPoint which methods are available for the shipment's carrier. If the carrier's ELD or telematics is available, the panel lets you track by the truck/vehicle number (and by trailer number if trailer GPS or telematics is available). If none of those are available, or PartnerStatus is not on, tracking falls back to the driver's cell phone number.

Which credential error messages might I see, and what do they mean?

"Unauthorized to initiate load track with MacroPoint." means MacroPoint rejected the request; correct the username and password on the MacroPoint integration source. "You credentials are not correct, please fix this in the integrationsource!" comes from the shared driver-tracking flow and counts toward the source's authentication failures; after more than 5 failures (or the allowedFailureCount value) the source goes into an authentication-error state until the source is saved again.

Why can I only have one tracking on a shipment?

The TMS allows a single active tracking record per shipment. If one already exists you'll see "Tracking already exists for Shipment ID {id}." Cancel the existing tracking before starting a new one.

How long will MacroPoint keep tracking a load?

The request asks MacroPoint to track for the hours remaining until the delivery stop's ready time plus 72 hours. With no delivery time it is 72 hours. If the delivery time is more than 72 hours in the past the window is set to 72 hours, but a delivery time only a day or two in the past gives a window shorter than 72 hours.

A location update didn't create a new point — is that a bug?

Not necessarily. Location updates are de-duplicated within a 4-minute window, so a near-identical ping arriving right after another is intentionally not written as a separate point.

Why does a shipment show a "Possible Fraud Detected" alert from MacroPoint?

MacroPoint sent order-status code 1076, meaning the tracking data may be fraudulent and the broker should confirm the shipment's status with the carrier directly. The alert is added once per shipment and the tracking status stays Active because tracking is still running. The alert is raised only when the fraud-alert feature flag is on.

A load shows as actively tracking but has a "Load Track Exception" alert. Why?

MacroPoint refused to track the load, for example because the phone cannot run the app, the truck, trailer, bill of lading, PRO, air waybill, or container number is invalid, or the carrier is not supported. The tracking status stays Active, so the alert is the signal that it will never produce data. Fix the identifier or choose another tracking method. The alert is raised only when the not-tracking alert feature flag is on.

When does MacroPoint raise a "Shipment Delayed" alert?

When a schedule update for the current stop says the carrier is more than 3 hours BEHIND. With the callback-alert-codes feature on, it is also raised when MacroPoint reports the carrier cannot make the appointment or is past the appointment time. A pickup update counts only before the shipment is In Transit and a drop-off update only once it is In Transit or later.

Why did my geofence radius not apply, or apply only to some stops?

The radius comes from the GeofenceInMiles source setting. A blank or zero value is not sent, so MacroPoint uses its own default. The first and last stops always carry the radius, but middle stops carry it (and are typed as pickup or drop-off) only when the middle-stop feature flag is on.

If I edit a shipment after tracking starts, does MacroPoint find out?

Yes. While the tracking is active, a shipment update queues a change order that resends the stops, times, and reference numbers, and the shipment activity log records whether MacroPoint accepted it.

Which MacroPoint settings must be typed exactly?

PartnerMPID and StopSequencingRequired must be typed exactly as shown. A DriverTrackFrequency name must also be typed exactly (or use the minutes number). Other setting names are matched without regard to case.