For All 4.x.x Add-In Versions

April 2024

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

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

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

1. Navigate to Administration > System… > System Settings.
2. On the System Settings page, select the Add-Ins tab and click New Add-In.
3. 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 configuration file support 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.

Example

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:

1. A header row is expected.

✱ NOTE: The first row is skipped as it is assumed to be a header row.

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

Importing Fuel Transactions prerequisites

There are some prerequisites for importing fuel transactions. These include:

1. To select the configuration file (JSON), select the Choose file button. (1)
2. Select the fuel provider from the Choose provider dropdown. (2)
3. To pick the correct import file (XLS or XLSX), select the Choose file button. (3)
4. If the sheet is not the first one in the workbook then change the Sheet number. (4)
5. 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)
6. Select the Import button after the input criteria is complete to initiate the process. (6)
7. In order to reset all the input fields, hit the Reset button. (7)



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

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, you can import fuel transactions for other time zones or for different time periods, such as importing transactions that occurred during daylight savings time.

Appendix 1

Configuration File Example

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 Explanations

Example describing each property and its associated setting/value.

FuelProviderExample1 Explanation

Multiple Fuel Provider Example

To see how a configuration file containing multiple fuel providers is configured, refer to this link.