Catena ELD Aggregator (formerly Axle)

Monitor and manage Fleet operations with the Revenova integration with Catena, an aggregator of Telematics Service Providers (TSP). Catena connects the TMS with over 80 TSPs to provide real-time driver and vehicle information.

Catena provides information from several Telematics Service Providers (TSP). The Revenova TMS refers to a specific TSP as the Electronic Logging Device (ELD) Brand or Provider.

• The terms TSP, ELD Provider, and ELD Brand are used interchangeably.

• ELD Providers often include access to an environment to view Fleet Assets, Drivers, and control other configuration settings. Each ELD Provider manages and provides the login information for these environments. See Driver and Fleet Asset syncing information below to control how and when records are updated.

Fleet Asset and Driver records exist in both the TMS and and the corresponding ELD Provider. Each time the Fleet Management Job 2 runs, records are kept in sync to ensure any record changes are consistent from both Catena and the TMS. In most cases, any record changes originate from the ELD Provider and propagate through Catena to the TMS. A small subset of fields may be created or updated in the TMS and sent back to Catena to populate the corresponding ELD Provider. For specific field information, see the Fleet, Driver, and Vehicle sections below.

Setup

Each Telematics Service Provider (ELD Provider) has record requirements and restrictions. Use caution with Fleet Asset Name or License Plate Number fields that may be sent to Catena to update records. For example, some services limit Name fields to a specific number of characters. TMS Fleet Asset record Name and License Plate Number fields may allow for more characters.

Add Named Credentials

Enter the Revenova-provided Named Credentials for the Catena integration.

1. From Setup, search for Named Credentials.

2. Choose the Named Credentials link.

3. Select the External Credentials tab.

4. From the list, click the Catena External Credential.

   1. In the Principals section, find the Admin row.

   2. From the Actions column on the far right, click the arrow and choose Edit.

   3. In the modal, enter the customer production Username and Password credentials.

   4. Click Save.

5. From the list, click the Catena_Test External Credential.

   1. In the Principals section, find the Admin row.

   2. From the Actions column on the far right, click the arrow and choose Edit.

   3. In the modal, enter the customer test Username and Password credentials.

   4. Click Save.

6. Add support for the appropriate Profiles and/or Permission Sets as necessary.

   1. For Profiles, navigate to Setup → Profiles.

      1. Select the appropriate Profile(s).

      2. Find the Enabled External Credential Principal Access section.

      3. Click Edit.

         1. Add Catena - Admin to the Enabled External Credential Principals section in production orgs.

            1. Add Catena_Test - Admin to the Enabled External Credential Principals section in sandbox orgs.

         2. Click Save.

   2. For Permission sets, navigate to Setup → Permission Sets.

      1. Select the appropriate Permission Set(s).

      2. Choose the External Credential Principal Access link.

      3. Click Edit.

         1. Add Catena - Admin to the Enabled External Credential Principal Access section in production orgs.

            1. Add Catena_Test - Admin to the Enabled External Credential Principal Access section in sandbox orgs.

         2. Click Save.

Credentials Card

Enable the Catena integration by completing the following steps.

1. Navigate to TMS Admin.

2. Select Credentials.

3. Select the Global Services tab.

4. Find Catena in the list and select the card. (Catena, formerly Axle)

5. Check the Enabled box.

6. The User ID and Password 1 are provided and entered by a Revenova representative into the text fields.

   1. The Customer Number is automatically set to the Fleet Id field provided by Catena.

7. Click the Save button.

Remote Site Settings

Upgrading from previous versions of the TMS may have outdated information.

1. Click the Setup gear icon in the top right corner.

2. From the drop-down, click Setup.

3. In the Quick Find Toolbar type Remote Site Settings and click the link.

4. From the list of remote sites find Axle and click the Edit link.

5. Update the Remote Site URLs to match the Service URLs below.

Service URL: https://api.axleapi.com/v1

Link ELD Providers

Do not test the Catena integration in production orgs. Only test the integration in a sandbox to avoid creating records for test Drivers and Fleet Assets in the production org. When testing, ensure that the Catena Test Mode box is Checked on the Credentials card. To configure a production org, Uncheck the Test Mode box before running Fleet Management Job 2.

Check the Test Mode field on the Catena credentials card while linking ELD Providers. Test the integration once a ELD Provider is linked in the sandbox before performing the steps below in production.

1. Select the Catena credentials card to view the card.

2. Check the Test Mode field and click Save.

3. Select the Catena credentials card again to view the card.

4. Click the Link ELD Account button.

5. Click Continue and follow the prompts to find the appropriate ELD Provider.

6. Enter the ELD Provider account credentials and select Connect Telematics.

   Some ELD Providers may prompt an issue that the Revenova TMS is not recognized or “supported.” Continue linking process as this issue may be skipped.

