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
May 2023
Revision history
Version | Date | Change |
1.0.0 | 2022-12-30 | First release for this version. |
1.0.1 | 2023-03-09 | Configuration file section improvements. Importing fuel transaction steps improvements. |
1.0.2 | 2023-04-27 | Added The Add-In and the How to access it sections Made some general improvements |
2.0 | 2023-05-05 | Updated the document style and updated content to adhere to the style guide. |
2.1 | 2023-09-22 | Made the version 4.1.0 updates like the menu image change and the import image changes. |
2.2 | 2024-02-27 | Added the FAQ section. |
Introduction
The Fuel Transaction Import Add-In allows users to import fuel fill-up transactions supplied by a fuel card provider into a MyGeotab database.
References
- The Configuration file git repo is provided as a reference for the configuration file. The repository should provide all the necessary information to get a new configuration file configured and functioning.
- The Fuel transaction entity (SDK) provides the backend object structure that is called in order to add the fuel transaction data. This is for any users that have more of a technical interest in the underpinning of this utility.
Installing the Add-In
To install the Fuel Transaction Import Add-In, go to MyGeotab, then follow the steps below:
- Navigate to Administration > System… > System Settings.
- On the System Settings page, select the Add-Ins tab and click New Add-In.
- In the Add-In popup window, add the following configuration:
{ "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.
Understanding the configuration file
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.
Understanding the Excel import file
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:
- A header row is expected.
- There has to be at least one device identification field which is either a licence plate (licencePlate), VIN number (vehicleIdentificationNumber), or the Geotab serial number (serialNumber). The Comments and Description fields will also be searched for device identification details if the prior mentioned options do not resolve a device.
✱ 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 |
|
Importing Fuel Transactions prerequisites
There are some prerequisites for importing fuel transactions. These include:
- A correctly structured configuration file.
- An Excel file containing the transactions to import.
- Each transaction should at least identify a device by containing either a serial number, a VIN (vehicle identification number) or a licence plate number reference in order to successfully identify the device.
✱ 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.
Importing the fuel transaction files
Follow these steps to import the fuel transaction files (refer to the image that follows).
- To select the configuration file (JSON), select the Choose file button. (1)
- Select the fuel provider from the Choose provider dropdown. (2)
- To pick the correct import file (XLS or XLSX), select the Choose file button. (3)
- If the sheet is not the first one in the workbook then change the Sheet number. (4)
- Choose the correct time zone by selecting the Reference Time zone dropdown. This should default to your user profile time zone set in MyGeotab options. (5)
- Select the Import button after the input criteria is complete to initiate the process. (6)
- In order to reset all the input fields, hit the Reset button. (7)
- The page will display the progress loading status while importing. Once this is complete, the Import Summary section will display a summary of imported, skipped, and errors.
✱ 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.
Frequently Asked Questions (FAQ)
Q: How long does it take for a transaction to be matched with the fill-up event?
Imported fuel transactions are not reflected in the database immediately. They are processed by an end of day process and will only reflect the following day. A 24 hour wait period should be assumed.
Q: What is the purpose of the Reference Time Zone field?
The Reference Time Zone field allows you to select a time zone other than the current local time zone. In other words, it allows you to import fuel transactions for other time zones or for different time periods e.g. transactions that occurred during daylight savings time and imported outside this time zone.
