Introduction to the Driver Retention feature

First available in TMW Operations 2019.2

Requirements

A PeopleNet telematics device (PMG, PCT), any version
A DRIVERRETENTIONSCORECARD license

The Driver Retention feature uses key driver metrics to identify dissatisfied drivers who are at risk of leaving the company. Trimble designed the feature to help you intervene before you lose a driver. This can help you avoid the costly process of recruiting and training a new driver. The feature provides you with a calculated score provided by Trimble Cloud Exchange (TCX).

This information displays in the Driver Retention window. This window is available in TMW Operations and in TMW Back Office. The window has four main sections:

The Drivers section
In this section, you retrieve a list of your drivers.
The Score section
This section contains these two important fields:
The Retention Score field
The calculated score shows in the Retention Score field. It is a value from 1 to 100, the higher the number, the greater the risk of losing the driver.
The Retention Predictor field
This field indicates the predictor that is most influential on the Driver’s Predictive Retention Score. This entry is determined and supplied to TMW Operations by Trimble Cloud Exchange.
The Coaching section
This section contains a grid that displays a list of all previous coaching meetings for the selected driver.
The Details section
This section contains fields that allow you to record information about a coaching session with an at-risk driver.

As an option, you can set up the system to display the driver’s retention score in the driver profile. For more information, see Setting up the profile to show the driver retention score.

Setting up the Driver Retention feature

The setup for the Driver Retention feature includes:

Applying the DRIVERRETENTIONSCORECARD license
Recording connection information

Applying the DRIVERRETENTIONSCORECARD license

To use the Driver Retention feature, you must apply the DRIVERRETENTIONSCORECARD license to your database.

You can verify that the license is applied from within TMW Operations. Go to Help > About. In the About window, click More. A second window opens. It lists licenses in a table. Look for DRIVERRETENTIONSCORECARD in the Name column, and verify that the Value column is set to Y. Click Close in the windows.

If the DRIVERRETENTIONSCORECARD license is not listed, contact your Support Team.

Recording connection information

Go to Tools > Analytics > Driver Retention Configuration.
The Driver Retention Configuration window opens.
In 2021.3, the window was changed.

The Driver Retention Configuration window prior to 2021.3.

The Driver Retention Configuration window in 2021.3 and greater.

Make entries in these fields.

Note: Contact Support if you need help recording your configuration information.

Required field: *

Field	Definition
Authentication URL *	The base URL from where the system obtains authorization and access tokens
Retention URL *	The URL that connects you to your Driver Retention data
Customer ID *	Specifies the customer data to which you are connecting Note: This is set up by Trimble Cloud Exchange (TCX).
Consumer Key *	Description for version 2021.2 and earlier The consumer key is the API key associated with Driver Retention functionality on Trimble Cloud Exchange (TCX). The key identifies the client making the API request. The value in the Consumer Key field is used as a part of authentication. It has two parts: Consumer key Consumer secret (a password) The two parts are separated by a colon. The key is encoded using base64. This lets it be stored as a single value. To get your consumer key and secret: Subscribe to the application in the Trimble Cloud Console. Generate the Base64 value on the Base64 Encode site. Description for version 2021.3 and later The consumer key is the API key that identifies the client making the API request. This key and the consumer secret are used together for authentication. The consumer key and the consumer secret are created when you subscribe to the application in the Trimble Cloud Console. After subscribing to the application, complete this registration form for access to the APIs. Your application will not communicate with the API until you complete the form.
Consumer Secret *	Available only in version 2021.3 and later The consumer secret and the consumer key are used together for authentication.
Search on Alternate ID	Specifies whether the system uses the Driver ID or the Alt ID to search for driver data Select the checkbox to use Alt ID Clear the checkbox to use Driver ID

Field

Definition

Authentication URL *

The base URL from where the system obtains authorization and access tokens

Retention URL *

The URL that connects you to your Driver Retention data

Customer ID *

Specifies the customer data to which you are connecting