7. Repeat steps 3 through 5 to link additional fleets as necessary.

8. The Link Status field is automatically set to Checked the first time Fleet Management Job 2 runs.

Production and testing environment credentials are provided by each ELD Provider. Contact the ELD Provider to acquire these credentials.

Other Setup Information

Navigate to TMS Admin → Configuration, Fleet Management.

• Check the Fleet Management 2 Enabled box. Fleet Management Enabled must NOT be Checked.

  • Fleet Management 2 job and Samsara cannot be enabled at the same time.

• Review the Driver Log Grace Period (Days) value. The default value is 2 days. Enter another value if necessary.

• Enter an email address in the Fleet Management Email box.

• Search Accounts and select a Fleet Management Default Carrier. A Default Carrier is not required, but recommended.

• Select a Default ELD Provider from the picklist.

  • Save the information when complete.

• Enable Feed Tracking for the Driver object. This enables the Chatter feature and allows for Driver messaging across the Fleet Management Module.

  • From Setup → Feed Tracking, select the Driver object.

  • Check Enable Feed Tracking.

  • Click Save.

• Set the Sync Active Drivers Only field, as necessary.

  • When Checked, only Drivers set as Active in the ELD Provider and TMS are sent to create or update records in the ELD Provider or TMS.

  • When Unchecked, all Drivers in the ELD Provider are created or updated in the TMS.

• Set the Sync Active Fleet Assets Only field, as necessary.

  • When Checked, only Fleet Assets set as Active in the ELD Provider are created or updated in the TMS.

  • When Unchecked, all Fleet Assets in the ELD Provider are created or updated in the TMS.

The Revenova TMS is packaged with a Driver Lightning Record Page designed for use with the Catena integration. Assign the Driver Lightning Page Layout by completing the following steps.

1. Navigate to Setup → Object Manager.

2. Choose the Driver object.

3. Select the Lightning Record Pages link.

4. Choose the Driver - Revenova Default (Catena) page.

5. Click the Edit button.

6. Choose the Activation… button.

7. Click the Assign as Org Default button.

8. Select Desktop and phone.

9. Choose Next.

10. From the Review assignment modal, click Save.

Driver Records

• Driver records may be loaded into the TMS manually, the Salesforce Data Loader, or from the ELD Provider. After records are created, the Revenova TMS is the “system of record” or “source of truth” for Driver records.

  • Any later changes to existing Driver record fields are sent to Catena to update records in the ELD Provider.

  • The only Driver fields that may update from changes made in the ELD Provider and sent to the TMS are the ELD ID and ELD Brand fields.

• When Driver records are created from the ELD Provider, Driver record fields are populated with the response from the Get Drivers end point.

• Changes made to Driver records in the TMS are sent to the ELD Provider in the Update Driver call.

Note the following Driver fields that control how records are created or synced between Catena and the TMS.

• ELD Enabled

  • When Checked, Drivers that do not exist in the ELD Provider are sent from the TMS to create those records in the ELD Provider.

• ELD Exempt

  • When Checked, Hours of Service features and violations do not sync between Catena and the TMS.

Fleet Asset Records

• Fleet Asset records are loaded into the TMS from the ELD Provider. After records are created, the ELD Provider is the “system of record” or “source of truth” for Fleet Asset records.

  • Any later changes to existing Fleet Asset record fields are received from Catena to update records in the TMS.

  • The only Fleet Asset fields that may update from changes made in the TMS and sent to the ELD Provider are the Name and License Plate Number fields. These fields are sent to Catena with the Update Vehicle call.

To begin syncing ELD information from Catena, run Fleet Management Job 2.

• Setting a Driver or Fleet Asset from Active to Inactive (or vice versa) in the TMS does not set the equivalent value in the ELD Provider. Likewise, changing a Driver or Fleet Asset from Active to Inactive (or vice versa) in the ELD Provider environment does not update the equivalent value in the TMS.

• Deactivate a Driver or Fleet Asset by deactivating the Driver or Fleet Asset records in both the TMS and the ELD Provider.

  • In the TMS, set the Driver Driver Activation Status field to Deactivated.

  • In the TMS, set the Fleet Asset Status field to Out of Service.

  • Set the corresponding statuses to Inactive in the ELD Provider.

Catena API Endpoints

Authentication

The Catena authentication endpoints verify the credentials of TMS users and pair TMS Fleet Account records to a Catena account.

Get Authentication token

Calling any of the Catena API endpoints requires an authentication token. A new authentication token is requested or refreshed before any other calls to Catena endpoints. Each time the Fleet Management 2 job runs, the Get Authentication token endpoint is called to request or refresh the authentication token.

Authentication tokens expire every 12 hours.

