Introduction to the Driver Retention feature

First available in TMW Back Office 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 Back Office 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.

image1

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 Back Office. 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

  1. Go to Tools > Setup > * *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.

    image2

    The Driver Retention Configuration window in 2021.3 and greater.

    image13

  2. 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:

    1. Subscribe to the application in the Trimble Cloud Console.

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

  3. Click image3 Save.

  4. Click image4 Close.

Setting up the profile to show the driver retention score

First available in: TMW Back Office 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.

image5

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.

  1. Locate the Trimble Analytics Service installer you downloaded to your computer.
    The installer is named Trimble.WinServices.Analyics.Install.msi.

  2. Double-click the .msi file.
    The Welcome to the Trimble Analytics Service Setup Wizard opens.

  3. Click Next to continue.

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

        1. In the Browse for Folder window, locate the appropriate folder.

        2. Click OK.

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

  1. In Windows Explorer, access the folder and double-click the TMWBackOfficeDBMods.SQL file.

    image6

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

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

    image7

    Note: See your Windows documentation for information about accessing or using Windows Services.

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

      image8

    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.

      image9

      Note: If needed, you can set this up to log on with a local account.

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

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.

image10

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

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

  1. Open a command prompt as an administrator.

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

  3. Press ENTER.

    When it completes the command, the system displays the SUCCESS message.

    image11

  4. 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:

  1. Go to Tools > Analytics > Driver Retention.
    The Driver Retention window opens.

  2. To restrict the list of drivers:

    1. Click Restrict.
      A restriction window opens.

    2. Set restrictions on any of the restriction tabs.

  3. Click Refresh.
    The system retrieves a list of drivers that match your restrictions.

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

    image12

  5. Record coaching comments.

  6. To view another driver’s data, click on that driver in the Drivers grid.

  7. Click image4 Close to exit.

Recording coaching comments

To record coaching comments:

  1. Go to Tools > Analytics > Driver Retention.
    The Driver Retention window opens.

  2. To restrict the list of drivers:

    1. Click Restrict.
      A restriction window opens.

    2. Set restrictions on any of the restriction tabs.

  3. Click Refresh.
    The system retrieves a list of drivers that match your restrictions.

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

  5. In the Coaching section, click Add.
    The system adds a new line in the Coaching grid.

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

  7. Click image3 Save.

  8. Click image4 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