Other Integrations: IMEI Interfaces

IMEI Interfaces

International Mobile Equipment Identity (IMEI) interfaces are used to collect information such as odometer readings and vehicle postition from a telematic device that is installed in a vehicle. Catch-e has created a web-service to retrieve odometer readings for these vehicles from a scheduled service, or on the fly in the Contracts / Maintenance tab. Contact Catch-e: support@catch-e.com.au or phone us on +61 03 9017 3520 if you wish to activate this interface.

IMEI Button

The International Mobile Equipment Identity (IMEI) button can be used to get the latest odometer reading available where the contract has an IMEI device fitted. A scheduled service may also be getting readings on a regular basis - Refer IMEI Interfaces.

The button is displayed on the Contracts / Maintenance tab if the following conditions are met:

1. User is a backoffice user.
2. IMEI field on the Contracts / Contract screen is populated.
3. IMEI status flag on the Contracts / Contract screen is set to 'active'.
4. The gbcontrol fm->fleetraklogin exists.

Clicking the button will call the fleetrak::getOdometers method for this contract, and collect the current Odometer data from Fleetrak.
If the Odometer data is not duplicated new fm_maintenance record is created store it.

Possible warnings are:

1. "Cannot update odometer at this time as this contract is in use by the user 'xyz'"
2. "The odometer reading is up to date, nothing to add!"
3. "The IMEI number is not recognised! Please enter the correct IMEI number on the Contract page. You will also need to change the IMEI status to 'active' before you try again."

** Setup

1. Advise Catch of your FleetTrack login. It will then be recorded in your Global Controls:
2. Record the vehicle IMEI number's on the Contracts / Contract screen in the "IMEI" field (bottom right of the screen) and set the "IMEI Status" to "Active".
3. Confirm or create the VMRS code "FLEETRAK" in Controls / Maintenance / VMRS Codes. When IMEI odometer readings are recorded, this VMRS code is used to populate the odometer description field as: VMRS Description + Fleetrak address location + Time. These odometer records are are always given a odometervalidflag entry of "valid".

IMEI Status Description

• Active — When adding an IMEI number to a contract, select "Active" for the IMEI Status.
• Invalid — The IMEI status will change to "Invalid" if the scheduled web service did not find an Odometer reading for that contract. We can create an exception report to find contracts with an "Invalid" IMEI Status if needed.
• Inactive — The web service will not look for or add any readings for contacts with an IMEI status of "Inactive". You might want to set the status to "Inactive" at the end of a vehicle's term when no more readings are required. For example, the Transponder unit might have been transferred to a different vehicle and will then return unexpected (and confusing) readings.

Fleetrak Interface Description

Fleetrak is a telematics company that provides vehicle transponders and GSP tracking of Odometer Readings, Vehicle Location and other data inputs.

This web service can be run via the scheduler to get regular odometer readings (e.g. weekly, monthly etc) from Fleetrak's database. It can also be run on the fly by clicking on the "IMEI" button in the Contracts / Maintenance screen.

fm → fleetrak → getOdometers

This service calls the Fleetrak web service, getVehicleCurrentStatus, for each contract that has a value in the field that is not suspended.

The Fleetrak interface will try to get readings for IMEIs with a status of "Active" or "Invalid". If a reading is found it will re-set the IMEI Status to "Active". If no reading is returned, the IMEI Status will be re-set to "Invalid".

If a reading is found, the Fleetrak service returns adds this odometer reading to the Contract / Maintenance screen as an "ODO" transaction. If an "ODO" transaction already exists with the same date and odometer value, then no new (duplicate) transaction is created.

Fleettrak stores the Odometer reading in miles, the interface converts this into kms at the following rate: 1 mile = 1.609344 kilometres.

Interface To Interface

The Card Services / Interface tab stores the summary details for each interface. You can enter or update specific card service interface details here.
E.g an interface for importing electronic fuel data from a fuel card supplier.

Visit Card Interfaces for a directory of the available interfaces with a link to detail page for each one.

Header

• Card Interface (Lookup) — Lookup or enter an interface short code, e.g. "BP". Go to the Card Interfaces for a list of available interfaces. Each interface has a detail page.

Fields