Sample Get Token Request Payload

{
  "email": "demo_test@axleapi.com",
  "password": "test"
}

Sample Get Token Response Payload

{
    "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2FwaS5gHQ_yVrtYnkmA",
    "expires_in": 43200,
    "refresh_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVC3MiOiJodHRwczovcmVmcmVBIeLfMTIU4rOQuZj3ZblNw",
    "refresh_token_expires_in": 2592000,
    "email": "demo_test@axleapi.com",
    "service_id": 981,
    "token_type": "Bearer"
}

No TMS Field Updates

Link Fleets

The Link Fleet endpoint is called to pair a TMS Account record to an Catena Fleet Code. The Link Fleet endpoint may be called more than once to add additional Fleets (TMS Account records) to a single Catena account.

Multiple Linked Fleets are required when requesting information from multiple ELD Providers or when managing multiple Companies/Divisions.

Complete the steps for linking ELD Providers here.

TMS fields sent in the Link Fleet Request

Sample Link Fleet Response

{
  "token": "exampleLinkTokenABC123",
  "expires_in_seconds": 3600,
  "url": "https://auth.axleapi.com?token=exampleLinkTokenABC123"
}

No TMS Field Updates

Fleet

The Catena Fleet endpoints send Fleet information into the TMS from the ELD Providers. Fleet information, Fleet Assets, Drivers, and Vehicle locations are sent to the TMS with this collection of calls.

Get Fleets IDs

The Get Fleet IDs call returns all of the Fleet ID(s) associated with a Catena account and stores them until the end of the current run of Fleet Management Job 2. Fleet IDs are required for calls to other Catena API endpoints.

No TMS Fields are sent in the Get all Fleets call.

The Token returned from Get Authentication Token is sent in the Get All Fleets call.

Sample Get all fleets Response Payload

{
    "fleet_ids": [
        20696,
        8847
    ]
}

No TMS Field Updates

Get Fleet Data

The Get Fleet Data call returns the Catena tsp_id, name, and fleet_code for updating Driver and Fleet Asset records. This endpoint is called for each TMS Account record paired to an Catena account.

Sample Get Fleet Data Response

{
  "id": 2354,
  "time": "2020-01-27T07:06:25.000Z",
  "fleet_code": "dafhjk13cxiLE48",
  "tsp_source": "motive",
  "invalid_credentials": false,
  "tsp_details": [
    {
      "axle_tsp_id": 25,
      "name": "motive",
      "invalid_credentials": false
    },
  ],
  "carrier": {
    "carrier_name": "Acme Inc.",
    "dot_number": 87654321,
    "home_terminal_address": "1234 Pear St., Scranton, PA 62814",
    "home_terminal_name": "Acme Inc.",
    "main_office_address": "1234 Pear St., Scranton, PA 62814"
  }
}

No TMS Field Updates

Get Vehicles in a Fleet

The Get vehicles in a fleet endpoint populates Fleet Asset records in the TMS from Catena.

To prevent record sync errors, Fleet Asset records must have a Company/Division Id field value.

Fleet Asset records are not created in the TMS and sent to Catena or the ELD Provider. They are received from the ELD Provider via Catena and created in the TMS. Any Fleet Asset records created in the TMS do not populate into Catena or to the original ELD Provider. Many Fleet Asset record field values that are manually changed in the TMS are synced with the field values received from Catena. Contact the ELD Provider to update Fleet Asset fields that are synced with Catena.

Fleet Asset records are received from Catena and then created in the TMS. Each time the Fleet Management 2 Job runs, the TMS and Catena records are compared. Any new Fleet Assets are created in the TMS. See the Update vehicle section for more information on updating the Field Asset Name or License Plate Number fields and sending to Catena.

The Fleet ID(s) are sent to the Get vehicles in a fleet endpoint. Fleet Asset records are returned to the TMS where records are either created or updated as necessary.

Sample Get vehicles in a fleet Response Payload

{
  "fleet_id": 2354,
  "vehicle_ids": [
    103,
    243,
    823
  ],
  "details": [
    {
      "id": 103,
      "fleet_id": 2354,
      "time": "2020-01-27T07:06:25.000Z",
      "tsp_source": "motive",
      "oem": "Freightliner",
      "model": "Cascadia",
      "model_year": "2018",
      "vin": "3AKJHHDR9JSJV5535",
      "license_plate_state": "CA",
      "license_plate_number": "5T31250",
      "status": "active",
      "name": "Truck 1234",
      "eld_device_id": "1000000492436002",
      "location": {
        "latitude": 122.142,
        "longitude": -93.343,
        "address": "16 N Fair Oaks Ave",
        "Pasadena": null,
        "CA 91103": null
      },
      "speed": {
        "value": 48.3,
        "unit": "mph"
      },
      "odometer": {
        "value": 140100,
        "unit": "miles"
      },
      "fuel": {
        "value": 54,
        "unit": "percent"
      },
      "current_driver_id": 123
    }
  ]
}

