Automated Customer Onboarding Starter Kit
Learn how to use the Customer Onboarding Starter Kit to assist Geotab Platform Partners onboarding new customers by automating certain tasks using MyGeotab SDK-based workflows. This is an API-only option that does not include the MyGeotab interface.

Support Document

12 mins to read

In this document

User Guide

Latest Update: 2024-10-28

Table of Contents

Overview

The Customer Onboarding Starter Kit is a sample application intended to assist Geotab Platform Partners onboarding new customers by automating certain tasks using MyGeotab SDK-based workflows. In this case, Geotab Platform Partners are Resellers using the API-only option that does not include the MyGeotab interface. The sample application may be run as-is if it satisfies all requirements, or modified as needed. The code — in the form of a .NET console application, using the MyGeotab .NET API — focuses on API calls and associated logic rather than being overwhelmed with the application, framework or user interface specific code.

The Customer Onboarding Starter Kit includes the following utilities:

Utility

Description

Create Databases & Load Devices

  1. Creates a new MyGeotab database;
  2. Adds an administrative/service user to the new database; and
  3. Uploads a list of devices from a CSV file into the new database.

Update Devices

  1. Connects to an existing MyGeotab database; and
  2. Loads a list of devices from a CSV file and adds or updates devices in the MyGeotab database — setting the name and driver feedback options of the devices as defined in the CSV file.

Prerequisites

