FS 322073 EPOD WEBFLEET Interface - Basic
OBS Logistics
WEBFLEET Interface - Basic
CALIDUS EPOD
15th April 2015 - 0.2
Reference: FS 322073
Contents
Functional Overview
Client Requirement
CALIDUS EPOD needs to get the Mobile Application to trigger the TomTom Nav App with the address of the job the driver is travelling to.
Solution Overview
The TomTom Nav App on the device does not allow this kind of triggering with an ad-hoc address - it must work through triggering WEBFLEET orders.
The only way to trigger the start/arrive/complete of WEBFLEET orders is:
- Through the device's Pro.CONNECT interface (device-side)
- Through WEBFLEET.CONNECT webservices (server-side)
In order for either of these methods to work, there is a pre-requirement to create the orders in WEBFLEET.
In order for this to work, there is a pre-requirement for all addresses to have a Lat/Long.
The Pro.CONNECT interface is proving too difficult to implement at this time, so the design will fall back on:
- Triggering the display of the webfleet app through Android (which will just display the app, not trigger the start of the job.
Additionally, TomTom state that the requests that are currently being made through TomTom Webservices are not being counted towards OBS Logistics use, as the OBS API Key is not included in current requests. Any solution put in place at this time will ensure this key is utilised.
This change covers:
- Basic implementation of an interface mechanism for WEBFLEET messages.
- Geocoding addresses in CALIDUS EPOD
- Triggering the display of the TomTom Nav App on TomTom PRO devices only.
All other functionality relating to WEBFLEET interfaces will be completed in other specifications, referenced in Appendix A.
Scope
- This change affects the latest version of the CALIDUS EPOD application only.
- The existing CTMS-TomTom interfaces also need to be modified to use an API key, which will be provided by Matt Turner. This functionality is not part of the scope of this change.
- This change only covers a basic integration of geocoding within CALIDUS EPOD. Further revisions of this interface should occur for:
- Amended addresses for customer and job
- Displaying selected Lat/Long on a map within the Admin application
- Manually looking up an address' Lat/Long from within the Admin application
- Sending Lat/Long information to the mobile device, for potential integration directly into the device.
- Efficiency f the interface (removing duplicate sends)
- Country Code definition against addresses (for international use)
Set-up
Pre-requisites
A working CALIDUS EPOD implementation.
Menu Structure
None
Data
New EPOD_XF_CONFIG configurations will be required:
- EPL_XF_CONFIG_ID - A new configuration name to be applied to sites that do not have an Export Configuration yet, or the Export Configuration ID of the existing configuration.
- EPL_XF_ID - "TO" - TomTom Geocoder
- EPL_WEB_USER - "admin"
- EPL_WEB_PASSWORD - "Matt3221"
- EPL_XF_RECIPIENT - Account - "logistics-obs"
- EPL_XF_DESTINATION - "http://connect.webfleet.tomtomwork.com/extern"
- EPL_WEB_PARAMETER - API Key - "000fcb2a-6631-477a-b00e-de0505e7c7e3"
- EPL_XF_DIRECTION - "O"
- EPL_XF_TYPE - "POST"
Import/Export Config Screen
This configuration should be added to site that requires TomTom interfaces, in the Site Maintenance screen. If a site already has a configuration attached to it, a configuration should be added to the same configuration name.
Functional Description
Database/DAL
A new table EPOD_XF_CONTROL will be added along with a DAL object to control sending of export messages, with the following fields and indexes.
- EXC_ID - unique numeric ID
- EXC_EXTERNAL_SYSTEM - string e.g. "TOMTOM"
- EXC_ACTION - D - Delete, A - Add/Amend, allowed to be null
- EXC_STATUS - P - Pending, I - In Progress, C - Complete, E/X - Error
- EXC_TYPE - J - Job, L - Load, JA - Job Address, C - Customer
- EXC_SITE_ID - nvarchar(10)
- EXC_LOAD_ID - nvarchar(20)
- EXC_JOB_ID - nvarchar(10)
- EXC_JOB_TYPE - nvarchar(2)
- EXC_CUSTOMER_CODE - nvarchar(20)
- EXC_CREATED_DATE - int, 8 digit number format YYYYMMDD
- EXC_CREATED_TIME - int, 8 digit number format HHMMSSNN
Indexes:
- PK_EXC: EXC_ID
- IX_EXC_TYPE: EXC_STATUS, EXC_EXTERNAL_SYSTEM, EXC_ACTION
- IX_EXC_LOAD: EXC_STATUS, EXC_SITE_ID, EXC_LOAD_ID
- IX_EXC_JOB: EXC_STATUS, EXC_SITE_ID, EXC_JOB_ID, EXC_ADDRESS_TYPE
- IX_EXC_CUST: EXC_STATUS, EXC_SITE_ID, EXC_CUSTOMER_CODE
The existing table and DAL object EPOD_JOB_ADDRESS will be modified to add 2 new fields, as below:
- EPL_LAT - float
- EPL_LONG - float
Note: It is not necessary to export or import these fields through XML at this time.
A new Trigger will be written for this table, to write a record of type "JA" to EPOD_INT_CONTROL if "TomTom Geocoder" is enabled for the Site's Export Configuration when adding a Job Address.
The existing table and DAL object EPOD_CUSTOMER will be modified to add 2 new fields, as below:
- EPL_LAT - float
- EPL_LONG - float
Note: It is not necessary to export or import these fields through XML at this time.
A new Trigger will be written for this table, to write a record of type "C" to EPOD_INT_CONTROL if "TomTom Geocoder" is enabled for the Site's Export Configuration when adding a Customer.
The existing table and DAL object EPOD_VEHICLE will be modified to add a new field, as below:
- EPL_EXT_REF - nvarchar(10)
Note: It is not necessary to export or import this field through XML at this time.
AutoExport
A new sending type should be created for type "HTTP". This type will receive the URL and all querystring parameters already built and open the URL, similar to the existing "SOAP" mechanism.
A new procedure should be created to send messages from EPOD_INT_CONTROL:
- Store Site XF_CONFIG settings (or get them as part of the message retrieval)
- New TOMTOM process to find only messages EXC_STATUS = "P", order by EXC_ID
- Change message status to "I" - Progress - any failure from this point to change status to "E" and log error.
- Check EXC_EXTERNAL_SYSTEM and EXC_ACTION: For TOMTOM:
- Build URL to geocoder from parameters in EPOD_XF_CONFIG:
- EPL_XF_DESTINATION +
- ?account=EPL_XF_RECIPIENT
- &username=EPL_WEB_USER
- &password=EPL_WEB_PASSWORD
- &apikey=EPL_WEB_PARAMETER
- Depending on EPOD_XF_CONFIG.EPL_XF_ID of "TG", add specific geocoder parameters:
- &lang=en&action=geocodeAddress&outputformat=json&addrcountry=GB&provider=2&freetext=
- Build address into a string, from NAME, ADDRESS_1/2/3/4, POSTCODE, delimited by space.
- Make address string HTMLsafe and add to URL
- Send message using the new HTTP method, if configured that way.
- Process Response:
- Parse result as JSON. Take result of first object that matches the first part of the postcode, or the first result.
- Store objResult[0].latitude/1000000 in EPL_LAT and objResult[obj].longitude/1000000 in EPL_LONG
- Failure - update status of message to "E" and audit.
- Success - update record indicated by EXC_XF_TYPE and mark status of message to "C":
- Update EPOD Audit records as normal for success or failure.
Admin
AutoExport Config Screen
This screen should be modified to allow for new IDs:
- TO - displayed as "TomTom Orders"
- TG - displayed as "TomTom Geocoder"
This modification should affect the pop-up Edit/New screen drop-down list, and the display of the ID in the table.
Import/Export Configuration Screen
The Type drop-down list should be modified to allow a new value "HTTP".
The screen should be renamed "Import/Export Interface" on the main menu and on the title of this screen.
When adding or editing a record of one of the new IDs on this pop-up screen, the screen should display the XF-Recipient field, labelled as "Account".
The pop-up Edit/New screen should be made wider, and the Destination and Parameter fields should be made longer, at all times for all types. Additionally, the Direction field should become a drop-down list, holding only the appropriate values (I and O, labelled as "Import" and "Export"). The ID should be brought in-line with the other items on the screen.
Vehicles Maintenance Screen
This screen will be modified to add the new Ext Ref field to the Edit/New pop-up. This will be labelled as "External Ref" and positioned as shown below.
Vehicles Maintenance Screen
Customers Maintenance Screen
This screen will be modified to add the new Lat/Long fields to the Edit/New pop-up. These will be labelled as "Latitude" and "Longitude" respectively and positioned as shown below.
Customers Maintenance Screen
Job Maintenance Screen
This screen will be modified to add the new Lat/Long fields to the Edit/New pop-up. These fields will only be present when entering a JOb Address (i.e. not using the customer's address). These will be labelled as "Latitude" and "Longitude" respectively and positioned as shown below.
Job Maintenance Screen
Mobile Device
Job Detail
This screen will be modified to change the way that the Map button works, if the device is a TomTom PRO device.
The application will check the type of device and, if this is a TomTom PRO device, will instead call a different intent when pressing this button. Rather than a standard Geo intent, the device will initiate the TomTom Nav App directly, using the intent com.tomtom.navpad.navapp and activity NavPadNavAppActivity.
Appendix A: Quote & Document References
| Cost Details | |||
| Activity | No. of Days | Rate per Day (£) | Cost (£ Exc. VAT) |
| Requirements | 0.00 | 0 | £0.00 |
| Change Request Evaluation | 0.00 | 0 | £0.00 |
| Functional Specification | 2.00 | 0 | £0.00 |
| Technical Specification | 2.00 | 0 | £0.00 |
| Development | 10.25 | 0 | £0.00 |
| Testing and Release | 2.00 | 0 | £0.00 |
| Implementation | 0.50 | 0 | £0.00 |
| Project Management | 1.25 | 0 | £0.00 |
| TOTAL | 18.00 | £0.00 | |
| Estimate excludes training, release to live and go live support. |
A.1 References
| Ref No | Document Title & ID | Version | Date |
| 1 | FS 322073 EPOD WEBFLEET Interface - Orders | 0.1 | 16/04/2015 |
A.2 Glossary
| Term | Definition |
|---|---|
| EPOD | Electronic Proof of Delivery. The OBS EPOD system is CALIDUS ePOD. |
| CALIDUS eSERV | The OBS mobile system to complete Service functionality in the field. This is part of the CALIDUS ePOD system. |
| PDA | The mobile device on which the C-ePOD system will run in the field. This can be a Phone, EDA or industrial PDA, running Android. |
| DAL | Data Access Layer. A mechanism for accessing data by the system that is removed from the application, allowing for simplified access and providing protection to the data, as only approved DAL methods can be used to modify it. |
| GPS | Global Positioning System. A mechanism of retrieving accurate positioning information in the form of Latitude and Longitude (Lat-Long) co-ordinates from a device. |
| GPRS, 3G, HSDPA, Data Service | All terms referring to mobile device network connectivity, and the speed at which the device connects to the internet. |
A.3 Authorised By
Matt Turner | OBS CALIDUS EPOD Product Manager | _____________________________ |
Murray Middleton | OBS CALIDUS EPOD Development Manager | _____________________________ |