TMS Field Updates

Get Latest Vehicle Locations

The Get all latest vehicle locations in a fleet endpoint provides the latest location information for Fleet Assets.

The Fleet ID(s) are sent to the Get all latest vehicle locations in a fleet endpoint.

Sample Get all latest vehicle locations in a fleet Response Payload

{
  "fleet_id": 432,
  "vehicle_locations": [
    {
      "id": 103,
      "vehicle_id": 407,
      "latitude": 122.142,
      "longitude": -93.343,
      "course": 32.42,
      "address": "16 N Fair Oaks Ave, Pasadena, CA 91103",
      "date_time": "2020-01-27T07:06:25.000Z",
      "odometer": {
        "value": 311560,
        "unit": "miles"
      },
      "speed": {
        "value": 31,
        "unit": "mph"
      },
      "fuel": {
        "value": 57,
        "unit": "percent"
      },
      "vehicle": {
        "id": 407,
        "name": "Best Vehicle 123",
        "oem": "Freightliner",
        "model": "Cascadia",
        "model_year": "2017",
        "vin": "3AKJHHDR9JSJV5535",
        "license_plate_state": "US-MA",
        "license_plate_number": "XHJ-48D",
        "eld_device_id": "832SZ"
      },
      "driver": {
        "id": 209,
        "name": "John Doe",
        "license_number": "X192AGJ",
        "license_state": "MA",
        "license_country": "US"
      }
    }
  ]
}

TMS Field Updates

Get Drivers

The Get drivers in a fleet endpoint returns a list of driver ids and Driver records from Catena. Any Drivers (and their associated Contact records) that do not exist in the TMS are created in the TMS.

Drivers are created in the TMS based on the status received from the ELD Provider and the Sync Active Drivers Only field in the TMS.

When the Sync Active Drivers Only field is Checked, the following logic controls Driver updates in the TMS and ELD Provider.

• Drivers are created in the TMS with an Active Driver Activation Status.

• Drivers set as Inactive in the ELD Provider environment do not update in the TMS.

TMS Contact records are searched by name for any existing records. If found, a Driver is created and paired to the existing Contact record. The Driver Phone and Email fields are populated from the existing Contact record.

When a Driver Phone and Email are populated, the Contact Phone and Email values are updated to match. If a Driver Phone or Email are not populated, the Driver fields are updated to match the corresponding Contact fields.

The Fleet ID(s) are sent to the Get drivers in a fleet endpoint.

Sample Get drivers in a fleet Response Payload

{
  "fleet_id": 2354,
  "driver_ids": [
    123,
    211,
    601,
    621,
    741
  ],
  "details": [
    {
      "id": 123,
      "fleet_id": 2354,
      "time": "2020-01-27T07:06:25.000Z",
      "tsp_source": "motive",
      "name": "Susan Smith",
      "phone": "”5558234327“",
      "email": "susan@company.com",
      "carrier": {
        "carrier_name": "Acme Inc.",
        "dot_number": 87654321,
        "home_terminal_address": "1234 Pear St., Scranton, PA 62814",
        "home_terminal_name": "Acme Inc.",
        "main_office_address": "1234 Pear St., Scranton, PA 62814"
      },
      "status": "active",
      "license": {
        "license_number": "E1834567",
        "license_state": "CA",
        "license_country": "USA"
      },
      "work_rules": {
        "break": "Property (off-duty/sleeper)",
        "cycle": "USA 60 hour / 7 day",
        "jurisdiction": "AR",
        "restart": "34-hour Restart",
        "shift": "US Interstate Property"
      },
      "hours_of_service": {
        "date": "2020-01-27",
        "off_duty_seconds": 43200,
        "on_duty_seconds": 7200,
        "sleeper_seconds": 0,
        "driving_seconds": 21600,
        "waiting_seconds": 0,
        "active_seconds": 7200,
        "personal_conveyance_seconds": 0,
        "yard_move_seconds": 0
      },
      "external_ids": {
        "maintenance_id": "250020",
        "payroll_id": "ABFS18600"
      },
      "notes": "Prefers West Coast trips.",
      "created_at_time": "2019-05-18T20:27:35.000Z",
      "timezone": "America/Los_Angeles",
      "current_vehicle_id": 103,
      "vehicle_group": {
        "id": "3914",
        "name": "East Coast"
      }
    }
  ]
}

TMS Field Updates

*If the Activation Status field is set to Deactivated for a new Driver, the Driver Status field is set to Unavailable. Manually setting the Activation Status for a Driver to Deactivated does not update the driver record in Catena.

