The Fleet Management Job 4 is a batch job and a set of platform events that receives information from, and syncs record information with Catena to monitor and manage Fleet ELD information. Run this job instead of the original Fleet Management Job 2. It is significantly faster and more efficient. The job runs continuously every 15 minutes. This document outlines the tasks completed by the job.
Only one Fleet Management Job may be enabled. Before running Fleet Management Job 4, 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.
Configuration
TMS Admin
Before running Fleet Management Job 4, complete the following configuration setup.
Navigate to TMS Admin → Configuration, Fleet Management.
Check the Fleet Management Enabled field.
From the Fleet Management Job field, select Fleet Management Job 4.
Set the Driver Log Grace Period (Days) field to control the number of days that Driver Log Entries may be updated.
Click Save.
The Fleet Management Pass Counter field on TMS Admin → Configuration, Fleet Management does not apply to Fleet Management Job 4. Platform Event actions cannot be selected individually.
Platform Cache
Errors encountered when running Fleet Management Job 4 are stored in the Platform Cache. The next time the job runs, an email is sent to the email address entered in the Fleet Management Email field. If no value is entered, the user running the batch job receives the email containing any errors.
Navigate to Setup and search for Platform Cache.
Choose Platform Cache to view the Platform Cache setup.
Confirm all available platform cache is assigned to rtms.
Click the Edit link for rtms.
Find the Org Cache Allocation section.
Increase the value for the Organization, to 3 if available.
The image below shows an org with all available platform cache assigned to rtms.
While most organizations should already have the correct allocation, certain factors can cause the value to be lower than expected. This may include custom code that utilizes Platform Cache, changes to cache allocation by administrators, or Salesforce platform changes that impact cache behavior. It is always safe to verify the allocation during troubleshooting to ensure sufficient cache capacity is available and to rule out cache configuration issues as a cause of system behavior.
Stop a running instance of the Fleet Management Job 4 by completing the following steps.
Navigate to TMS Admin → Configuration. Find the Fleet Management section.
Uncheck the Fleet Management Enabled field.
Click Save.
Transportation Profile
Multiple fields on the Carrier Transportation Profile control how Fleet Asset distance fields are calculated. Set these fields on the Fleet Management Default Carrier Transportation Profile and any other Fleet Carrier Transportation Profiles.
Mileage API
Mileage API Routing
Milage API Version
Job Functions
The Fleet Management Job 4 runs as a combination of mostly platform events and additional batch processes. The first time the job runs in a day includes the additional batch processes. All remaining runs in the day contain only the platform event actions.
TMS Broker users may use Fleet Management Job 4 to update the Timezone field for Account records.
Select Emergency Run from the Job Monitor LWC to run the process once to update existing Account records.
Select Run Now to run the job on a schedule and continuously update new Account records.
Batch Processes
Error emails are generated and sent as part of the batch process each time the job runs. Emails are not generated or sent when the job is run with the Emergency Run from the Job Monitor.
The following batch process completes the first time Fleet Management Job 4 runs in a day (usually the first time the job runs after midnight). This batch process only completes once per day.
Get Authentication Token and Provider Information
Retrieves an authentication token and the linked Fleet information for all remaining batch job and platform event calls to Catena. This process occurs first as the first portion of every job run.
Get Fleet IDs
Retrieves the list of active Fleet IDs for linked ELD Accounts.
Get Driver Logs and Log Entries
The following actions are completed sequentially as a batch process when Fleet Management Job 4 runs the first time in a day (usually the first time the job runs after midnight). This batch process only completes once per day.
Note: Driver Log records are never created for the current day.
Gets the latest Driver Hours of Service (HOS) Driver Log and Driver Log Entry records. 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.
Driver Log and Driver Log Entries are returned from Catena. Drivers are matched to Log and Log Entry records by the driver_id field. This value is stored in the Driver ELD ID field.
Log and Log Entries are matched to existing records or create new records in the TMS.
Log and Log Entries are updated with the values returned from Catena.
Values returned from Catena overwrite existing field values. They do not add to existing field values or roll-ups for TMS records.
One Driver Log record is created for each day and named the “Driver Name - Date.” For example: “Joe Driver - 2024-09-30.”
Time fields for a Driver Log record start at 00:00:00 and end at 23:59:59.
Catena can populate multiple Driver Log Entry records to a single Driver Log record.
A driver may create additional Log Entries on a date for a Driver Log record that already exists.
These log entries are sent to the TMS and added to the existing Driver Log Record as an additional Driver Log Entry.
When a Driver Log Entry is added or updated, any obsolete Log Entry records are deleted as part of the following step of the job. Driver Log Entry records can only be updated within the configured Driver Log Grace Period window. If a Driver Log Entry is modified in the ELD system outside of the Driver Log Grace Period window, the update is not retrieved by the TMS and no changes are made to the corresponding Driver Log or Driver Log Entry records in the TMS.
Catena sends an “Event” that 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 by this step of the job.
Delete Obsolete Driver Log Entry Records
The following actions are completed sequentially as a batch process when Fleet Management Job 4 runs the first time in a day (usually the first time the job runs after midnight). This batch process only completes once per day.
Deletes obsolete Driver Log Entry records from the TMS. Any Log Entry records that do not match the Driver Log records received during the previous step are deleted, provided the associated Driver Log Start Time is greater than or equal to the configured Driver Log Grace Period (Days) in the past. Driver Log Entries associated with Driver Logs that fall within the Driver Log Grace Period are not deleted. This step does not delete Driver Log records.
Record Delete example: While in the Driver Log Grace 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 the job runs, the updated entry is received by the TMS. A new Driver Log Entry record is created for the appropriate Driver Log. The job deletes the original 7:00 pm record entry as it does not match the Log or Entry received in the previous step.
Create or Update Fleet Notification Log Records
The following actions are completed sequentially as a batch process when Fleet Management Job 4 runs the first time in a day (usually the first time the job runs after midnight). This batch process only completes once per day.
During this process, Fleet Notifications are created and updated for Drivers and Fleet Assets. The TMS evaluates the configured date field on the Driver or Fleet Asset record against Today’s Date + Days Out, where the Days Out field represents the number of days in advance from when a notification is is generated. If the configured date field falls on or before Today’s Date + Days Out, the notification is considered due and a Fleet Notification Log is created or updated. Refer to the Generate a Notification Example.
Create Log: If a Fleet Notification Log does not exist and the date field on the Driver or Fleet Asset record is approaching today’s date + Days Out, a new notification log is created.
Update Log: If a Fleet Notification Log already exists and the date field on the Driver or Fleet Asset record is approaching today’s date + Days Out, the Last Modified Date on the existing log is updated.
No Update: If the Driver or Fleet Asset date field is set to a future date beyond today’s date + Days Out and a Fleet Notification Log already exists, then that log is not updated. If a Fleet Notification Log’s Last Modified Date is older than 30 days ago and the DataCleanupJob is running, that job will delete the log.
Platform Events
The following actions are completed asynchronously each time the job runs as several platform events.
Set Timezones for Shipping Locations
Sets the Timezone for all Account shipping locations (1000 max per run).
This action is only completed if the Timezone Update Disabled field in TMS Admin → Configuration is not Checked.
All shipping locations without a time zone and that have the Shipping Postal Code and Shipping Latitude fields populated are eligible to update.
Eligible shipping locations are sent to Addrexx for address matching. Addrexx requires an address to have a Country value paired with either a City or Postal Code. An address without a Country value generates an error message that is sent to the Admin user via email. The TMS does not validate that a Country value is present before sending the address to Addrexx.
Addresses returned from Addrexx are matched to Account locations. Addresses must match on City and State or Postal Code and the Time Zone must match the Salesforce Time Zone picklist value.
When an address matches, the Account Timezone is set to the time zone returned from Addrexx.
When an address does not match, the Timezone is set to Unknown.
Sync Fleet Assets
Creates new Fleet Asset records and updates existing Fleet records in the TMS with data received from Catena. New Fleet Assets created in the TMS are not sent to Catena to create corresponding Vehicle records.
For missing values, the Fleet Management Default Carrier value populates the Company/Division field. The Fleet Management Default Carrier is set under TMS Admin → Configuration, Fleet Management.
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.
Records are first sorted and compared to create or update records in either the TMS or Catena.
The VIN and ELD Id field values are compared to determine if the vehicle record exists in the TMS.
Create records in the TMS: When a Catena vehicle does not exist in the TMS, a Fleet Asset record is created.
The following field values from Catena populate the TMS Fleet Asset record.
Name
Company/Division
ELD Brand
ELD Serial Number
ELD ID
ELD ID values cannot begin with 0.
License Plate Number
VIN
Year
The following field values are set by the TMS.
Company/Division is set the value in the Fleet Management Default Carrier field.
Type is set to Tractor.
Status is set to Available when Catena sends an active status.
Status is set to Out of Service when Catena sends any value other than an active status.
Vehicle Make and Vehicle Model are set to Other if a specific picklist option is not available.
Update records in the TMS: TMS field values are updated in the following scenarios.
When TMS and Catena records match by VIN, but the ELD Id does not, no new record is created. The following field values from Catena update the TMS Fleet Asset record.
ELD ID
ELD Serial Number
ELD Brand
When a TMS Fleet Asset matches two Catena vehicles by VIN and ELD Id, the following TMS field is updated.
ELD Serial Number
ELD Brand
When two or more TMS records match a single Catena vehicle by VIN or ELD Id, the following occurs.
The TMS record that matches by VIN is updated with the following Catena values.
ELD ID
ELD Serial Number
ELD Brand
The TMS record with the matching ELD Id is updated, and the following field values are cleared:
ELD ID
ELD Serial Number
ELD Brand
Update records in Catena: Update records in Catena: In the following scenarios, records are updated in Catena. New vehicle records are not created in Catena.
If any of the following values do not match, the Catena value is updated from the TMS value.
Name
License Plate
Note: These updates may occur during vehicle matching/reconciliation when a TMS Fleet Asset matches a Catena vehicle by VIN, but has a different ELD ID OR when a TMS Fleet Asset is matched to multiple Catena vehicle records. In these scenarios, Catena is updated to reflect the Name and License Plate values stored in the TMS.
Get Updated Stats
Updates the geolocation and location information for each Fleet Asset based on the GPS location of the ELD. The following Fleet Asset fields are updated.
Current Location
Geolocation Latitude and Longitude
Last Odometer Reading
Last Odometer Reading Date
Speed (mph) and Speed (kph) with unit conversion applied, if necessary.
Vehicles are matched by the Catena vehicle_id field to the ELD ID field on the Fleet Asset record. These updates only occur when this matching condition is met.
The ELD Last Update field is also updated in this same matching scenario.
Calls the Trimble integration to update the Trip Plan Segment position.
Sync Drivers
Syncs Driver records between the TMS and Catena. A list of Drivers is retrieved from Catena and matched against existing TMS Driver records.
The Driver ELD Enabled field must be Checked for TMS Driver records to be eligible for updates from Catena. When no match is found, new records may be created in either system depending on the direction of the sync.
Records are first sorted and compared using matching criteria to determine whether to create or update records in either the TMS or Catena.
Create records in Catena: TMS Driver records with the ELD Enabled field Checked are sent to Catena when no matching driver is found.
Update records in Catena: In the following scenarios, Driver matching is performed using the criteria below. When a match is found, TMS Driver field values are sent to Catena to update the corresponding Driver record.
The ELD ID, 3 License fields, or Username and ELD Brand field value combinations are compared to determine if a driver received from Catena matches in the TMS.
When the ELD ID field values match, the following fields are sent to Catena to update records when any mismatches occur.
CDL #
CDL State/Province
Cycle Override
Rest Break Override
Restart Override
Timezone
When all 3 License fields match (CDL #, CDL State/Province, CDL Country), the following fields are sent to update Catena records when any mismatches occur.
Cycle Override
Driver Name
Rest Break Override
Restart Override
Timezone
When the Username and ELD Brand fields match, the following fields are sent to update Catena records when any mismatches occur.
CDL #
CDL State/Province
Cycle Override
Driver Name
Rest Break Override
Restart Override
Timezone
Create records in the TMS: When a matching Driver is not found in the TMS based on the defined matching criteria, a new Driver (and Contact) record is created in the TMS from Catena data.
When receiving new Driver records from Catena, a new Driver and Contact record is created. The Contact Account field is populated with the value set in the Fleet Management Default Carrier field.
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.
The Driver Type field is set to Employee when the following occurs.
The Type field does not have a value and the Contact Account Name is set to the Fleet Management Default Carrier.
The Driver Type field is set to Independent Contractor when the following occurs.
The Type field does not have a value and the Contact Account Name is not associated with the Fleet or the Fleet Management Default Carrier.
Contact records are created when the driver’s name does not match an existing TMS Contact record. Contact records are created with the following values.
The Contact Name field is the Driver Name.
The Contact Account Name field is set to the Account in the Fleet Management Default Carrier field.
The Contact Transportation Role is set to Driver.
Update records in the TMS: TMS Driver and Contact records that match a new Driver record name are updated as follows.
The following Contact record fields are updated when the Contact already exists. Field values are populated from the new Driver record.
Email
Phone
The following Driver record fields are updated when matching the following criteria.
All 3 License fields match (CDL #, CDL State/Province, CDL Country), but other mismatches occur. The following TMS fields are updated to match Catena records.
ELD Brand
ELD ID
When the Username and ELD Brand fields match, the following TMS fields are updated to match Catena records when any mismatches occur.
ELD ID
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.
Get Driver HOS Clocks
Retrieves Driver Hours of Service Clocks.
The following TMS Driver fields are updated with values returned from Catena.
Cycle Time Remaining
Drive Time Remaining
Shift Time Remaining
Time Until Break
The TMS does no calculations to determine these values.
Update Load Locations
Updates the current location of a Load based on the Fleet Asset Geolocation.
If the Geolocation field changes from the previous time the job ran.
Fleet Asset locations are updated even when a Driver Assignment record does not exist for the associated Driver.
Get Documents
Retrieves all documents associated with a Fleet ID and saves them in the TMS.
A Start Date and End Date are passed to Catena to define a period based on the last time the Fleet Management Job 2 ran. The Start Date is the date and time from the last run of the job. The End Date is now.
Documents are linked to a Driver by the Driver Id field. When a Driver on a Trip Plan Segment contains a Load, the document is attached to the Load record. If a Driver is not associated with a Load, an Inbound Email record is created.
The subject contains “The driver document could not be associated with a Load.”
The “From” email address is determined by the logic below.
In cases when a Driver submits a document and that document is not associated with a Trip Plan Segment, the document cannot be linked to a Load. In this scenario an Inbound Email record is created to capture the document.
The TMS attempts to populate the “From” address on the Inbound Email using the following priority.
Driver Contact Email Address
If present, the value is used.
Fleet Management Email field set in TMS Admin → Configuration.
If present, the value is used.
Fallback Email Address
If neither of the first two values are present, the TMS uses a placeholder email address: FleetManagementJob4@gmail.com.
This logic assures that an Inbound Email record is always created successfully and no submitted Driver documents are lost.
Get Messages
Retrieves all driver messages associated with a Fleet ID and saves them in the TMS.
A Start Date and End Date are passed to Catena to define a period of time
Based on the last time the Fleet Management Job 4 ran. The Start Date is the date and time of the last run of the job. The End Date is now.
Messages with a Sender Name of “Dispatch” are ignored. These messages are sent from Samsara to the Driver.
Messages are linked to a Driver by the Driver ELD ID field.
Each message has “From Driver, Load + [Load Name]” added to the beginning of the message when associated with a Load.
When a Driver is not associated with a Load, the message begins with “From Driver:”
Messages are saved to the Driver’s chatter feed.
Individual ELD Providers may not support all features and functionality. Contact Catena or the ELD Provider for additional information.
Job Monitor LWC
The Batch Process Monitor may be used to run Fleet Management Job 4 and also perform an Emergency Run of the job. View Batch Process information for more specific functionality.
Select Run Now to initialize the job. The job schedules itself to run again when it completes.
Choose Emergency Run to initialize only the platform event actions portion of Fleet Management Job 4. Choosing Emergency Run skips the Driver Log, Driver Log Entry, and Fleet Notification batch process portion of the job and runs the platform events immediately. Error emails are not generated by the Emergency Run action. This action should only be used when experiencing issues with the Salesforce batch scheduler. Typically, issues requiring an Emergency Run may arise when trying to run multiple other batch processes.
