RatebooksImport guide

Ratebook import guide

Target audience: Technical administrators who are responsible for uploading ratebooks to the Gensen system. We assume some familiarity with FTP, CSV files, and common networking protocols.

Background

Gensen needs current ratebooks to show up to date information and offers to drivers, sales staff and employees.

An administrator can prepare and upload a ratebook archive to keep the site updated.

When a ratebook archive is uploaded, the importer extracts vehicle and rate information from each row of the CSV files provided, outputs warnings or errors if needed, and then publishes/unpublishes rates as needed.

When setting up the process for the first time (or when making changes), you can run a test import to make sure the ratebooks are valid. A test import will output a report that indicates any errors that were encountered, and will not replace any existing ratebooks.

What you need to get started

  • Before you can start uploading and importing ratebooks, you need to have access to the FTP server that has been set up for you. Please see our guide on connecting to the server on the Connecting to FTP page.

  • Access to the email notifications to receive reports and notifications from the import system. Contact us at support@gensen.software if you need to be added to the notification list.

Instructions

  1. Format your rate file(s) according to the ratebook data specification.

  2. Choose one of the following methods:

    • Create a ZIP archive (.zip) that includes multiple .csv files.
    • Prepare a single .csv file containing all rates.

    We recommend using a recognisable name for your upload file something identifiable, such as your-company-name-ratebooks.yyyy-mm-dd.zip. This will help with auditing and troubleshooting.

  3. Upload the file to the designated ratebook upload folder:

    • Default ratebooks folder: to replace all existing ratebooks with the new ratebook (applicable for single-ratebook sites only)
    • test: if you only want an error report without publishing the ratebooks
    • add: if you want to add a new ratebook to the existing ratebooks (for multi-ratebook sites only)
    • replace: if you want to replace all existing ratebooks with the new ratebook (for multi-ratebook sites only)

  4. Expect an email notification to say the import has started, followed by an email report detailing the results of the import. An import will typically take between 1–15 minutes to complete.

  5. If there are errors, fix any issues and repeat from step 1.

  6. On success, the new ratebooks will be published live, all previous ratebooks will be archived (unless you are adding a new ratebook on a multi-ratebook site), and any server caches will be flushed, as necessary. (Excepting test imports where no action will be taken.)

  7. When setting up for the first time or making changes to your processes, check the site to make sure the new ratebooks are live and that vehicle and rate data match your expectations. If you don’t have access to the site, please contact us.

Automating this process can help prevent manual errors and ensure ratebooks are kept up to date.

Integration of purchase price or residual value data

If you don’t have access to purchase price or residual value data, we may in some cases be able to merge this data for you after import. Please speak to your account manager for more information.

Sample report output

Example 1: Successful import

===============================================================================
  Import summary
===============================================================================

Ratebooks imported: 9
Total rates imported: 900 (on average 100 per ratebook)
We added 173 new vehicle derivatives to the existing ones.
218 pre-existing vehicle derivatives were updated.
We added 2 new vehicle models to the existing ones.

Previous ratebooks will be archived.
Triggering any post import actions for ratebooks (102, 103, 104, 105, 106, 107, 108, 109, 110).
Finished.


View error log: https://www.example.com/log-file.txt

The linked error log will contain any errors and warnings that occurred during the import.

Example 2: Import with an error

┌─────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Line number │ Warnings or errors                                                                                     │
├─────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 245         │ Error: 'insurance_group': value 'N' must be between 1 and 50 (inclusive)                               │
│             │ Error: 'insurance_group': value 'N' doesn't match pattern '/^\d{1,2}[A-Z]?$/i'                         │
│             │ {"cap_code": "IEGR30   6WDTA4", "cap_id": "100680", "derivative": "Diesel Station Wagon 3.0 TD 6Dr     │
│             │ Auto", "fuel_type": "Diesel", "make": "Ineos", "model": "Grenadier", "model_year": "2022",             │
│             │ "vehicle_id": "100680"}                                                                                │
├─────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤

Interpretation: The insurance group is set to N for this vehicle on line 245 of the supplied file, which is not a valid value. This is an error, so the vehicle and rate will not be imported.

Potential fix: Check the insurance group value for this vehicle in the source data and make sure they are valid. If the insurance group is not known, you can leave the field blank.

Example 3: Import with a fuel type error

┌─────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Line number │ Warnings or errors                                                                                     │
├─────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 1904        │ Error: 'fuel_type': has an unknown value 'Gasoleum Hybrid'                                             │
│             │ {"cap_code": "MAM000EXL5HR A", "cap_id": "102275", "derivative": "125kW R-EV Exclusive Line 5dr Auto   │
│             │ Hatchback 1sp EU6 MY23", "fuel_type": "Electric Petrol REX", "make": "Mazda", "model": "MX-30",        │
│             │ "model_year": "2023", "vehicle_id": "294677"}                                                          │
├─────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤

Interpretation: The fuel_type field has an invalid value for this row (line 1904 in the supplied file). This is an error, so the vehicle and rate will not be imported.

Potential fix: Check the valid fuel_type mappings in the ratebook data specification and make sure the value is correct. If this is a fuel type we don’t support, we may be able to add it for you in the future.

Example 4: Other warnings and notices

┌─────────────┬────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Line number │ Warnings or errors                                                                                     │
├─────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 1186        │ Notice: Using 'weighted_mpg_wltp' column for mpg (combined_mpg_wltp* expected).                        │
│             │ Notice: Using 'co2_weighted_comb' column for CO2 (co2_comb* expected).                                 │
│             │ {"cap_code": "MAM000MKO5HR A", "cap_id": "102276", "derivative": "Hatchback 125kW R-ev Makoto 5Dr      │
│             │ Auto", "fuel_type": "HybridPetrolElectric", "make": "Mazda", "model": "MX-30", "model_year": "2023",   │
│             │ "vehicle_id": "102276"}                                                                                │
├─────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 1297        │ Notice: Omitted some repeated errors like 'A valid range must be given for ULEV car...'.               │
├─────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ 1859        │ Warning: Battery EVs should have fuel economy (EC) rating                                              │
│             │ {"cap_code": "PE2000AV 5EE A  3", "cap_id": "103135", "derivative": "E-2008 Electric Estate 115kW      │
│             │ Active 54kWh 5Dr Auto", "fuel_type": "Electric", "make": "Peugeot", "model": "2008", "model_year":     │
│             │ "2023", "vehicle_id": "103135"}                                                                        │
├─────────────┼────────────────────────────────────────────────────────────────────────────────────────────────────────┤

Notice: Using ‘weighted_mpg_wltp’ column for mpg…

Interpretation: WLTP columns are intended for certain vehicle types only. For example, we would expect weighted_mpg_wltp to be used for plug-in hybrids, but not for battery electric vehicles or mild hybrids.

Potential fix: Check the WLTP data mapping and fuel types are correct. Sometimes, data providers may use the wrong WLTP column for a vehicle type and you may not be able to fix this.

If you are confident you are using the correct column mapping for WLTP data we can switch off these WLTP validation checks entirely, or you can ignore it.

Notice: Omitted some repeated errors like…

Interpretation: The same error may occur multiple times for the same vehicle. We only show the first few occurrences *of the same error to avoid cluttering the output.

Potential fix: Check your mapping for the field indicated for any systematic errors.

Warning: Battery EVs should have fuel economy (EC) rating

Interpretation: Battery electric vehicles should have a fuel economy rating. This is a warning, so the vehicle and rate will still be imported, but Gensen will omit to show this data in the user interface, and may have reduced capability for calculating fuel costs.

Data specificationImport channels