Note: This is set up by Trimble Cloud Exchange (TCX).

Consumer Key *

Description for version 2021.2 and earlier
The consumer key is the API key associated with Driver Retention functionality on Trimble Cloud Exchange (TCX). The key identifies the client making the API request.

The value in the Consumer Key field is used as a part of authentication. It has two parts:

Consumer key
Consumer secret (a password)

The two parts are separated by a colon. The key is encoded using base64. This lets it be stored as a single value. To get your consumer key and secret:

Subscribe to the application in the Trimble Cloud Console.
Generate the Base64 value on the Base64 Encode site.

Description for version 2021.3 and later

The consumer key is the API key that identifies the client making the API request.
This key and the consumer secret are used together for authentication.
The consumer key and the consumer secret are created when you subscribe to the application in the Trimble Cloud Console.
After subscribing to the application, complete this registration form for access to the APIs. Your application will not communicate with the API until you complete the form.

Consumer Secret *

Available only in version 2021.3 and later
The consumer secret and the consumer key are used together for authentication.

Search on Alternate ID

Specifies whether the system uses the Driver ID or the Alt ID to search for driver data

Select the checkbox to use Alt ID
Clear the checkbox to use Driver ID

Click Save.
Click Close.

Setting up the profile to show the driver retention score

First available in: TMW Operations 2019.3

As an option, you can set up the system to show the following driver retention data on the Driver Management tab in the driver’s profile:

Latest retention score
Retention predictor
Date of the latest retention score

For details about retention information, see the introduction to this topic.

To view this information in the driver profile, you must set up the Trimble Analytics Service. This Windows Service updates the driver profiles periodically with the latest retention data.

The set up includes:

Installing the Trimble Analytics Service
Applying SQL to your database
Editing the configuration file
Editing the Windows Service
Configuring a Service Controller Configuration command

Installing the Trimble Analytics Service

After you complete Setting up the Driver Retention feature, you can set up the Trimble Analytics Service. Follow these steps.

Locate the Trimble Analytics Service installer you downloaded to your computer.
The installer is named Trimble.WinServices.Analyics.Install.msi.
Double-click the .msi file.
The Welcome to the Trimble Analytics Service Setup Wizard opens.
Click Next to continue.
In the Select Installation Folder window:
1. Specify who will have access to the application by selecting the appropriate radio button:
  - Everyone
    Select this option if other users will be accessing the application from this computer.
  - Just me
    Select this option if you will be the only person accessing the application from this computer.
2. Do one of the following:
  - To accept the default installation folder, click Next.
    
    Note: The default location is at
    C:\Program Files (x86)\Trimble Transportation Enterprise\Trimble Analytics Service
  - To change the installation folder, click Browse.
    
    In the Browse for Folder window, locate the appropriate folder.
    
    Click OK.
Follow the onscreen prompts to complete the installation.

After the installation is complete, your install directory contains:

An executable named TMWSystems.WindowsServices.Analytics.Scheduler.exe
The necessary DLLs to run the service
A SQL folder containing a copy of TMWBackOfficeDBMods.sql

Applying SQL to your database

To ensure that your database is correctly modified, you must apply the TMWBackOfficeDBMods.SQL file to your database. This file was installed in the SQL folder in the Trimble Analytics Service directory along with the TMWSystems.WindowsServices.Analytics.Scheduler.exe and other files.

To apply the SQL file to your database, follow these steps.

In Windows Explorer, access the folder and double-click the TMWBackOfficeDBMods.SQL file.
Apply the SQL to your database.

Note: For instructions, consult your Microsoft SQL Server Management Studio or SQL Server Enterprise Manger help system. If you need further assistance, contact your Support representative.

Editing the configuration file

Edit the TMWSystems.WindowsServices.Analytics.Scheduler.exe.config file to set the polling interval and the service start and stop time.

