Fall '24 Fleet Management Job 2

  • Updated on Mar 5, 2025
  • Published on Jan 15, 2025
  • 10 minute(s) read
Prev Next

Overview

Fleet Management Job 2

The Fleet Management Job 2 is a series of batch jobs that sends requests to and receives information from Catena, an ELD aggregator. This job runs continuously every 15 minutes from beginning of Pass 1. It is a 9-pass batch process that performs the following tasks.

Both Fleet Management 1 and Fleet Management 2 jobs may NOT be enabled at the same time. Before running Fleet Management Job 2, confirm that the Samsara integration is not Enabled. Navigate to TMS Admin → Credentials and find the Samsara card. Uncheck the Enabled field and click Save.

Pass Overview

Pass 1

Get Authentication Token

↓

Pass 2

Set Timezone for all Shipping Locations

↓

Pass 3

Sync Fleet Asset Records

↓

Pass 4

Update Fleet Asset Locations

↓

Pass 5

Sync Driver Records

↓

Pass 6

Get Latest Driver HOS Clocks

↓

Pass 7

Get Latest Driver HOS Logs & Log Entries

↓

Pass 8

Delete Obsolete Driver Log Entry Records

↓

Pass 9

Update Load Locations

  1. PASS 1: Calls the Catena API to generate an authentication token to allow for additional calls to Catena. Executes each time the job runs.

  2. PASS 2: Set Timezone for all shipping locations (1000 max per pass). Executes each time the job runs.

    Pass 2 only runs if the Timezone Update Disabled field in TMS Admin → Configuration is Unchecked.

    1. All shipping locations without a time zone but have the Shipping Postal Code and Shipping Latitude fields populated are eligible to update.

    2. The Addrexx integration is called to match Account addresses. Addrexx requires addresses have a Country value paired with either a City or Postal Code. Addresses without a Country value generate an error message that is sent via email.

      1. Addresses returned from Addrexx are matched to Account locations. Addresses must match on City, State, and the Time Zone must match the Salesforce Time Zone picklist value. If no match is found, the Timezone is set to Unknown.

      2. When a match is made, the Account timezone is set to the time zone returned from Addrexx.

  3. PASS 3: Sync Fleet Assets with Catena Vehicles. Executes each time the job runs.

    Fleet Assets are NOT created in the TMS first and sent to Catena.

    1. The Account SFID is matched to the Catena fleet_id record to populate the Fleet Asset Company/Division field in the TMS.

      1. If the Account SFID does not exist in the TMS, the Fleet Management Default Carrier populates the Company/Division field. The Fleet Management Default Carrier is set under TMS Admin → Configuration, Fleet Management.

      2. Catena Vehicles are sorted for creating or updating records in the TMS. The VIN and ELD Id fields in Catena and the TMS are compared to determine if the record exists in the TMS.

        ELD ID values cannot begin with a 0.

    2. If an Catena vehicle does not exist in the TMS, a Fleet Asset record is created.

      1. The following Catena fields populate the TMS Fleet Asset record.

        1. Name

        2. Company/Division

        3. ELD Brand

        4. ELD Model Number

        5. ELD Serial Number

        6. ELD ID

        7. License Plate Number

        8. VIN

        9. Year

      2. The TMS sets the following fields.

        1. The Type field is set to Tractor.

        2. The Status field is set to Available.

        3. The Vehicle Make and Vehicle Model fields are set to Other if a specific picklist option is not available.

    3. If a Fleet Asset record matches an Catena record by VIN, no new record is created.

      1. When the VIN matches, but the ELD Id does not, the following TMS Fleet Asset fields are updated with Catena values.

        1. ELD ID

        2. ELD Serial Number

        3. ELD Brand

    4. If a single TMS Fleet Asset record matches two separate Catena vehicles by VIN and ELD Id, the following occurs.

      1. The ELD Serial Number is compared between Catena and the TMS.

        1. If the ELD Serial Number does not match, the TMS record is updated with the Catena value.

      2. The record Name and License Plate fields are compared between Catena and the TMS.

        1. If either field does not match, the TMS sends the information to update the Catena record.

          No TMS records are sent to create records in Catena. Only the Name and License Plate fields are sent to update Catena records in this scenario.

    5. If 2 or more TMS Fleet Asset records match an Catena record by VIN and ELD Id, the following occurs.

      1. The TMS record that matches the Catena VIN has the following fields updated with the Catena value.

        1. ELD ID

        2. ELD Serial Number

        3. ELD Brand

      2. The TMS record that matches the Catena ELD Id has the following fields update and are set to no value.

        1. ELD ID

        2. ELD Serial Number

        3. ELD Brand

          Each Telematics Service Provider (TSP) has unique record requirements and restrictions. Use caution with Fleet Asset Name or License Plate 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 fields may allow for more characters.

  4. PASS 4: Get and Save the latest Vehicle Locations. Executes each time the job runs.

    1. Vehicles are matched by the Catena vehicle_id field to the ELD ID field on the Fleet Asset record.

  5. PASS 5: Sync TMS Drivers with Catena Drivers. Executes each time the job runs.

    1. Drivers are returned from Catena and matched to existing TMS Driver records.

    2. Account SFIDs are matched to Catena fleet_id fields. to The Account record value populates the Driver and Contact record Company/Division fields in the TMS.

      1. If the Account SFID does not exist in the TMS, the Fleet Management Default Carrier populates the Company/Division field. The Fleet Management Default Carrier is set under TMS Admin → Configuration, Fleet Management.

    3. Catena Drivers are sorted for record syncing. Catena and TMS Driver records are matched based on 3 separate criteria: ELD ID, 3 License fields, or Username and ELD Brand.

      1. The Catena ELD Id matches the TMS Driver ELD ID field.

        1. The following Driver fields are compared. Any mismatches are sent sent from the TMS to update the Driver record in Catena.

          1. CDL #

          2. CDL State/Province

          3. Cycle Override

          4. Rest Break Override

          5. Restart Override

          6. Timezone

      2. The Catena License Number, License State, and License Country fields all match to the corresponding TMS Driver fields.

        Catena Field

        TMS Field

        License Number

        ↔

        CDL #

        License State

        ↔

        CDL State/Province

        License Country

        ↔

        CDL Country

        1. The TMS Driver ELD ID and ELD Brand fields are updated to match the Catena values.

        2. The following Driver fields are compared. Any mismatches are sent sent from the TMS to update the Driver record in Catena.

          1. Cycle Override

          2. Driver Name

          3. Rest Break Override

          4. Restart Override

          5. Timezone

      3. The Catena username field matches the TMS Driver Username and ELD Brand fields.

        1. The TMS Driver ELD ID field is updated to the Catena value.

        2. The following Driver fields are compared. Any mismatches are sent sent from the TMS to update the Driver record in Catena.

          1. CDL #

          2. CDL State/Province

          3. Cycle Override

          4. Driver Name

          5. Rest Break Override

          6. Restart Override

          7. Timezone

    4. Drivers that only exist in the TMS (no matches) and have the ELD Enabled field Checked are sent to Catena.

    5. Drivers that only exist in Catena (no matches) are created in the TMS.

      1. TMS Contact records are searched for any Driver names that only exist in Catena. If no record exists, a new Contact is created.

        1. The Contact Name field is the Driver Name.

        2. The Contact Account Name field is set to the Account associated with the Fleet. If the Account does not exist in the TMS, the Fleet Management Default Carrier populates the field. The Fleet Management Default Carrier is set under TMS Admin → Configuration, Fleet Management.

        3. The Contact Transportation Role is set to Driver.

      2. If a TMS Contact record exists, the new Driver record Email and Phone fields are populated from the Contact record.

        1. The Driver Type field is set to Employee when the following occurs.

          1. When the Driver Type field does not have a value AND;

          2. The Contact Account Name field is associated with the Fleet or the Fleet Management Default Carrier. The Fleet Management Default Carrier is set under TMS Admin → Configuration, Fleet Management.

        2. The Driver Type field is set to Independent Contractor when the following occurs.

          1. When the Driver Type field does not have a value AND;

          2. The Contact Account Name field is NOT associated with the Fleet or the Fleet Management Default Carrier. The Fleet Management Default Carrier is set under TMS Admin → Configuration, Fleet Management.

        3. The Driver Phone updates the corresponding Contact record Phone.

    The Driver First and Last Name fields must be unique for some ELD Providers. Creating a duplicate Driver (same First and Last Name) for a Driver record that already exists in Catena causes an error.

    Use caution when creating Driver records in the TMS. Driver records cannot be deleted once sent to Catena. Driver Name (First and Last Name) fields cannot be changed in Catena. Changing a Driver Name in the TMS does not update the Catena record for that Driver.

    Cycle Override Value Mapping

    Catena Value

    TMS Cycle Override Picklist Option

    USA 70 hour / 8 day

    USA Property (8/70)

    USA 60 hour / 7 day

    USA Property (7/60)

    70-hour/8-day

    USA Property (8/70)

    60-hour/7-day

    USA Property (7/60)

    Any other value

    Unrecognized Value from API

  6. PASS 6: Retrieves the Driver Hours of Service Clocks. Executes each time the job runs.

    1. Catena Drivers are matched to TMS Drivers. The following TMS Driver fields are updated with Catena values.

      1. Cycle Time Remaining

      2. Drive Time Remaining

      3. Shift Time Remaining

      4. Time Until Break

      The TMS does no calculations to determine these values.

  7. PASS 7: Retrieves the latest Driver Hours of Service (HOS) Driver Log and Driver Log Entry records. Executes once per day. The period when Driver Long Entry records may be updated is defined by the Driver Log Grace Period (Days) field. By default, Driver Log Entry records for 2 days prior to the current day. Driver Log records are only created once the day is ended. This field may be changed under TMS Admin → Configuration, Fleet Management.

    1. Driver Log and Driver Log Entries are returned from Catena. Drivers are matched to Log and Log Entry records by the driver_id field returned from Catena and stored in the Driver ELD ID field.

    2. Driver Log and Driver Log Entry records are matched to existing records or new records are created in the TMS.

      1. When Driver Log or Driver Log Entry records exist in the TMS and match records from Catena, the records are updated with values received from Catena.

        1. The Catena values are not added to existing fields or rolled-up when updating TMS records. The values received from Catena overwrite the existing values.

      2. When Driver Log or Driver Log Entry records do not match any existing TMS records, new records are created in the TMS.

      3. One Driver Log record is created for each day and named the “Driver Name - Date.” For Example: “Joe Driver - 2024-09-30.”

        1. Time fields for a Driver Log record start at 00:00:00 and end at 23:59:59.

      4. Catena can populate multiple Driver Log Entry records to a single Driver Log record.

        1. A driver may create additional Log Entries on a date for a Driver Log record that already exists.

          1. These additional log entries are passed from Catena to the TMS and added to the existing Driver Log Record as an additional Driver Log Entry.

        2. When a Driver Log Entry is added or updated, any obsolete Driver Log Entry records are deleted in Pass 8. Driver Log Entry records can only be updated during the Driver Log Grace Period.

        3. Catena sends an “Event” and each event corresponds to a single Driver Log Entry record. This event is stored in the Status field. Refer to the Catena documentation for more information regarding fields populated in this pass.

          Catena Event Type

          TMS Driver Log Entry Status

          driving

          Driving

          onDuty

          On Duty Not Driving

          offDuty

          Off Duty

          personalConveyance

          Personal Conveyance

          sleeperBed

          Sleeper Berth

          yardMove

          Yard Move

          Any other value

          No Status

          Driver Log records are never created for the current day.

  8. PASS 8: Deletes obsolete Driver Log Entry records from the TMS. Executes each time the job runs. Any Log Entry records within the Driver Log Grace Period and do not match to the Driver Log records received during Pass 7 are deleted. Driver Log Entries outside of the Driver Log Grace Period are not deleted. This pass does not delete Driver Log records.

    1. Record Delete example: While in the Driver Log Grade Period, a driver updates a log entry from 2 days prior. The driver updates the off duty time from 7:00 pm to 6:15 pm. The next time Pass 7 runs, the updated entry is received by the TMS. A new Driver Log Entry record is created for the appropriate Driver Log. Pass 8 then runs and deletes the original 7:00 pm record entry as it does not match the Log or Entry received in Pass 7.

  9. Pass 9: Updates the current location of a Load based on the Fleet Asset Geolocation. Executes each time the job runs.

    1. Geolocations are requested for each Fleet Asset. If the Geolocation field changes from the previous time the job ran, then the ELD Last Update field also updates.

When performing only 1 pass the Fleet Management 2 Job does not reschedule itself. Run a single Pass for testing or troubleshooting ONLY.