Winter '25 Catena ELD Aggregator

Overview

Monitor and manage Fleet operations with the Revenova integration with the Catena API, an aggregator of Telematics Service Providers (TSP). Catena connects the TMS with over 40 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.

Fleet Asset and Driver records exist in both the TMS and and the corresponding TSP. 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 TSP 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 TSP. For specific field information, see the Fleet, Driver, and Vehicle sections below.

Setup

Each Telematics Service Provider (TSP) 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 TSP 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.

Enter Credentials

Enable the Catena integration by:

1. Navigate to TMS Admin, 

2. Select Credentials. 

3. Select the Global Services tab,

4. Find Axle in the list and select the card. (Catena does business as Axle)

5. Check the Enabled box.

6. Enter a User ID and Password 1 into the text fields. These fields are provided by Catena.

7. Click the Save button when finished.

8. Enter a Fleet Account in the Account Lookup field. An Account must be selected to enable the Link Fleet button.

9. Click the Link Fleet button.

Additional Telematic Service Providers or Fleet Account records may be associated with a single Catena account. Search for the account record(s) and click the Link Fleet button to associate additional Fleets.

The User Id and Password credentials are provided by Catena.

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

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

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.

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

Catena API Endpoints

Authentication

The Catena authentication endpoints verify the credentials of TMS users and pair TMS Fleet Account records to an 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 Fleet

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.

1. Navigate to the Axle Credential Card under TMS Admin → Credentials, Global Services.

2. Search for the appropriate account record in the Account Lookup field. An Account must be selected to enable the Link Fleet button.

3. Click the Link Fleet button.

4. Repeat as necessary to pair additional accounts to Catena Fleet Codes.

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 TSPs. 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. 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 TSP. They are received from the TSP via Catena and created in the TMS. Any Fleet Asset records created in the TMS do not populate into Catena or to the original TSP. Many Fleet Asset record field values that are manually changed in the TMS are synced with the field values received from Catena. Contact the TSP 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.

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 TMS does not create Driver records from Catena with an Inactive status.

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.

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.

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.

Create Driver

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

Catena requires Driver Names be unique (regardless of TSP 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 send to Catena.

• Company/Division Id

• ELD Enabled

• 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.

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 Axle 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 responds with 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.

TMS Fields sent in the Update driver call.

*The Driver Name (First & Last) field can only update in Axle 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 TSP. All active Drivers with a record through Catena to the TSP 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 TSP have HOS Logs return.

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.

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 TSP through Catena.

Update vehicle

Use caution when updating Fleet Asset records in the TMS. Once sent to Catena, Fleet Asset records cannot be edited or deleted in Catena or the TSP. Changing a Fleet Asset Name or License Plate Number field in the TMS does not update that Fleet Asset in Catena or the TSP.

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

Each Telematics Service Provider (TSP) 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 TSP 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

API Field Reference

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