Setting Key	Description
DriverRetentionPollingInterval	Specifies how often the service polls the retention service. The value is in milliseconds (e.g. 5000 → 5 seconds). The default value is 21,600,000 (6 hours)
DriverRetentionPollingStartTime	The earliest polling time The default value is 12:00:00 AM Note: Works in conjunction with the DriverRetentionPollingEndTime setting to create a time window for which the service is active.
DriverRetentionPollingEndTime	The latest polling time The default value is 11:59:59 PM Note: Works in conjunction with the DriverRetentionPollingStartTime setting to create a time window for which the service is active.

Setting Key

Description

DriverRetentionPollingInterval

Specifies how often the service polls the retention service.

The value is in milliseconds (e.g. 5000 → 5 seconds).

The default value is 21,600,000 (6 hours)

DriverRetentionPollingStartTime

The earliest polling time

The default value is 12:00:00 AM

Note: Works in conjunction with the DriverRetentionPollingEndTime setting to create a time window for which the service is active.

DriverRetentionPollingEndTime

The latest polling time

The default value is 11:59:59 PM

Note: Works in conjunction with the DriverRetentionPollingStartTime setting to create a time window for which the service is active.

The configuration file is located in the directory you specified when installing the Trimble Analytics Service. The default location is C:\Program Files (x86)\Trimble Transportation Enterprise\Trimble Analytics Service.

Verifying the Windows Service

When you ran the Trimble Analytics Service installer, the system automatically created the Windows Service named Trimble Analytics Polling Service. The Trimble Analytics Polling Service calls the Trimble_AnalyticsPolling.exe, which pulls retention data into the database.

A Windows Service is an application type that runs in the system background without a user interface.

To verify the Windows Service, follow these steps.

Open the Services window and go to the Trimble Analytics Polling Service.

Note: See your Windows documentation for information about accessing or using Windows Services.
Right-click on Trimble Analytics Polling Service, and select Properties.

The Trimble Analytics Polling Service Properties window opens.
1. Notice that the Service name is Trimble_AnalyticsPolling.
2. Also, notice that the service is automatically set up to log on with a network account.
  The system assigns the account when the service is installed.
  
  Note: If needed, you can set this up to log on with a local account.
Close the Services window.

Configuring a Service Controller Configuration command

Each time you start your system, the Trimble_AnalyticsPolling service needs to know the location of the program files and the login information. You use a Service Controller Configuration command (sc config) to permanently register this information as a command line argument.

The following two tables describe the required command parameters and arguments for the Trimble Analytics Polling Service.

Commands

Commands
Parameter	Description
sc config	Command for accessing the Service Controller’s configuration utility It runs a specified service automatically when you start your system.
Service name	Enter Trimble_AnalyticsPolling Notes: The service name identifies the Windows Service, in this case, the Trimble_AnalyticsPolling. The name is visible on the service’s property window. Also, you can use the getkeyname command at the command prompt to retrieve the service name. The `sc getkeyname` command has the following format: `sc` [machine address for Windows Service] `getkeyname` "[Name of Service]" See your Microsoft documentation for more information.
binPath=	Enter the path to the TMWSystems.WindowsServices.Analytics.Scheduler.exe file followed by the applicable command line arguments. You must enter a space between the binPath parameter and its argument. You should also use double quotes around the entire argument. Note: The binPath= parameter tells the Service Controller what should occur when the Trimble_AnalyticsPolling Windows Service is started. In this case, it launches the installed TMWSystems.WindowsServices.Analytics.Scheduler.exe file, and it passes the command line arguments you specify.

Parameter

Description

sc config

Command for accessing the Service Controller’s configuration utility

It runs a specified service automatically when you start your system.

Service name

Enter Trimble_AnalyticsPolling

Notes:

The service name identifies the Windows Service, in this case, the Trimble_AnalyticsPolling.

The name is visible on the service’s property window.

Also, you can use the getkeyname command at the command prompt to retrieve the service name.

The sc getkeyname command has the following format:
sc [machine address for Windows Service] getkeyname "[Name of Service]"