When a Driver is created in the TMS from Catena, an associated Contact record is created.

After a Driver record is created in the TMS, the only fields that may update based on changes received from Catena are the ELD ID and ELD Brand fields.

TMS Field Updates with no matching Driver Contact

** See the Fleet Management 2 Job documentation for information on how the TMS sets the Driver Type field value.

Get Fleet Documents

The Get all fleet documents endpoint returns documents from Catena. Some ELD Providers include additional document file information. No field information is stored in the TMS when documents are returned from Catena.

All Documents are requested from Catena since the date and time the Fleet Management Job last ran. Set a date and time in the Fleet Management Job Last Run field under TMS Admin → Configuration, Fleet Management to request all documents from that date. If no value is in this field, all queued documents are requested from Catena. This includes all documents for approximately the two previous weeks.

Documents are sent to the TMS and are handled based on the following criteria.

1. When a Load is associated with a Trip Plan Segment, documents are stored on the Load Documents section.

2. When no Load is associated with a Trip Plan Segment, an Inbound Email Record is created.

3. When the Driver is not associated with any Trip Plan Segments, an Inbound Email record is created.

Inbound Email records are formatted with the following information. From the App Launcher, search for Inbound Emails to open the list view.

• The document file is attached to the email.

• The subject and body read, “The driver document could not be associated with a Load.”

• The “From” email is the Driver Contact record.

  • If the Driver Contact does not have an email address, the Inbound Email record is created with an error. The error includes: “Pass 10: No Email on Matching Contact Record: + Driver Name”

  • When the Driver Contact record does not have an email address, the document is inserted into the TMS as a file.

The Fleet ID(s) and Start Date are sent to the Get all fleet documents endpoint. All documents are returned from the Start date to the current time running the Fleet Management Job 2.

Drivers may be associated with multiple Loads. The Load Name added to received documents is set by the Trip Plan Segment with the most recent Start Date/Time.

Loads are associated with a Trip Plan when the Load is included on at least one Trip Plan Segment for a Trip Plan.

TMS Fields sent in the Get all fleet documents Request

Sample Get all fleet documents Response Payload

{
  "fleet_id": 432,
  "documents": [
    {
      "document_id": 2354,
      "type": "dvir",
      "url": "https://samsara-driver-media-upload.s3.us-west-2.amazonaws.com/123456",
      "name": "dvir doc 1",
      "notes": "additional comments",
      "status": "submitted",
      "time": "2020-01-27T18:07:35.000Z"
    }
  ]
}

Documents are processed and stored based on the following logic.

1. Documents received from Catena are matched to the Driver ELD ID. Documents are saved to the Load matched with the Driver ELD ID.

2. If no Load is matched with the Driver ELD ID, an Inbound Email record is created and saved in the TMS.

3. If no Load is matched with the Driver ELD and the Driver does not have an email address, the document is saved in the org Files.

No TMS Field Updates

Fleet Messages

Send and receive messages to and from Drivers and store them in the TMS.

All messages are requested from Catena since the date and time the Fleet Management Job last ran. Set a date and time in the Fleet Management Job Last Run field under TMS Admin → Configuration, Fleet Management to request all messages from that date. If no value is in this field, all queued messages are requested from Catena. This includes all messages for approximately the two previous weeks.

Messages are stored on the Driver object and are not stored on the Load.

Send and receive Driver messages from the following locations.

1. From the Load Detail LWC.

2. The Related Records section on the Fleet Management Console.

   1. It is possible to send the same message to multiple Drivers at one time.

   2. Multiple messages cannot be sent to multiple Drivers at one time. Split up messages as necessary to send to multiple Drivers.

3. Trip Plan Segments on the Trip Planner LWC.

Send Fleet Messages

Outbound messages to drivers are sent immediately when the Send button is clicked.

TMS Fields sent in the Post message Request

Sample Post message Request Payload

{
  "fleet_id": 12345,
  "recipient_ids": [
    456,
    789
  ],
  "body": "Hello, this is a test message."
}

Sample Post message Response Payload

{
  "fleet_id": 432,
  "message": {
    "sender": {
      "sender_id": 2354,
      "sender_name": "John Doe"
    },
    "recipients": [
      {
        "recipient_id": 123,
        "recipient_name": "Jane Smith"
      },
      {
        "recipient_id": 345,
        "recipient_name": "Bob Johnson"
      }
    ],
    "body": "Lorem ipsum",
    "is_read": false,
    "time": "2020-01-27T18:07:35.000Z"
  }
}

No TMS Field Updates

Receive Fleet Messages

The Get all fleet messages endpoint returns messages from Drivers through Catena.

The Fleet ID(s) and Start Date are sent to the Get all fleet messages endpoint. All messages are returned from the Start date to the current time running the Fleet Management Job 2.