This sample application requires:

  1. .NET 8.0 SDK (https://dotnet.microsoft.com/download) or higher; and
  2. MyAdmin credentials, entered manually when prompted, with the MyAdminApiUser and Device_Admin roles.

Getting Started

The Customer Onboarding Starter Kit can be accessed by cloning the Git repository. Once downloaded, open the project — CustomerOnboardngStarterKit.csproj — using Microsoft Visual Studio or Visual Studio Code.

NOTE: After populating the Configuration and Device List files — outlined in the respective sections below — the application can be run directly in the development environment using debug mode, or it can be compiled into an executable that is executed independently.

On start-up, the following screen is displayed.

document Image

Enter the number of the utility to run and then press Enter. The following screenshot demonstrates that the Create Database Load Devices utility has been started and the user has supplied a value after receiving the prompt.

document Image

NOTE: At various points while running, the utilities may require user input. In each case, the user prompt is displayed in yellow text — prefixed by the ‘>’ symbol — and the user input is displayed in blue text. To submit a user input, press Enter to proceed.

In cases where credentials are requested, password values display as asterisks (i.e. ********). Error text appears similar to ERROR: ….

For more information about each utility, refer to the sections below.

Create Database & Load Devices

At a high level, the Create Database & Load Devices utility:

  1. Creates a new MyGeotab database;
  2. Adds an administrative/service user to the new database; and
  3. Uploads a list of devices from a CSV file into the new database.
  4. ! IMPORTANT: Ensure the Configuration and Device List files are prepared as listed below before running the Create Database & Load Devices utility.

  5. Configuration File

  6. The Create Database & Load Devices utility requires a CSV configuration file, formatted as shown below. You may also choose to copy and paste the sample configuration into a new file, modify the parameter values with the required values, and save the file with a .csv extension.

  7. # Configuration file for Customer Onboarding Starter Kit utility: Processor_CreateDatabaseAndLoadDevices

  8. # Structure: <Key>,<Value>

  9. # -------------------------------------------------------------------------

  10. # lines beginning with '#' are comments and ignored

  11. Key,Value

  12. ResellerName,<ResellerName>

  13. ResellerErpAccountId,<ResellerErpAccountId>

  14. CustomerCompanyName,<CustomerCompanyName>

  15. CustomerAccountAdminFirstName,<CustomerAccountAdminFirstName>

  16. CustomerAccountAdminLastName,<CustomerAccountAdminLastName>

  17. CustomerAccountAdminEmail,<CustomerAccountAdminEmail>

  18. CustomerPhoneNumber,<CustomerPhoneNumber>

  19. CustomerFleetSize,<CustomerFleetSize>

  20. CustomerSignUpForNews,false

  21. CustomerDesiredDatabaseName,<CustomerDesiredDatabaseName>

  22. CustomerTimeZoneId,<CustomerTimeZoneId>

  23. CustomerDeviceListPath,<CustomerDeviceListPath>

  24. Parameter Descriptions

  25. The table below provides descriptions for the parameters in the Configuration file.

  26. Value

    Description

    ResellerName

    The Reseller name (e.g. Reseller 123 Inc.).

    ResellerErpAccountId

    The Reseller ERP account ID in MyAdmin (e.g. ABC01).

    CustomerCompanyName

    The Customer’s company name (e.g. Customer XYZ Ltd.).

    CustomerAccountAdminFirstName

    The first name of the Customer Account Administrator (e.g. John).

    CustomerAccountAdminLastName

    The last name of the Customer Account Administrator (e.g. Doe).

    CustomerAccountAdminEmail

    The email address of the Customer Account Administrator (e.g. John.Doe@email.com) — used as the MyGeotab login credentials for the customer administrative/service user.

    CustomerPhoneNumber

    The Customer phone number (e.g. +1 555 123-4567).

    CustomerFleetSize

    The Customer fleet size (e.g. 125).

    CustomerSignUpForNews

    The choice to sign up a Customer for email marketing (True or False).

    CustomerDesiredDatabaseName

    The desired name of the Customer database (e.g. XYZ). If the database name is unavailable, the user is prompted for alternative names until an available name is entered.

    CustomerTimeZoneId

    The Olson time zone identifier to be used for the Customer database (e.g. America/New_York). If an invalid entry is made, the user is provided with a list of supported timezone IDs and prompted to enter a supported ID.

    CustomerDeviceListPath

    The path to the Device List file that contains the list of devices to add to the database (e.g. C:\Temp\DevicesToImport.csv).

  27. Device List File

  28. The Create Database & Load Devices utility also requires a CSV file containing a list of device serial numbers to add to the new database, formatted as shown below. A device is added to the database if the serial number is valid and the device does not already belong to another account. You may also choose to copy and paste the sample configuration into a new file, replace the sample serial numbers with the required device serial numbers, and save the file with a .csv extension.

  29. # DevicesToImport.csv

  30. # Structure: <SerialNumber>

  31. # -------------------------------------------------------------------------

  32. # lines beginning with '#' are comments and ignored

  33. SerialNumber

  34. G92720FA10E9

  35. G86320E39137

  36. Run the Create Database & Load Devices Utility

  37. Once the Configuration and Device List files are prepared as outlined above, the Create Database & Load Devices utility can be run in the development environment or compiled into an executable that is run independently. The Create Database & Load Devices utility workflow is described below:

  38. 1

    The user is prompted to input the path to a Configuration file, which is loaded.

    2

    The system validates the values of the various configuration items. If any values are invalid, the user is prompted to input valid values.

    3

    The system performs a check to verify that the Device List file exists. If the file does not exist, the system displays an error message and the utility aborts.

    4

    The user is prompted for MyAdmin credentials. If invalid credentials are provided, the user has another opportunity to enter the credentials. If invalid credentials are provided for a second time, the system displays an error message and stops processing the utility.

    5

    The user’s MyAdmin credentials are used to authenticate against the MyGeotab API. If the authentication fails, an error message is displayed and the utility aborts.

    6

    The system performs a check to determine whether the desired Customer database name — Customer DesiredDatabaseName — is available. If the name is not available, the user is prompted to enter an alternate database name until an available name is specified.

    7

    The user is prompted to enter the desired password for the creation of the administrative/service user in the new database.

    8

    The system validates the CustomerTimeZoneId from the Configuration file. If the value is not valid, the user is presented with the entire list of supported timezone IDs and continues to prompt the user until a valid timezone ID is entered.

    9

    The new database is created and the database path is presented to the user (e.g. my0.geotab.com/abc_company).

    10

    The user’s MyAdmin credentials are used to authenticate the MyGeotab API against the new database.

    11

    The Customer’s administrative/service user is created in the new database.

    12

    The system retrieves the list of devices to add to the database from the Device List file. If the device is registered in the current database, the device is updated.

    If the device does not exist in the current database, a check is performed to determine whether the device is registered in another database.

    1. If the device is already registered in another database, the system notifies the user and the device is not added to the current database.
    2. If the device is not registered in another database, the device is added to the current database and the properties are updated based on the values in the Device List file.
  39. Update Devices

  40. At a high level, the Update Devices utility:

  41. Connects to an existing MyGeotab database; and
  42. Loads a list of devices from a CSV file and adds devices to or updates devices in the MyGeotab database, setting the name and driver feedback options of the devices as defined in the CSV file.

! IMPORTANT: Ensure the Configuration and Device List files are prepared as listed below before running the Create Database & Load Devices utility.

Configuration File

The Update Devices utility requires a CSV configuration file, formatted as demonstrated below. You may also choose to copy and paste the configuration into a new file, modify the parameter values with the required values, and save the file with a .csv extension.

# Configuration file for Customer Onboarding Starter Kit utility: Processor_UpdateDevices

# Structure: <Key>,<Value>

# -------------------------------------------------------------------------

# lines beginning with '#' are comments and ignored

Key,Value

ResellerErpAccountId,<ResellerErpAccountId>

DatabaseName,<DatabaseName>

DevicesToUpdateFilePath,<DevicesToUpdateFilePath>

Parameter Descriptions

The table below provides descriptions for the parameters in the Configuration file.

Value

Description

ResellerErpAccountId

The Reseller ERP account ID in MyAdmin (e.g. ABC01)

DatabaseName

The name of the Customer database where devices are added or updated (e.g. XYZ).

DevicesToUpdateFilePath

The path to the device list file that contains the list of devices that are added to or updated in the database (e.g. C:\Temp\DevicesToUpdate.csv).

Device List File

The Update Devices utility also requires a CSV file containing a list of devices to add or update in the subject database. A device is added to the database if the serial number is valid and the device does not already belong to another account. You may also choose to copy and paste the sample configuration into a new file, replace the sample records with the required records, and save the file with a .csv extension.

# DevicesToUpdate.csv

# Structure: <SerialNumber>,<Name>,<EnableDeviceBeeping>,<EnableDriverIdentificationReminder>,<DriverIdentificationReminderImmobilizeSeconds>,<EnableBeepOnEngineRpm>,<EngineRpmBeepValue>,<EnableBeepOnIdle>,<IdleMinutesBeepValue>,<EnableBeepOnSpeeding>,<SpeedingStartBeepingSpeed>,<SpeedingStopBeepingSpeed>,<EnableBeepBrieflyWhenApprocahingWarningSpeed>,<EnableBeepOnDangerousDriving>,<AccelerationWarningThreshold>,<BrakingWarningThreshold>,<CorneringWarningThreshold>,<EnableBeepWhenSeatbeltNotUsed>,<SeatbeltNotUsedWarningSpeed>,<EnableBeepWhenPassengerSeatbeltNotUsed>,<BeepWhenReversing>

# ---------------------------------------------------------------------------------

# lines beginning with '#' are comments and ignored

SerialNumber,Name,EnableDeviceBeeping,EnableDriverIdentificationReminder,DriverIdentificationReminderImmobilizeSeconds,EnableBeepOnEngineRpm,EngineRpmBeepValue,EnableBeepOnIdle,IdleMinutesBeepValue,EnableBeepOnSpeeding,SpeedingStartBeepingSpeed,SpeedingStopBeepingSpeed,EnableBeepBrieflyWhenApprocahingWarningSpeed,EnableBeepOnDangerousDriving,AccelerationWarningThreshold,BrakingWarningThreshold,CorneringWarningThreshold,EnableBeepWhenSeatbeltNotUsed,SeatbeltNotUsedWarningSpeed,EnableBeepWhenPassengerSeatbeltNotUsed,BeepWhenReversing

G92720FA10E9,Vehicle1,true,true,30,true,3500,true,5,true,120,115,true,true,23,-35,27,true,10,true,true

G86320E39137,Vehicle2,true,true,30,true,3500,true,5,true,120,115,true,true,23,-35,27,true,10,true,true

Parameter Descriptions

The table below provides descriptions for the parameters in the Device List file.

Value

Description

SerialNumber

The device serial number.

Name

The description used as the vehicle name (e.g. Vehicle 1).

EnableDeviceBeeping

The master toggle to enable the driver feedback on the device. When set to False, the device will not provide driver feedback (True or False).

EnableDriverIdentificationReminder

The value used to enable or disable the Driver Identification reminder. If used in conjunction with vehicle relay circuits, the value can force the driver to swipe the driver key before starting the vehicle (True or False).

DriverIdentificationReminder ImmobilizeSeconds

The value used to define the delay before the Driver Identification reminder is sent if the driver key is not swiped when EnableDriverIdentificationReminder is set to True.

The maximum value of this property is 255. A value of less than or equal to 180 indicates the number of seconds of delay time. When the value is greater than 180, the delay time increases by 30 seconds as the value incrementally increases by one (e.g. 180 indicates 180 seconds, 181 indicates 210 seconds, 182 indicates 240 seconds, etc).

EnableBeepOnEngineRpm

The toggle to enable beeping when the vehicle’s RPM exceeds the EngineRpmBeepValue (True or False).

EngineRpmBeepValue

The RPM value that triggers device beeping when exceeded (e.g. 3500).

EnableBeepOnIdle

The toggle to enable beeping when the vehicle idles for more than the value set for IdleMinutesBeelpValue (True or False.)

IdleMinutesBeepValue

The number of minutes of allowed idling before the device starts beeping. EnableBeepOnIdle must be enabled (e.g. 5).

EnableBeepOnSpeeding

The toggle to enable the device to beep continuously when the vehicle reaches the speed set for SpeedingStartBeepingSpeed and stops when the vehicle slows down to the speed set for SpeedingStopBeepingSpeed.

To enable the device to beep briefly rather than continuously, enable the EnableBeepBrieflyWhenApproachingWarningSpeed (True or False).

SpeedingStartBeepingSpeed

The beep on speeding value in km/h. When EnableBeepOnSpeeding is enabled, the device starts beeping when the vehicle exceeds this speed (e.g. 120).

SpeedingStopBeepingSpeed

The beep on speeding off value in km/h. When EnableBeepOnSpeeding is enabled, the vehicle must slow down to the set speed for the beeping to stop (e.g. 115).

EnableBeepBrieflyWhenApproachingWarningSpeed

The toggle to enable the speed warning value for the vehicle. When enabled and set to True, the device beeps briefly when the speed set for SpeedingStopBeepingSpeed is exceeded and SpeedingStartBeepingSpeed must be enabled (True or False).

EnableBeepOnDangerousDriving

The toggle to enable beeping when any of the acceleration thresholds are exceeded by device accelerometer readings (True or False).

AccelerationWarningThreshold

The acceleration warning accelerometer threshold (y-axis) value for the vehicle. A positive value that triggers device beeping when exceeded (e.g. 23).

Threshold value to mS2 conversion: threshold*18 = milli-g / 1000 = g / 1.0197162 = mS2.

BrakingWarningThreshold

The braking warning accelerometer threshold (y-axis) value for the vehicle. A negative value that triggers device beeping when exceeded (e.g. -35).

Threshold value to mS2 conversion: threshold*18 = milli-g / 1000 = g / 1.0197162 = mS2.

CorneringWarningThreshold

The cornering warning threshold (x-axis) value for the vehicle. A positive value that triggers device beeping when exceeded — the additive inverse is automatically applied: 26/-26 (e.g. 27).

Threshold value to mS2 conversion: threshold*18 = milli-g / 1000 = g / 1.0197162 = mS2.

EnableBeepWhenSeatbeltNotUsed

The toggle to enable the device to beep if an unbuckled seat belt is detected. This value only works if the device is able to obtain seat belt information from the vehicle (True or False).

SeatbeltNotUsedWarningSpeed

The value in km/h that will not trigger EnableBeepWhenSeatbeltNotUsed (e.g. 10).

EnableBeepWhenPassengerSeatbelt NotUsed

The toggle that monitors the seat belt use for both the passenger and driver, otherwise only the driver is monitored (True or False).

BeepWhenReversing

The toggle that enables the device to beep when the vehicle is in reverse (True or False).

Run the Update Devices Utility

Once the Configuration and Device List files have been prepared, as outlined above, the Update Devices utility can be run in the development environment using debug mode or compiled into an executable that is independently executed. The Update Device utility workflow is described below:

1

The user is prompted to input the path to a Configuration file, which is loaded.

2

The system validates the values of the various configuration items. If any values are invalid, the user is prompted to input valid values.

3

The system performs a check to verify that the Device List file exists. If the file does not exist, the system displays an error message and the utility aborts.

4

The user is prompted for MyAdmin credentials. If invalid credentials are provided, the user has another opportunity to enter the credentials. If invalid credentials are provided for a second time, the system displays an error message and stops processing the utility.

5

The user’s MyAdmin credentials are used to authenticate the MyGeotab API against the subject database. If the authentication fails, an error message is presented and the utility aborts.

6

The system retrieves the list of devices to add to the database from the Device List file. If the device is registered in the current database, the device is updated.

If the device does not exist in the current database, a check is performed to determine whether the device is registered in another database.

  1. If the device is already registered in another database, the system notifies the user and the device is not added to the current database.
  2. If the device is not registered in another database, the device is added to the current database and the properties are updated based on the values in the Device List file.

scroll-up