Support Document
12 mins to read
Automated Customer Onboarding Starter Kit
Support Document
12 mins to read
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.
User Guide
Latest Update: 2024-10-28
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 |
|
Update Devices |
|
This sample application requires:
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.
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.
✱ 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.
At a high level, the Create Database & Load Devices utility:
! IMPORTANT: Ensure the Configuration and Device List files are prepared as listed below before running the Create Database & Load Devices utility.
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.
# Configuration file for Customer Onboarding Starter Kit utility: Processor_CreateDatabaseAndLoadDevices
# Structure: <Key>,<Value>
# -------------------------------------------------------------------------
# lines beginning with '#' are comments and ignored
Key,Value
ResellerName,<ResellerName>
ResellerErpAccountId,<ResellerErpAccountId>
CustomerCompanyName,<CustomerCompanyName>
CustomerAccountAdminFirstName,<CustomerAccountAdminFirstName>
CustomerAccountAdminLastName,<CustomerAccountAdminLastName>
CustomerAccountAdminEmail,<CustomerAccountAdminEmail>
CustomerPhoneNumber,<CustomerPhoneNumber>
CustomerFleetSize,<CustomerFleetSize>
CustomerSignUpForNews,false
CustomerDesiredDatabaseName,<CustomerDesiredDatabaseName>
CustomerTimeZoneId,<CustomerTimeZoneId>
CustomerDeviceListPath,<CustomerDeviceListPath>
The table below provides descriptions for the parameters in the Configuration file.
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). |
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.
# DevicesToImport.csv
# Structure: <SerialNumber>
# -------------------------------------------------------------------------
# lines beginning with '#' are comments and ignored
SerialNumber
G92720FA10E9
G86320E39137
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:
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 — CustomerDesiredDatabaseName — 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.
|
At a high level, the Update Devices utility:
! IMPORTANT: Ensure the Configuration and Device List files are prepared as listed below before running the Create Database & Load Devices utility.
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>
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). |
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
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). |
DriverIdentificationReminderImmobilizeSeconds | 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). |
EnableBeepWhenPassengerSeatbeltNotUsed | 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). |
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.
|