Catena provides messages in different format types depending on the ELD Provider. The sender_name field controls when messages are stored in the TMS. The two scenarios outlined below are examples when messages are not saved from Drivers using a particular ELD Provider.

• Samsara messages with a sender_name value of “Dispatch” are not saved. Messages with this value are sent from Samsara to the Driver.

• Motive messages do not contain a sender_name or sender_id to match to a Driver and are not saved.

The recipient_id field pairs a message to a specific Driver.

TMS Fields sent in the Get all fleet messages Request

Drivers may be associated with multiple Loads. The Load Name added to received messages is derived from the Trip Plan Segment with the most recent Start Date/Time.

Messages are returned and matched to each Driver via the ELD ID and the recipient_id returned from Catena.

Sample Get all fleet messages Response Payload

{
  "fleet_id": 28183,
  "messages": [
    {
      "sender": {
        "sender_name": "John Test"
      },
      "recipients": [
        {
          "recipient_id": 4259414,
          "recipient_name": "Bill Test"
        }
      ],
      "body": "Driver sending back ",
      "is_read": false,
      "time": "2025-02-05T17:56:30Z"
    },
    {
      "sender": {
        "sender_name": "Dispatch"
      },
      "recipients": [
        {
          "recipient_id": 4261050,
          "recipient_name": "August Eighth Twenty Twenty Four Ten Fifty"
        }
      ],
      "body": "Dispatch text",
      "is_read": false,
      "time": "2025-02-05T17:55:20Z"
    },
    {
      "sender": {
        "sender_name": "Dispatch"
      },
      "recipients": [
        {
          "recipient_id": 4260923,
          "recipient_name": "August Seventh Twenty Twenty Four Sixteen Thirty Five"
        }
      ],
      "body": "Dispatch text 2",
      "is_read": false,
      "time": "2025-02-05T17:55:20Z"
    },
    {
      "sender": {
        "sender_name": "Dispatch"
      },
      "recipients": [
        {
          "recipient_id": 4259414,
          "recipient_name": "Bill Test"
        }
      ],
      "body": "Test",
      "is_read": true,
      "time": "2025-02-04T16:02:52Z"
    },
    {
      "sender": {
        "sender_name": "Dispatch"
      },
      "recipients": [
        {
          "recipient_id": 4259414,
          "recipient_name": "Bill Test"
        }
      ],
      "body": "Hello World",
      "is_read": true,
      "time": "2025-02-04T15:54:43Z"
    }
  ]
}

The “Dispatch” sender_name in the example above is specific to Samsara in the Catena environment. Sender “Dispatch” messages are original messages sent from the TMS.

No TMS Field Updates

Driver

The Driver API endpoints allow for creating and syncing Driver and Driver Log records between Catena and the TMS. See the individual calls below for the field values that are exchanged for each endpoint.

Catena requires unique Driver First and Last Name fields. If multiple TMS Driver records have the same Driver Name fields they are not sent to Catena. An email with the duplicate names is sent to the Fleet Management Email.

When Checked, the Sync Active Drivers Only field controls the following actions.

• TMS Driver records with a Deactivated Driver Activation Status field but are Active in the ELD Provider generate a “Duplicate Contact Found for Driver” error.

• TMS Driver records with a Deactivated Driver Activation Status field do not update Drivers in the ELD Provider during the Create and Update Driver calls.

Create Driver

The Create driver endpoint is called to send Driver records from the TMS to Catena and the ELD Provider.

Catena requires Driver Names be unique (regardless of ELD Brand). When creating Driver records in the TMS, confirm no Drivers share the same First and Last Name. TMS Driver records must have the following fields to create the Driver in the ELD Provider.

• Company/Division Id

• ELD Enabled (Checked)

• ELD Brand

• Username

Use caution when creating Driver records in the TMS. Once sent to Catena, the Driver Name (First & Last) field can only update in Catena when all of the following fields match. If at least one field does not match, a duplicate match error is generated.

• CDL #

• CDL State/Province

• Cycle Override

• Rest Break Override

• Restart Override

• Timezone

Catena returns a list of the Driver ELD ID fields that populate on TMS Driver records.

When the Sync Active Drivers Only field is Unchecked, the following logic controls Driver updates in the ELD Provider.

• A Driver is sent to the ELD Provider. No active Driver matches and an “Username already exists.” error is generated.

  • ELD Providers without duplication logic may create duplicate Drivers.

See Fleet Management Job 2 information for more specific syncing criteria.

TMS Fields sent in the Create driver call.

*The Driver Name (First & Last) field can only update in Catena when all of the following fields match. If at least one field does not match, a duplicate match error is generated.

• CDL #

• CDL State/Province