• Interface ID (Num) — Unique system generated ID, not editable.
• Interface (Lookup) — Displays the interface code. Lookup or enter an interface short code when editing, e.g. "BP". Go to the Card Interfaces for a list of available interfaces. Each interface has a detail page.
• Supplier (Lookup) — Enter the supplier code. Only suppliers classified with a type of 'Card Services' are allowable. Go to Suppliers for set-up details.
• Interface Type (List) — Usually set to 'Card Services'
• Description (Text) — A stored description of the interface. This usually notes the data file format that is required.
• Description Import Type (List) — This is used to determine how the description in the fmmaintenance file is built and limited to the following values: ::Prefix - imported description is added as a prefix to the description looked up from the fmvmrscodes table. ::Suffix - imported description is added as a suffix to the description looked up from the fmvmrscodes table. ::Replace - imported description replaces the description looked up from the fmvmrs_codes table, unless it is blank. ::Ignore - imported description is ignored. ::NOTE: The description also contains the Site Location, and the Transaction Time if they are set.

Claims Set-up

The Card Services / Interface tab is also used to create the mapping used to manage which classes can be selected in the Contracts / Claim tab.
The recommended entries are below.

Interface To Mappings

The Card Services / Mappings tab is used to link supplier's product codes with Catch-e Posting Classes (cost categories) and VMRS Codes (codes used to describe the service carried out).

Click on the New button on the bottom right of screen to enter new records.
Existing records can be edited and deleted by first clicking on the check box on the row.

Header

• Card Interface (Lookup) — Lookup or enter an interface short code, e.g. "BP". Go to the Card Interfaces for a list of available interfaces. Each interface has a detail page.

Filter

• Class (List Box) — Default is '--All--'. Select a class to filter the mapping table on.

Fields

• # (Check Box) — Select to activate Edit or Delete buttons for the row.
• Product Code (Text (30)) — The code used by the supplier and in the exact format which it appears in the electronic interface file supplied by the external supplier. For the REIMBURSE interface, use the Catch-e VMRS descriptions. This will keep the data consistent. For the CLINK interface use the Product code 'TOL', as CityLink do not pass across product codes. For the FLEETCOR interface use the Product Description as the Product Code.
• Description (Text) — Enter the product description, usually the description used by the supplier.
• Class (Text) — Enter the Posting Class the product should be classified against.
• Description (Text) — Displays the selected Posting Class description.
• VMRS (Text) — Enter the VMRS code used to describe the details of the transaction.
• Description (Text) — Displays the selected VMRS description.
• Fee (Numeric) — Enter a value here if you would like to add an internal fee to particular product transactions. This can be a negative value. When the fuel file is being processed in Fleet / Card Services / Transactions, this fee value will not be visible. When the file is ‘Posted’, the value of the internal charge will be added to the selected row when it is processed into the Maintenance table. This means the Contracts / Maintenance tab will display the sum of the original value from the file, plus this extra fee. You can also add an uplift fee at client level, this is stored in Clients / Card Fee "Fee" for the required interface/product combination. If a Clients / Card Fee "Fee" exists it will use that value for the uplift, otherwise it will use this 'Mapping' "Fee".

Interface Query

This type of scheduled job allows you to extract data with a User Defined Query and save it in a file in your DMZ area. You can then access the file using utilites such as FTP if you have been granted permission, or use it as the basis of an automated interface between Catch-e and your external systems.

If an external process will be polling for this file, it can be very useful to combine this job with dmzMoveFile to ensure the file is completely built before making it available using the following steps:

1. Use an Interface Query job to build the file using a temporary filename, or placing it in a temporary sub-folder
2. Use dmzMoveFile as a child job to move / rename the file to the correct place / name expected by the external process
3. Use dmzUploadFile as a child job to upload the file to the external sftp location (if required)

Parameters

The Scheduler Job Screen screen has the following input parameters:

