Fuel Transaction Import Add-In

Learn about the Fuel Transaction Import Add-In, a configuration-file based method for bulk importing fuel transactions into MyGeotab.

The Fuel Transaction Import Add-In allows you to import fuel fill-up transactions supplied by a fuel card provider into your MyGeotab database. It uses a configuration file to map the columns in an Excel import file to the fuel transaction fields MyGeotab expects.

Note: If you don't already have fuel transactions flowing in from a connected fuel card provider, you can also import fuel transactions directly on the Fuel Transactions page without a configuration file. See Bulk importing fuel transactions.

Installing the Fuel Transaction Import Add-In

Learn how to install the Fuel Transaction Import Add-In in MyGeotab.

Before you begin: To add an Add-In, you must have the Change system settings and Administer Add-Ins security clearances.

Navigate to System > Settings.
Select the Add-Ins tab.
Click + Add-In.
In the Add-In popup window, replace the placeholder text with the following configuration:
{
"url": "https://app.geotab.com/addins/geotab/addin-fuel-transaction-import/manifest.json"
}
Click Done.

To access the Add-In, select Sustainability > Fuel Transaction Import from the MyGeotab main menu.

Fuel Transaction Import Add-In configuration file requirements

Review the configuration file structure required by the Fuel Transaction Import Add-In.

The configuration file is a JSON file that defines the column mapping and import settings required to successfully import fuel transaction data using the Fuel Transaction Import Add-In. It describes the structure of your Excel import file, so the Add-In knows which column contains which piece of data.


Property	Description
Name	The name that identifies the configuration. This is the value you select in the Fuel provider dropdown after selecting the configuration file in the Add-In.
unitVolumeLiters	Whether the fuel volume in the import file is metric or imperial. Set to `Y` for metric (liters), or `N` for imperial (gallons).
unitOdoKm	Whether the odometer reading in the import file is metric or imperial. Set to `Y` for metric (kilometers), or `N` for imperial (miles).
isCellDateType	Whether the date column in the import file is formatted as a date type or a general (text) value. Set to `Y` for date type, or `N` for text.
dateFormat	The date format used in the import file (for example, `dd/MM/yyyy`).
data	A set of column references that map each required or optional fuel transaction field (such as `cardNumber`, `cost`, `currencyCode`, `dateTime`, `volume`, `odometer`, `licencePlate`, and `provider`) to a column letter in your Excel file.

Note: Only the dateTime and location properties accept array-type data (for example, ["ColumnE", "ColumnZ"] to represent separate date and time columns). All other data properties accept only a single column reference, not a literal value.

Example configuration file showing provider name, unit settings, date format, and column mapping properties.

To configure multiple fuel providers in a single file, nest an additional provider object for each provider inside the providers array.

Fuel Transaction Import Add-In Excel file requirements

Review the file and data requirements for the Excel file used with the Fuel Transaction Import Add-In.

File requirements

File format: XLS or XLSX
A header row is expected. The first row is always skipped, since it's assumed to be a header row.
Maximum number of transactions per import file: 5,000. Split larger files to stay below this limit.

Required data

Each transaction must include:

A UTC date and time of the transaction
Coordinates (latitude, longitude)
A vehicle identifier matching at least one of the following telematics device fields: VIN, serial number, license plate, or description
Volume, in liters
Cost
ISO currency code

Note: If a vehicle identifier field doesn't yield a device match, the system checks the Comments and Description fields in the file for device identification information.

Important: If a transaction doesn't contain any identification reference, the record is still imported, but it will be orphaned and won't have the possibility of matching an actual fill-up event.

Example

Importing fuel transaction files using the Add-In

Learn how to use the Fuel Transaction Import Add-In to import fuel transaction files into MyGeotab.

Before you begin, prepare your configuration file and Excel import file according to Fuel Transaction Import Add-In configuration file requirements and Fuel Transaction Import Add-In Excel file requirements.

Select the configuration file (JSON) using the Choose file button.
Select the fuel provider from the Fuel provider dropdown.
Select the import file (XLS or XLSX) using the Choose file button.
If the data isn't on the first sheet of the workbook, update the Sheet number field.
Select the Reference Time zone that applies to the date and time values in your file.
This defaults to your user profile time zone set in MyGeotab options. Use this field to import transactions for a different time zone, or for a different time period such as one that occurred during daylight saving time.
Click Import to begin importing your fuel transactions, or click Reset to clear all the input fields.

Fuel Transaction Add-In input criteria and progress sections, with each step numbered.

The page displays a progress status while importing. Once complete, the Import Summary section displays the number of transactions imported, skipped, and errors.

Note: Imported transactions aren't reflected on the Fill-ups page immediately. A post-processing step matches the transactions to fill-ups at a later stage, and generally completes within 24 hours.