• Cycle Override

• Rest Break Override

• Restart Override

• Timezone

**Sent as “TMS - Username: ” + Driver Username.

***US DOT Number is numeric only.

Catena only accepts the following Cycle Override values.

• USA Property 8/70

• USA Property 7/60

• USA Passenger 7/70

• USA Passenger 7/60

Sample Create driver Request Payload

  "fleet_id": 20696,
  "axle_tsp_id": 25,
  "override_duplicates": false,
  "carrier_name": "Test Carrier Fleet",
  "dot_number": 123456789012,
  "first_name": "Bill",
  "last_name": "Driver",
  "username": "bdriver2",
  "password": "password1",
  "phone": "”5558234327“",
  "license": {
    "license_number": "E1834567",
    "license_state": "CA",
    "license_country": "USA"
  },
  "timezone": "Eastern Time (US & Canada)",
  "notes": "From TMS- Username: bdriver2",
  "primary_cycle": "USA Property (8/70)",
  "is_eld_exempt": false,
  "is_yard_move_enabled": false,
  "is_personal_conveyance_enabled": false
  }

Catena returns the Driver ELD ID field.

Sample Create driver Response Payload

{
  "id": "2143"
}

TMS Field Updates

Update Driver

The Update driver endpoint sends Driver record updates from the TMS through Catena. The payload is similar to the Create driver call, but is used when a record already exists and requires updating through Catena.

Drivers are only updated to Catena when the ELD Enabled field is Checked.

When the Sync Active Drivers Only field is Checked, only Drivers with an Active Driver Activation Status are sent to Catena.

TMS Fields sent in the Update driver call.

*The Driver Name (First & Last) field can only update in Catena when all of the following fields match. If at least one field does not match, a duplicate match error is generated.

• CDL #

• CDL State/Province

• Cycle Override

• Rest Break Override

• Restart Override

• Timezone

**Sent as “TMS - Username: ” + Driver Username.

Catena only accepts the following Cycle Override values.

• USA Property 8/70

• USA Property 7/60

• USA Passenger 7/70

• USA Passenger 7/60

Sample Update driver Request Payload

  "fleet_id": 20696,
  "axle_tsp_id": 25,
  "override_duplicates": false,
  "carrier_name": "Test Carrier Fleet",
  "dot_number": 123456789012,
  "first_name": "Bill",
  "last_name": "Driver",
  "username": "bdriver2",
  "password": "password1",
  "phone": "”5558234327“",
  "license": {
    "license_number": "E1834567",
    "license_state": "CA",
    "license_country": "USA"
  },
  "timezone": "Eastern Time (US & Canada)",
  "notes": "From TMS- Username: bdriver2",
  "primary_cycle": "USA Property (8/70)",
  "is_eld_exempt": false,
  "is_yard_move_enabled": false,
  "is_personal_conveyance_enabled": false
  }

Sample Update driver Response Payload

{
  "message": "Updated successfully"
}

No TMS Field Updates

Get HOS Availability

The Get Hours of Service (HOS) availability endpoint returns Driver availability information from the ELD Provider. All active Drivers with a record through Catena to the ELD Provider have HOS values returned.

Fleet Driver IDs are sent to the Get Hours of Service (HOS) availability endpoint in the request.

Sample Get Hours of Service (HOS) availability Response Payload

{
  "hos_availability": [
    {
      "fleet_id": 2354,
      "time": "2020-01-27T07:06:25.000Z",
      "tsp_source": "motive",
      "driver_id": 123,
      "name": "Susan Smith",
      "available_time": {
        "cycle_seconds": 214800,
        "shift_seconds": 49200,
        "drive_seconds": 39600,
        "break_seconds": 27600
      }
    }
  ],
}

TMS Field Updates

Get HOS Logs

The Get Hours of Service (HOS) logs endpoint returns Log and Log Entry records. All active Drivers with a record through Catena to the ELD Provider have HOS Logs return.

The Sync Active Drivers Only field does not control Driver HOS Logs. TMS Driver HOS Logs continue to sync to the TMS when the TMS Driver record Driver Activation Status is set to Deactivated.

Fleet Driver IDs, a start date, and end date are sent to the Get Hours of Service (HOS) logs endpoint in the request. The start and end date is determined by the Driver Log Grace Period field set under TMS Admin → Configuration, Fleet Management.

Driver Log records are named as Driver Name + Log Date. The Log Date is returned from Catena in the response.

Log Events are also requested and populate as Log Entry records.

Driver Log records are never created for the current day.

Driver Log and Log Entry records are returned and created in the TMS. If they match an existing Driver ELD ID, Start Time, and End Time fields, the Log or Log Entry is updated. When matched to an existing record, a new Log or Log Entry is not created.