• Query ID — Is the queryid of the required gbqueries record. A search icon is provided to find the required query. Query ID cannot be blank. Attachment Format Choose the required format for the attachment file from 'Office(xlsx))', 'Office(xls)', , 'Text(csv)', ‘Text(txt)’ or 'XML'.. 'Office(xlsx))' is the default value and saves with an xlsx suffix. Further parameter variables are hidden if this format is chosen. 'Office(xls)'Format) enables you to customiseFormat) the presentation of the generated files. Further parameter variables are hidden if this format is chosen. 'Text(csv)' generates a text delimited file and uses the CSV, Comma Separated Variable, format. 'Text (txt)' generates a text delimited file and uses the Text (Tab Delimited) format. 'XML' generates an XML based file. Office(xls) and office(xlsx) reports that contain more than 65,500 individual rows will be automatically converted to Text(csv) format.
• Column Headings — Text If you turn this on, the first row of the output will contain column headings.
• Format Column Headings — Text used in conjunction with Format Column, if you turn this on, the column headings will be formatted by replacing underscores with spaces and words will be capitalised.
• Separated By — Text Sets the character(s) used to separate columns / fields in the output. E.g. using the option '\ ' will create a pipe separated file. In the special case where {tab} is being used for the separator, all tabs in the data will be replaced with white spaces to conform to the IANA standard for TSV files.
• Text Delimited By — Text Sets the character used to delimit columns / fields in the output if they contain special characters. Special characters include double quotes, newlines, and this delimiter character itself. The 'none' option will add no delimiters and is useful when the query itself adds the delimiters e.g. creating a custom interface file to specification.
• Omit Final Line Break — Text If you turn this on, there will be no line break after the last row of output. This is required by some third party software for import purposes. This is turned off by default.
• Singleton Tags — XML If you turn this on, tags with empty values will use the singleton style format e.g. as opposed to .
• Indent Size — XML Sets the indentation (whitespaces) used, this must be an integer between 0 and 9. The default is 2.
• Newlines — XML If you turn this on, all lines will end in a newline character. This improves readability when viewing or printing the XML from non-specialized text editors. File Name Enter the file name you want to use for this file. The file extention needs to be entered as part of the name. The setting you use for the "File Name Timestamp" check box affects the filename that is generated by the job. Visit File Name Timestamp for examples of how various "File Name" and "File Name Timestamp" combinations would work. File Name Timestamp Check to append the file creation timestamp to the file name to make it unique. Add the #timestamp# placeholder to your file name to control the location of the timestamp. Eg. The following file names would yield the following results; 'inventory.xlsx' would create as inventory.xlsx.20201016112943 '#timestamp#inventory.xlsx' would create as 20201016112943inventory.xlsx # #date##time#filename would create as 20210528135144inventory # #date#filename#time# would create as 20210528inventory135144 # #date##time#filename.csv would create as 20210528135144inventory.csv # #date#filename#time#.csv would create as 20210528inventory135144.csv Go to File Name Timestamp for a complete range of file naming examples. Note: The #timestamp# placeholder will only generate if "File Name Timestamp" is checked
• DMZ Subfolder — Enter the folder name you want the created file to be stored in. E.g. 'reports' Folders can be nested. E.g. 'reports/out' If the folder does not exist, it will be created the first time this job is run. If this field is blank, the file will be stored in the DMZ home folder.
• Zip File Name — If you enter the name of a zip file, the interface file will be added to it. If the zip doesn't exist it will be created. If Zip File Name doesn't have a file extension, it will be given the extension '.zip', otherwise it will use the exention provided. If the interface file already exists in the zip file, it will be replaced. Once it has been added to the zip file, the interface will be deleted.

Validations and Alerts

SendGrid

Sendgrid provides clients the ability to use an existing SMTP transmission provider method but define their own custom SMTP transmission parameters

If you want to use, or change-over to SendGrid, contact your Account Manager to arrange this.

Domain settings

Visit the Domain Setup page for an explanation of the domain configuration that is used for SMTP emailing.

SPF record

Visit the SPF records page for details of the spf record that needs to be stored on your domain if you use SMTP emailing.

Global Controls

Check the controls below use the values shown if you are using SendGrid emailing.

| gb | mailtransmissionprovider | smtp | Choose which emailing protocol you want to use to send emails. You can either use 1. 'ses' - Amazon Simple Email Service (SES). This is the recommended method. You will need to set-up a DKIM key to verify the email's domain. 2. 'smtp' - Simple Mail Transfer Protocol (SMTP). You will need to set-up an SPF record to verify the email's domain.

The Catch-e System was developed to use only SMTP at first. SES was introduced later and is now our recommended protocol for clients. |
| gb | mailsenderdomainsenforcingflag | yes | Set to 'yes' to control the status of Domain enrolling of SPF Records. |
| gb | emailattachmentsmaxsizein_bytes | 7864320 | Your emails will switch to a URL link if the combined size of the attached files is larger than the specified maximum size. We recommend a maximum of '7864320' as the Amazon SES feature enforces a mail size limit of 10MiB. If this control is set to a higher value, emails will fail if the size limit of 10MiB is exceeded. If you are using SMTP, this can be set to a higher value if desired. Note: Amazon SES converts the attached files to a binary file before attaching it to the email which can increase in size when converted. For example: a file of size 7.5 MB when converted can go over 10MiB, hence we recommend using maximum of '7864320' so the file is still less than 10MiB in size after conversion to binary file. |

Toyota Financial services

The Business rules for importing the TFS file are:

• Set cell A1 text to be Tax Invoice - Novated.
• Invoice Date - cell E2.
• Invoice Number - C2.
• Card Number - column C, 4th row onwards.
• Product Code - J
• Odometer Date - L
• Amount Net - M
• GST Amount - N

The .xls file needs to be saved as .csv prior to importing.

Click here to see a sample input file