User Guide

Latest Update: 2021-05-20

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:

Prerequisites

This sample application requires:

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

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.

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.



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

Configuration File

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>

Parameter Descriptions

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

Device List File

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

Run the Create Database & Load Devices Utility

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. If the device is already registered in another database, the system notifies the user and the device is not added to the current database. 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.

Update Devices

At a high level, the Update Devices utility:

4. Connects to an existing MyGeotab database; and
5. 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.

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.

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.

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: