User Guide
0 mins to read
Fuel Transaction Import Add-In User Guide
User Guide
0 mins to read
Learn more about the Fuel Transaction Import Add-In, which allows users to import Fill-up transactions extracted by the fuel provider’s application/service into MyGeotab. This document demonstrates how to import transactions using three different options: WEX, General Standard, and Import Fuel Provider.
For All 4.x.x Add-In Versions
April 2024
The Fuel Transaction Import Add-In allows users to import fuel fill-up transactions supplied by a fuel card provider into a MyGeotab database.
To install the Fuel Transaction Import Add-In, go to MyGeotab, then follow the steps below:
{ "url": "https://app.geotab.com/addins/geotab/addin-fuel-transaction-import/manifest.json" }
To access the Add-In, select Engine & Maintenance > Fuel Transaction Import from the MyGeotab main menu.
The configuration file is the column mapping and configuration information required to execute a successful fuel transaction import operation.
See the GitHub configuration file repository to understand the configuration file structure, its properties, and how to correctly compile it in order to successfully import fuel transaction data into the MyGeotab database system.
The configuration file must contain the column mapping and configuration to be expected in the import process and describes the Excel import file.
An example configuration file and some formatting instructions can be found in the git repo, for example, source.json.
The data JSON object in the configuration file contains the Fuel Transaction entity property fields to be imported and their column references.
The Excel import file is an Excel spreadsheet (XLS, XLSX) file supplied by a fuel card provider (or a custom file produced through some other mechanism) containing the fuel fill-up transaction data to be imported.
Some context for the Excel import file includes:
✱ NOTE: The first row is skipped as it is assumed to be a header row.
✱ NOTE: The Maximum number of transactions that will be imported per import file is 5000, so truncate your import files where necessary to below this threshold in order to succeed.
Note |
|
There are some prerequisites for importing fuel transactions. These include:
✱ NOTE: If a device does not have any of the identification references, the record will still be imported, but it will be orphaned and will not have the possibility of matching an actual fill-up event.
Follow these steps to import the fuel transaction files (refer to the image that follows).
✱ NOTE: The imported transactions will not reflect in the fuel fill-ups page report immediately. There is a post-processing action required that performs the physical matching of these transactions to the fill-ups at a later stage. Generally, the matched transactions will display the following day.
Imported fuel transactions are processed at the end of each day, and are not reflected in the database immediately. A delay of up to 24 hours should be assumed.
The Reference Time Zone field allows you to select a time zone other than the current local time zone. In other words, you can import fuel transactions for other time zones or for different time periods, such as importing transactions that occurred during daylight savings time.
Refer to this sample configuration file and then the following explanation.
Also refer to the sample Excel import file associated with this configuration.
Screenshot of the example.json file:
Screenshot of the example Excel import file:
Example describing each property and its associated setting/value.
Property | Setting/Value | Explanation | ||
Name | FuelProviderExample1 | The name property that identifies the configuration. It is the value you select in the Fuel provider dropdown menu in the Add-In after the configuration has been selected in the prior field (Select the configuration file (JSON):). | ||
unitVolumeLiters | Y | This option indicates whether the fuel volume is defined in metric or imperial units. Set to Y for metric (litres), and set to N for imperial (gallons). | ||
unitOdoKm | Y | This option indicates whether the odometer reading is defined in metric or imperial units. Set to Y for metric (kilometres), and set to N for imperial (miles). | ||
isCellDateType | N | This option indicates whether the import file column containing the date is formatted as a date type or a general (text) value. Set to Y for date type, and set to N for text. | ||
dateFormat | dd/MM/yyyy | The date format to be expected in the transaction file, based on the luxon table of tokens formatting definition. | ||
timeFormat | empty | N/A - empty | ||
currencyCodeMapped | empty | N/A - empty | ||
Data section | ||||
cardNumber | ColumnA | The column in which the fuel card number is found in the Excel spreadsheet. | ||
licencePlate | ColumnG | The column in which the vehicle licence plate is found in the Excel spreadsheet. | ||
provider | ColumnB | The column in which the provider is found in the Excel spreadsheet. | ||
cost | ColumnC | The column in which the transaction cost is found in the Excel spreadsheet. | ||
currencyCode | ColumnD | The column in which the currency code is found in the Excel spreadsheet. | ||
dateTime | ColumnE | The column in which the transaction date and/or time is found in the Excel spreadsheet. This is a special property called an Array which is demarcated by [square brackets] which can contain either one or two column references. For example, [“ColumnE”] or [“ColumnE”, “ColumnZ”], representing the date and/or the time. | ||
volume | ColumnF | The column in which the transaction volume is found in the Excel spreadsheet. | ||
odometer | ColumnH | The column in which the vehicle odometer is found in the Excel spreadsheet. |
To see how a configuration file containing multiple fuel providers is configured, refer to this link.