User Guide
0 mins to read
Custom Telematics Devices and MyGeotab User Guide
User Guide
0 mins to read
Learn how to integrate custom telematics devices onto the MyGeotab platform, access additional resources to support custom telematics integration, and browse frequently asked questions about the integration process and device administration.
Reseller and Partner Guide
January 2023
Introduction
This document provides a high level overview of the process Resellers and Partners need to follow to integrate Custom Telematics Device data onto the MyGeotab platform.
MyGeotab accepts data logging from both Geotab GO devices and telematics devices not manufactured by Geotab (Custom Telematics Devices), at the same time. MyGeotab provides a unified interface, allowing fleets to manage vehicles and other operations, regardless of the telematics hardware that is installed.
Custom Telematics Device integrations are made possible by sending device data to Geotab’s Data Intake Gateway APIs. Custom Telematics Devices are managed using the MyAdmin APIs. This is illustrated in the following application integration workflow:
Custom telematics device serial numbers
Each custom telematics device requires a unique Geotab serial number. Geotab serial numbers for custom telematics devices are generated as needed by the integrator using the ProvisionDevice MyAdmin API calls. A Product ID that is unique to your hardware will be provided by Geotab to use with this API call.
Your telematics unit will likely have an IMEI or other unique identifier, but this is not used by the MyGeotab platform or Data Intake Gateway (DIG). Integrators must maintain a mapping of device IMEI/serial number to Geotab serial number so that data for your telematics unit can be sent to the correct MyGeotab asset using DIG. The below diagram shows an example of how device identifiers and serial numbers are used in each environment.
Integrator resources
When building the integration, the following resources are required::
Integration process
Integrating Custom Telematics Devices with MyGeotab requires the use of Geotab APIs and collaboration between Resellers and/or Partners and the Geotab Solutions Team.
Reseller Partners and/or Integration Partners
1 | Fill out the Custom Telematics Device Information Request Form, providing as much detail on the integration you wish to build as possible. Once you submit this form, a member of Geotab’s Solutions team will contact you and take you through a vetting/onboarding process. Once this is complete, you will be provided with a Product ID to use to create serial numbers to allow your Custom Telematics Device to exist in the MyGeotab environment. |
1a | If you do not have an ERP account set up with Geotab yet, submit the Third-Party Integration Hardware Request Form which will have one created. You will need to provide company information and can request hardware, if needed. Geotab can also provide a promo code allowing for free testing of 5 Custom Telematics Devices (CTDs) for 3 months. To request this please use the final “additional comments” on the Form to specify you would like a promo code for 5 CTDs for 3 months. |
2a | If you are an existing Reseller Partner and you have Custom Telematics Devices to integrate into a customer’s database:
Please refer to the Integrator as Reseller Billing Process Flow for more information on integration workflow as a Reseller. |
2b | If you are a Integration Partner beginning the implementation process for a Custom Telematics Device integration:
Please refer to the Partner to Reseller Billing Process Flow for more information on integration workflow as a Partner. |
3 | Contact your assigned member from Geotab’s Solutions team to assist with adding the necessary MyAdmin API roles to your MyAdmin accounts. Please see the Service Account Best Practice section for additional information. |
4 | Develop software that authenticates via MyAdmin, then provisions custom telematics devices and sends their data points to MyGeotab. Note that device administration, specifically the software to provision devices mentioned above, is completed via the MyAdmin API. Additionally, device data must be sent via the Data Intake Gateway. For more information, please refer to the Data Intake Gateway Guide. |
Solutions team
Geotab’s Solutions team will:
- Respond to the request submitted to the Custom Telematics Device Information Request Form and work to provide necessary information and onboard the solution.
- Grant MyAdmin and Data Intake Gateway (DIG) API privileges to the account(s) used for managing Custom Telematics Devices.
- Provide a Product ID once onboarding is complete, which is to be used to provision your device using the ProvisionDevice MyAdmin API method.
Service account best practice
As best practice, integrators should set up two service accounts:
- One account for device management (provisioning, managing plans, terminating devices, etc.) with the Device_Admin, and Third-Party-Integrator roles using the MyAdmin API.
- A second account for sending custom telematics data with the DIG-Access role using DIG.
This ensures that the account that sends data to DIG is isolated from other service accounts that would interact with the MyAdmin API. In situations where Resellers are working with Integrators and/or Partners, this best practice can be used to allow Resellers to control device management, while allowing Integrators and/or Partners to handle sending custom telematics data.
✱ NOTE: The required device management roles are still required for a reseller’s account when provisioning devices through MyAdmin.
Termination process
A Custom Telematics Device is terminated using the TerminateDeviceBilling MyAdmin API method.
✱ NOTE: Terminating a Custom Telematics Device using the API only stops billing. You must also stop sending telematics data to complete termination. Billing will be restarted automatically if you continue to send data after terminating billing.
API usage logging best practices
Custom Telematics Device (CTD) integrations rely on the MyAdmin API to manage devices and the DIG API to push device data to Geotab systems. To maintain data privacy, Geotab has limited visibility of the records submitted through the DIG APIs. We recommend that integrators maintain logs of the records submitted to DIG to aid with support and troubleshooting that may be required. We recommend storing the following:
- Timestamp when the API call was made
- Record details (type of record, serial number)
- Response from API (notably the Data and Error)
Use the InvalidRecords workflow with DIG to check for rejected records. Log responses from this endpoint as well.
FAQ
How can I register a new MyAdmin account?
Navigate to https://myadmin.geotab.com/login/register to create an account. Refer to the for more information.
What account type should I make my new MyAdmin account?
Use Reseller or Partner account types for Custom Telematics Device integrations. Please choose what is applicable based on your professional relationship with Geotab.
How do I add roles to my MyAdmin account?
After you submit the Custom Telematics Device Information Request Form you will be contacted by a member of Geotab’s Solutions team who will assist with adding roles to your MyAdmin account.
What are these MyAdmin roles needed for?
These MyAdmin roles are needed for the following purposes:
- DIG-Access – Push data through the Data Intake Gateway
- Device_Admin – Terminate custom telematics devices
- Third-Party-Integrator – Provision custom telematics devices
What is a Product ID?
A Product ID is a unique identifier provided by Geotab to the Integrator which enables the Integrator to send data to the MyGeotab platform. This also allows Geotab to identify the Integrator of each Custom Telematics Device.
Why do I need a Product ID?
A Product ID is needed to provision serial numbers.
A serial number is needed for each Custom Telematics Device. The serial number is similar to a standard Geotab GO device serial number. It consists of a 12-digit alphanumeric string and contains two pieces of important information:
- The type of device; and,
- The unique identifier of the device.
For example, a serial number for a Custom Telematics Device looks like this:
*C1-800-000-0001*
where C1 indicates the custom device type, and 800-000-0001 is the unique identifier.
Once these serial numbers are made, they can be added to a MyGeotab database and data can be associated with that serial number in MyGeotab.
Can I use one Product ID for multiple devices and integrations?
A new Product ID is required whenever a new integration is built or when a new device model is integrated. This allows Geotab to better track and understand various custom telematics integrations.
Does it cost money to build a Custom Telematics Device integration?
There is a monthly fee associated with each active Custom Telematics Device. For more information on pricing, please contact your Partner Account Manager or Business Development Manager.
Geotab will support and consult for the partners’ development of a new integration at no charge.
Where do I get help with building my integration?
It is recommended that Integrators read the documents listed under Integrator Resources. After the Custom Telematics Device Information Request Form is submitted, a member of Geotab’s Solution engineering team is assigned to answer questions and provide resources as needed. Additionally, you can reach out to integrations@geotab.com for technical assistance.
What is a CustomDevice and a CustomVehicleDevice?
These two terms refer to how the telematics device will be presented on MyGeotab’s vehicle page. A CustomVehicleDevice allows for more fields to be associated with the device. The properties associated with these options are available on the MyGeotab SDK site, as well as additional information about Geotab’s device options.
Where can I learn more about the different Geotab record types?
Please see the DIG API Reference section of the Data Intake Gateway Guide, which includes a link to the OpenYAML specification for all the supported record type models, and the appendix of DIG API Endpoint Workflow Guide, which provides additional context and content documentation for some record types.
What is the Authenticate MyAdmin API method?
ApiUser = Authenticate(string userName, string password)
This method authenticates the user with the MyAdmin API and returns an ApiUser object. It requires the username and password of a MyAdmin account with MyAdmin API privileges. (The syntax is also available in the MyAdmin reference API)
- string userName — The custom telematics integration email address to authenticate with.
- string password — The custom telematics integration password to authenticate with.
Note that sessions will expire after a period of time. Calling a method with an expired sessionId will throw a SessionExpiredException. If this occurs, call Authenticate to obtain a new sessionId.
Below is an example of a request made to the MyAdmin API to authenticate a user:
Request
curl --request POST \
--url https://myadmin.geotab.com/v2/MyAdminApi.ashx \
--header 'content-type: application/json' \
--data '{
"method": "Authenticate",
"params": {
"username": “userName”,
"password": “pw”
}
}’
✱ NOTE: When performing the Authenticate call, we expect you to use the POST HTTP method to pass sensitive username and password information to Geotab.
If authentication is successful, you will see a response similar to the following:
Response
{
"result":{
"userId":"24k380h7-a472-947f-33ee-d4b1lo5e12b8",
"sessionId":"083c6dfb-3e3a-4fea-a3db-1fa546062ee4",
"lastLogonDate":"2017-01-25T15:21:03.723Z",
"accounts":[
{
"accountId":"TEST01",
"currency":{
"code":"USD",
"name":"US Dollars"
}
}
],
"roles":[
{
"comments":"Special user for MyAdminApi",
"name":"MyAdminApiUser"
}
],
"name":"testuser@geotab.com"
}
}
✱ NOTE: The sessionID expires in approximately 20 minutes. Receiving a "SessionExpiredException" error as a result of a standard API call will require you to re-authenticate.
What are the ProvisionDevice/ProvisionDeviceToAccount MyAdmin API method
These methods are used to provision new devices in MyAdmin and generate new serial numbers for your devices. You will have to use only one of them:
ProvisionResult = ProvisionDevice (Guid apiKey, Guid sessionId, int productId, str promoCode)
This is a provisioning call that adds a device to MyAdmin and generates a serial number under the user’s ERP to be used for referencing or viewing the device in MyGeotab. (The syntax is also available in the MyAdmin reference API.)
ProvisionResult = ProvisionDeviceToAccount (Guid apiKey, Guid sessionId, int productId, str erpNo, str promoCode)
This is a provisioning call that adds a device to MyAdmin under the specified ERP account number to be used for referencing or viewing the device in MyGeotab. (The syntax is also available in the MyAdmin reference API.)
When the user in MyAdmin that will make this call is under more than one ERP account (or if you are not sure) use the ProvisionDeviceToAccount so you can specify the ERP account in the call.
✱ NOTE: Either of these methods only needs to be run once for each Custom Telematics Device you wish to integrate into MyGeotab.
Parameter description
Property | Description |
Guid apiKey | Based on the userID, the key used to authenticate the session. This is the result.userId property from the Authenticate response above. |
Guid sessionId | Identification used with the apiKey to authenticate the session. This is also found in the result.sessionId property from the authenticate response above. |
int productId | |
str erpNo | Account number for new activation. Only for ProvisionDeviceToAccount method |
str promoCode | Optional. Applies a promo code to modify pricing if available. |
See MyAdmin SDK for more details.
The following is an example of parameters that can be used to call ProvisionDevice within MyAdmin:
Request
curl --request POST \
--url https://myadmin.geotab.com/v2/myadminapi.ashx \
--header 'Content-Type: application/json' \
--data '{
"method": "ProvisionDeviceToAccount",
"params": {
"apiKey": "24k380h7-a472-947f-33ee-d4b1lo5e12b8",
"sessionId": "f684812e-377f-478f-a813-1eef7d25e1a2",
"productId": 10015,
"erpNo": "DEMO01"
}
}'
If successful, the request will return a result similar to:
Response
{
"result": {
"isSuccess": true,
"serialNo": "AB0C12DE3456"
}
}
The returned serialNo value can now be used to add a vehicle to your MyGeotab database using the steps below.
- Select Vehicles & Assets from the main menu.
- Click the Add button and select the Add asset button from the dropdown menu.
- Fill in the Serial number field with the serial number you received at the end of the previous section.
- Fill in the Description field with a value that will help you identify this device.
- Click OK to finalize your input.
How do I verify that the integration was successful?
Once your API calls are returning successfully, you can provide the end user with the serial number (the number that was returned by the ProvisionDevice method) for their Custom Telematics Device.
The end user or reseller can verify that your integration is operational by logging in to their MyGeotab database and doing the following:
- Adding a custom telematics device to a database:
- Navigate to Vehicles & Assets, select the Add dropdown, then select the Add asset option. On the following page, input the device serial number and click OK.
- Verifying the Trips History:
- Trip logs can be verified by navigating to Map > Trips History. Select a vehicle from the list or use the search box to filter for the relevant vehicle. The integration is successful if the user can see trip information for the vehicle with the custom telematics device installed.
- Verifying Status Data:
- If you are sending Status Data from your custom telematics device to MyGeotab, you can view this data by navigating to Activity > View Accidents & Log Data and using the filters to find your custom telematics device records.
