Support Document

0 mins to read

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:

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

    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.

      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 — 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.
    5. Update Devices

      At a high level, the Update Devices utility:

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