See your Microsoft documentation for more information.

binPath=

Enter the path to the TMWSystems.WindowsServices.Analytics.Scheduler.exe file followed by the applicable command line arguments.

You must enter a space between the binPath parameter and its argument. You should also use double quotes around the entire argument.

Note: The binPath= parameter tells the Service Controller what should occur when the Trimble_AnalyticsPolling Windows Service is started. In this case, it launches the installed TMWSystems.WindowsServices.Analytics.Scheduler.exe file, and it passes the command line arguments you specify.

You record the following command line arguments after the binPath parameter.

Arguments
Argument	Table header
-U	Username for the service application
-P	Password for the service application
-G	File path to TTS50.ini
-L	File path to TTSLocal.ini
-ret	Run the driver retention polling service

Arguments

Argument

Table header

-U

Username for the service application

-P

Password for the service application

-G

File path to TTS50.ini

-L

File path to TTSLocal.ini

-ret

Run the driver retention polling service

To permanently register the command line arguments that are passed to the service when you start your system, follow these steps.

Open a command prompt as an administrator.
Enter the command.
This string shows the command format:

sc config < enter the service name> binPath= <enter the path to the EXE \ TMWSystems.WindowsServices.Analytics.Scheduler.exe -U < Username for the service application -P < Password for the service application -G <enter the file path to TTS50.ini \TTS50.ini -L <enter the file path to TTSLocal \TTSlocal.ini -ret

This string shows a sample command:

sc config Trimble_AnalyticsPolling binPath= "C:\Program Files (x86)\Trimble Transportation Enterprise\Trimble Analytics Service\TMWSystems.WindowsServices.Analytics.Scheduler.exe -U DST -P DST -G C:\INIs\TTS50\TTS50.ini -L C:\INIs\Local_INIs\TTSLocal.ini -ret"

Note: The space between the binPath option and the argument is required.
Press ENTER.

When it completes the command, the system displays the SUCCESS message.
Start the Windows Service.
1. Open the Services window.
2. Go to the Trimble Analytics Polling Service and right-click on it.
3. Select Start or Restart.
Note: See your Windows documentation for information about accessing or using Windows Services.

Viewing retention data in the Driver Retention window

To view driver retention data:

Go to Tools > Analytics > Driver Retention.
The Driver Retention window opens.
To restrict the list of drivers:
1. Click Restrict.
  A restriction window opens.
2. Set restrictions on any of the restriction tabs.
Click Refresh.
The system retrieves a list of drivers that match your restrictions.
Click on a driver in the Drivers grid at the top of the window.
The system displays the most recent data for that driver in the Score and the Details sections of the window.
Record coaching comments.
To view another driver’s data, click on that driver in the Drivers grid.
Click Close to exit.

Recording coaching comments

To record coaching comments:

Go to Tools > Analytics > Driver Retention.
The Driver Retention window opens.
To restrict the list of drivers:
1. Click Restrict.
  A restriction window opens.
2. Set restrictions on any of the restriction tabs.
Click Refresh.
The system retrieves a list of drivers that match your restrictions.
Click on a driver in the Drivers grid at the top of the window.
The system displays the most recent data for that driver in the Score and the Details sections of the window.
In the Coaching section, click Add.
The system adds a new line in the Coaching grid.

In the Details section, make entries in these fields:

Required field: *

Field	Definition
Coach name *	Enter the name of the coach.
Source	Select the method used to conduct the coaching session: In Person Phone Call Telematics Message Other
Next Step	Select a recommended next step to help this driver: Additional Conversation Escalation Complete
Attitude	Select the attitude the driver displayed: Positive Neutral Negative
Follow up date	Record a date for a follow up discussion, if needed.
Comments	Enter free-form comments.

Field

Definition

Coach name *

Enter the name of the coach.

Source

Select the method used to conduct the coaching session:

In Person
Phone Call
Telematics Message
Other

Next Step

Select a recommended next step to help this driver:

Additional Conversation
Escalation
Complete

Attitude

Select the attitude the driver displayed:

Positive
Neutral
Negative

Follow up date

Record a date for a follow up discussion, if needed.

Comments

Enter free-form comments.

Click Save.
Click Close.

Activating the logging service

As an option, you can set up the Driver Retention feature to log all of its messages to a database table named TMWSystemWideLogging. The logged information can be useful for troubleshooting. If this setup is not performed, the service will not write any log messages.

To activate the logger, paste the following INI settings into the TTS50 you will be using with the Driver Retention feature. Be sure to include the section names, such as [LOGGER].

[LOGGER]

AppenderSetupCount=1
AppenderSetup0=AllBackofficeLoggingDB
ActivationRulesCount=1

[Logger/AppenderSetup-AllBackofficeLoggingDB]
AppenderClassName=DatabaseLogAppender
TableName=TMWSystemWideLogging
FieldMappingsCount=13
FieldMappings0=AppID
FieldMappings1=KeyWord1
FieldMappings2=KeyWord2
FieldMappings3=Importance
FieldMappings4=TMWUser
FieldMappings5=AppVersion
FieldMappings6=MiscDataDef
FieldMappings7=MiscData1
FieldMappings8=MiscData2
FieldMappings9=MiscData3
FieldMappings10=MiscData4
FieldMappings11=LogDate
FieldMappings12=Message
FieldMappings-AppID=%[AppID]
FieldMappings-KeyWord1=%[IF KeywordCount>0 THEN ToList(Keywords).Item(0) ELSE "Unknown" ENDIF]
FieldMappings-KeyWord2=%[IF KeywordCount>1 THEN ToList(Keywords).Item(1) ELSE "Unknown" ENDIF]
FieldMappings-Importance=%[Importance]
FieldMappings-TMWUser=%[TMWUser]
FieldMappings-AppVersion=%[AppVersion]
FieldMappings-MiscDataDef=%[ "1:" & IF AdditionalData().Keys.Count >0 THEN ToList(AdditionalData().Keys).Item(0) ELSE "Unknown" ENDIF & ", 2:" & IF AdditionalData().Keys.Count >1 THEN ToList(AdditionalData().Keys).Item(1) ELSE "Unknown" ENDIF& ", 3:" & IF AdditionalData().Keys.Count >2 THEN ToList(AdditionalData().Keys).Item(2) ELSE "Unknown" ENDIF& ", 4:" & IF AdditionalData().Keys.Count >3 THEN ToList(AdditionalData().Keys).Item(3) ELSE "Unknown" ENDIF]
FieldMappings-MiscData1=%[IF AdditionalData().Values.Count >0 THEN ToList(AdditionalData().Values).Item(0) ELSE "Unknown" ENDIF]
FieldMappings-MiscData2=%[IF AdditionalData().Values.Count >1 THEN ToList(AdditionalData().Values).Item(1) ELSE "Unknown" ENDIF]
FieldMappings-MiscData3=%[IF AdditionalData().Values.Count >2 THEN ToList(AdditionalData().Values).Item(2) ELSE "Unknown" ENDIF]
FieldMappings-MiscData4=%[IF AdditionalData().Values.Count >3 THEN ToList(AdditionalData().Values).Item(3) ELSE "Unknown" ENDIF]
FieldMappings-LogDate=%[Timestamp]
FieldMappings-Message=%[message]

[LOGGER/ACTIVATIONRULES0]
MatchAppIdsCount=1
MatchAppIds0=.NB
RequiredKeywordsCount=1
RequiredKeywords0=DriverRetentionPolling
AppenderSetupNamesCount=1
AppenderSetupNames0=AllBackofficeLoggingDB
OptionalKeywordsCount=2
OptionalKeywords0=DriverRetentionPolling
OptionalKeywords1=AnalyticsProcessing
NeededOptionalCount=1