FS 322073 EPOD WEBFLEET Interface - Basic
OBS Logistics
WEBFLEET Interface - Basic
CALIDUS EPOD
6th May 2015 - 0.6
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 addresses' Lat/Long from within the Admin application
- Sending Lat/Long information to the mobile device, for potential integration directly into the device.
- Efficiency of the interface (removing duplicate sends)
- Country Code definition against addresses (for international use)
Note: Changes to the Android Application are an interim solution only. At this time, this will only activate the Navigation app - all functionality regarding starting, arriving and completing orders will be completed within the Tom Tom WEBFLEET Navigation application manually by the user. This will be achieved using the Pro.CONNECT API. This is out of scope of this change.
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 - "TG" - TomTom Geocoder
- EPL_SOAP_ACTION - "geocodeAddress"
- EPL_SOAP_NS - "ser"
- EPL_SOAP_NS_PREFIX - "http://connect.webfleet.tomtomwork.com/services"
- EPL_WEB_USER - "admin"
- EPL_WEB_PASSWORD - "Matt3221"
- EPL_XF_RECIPIENT - Account - "logistics-obs"
- EPL_XF_DESTINATION - "http://connect.webfleet.tomtomwork.com/extern"
- EPL_XF_MSG_TYPE - API Key - "000fcb2a-6631-477a-b00e-de0505e7c7e3"
- EPL_XF_DIRECTION - "O"
- EPL_XF_TYPE - "SOAP"
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, S - Complete (Success), F - Error (Failed)
- 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 Housekeeping functions must be amended to include this table, keeping records for the same number of days as the XF Audit tables. Note also that Pending records should never be deleted.
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_XF_CONTROL if "TomTom Geocoder" is enabled for the Site's Export Configuration when adding or amending a Job Address. Note: The trigger may be achieved through the database or DAL objects.
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_XF_CONTROL if "TomTom Geocoder" is enabled for the Site's Export Configuration when adding or amending a Customer. Note: The trigger may be achieved through the database or DAL objects.
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.
The existing table and DAL object EPOD_XF_CONFIRG will be modified as follows:
- New fields:
- EPL_EXC_ID - as EPOD_XF_CONTROL.EXC_ID. This value should be nullable.
- Amended fields:
- EPL_JOB_GROUP - extend to 10 characters.
AutoExport
A new procedure should be created to send messages from the new EPOD_XF_CONTROL table.
- Messages will be found sorted by External System and ID, only at status Pending.
- Messages will be marked as In Progress when they are started processing.
- The message content will be built up from the authorising parameters in the EPOD_XF_CONFIG table, and the data being sent.
- For Job Addresses, the data will be built from the Job Address of the Job Type of the Job Id referenced in EPOD_XF_CONTROL.
- For Customer Addresses, the data will be built from the Customer of the Job Id referenced in EPOD_XF_CONTROL.
- The message will be sent based on its Config type - this is expected to be SOAP for WEBFLEET.
- The response will be checked, specific to WEBFLEET webservices:
- Failure - update status of message to "F" and audit.
- Success - update the data of the record indicated by EXC_XF_TYPE and mark status of message to "S":
- For Job Addresses, the Lat/Long values will be updated against the Job Address of the Job Type of the Job Id referenced in EPOD_XF_CONTROL.
- For Customer Addresses, the Lat/Long values will be updated against the Customer of the Job Id referenced in EPOD_XF_CONTROL.
- Limits Exceeded - in this case, the status of the message will be set back to Pending. No further messages of this type and action should be processed.
- In all cases, the return value should be audited against the standard Audit tables in CALIDUS EPOD. The value of the EXC_ID field should be written to the Audit tables in the new EPL_EXC_ID.
Note: WEBFLEET webservices are covered in detail in the WEBFLEET.connect specification, referenced in Appendix A.
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 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" and the EPL_XF_MSG_TYPE field labelled as "API Key".
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
The field will be validated only that the maximum length of the field is not exceeded.
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
The fields will be validated that the values are floating point (lat in range of -90 to +90, lon in range of -180 to +180).
Job 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.
Job Maintenance Screen
The fields will be validated that the values are floating point (lat in range of -90 to +90, lon in range of -180 to +180).
When saving, the screen should check whether this is a customer or job address, and update the appropriate record.
Load Maintenance Screen
This screen will be modified to alert the user for confirmation, when allocating the load to a vehicle or a user and saving the changes.
If some of the jobs on the load have not got Lat/Long co-ordinates for their customer or job addresses, and if the Site for the load is enabled for TomTom Orders, the warning "Some jobs do not have co-ordinates and will not be sent to TomTom WEBFLEET. Do you still want to assign this Load?" should be displayed.
If any other loads are in progress for this user, the warning "All loads currently in progress will be reset" should be displayed.
The screen should display one confirmation alert, concatenating these messages together if both are to be displayed.
The options available will be OK and Cancel
If the user clicks OK, the load will be updated. If not, the load will not be updated and the user will be returned to the Load Edit/Add Pop-up screen.
Load Maintenance Screen
Load Assignment Screen
This screen will be modified to check whether all jobs have got Lat/Long co-ordinates for their customer or job addresses, if the Site for the load is enabled for TomTom Orders, when allocating a user to a load through clicking the Loads button on the Users Maintenance screen, selecting a load and clicking Assign Loads'. If the addresses do not have Lat/Long values, the screen will display a warning "Some jobs do not have co-ordinates and will not be sent to TomTom WEBFLEET. Do you still want to assign this Load?". If any other loads are in progress for this user, the message should be extended with "All loads currently in progress will be reset". If the user clicks OK, the load will be updated. If not, the load will not be updated and the user will be returned to the Load Edit/Add Pop-up screen.
Load Assignment Screen
XF Audit Screen
The screen will be amended to display the Job Group as 10 characters.
The grid will translate the value "R" is status as "Reprocessed". An Action column will be added, to add a Reprocess button to those messages that have a value in EPL_EXC_ID.
The title of the screen will be renamed to "XF Audit" from "Calidus - ePOD".
The screen will also be amended so that, if the message failed and has an value in EPL_EXC_ID, a Reprocess button press will allow the message to be reprocessed, by finding the message on the EPOD_XF_CONTROL table and setting the status back to "P". The status of this Audit Header record should then be set to "R" - Reprocessed.
XF Audit 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.
Note: This is an interim solution. At this time, this will only activate the Navigation app - all functionality regarding starting, arriving and completing orders will be completed within the Tom Tom WEBFLEET Navigation application manually by the user.
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 | 13.50 | 0 | £0.00 |
| Testing and Release | 2.25 | 0 | £0.00 |
| Implementation | 0.50 | 0 | £0.00 |
| Project Management | 1.50 | 0 | £0.00 |
| TOTAL | 21.75 | £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.2 | 16/04/2015 |
| 2 | WEBFLEET.connect-en-1.24.0.pdf | 1.24.0 | 19/01/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 | _____________________________ |