A Driver Log Entry record is created for each Event returned from Catena. See a list of Catena-provided Events in the table below.

HOS Log errors do not appear in any Fleet Management emails. If calls to the Hours of Service logs endpoint fail, HOS log information does not update. Review HOS log information to confirm the job is returning information correctly.

Sample Get Hours of Service (HOS) logs Response Payload

{
  "hos_logs": [
    {
      "id": 14322,
      "fleet_id": 2354,
      "time": "2020-01-27T07:06:25.000Z",
      "tsp_source": "motive",
      "driver_id": 123,
      "name": "Susan Smith",
      "date": "2020-01-27",
      "work_rules": {
        "break": "Property (off-duty/sleeper)",
        "cycle": "USA 60 hour / 7 day",
        "jurisdiction": "AR",
        "restart": "34-hour Restart",
        "shift": "US Interstate Property",
        "deferral": "Day 1"
      },
      "exemptions": {
        "adverse_driving": false,
        "short_haul": false,
        "wait_time": false,
        "restart_24_hour": false,
        "break_8_hour": false
      },
      "hours_of_service": {
        "date": "2020-01-27",
        "off_duty_seconds": 43200,
        "on_duty_seconds": 7200,
        "sleeper_seconds": 0,
        "driving_seconds": 21600,
        "waiting_seconds": 0,
        "active_seconds": 7200,
        "personal_conveyance_seconds": 0,
        "yard_move_seconds": 0,
        "deferral_seconds": 0
      },
      "distance": {
        "drive_distance": {
          "value": 300,
          "unit": "miles"
        },
        "personal_conveyance_distance": {
          "value": 0,
          "unit": "m"
        },
        "yard_move_distance": {
          "value": 0,
          "unit": "m"
        }
      },
      "certified": true,
      "certified_time": "2020-01-27T07:06:25.000Z",
      "shipping_docs": "Delivery to warehouse 10",
      "events": [
        {
          "id": 26462,
          "type": "driving",
          "notes": "Going to warehouse",
          "location": {
            "latitude": 123.456,
            "longitude": 37.459,
            "address": "1234 Main St, San Jose, CA"
          },
          "start_time": "2020-01-26T19:08:25.000Z",
          "end_time": "2020-01-26T19:38:25.000Z",
          "deferral_seconds": 0,
          "vehicle": {
            "id": 103,
            "oem": "Freightliner",
            "model": "Cascadia",
            "model_year": "2018",
            "vin": "3AKJHHDR9JSJV5535"
          },
          "co_driver": {
            "id": 621,
            "name": "Sammy Simpson"
          }
        }
      ],
      "vehicles": [
        {
          "id": 103,
          "oem": "Freightliner",
          "model": "Cascadia",
          "model_year": "2018",
          "vin": "3AKJHHDR9JSJV5535"
        }
      ],
      "trailer_info": null,
      "co_drivers": [
        {
          "id": 621,
          "name": "Sammy Simpson"
        }
      ]
    }
  ],
}

TMS Field Updates

Catena Events to TMS Log Entry Status Table

Vehicle

The TMS calls one Vehicle endpoint to confirm Vehicle/Fleet Asset records are synced between the TMS and the ELD Provider through Catena.

Update vehicle

Use caution when updating Fleet Asset records in the TMS. Once sent to Catena, Fleet Asset records cannot be deleted in the ELD Provider. Changing the Fleet Asset Name or License Plate Number field in the TMS updates that Fleet Asset in Catena/the ELD Provider.

The Update vehicle endpoint is called when there are Vehicle/Fleet Asset record differences between Catena and the TMS. The Fleet Asset Name and/or License Plate Number fields are sent to Catena to update records. These two Vehicle fields are the only updates the TMS sends through Catena.

• When Sync Active Fleet Assets Only is Checked, only active Fleet Asset records are sent to Catena to update.

• When Sync Active Fleet Assets Only is Unchecked, all Fleet Asset records are sent to Catena to update.

Each Telematics Service Provider (ELD Provider) has unique record requirements and restrictions. Use caution with Fleet Asset Name or License Plate Number fields that may be sent through Catena to update records. For example, some ELD Provider services limit Name fields to a specific number of characters. TMS Fleet Asset record Name and License Plate Number fields typically allow for more characters.

Sample Update vehicle Request Payload

{
  "fleet_id": 8847,
  "name": "T-9944",
  "license_plate_number": "JPP1968 "
}

TMS Fields Sent

Sample Update vehicle Response Payload

{
  "message": "Updated successfully"
}

No TMS Field Updates

Field Reference Table

The following table relates TMS fields with the equivalent Catena fields included in Catena API calls.

Cycle Override Value Mapping

Catena Restart Override Codes

Catena Events to TMS Log Entry Status Table