OBS Logistics Ltd

WEBFLEET Logon Integration

CALIDUS ePOD

31st October 2017 - 1.0
Reference: FS 342934

Functional Overview

Client Requirement

WEBFLEET Logon Integration

Solution Overview

The EPOD system will be modified to store the configuration information required for the device to check WEBFLEET logon details. The External (WEBFLEET) IDs of the vehicles and users will be capable of being maintained and stored in the system.

This information will be passed to the device.

On logon, relogon and refreshing standing data from the server, the device will check the following, for TomTom PRO devices only:

The logged-on WEBFLEET ID and user will be obtained from the device.
The device will find an EPOD user with the exact same name.
If found, WEBFLEET will be queried for the WEBFLEET vehicle that this WEBFLEET user is using.
If found, WEBFLEET will be queried for the ODO reading and this stored on the device (for future use, not part of this change).
If all users and vehicles exist, the device will attempt to log on using the last known password for this user.

Scope

The latest version 4.X of CALIDUS EPOD will be modified for this change.

The device requires a data connection for this process to work as described.

The WEBFLEET and EPOD user names MUST be identical for this process to work as described.

Set-up

Pre-requisites

Menu Structure

Data

An Export configuration will be generated for the device interface to WEBFLEET for Driver and Vehicle Information:

Field	Value
EPL_XF_TYPE	SOAP
EPL_XF_DESTINATION	https://soap.business.tomtom.com/v1.31/objectsAndPeopleReportingService
EPL_XF_ID	TD
EPL_WEB_PARAMETER
EPL_WEB_USER	Provided WEBFLEET user
EPL_WEB_PASSWORD	Provided WEBFLEET password
EPL_SOAP_NS	http://connect.webfleet.tomtomwork.com/services
EPL_SOAP_NS_PREFIX	ser
EPL_XF_DIRECTION	D
EPL_XF_RECIPIENT	Provided WEBFLEET fleet
EPL_XF_MSG_TYPE	WEBFLEET API Key - for CALIDUS ePOD this is 000fcb2a-6631-477a-b00e-de0505e7c7e3

Each site will be configured with this Export Configuration.

Functional Description

Database/Data Access Layer

The following fields will be added to the User table EPOD_USER:

EPL_EXT_REF NVARCHAR(50) NOT NULL

This field will be added to all stored procedures in the database that requires it.

The new field is required on the mobile device.

This field is not required to be imported or exported through Webservices or CSV uploads.

This field is required to be used when filtering data for selection.

The following field is already present on the Vehicle table EPOD_VEHICLE:

EPL_EXT_REF NVARCHAR(10) NOT NULL

This field will be added to all stored procedures in the database that requires it.

The new field is required on the mobile device.

This field is not required to be imported or exported through Webservices or CSV uploads.

This field is required to be used when filtering data for selection.

The following fields will be added to table EPOD_XF_CONFIG:

EPL_LAST_CHANGE_DATE INTEGER
EPL_LAST_CHANGE_TIME INTEGER

These fields will be added to all stored procedures in the database that requires it.

The new fields are not required on the mobile device.

This fields are not required to be imported or exported through Webservices or CSV uploads.

This fields are required to be used when filtering data for selection.

The fields will be set to the system date and time whenever the record is changed or added. It is recommended that this will be through a new trigger on the table in the database.

The EPOD_SITE DAL object will be modified when sending XML to device, to get any attached EPOD_XF_CONFIG records and include any device-type interfaces (denoted by EPL_XF_DIRECTION = "D") in this new structure, as follows:

   <EPOD_SITE>
       ...
       <EPOD_XF_CONFIGS>
           <EPOD_XF_CONFIG>
               <EPL_XF_CONFIG_ID></EPL_XF_CONFIG_ID>
               <EPL_DESCRIPTION></EPL_DESCRIPTION>
               <EPL_XF_TYPE></EPL_XF_TYPE>
               <EPL_XF_DESTINATION></EPL_XF_DESTINATION>
               <EPL_XF_ID></EPL_XF_ID>
               <EPL_EXPORT_FULLHEADERS></EPL_EXPORT_FULLHEADERS>
               <EPL_WEB_PARAMETER></EPL_WEB_PARAMETER>
               <EPL_WEB_USER></EPL_WEB_USER>
               <EPL_WEB_PASSWORD></EPL_WEB_PASSWORD>
               <EPL_SOAP_ACTION></EPL_SOAP_ACTION>
               <EPL_SOAP_NS></EPL_SOAP_NS>
               <EPL_SOAP_NS_PREFIX></EPL_SOAP_NS_PREFIX>
               <EPL_XF_RECIPIENT></EPL_XF_RECIPIENT>
               <EPL_EXPORT_JOB_TYPES></EPL_EXPORT_JOB_TYPES>
               <EPL_XF_MSG_TYPE></EPL_XF_MSG_TYPE>
               <EPL_EXPORT_FORMAT></EPL_EXPORT_FORMAT>
               <EPL_IMAGE_TYPE></EPL_IMAGE_TYPE>
               <EPL_TIFF_COMPRESSION></EPL_TIFF_COMPRESSION>
               <EPL_FILENAME></EPL_FILENAME>
               <EPL_CONTRACT_OPERATION></EPL_CONTRACT_OPERATION>
               <EPL_SOAP_VERSION></EPL_SOAP_VERSION>
               <EPL_XF_CONFIG_UID></EPL_XF_CONFIG_UID>
           </EPOD_XF_CONFIG>
       </EPOD_XF_CONFIGS>
   </EPOD_SITE>

Any fields in the table without a value will not generate a tag in the XML (i.e. NULL or zero-length string).

If no device-type interfaces exist for the config id linked to the site or the XF Config has not changed since last it was sent to the device, this entire section will be omitted.

Note that this section may be added as a new root section rather than as part of the Site, if this is easier to achieve.

Webservices

The webservice handling device responses (Calidus_epod.asmx) will be modified.

In the response to a logon request, all the new fields for EPOD_USER and EPOD_VEHICLE will be included in the response. This is expected to have been achieved through modifications to the DAL objects when generating XML for export.

In the same procedure, the Site export XML structure will be modified with a new section for interfaces. Any device-type interfaces (denoted by EPL_XF_DIRECTION = "D") will be sent to the device in this new structure, as shown in the previous section.

Admin

Users Maintenance

The Users Maintenance screen (user_view.aspx) will be modified to allow the admin users to search for users by their External (WEBFLEET) user ID, by adding this to the search panel. This will be labelled as "External ID" and will be a fuzzy match on the entered value.

The results table will be modified to add the External ID as a new column.

The Add/Edit pop-up screen will be modified to add this field, again labelled as "External ID"

Vehicles Maintenance

The Vehicles Maintenance screen (user_view.aspx) will be modified to allow the admin users to search for users by their External (WEBFLEET) vehicle ID, by adding this to the search panel. This will be labelled as "External ID" and will be a fuzzy match on the entered value.

The results table will be modified to add the External ID as a new column.

Import/Export Interface Maintenance

The Import/Export Interface screen (xf_config.aspx) will be modified for this functionality.

The Add/Edit pop-up screen will be modified for the following:

the "Direction" drop-down list will have the value "Device", only for XF ID "TD".
the "ID" drop-down list will have the value "TD" added, labelled as "TomTom Device/Driver"

Mobile Device

DB/DAL

A new table EPOD_XF_CONFIG will be created:

EPL_XF_CONFIG_ID NVARCHAR(50) NOT NULL DEFAULT \'\'
EPL_DESCRIPTION NVARCHAR(40) NOT NULL DEFAULT \'\'
EPL_XF_TYPE NVARCHAR(10) NOT NULL DEFAULT \'\'
EPL_XF_DESTINATION NVARCHAR(255) NOT NULL DEFAULT \'\'
EPL_XF_ID NVARCHAR(20) NOT NULL DEFAULT \'\'
EPL_EXPORT_FULLHEADERS NVARCHAR(1) NOT NULL DEFAULT \'\'
EPL_WEB_PARAMETER NVARCHAR(50) NOT NULL DEFAULT \'\'
EPL_WEB_USER NVARCHAR(50) NOT NULL DEFAULT \'\'
EPL_WEB_PASSWORD NVARCHAR(100) NOT NULL DEFAULT \'\'
EPL_SOAP_ACTION NVARCHAR(100) NOT NULL DEFAULT \'\'
EPL_SOAP_NS NVARCHAR(225) NOT NULL DEFAULT \'\'
EPL_SOAP_NS_PREFIX NVARCHAR(50) NOT NULL DEFAULT \'\'
EPL_XF_RECIPIENT NVARCHAR(20) NOT NULL DEFAULT \'\'
EPL_EXPORT_JOB_TYPES NVARCHAR(20) NOT NULL DEFAULT \'\'
EPL_XF_MSG_TYPE NVARCHAR(100) NOT NULL DEFAULT \'\'
EPL_EXPORT_FORMAT NVARCHAR(10) NOT NULL DEFAULT \'\'
EPL_IMAGE_TYPE NVARCHAR(5) NOT NULL DEFAULT \'\'
EPL_TIFF_COMPRESSION NVARCHAR(5) NOT NULL DEFAULT \'\'
EPL_FILENAME NVARCHAR(100) NOT NULL DEFAULT \'\'
EPL_CONTRACT_OPERATION NVARCHAR(50) NOT NULL DEFAULT \'\'
EPL_SOAP_VERSION NVARCHAR(100) NOT NULL DEFAULT \'\'
EPL_XF_CONFIG_UID INTEGER NOT NULL DEFAULT \'\'

EPOD_USER:

EPL_EXT_REF NVARCHAR(50) NOT NULL DEFAULT \'\'

EPOD_VEHICLE:

EPL_EXT_REF NVARCHAR(50) NOT NULL DEFAULT \'\'

PDA_USER - getWebfleetUser function.

PDA_VEHICLE - getWebfleetVehicle function.

Webservices

The Logon Response handler (in Webservices.js) will be modified to populate these new EPOD_VEHICLE and EPOD_USER fields.

This process will also be modified to identify the new EPOD_XF_CONFIGS section (either as a new root section or as part of the EPOD_SITE section, depending on the server development) and save any EPOD_XF_CONFIG tag contents into the new EPOD_XF_CONFIG table on the device.

Note: If the site is changed, this table's contents will be removed - a method DeleteAllXFConfigs will be created to facilitate this.

A new DAL object PDA_XF_CONFIG will be created that reads the table, allowing selection by EPL_XF_ID.

Login

New procedure funCheckWebfleetDriver, to:

Get the TomTom WEBFLEET driver name from the TomTom PRO API (on the device).
Get the Driver's vehicle from WEBFLEET.
Get the vehicle information (including ODO reading) from WEBFLEET.

Called from:

GetSystemData - when all system data is uploaded successfully.
When the Login form is opened.
funRelogin - when re-logging in from a logout

Note: For TomTom PRO devices only.

Includes a function funGetWebfleetParms to build the parameters for the WEBFLEET messages from the EPOD_XF_CONFIG parameters. The following format is used:

   <aParm>
       <accountName>PDA_XF_CONFIG.EPL_XF_RECIPIENT</accountName>
       <userName>PDA_XF_CONFIG.EPL_WEB_USER</userName>
       <password>PDA_XF_CONFIG.EPL_WEB_PASSWORD</password>
       <apiKey>PDA_XF_CONFIG.EPL_XF_MESSAGE_TYPE</apiKey>
   </aParm>
   <gParm>
       <locale>UK</locale>
       <timeZone>Europe_London</timeZone>
   </gParm>

Note: This process is valid only for TomTom PRO devices only, so this process will check the model of the device that it is "TOMTOM PRO".

Note: A Progress activity indicator will be displayed whilst retrieving this information, updating the progress with text messages as required. Each message will be translated from the device's multi-lingual strings.

The activity indicator will show that the device is checking WEBFLEET for login details.

The process will use the existing TomTom WEBFLEET API module (com.obslogistics.proconnect) - the getDriver method will be modified to return the driver name and ID from the PRO.connect interface. If a driver is not found, the activity indicator will be hidden and a message shown that the driver could not be found in WEBFLEET.

The activity indicator will how that the device is looking for the matching EPOD user.

The user will be checked against the users table in EPOD (through creation of a PDA_USER object) calling the new function getWebfleetUser. If one is not found, the activity indicator will be hidden and a message shown that WEBFLEET user is unknown in EPOD.

If a user is found, a message will be displayed that the driver has been set from WEBFLEET, indicating the driver name.

The activity indicator will how that the device is looking for the user's vehicle information.

The process will send a request to WEBFLEET to achieve this. A SUDS client will be created with the following parameters:

endpoint : the base URL for WEBFLEET (from PDA_XF_CONFIG.EPL_XF_DESTINATION).
namespacePrefix : PDA_XF_CONFIG.EPL_SOAP_NS_PREFIX
targetNamespace : PDA_XF_CONFIG.EPL_SOAP_NS
envelopeBegin : '<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope" xmlns:PREFIX="PLACEHOLDER">'

The message to be sent will be built as follows:

   '<ser:showDriverReport>' + 
   funGetWebfleetParms() + 
   '<driverFilter>' + 
   '<driver driverNo="'+PDAUSER.EPL_EXT_REF+'"/>' + 
   '</driverFilter>' + 
   '</ser:showDriverReport>';

The process will then invoke the message.

Any failure to invoke or in the response will result in the activity indicator being removed and the message 'ERROR: WEBFLEET: No response from Driver request'.

On successful response, the response text will be parsed to remove the soap envelope, then parsed as an XML string. If the objectName tag does not exist, the activity indicator will be removed and the message WEBFLEET driver has no vehicle assigned - please select from the list provided.'.

If found, the activity indicator will be updated to show that the WEBFLEET vehicle has been found.

The vehicle will be checked against the vehicles table in EPOD (through creation of a PDA_VEHICLE_WF object) calling the new function getWebfleetVehicle. If one is not found, the activity indicator will be hidden and a message shown that WEBFLEET vehicle is unknown in EPOD.

If a vehicle is found, a message will be displayed that the vehicle has been set from WEBFLEET, indicating the vehicle registration.

If found, the activity indicator will be updated to show that the vehicle has been found, and that the WEBFLEET information is now being checked.

The process will send a request to WEBFLEET to achieve this. A SUDS client will be created with the following parameters:

endpoint : the base URL for WEBFLEET (from PDA_XF_CONFIG.EPL_XF_DESTINATION).
namespacePrefix : PDA_XF_CONFIG.EPL_SOAP_NS_PREFIX
targetNamespace : PDA_XF_CONFIG.EPL_SOAP_NS
envelopeBegin : '<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope" xmlns:PREFIX="PLACEHOLDER">'

The message to be sent will be built as follows:

   '<ser:showObjectReport>' + 
   funGetWebfleetParms() + 
   '<objectFilter>' + 
   '<object objectNo="'+PDAVEHICLE_WF.EPL_EXT_REF+'"/>' + 
   '</objectFilter>' + 
   '</ser:showObjectReport>';

The process will then invoke the message.

Any failure to invoke or in the response will result in the activity indicator being removed and the message 'ERROR: WEBFLEET: No response from Vehicle request'.

On successful response, the response text will be parsed to remove the soap envelope, then parsed as an XML string. If the odometer tag does not exist, the activity indicator will be removed and the message WEBFLEET vehicle has no odometer reading.'.

If found, the activity indicator will be hidden and a message shown of the value that WEBFLEET reports for the odometer reading.

The odometer reading will be stored on the PDA_VEHICLE_WF object and updated.

If the vehicle and user are taken from WEBFLEET with no issues, the device will automatically attempt to log on to EPOD, using the provided information and the stored password from the PDA_USER object.

Note:

The Change Vehicle option will allow the user to change the vehicle if required.
Relogin will work as described above, although the vehicle will be allowed to be changed, the use ID will not.

Appendix A: TEST PLAN

Test Script / Scenario Reference	WEBFLEET Logon Integration	Call Number(s): 342934
Test Script / Scenario Description	Testing the on-device WEBFLEET integration.	PASS / ISSUES / FAIL
Menu Access	Administration/Auto-Export
Pre-requisites		Tested By:
Test Objective	To test that: Admin can configure vehicles, users and XF configs as required and; the device will automatically log on if WEBFLEET is configured, on TomTom PRO devices.	Date:

Step	Action	Result	Remarks	P/F
1	Admin

1.01	In the Import/Export configuration screen, test that a Device configuration for TomTom Driver/Device can be created and edited.	The drop-down list of IDs and Destinations can be entered and edited as expected.
1.02	In the Users maintenance screen, enter a new user and edit an existing user.	The user can be created and edited with or without the External ID.
1.03	Search for the user by the external ID.	The correct records are displayed in the table. The External ID is displayed in the results. The user can be edited (with the Select button) and the External ID is visible and editable. Users without External IDs can still be viewed, edited and created.
1.04	In the Vehicles maintenance screen, enter a new vehicle and edit an existing user.	The vehicle can be created and edited with or without the External ID.
1.05	Search for the vehicle by the external ID.	The correct records are displayed in the table. The External ID is displayed in the results. The vehicle can be edited (with the Select button) and the External ID is visible and editable. Vehicles without External IDs can still be viewed, edited and created.

Step	Action	Result	Remarks	P/F
2	Device
	Ensure that TomTom WEBFLEET is configured for the device and that the Users and Vehicles are set up as required, matching WEBFLEET user and object IDs in the fleet selected. Ensure that the TomTom PRO device is linked to a vehicle and driver (i.e. logged on to a WEBFLEET user).
2.01	Using a non-TomTom device, start the EPOD app.	The log-on works as now, requiring the entry of user, vehicle and password.
2.02	Using a TomTom PRO device, log on to WEBFLEET with a driver an PIN. Start the EPOD App.	The device recognises the user and picks up the vehicle. The device displays the progress and messages required. The device automatically logs on.

Appendix B: Quote & Document References

Cost Details
Activity	Estimate No. of Days	No. of Days	Rate per Day (£)	Cost (£ Exc. VAT)
Requirements	0.00	0.00	0	£0.00
Change Request Evaluation	0.00	0.00	0	£0.00
Functional Specification	1.25	1.25	0	£0.00
Technical Specification	0.00	0.00	0	£0.00
Development	5.00	5.00	0	£0.00
Testing and Release	1.00	1.00	0	£0.00
Implementation	0.25	0.25	0	£0.00
Project Management	0.50	0.50	0	£0.00

TOTAL	8.00	8.00		£0.00

Estimate excludes training, release to live and go live support.

B.1 References

Ref No	Document Title & ID	Version	Date
1	REQ 339867 Marshalls Premier Mortars Solution Design	1.3	25/05/2017

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

B.3 Authorised By

Matt Turner	OBSL Account Manager	_____________________________
Murray Middleton	OBSL Project Manager	_____________________________

Anonymous

Search

FS 342934 WEBFLEET Logon Integration

Namespaces

More

Page actions

Contents

Functional Overview

Client Requirement

Solution Overview

Scope

Set-up

Pre-requisites

Menu Structure

Data

Functional Description

Database/Data Access Layer

Webservices

Admin

Users Maintenance

Vehicles Maintenance

Import/Export Interface Maintenance

Mobile Device

DB/DAL

Webservices

Login

Appendix A: TEST PLAN

Appendix B: Quote & Document References

Navigation

Navigation

Translate

Wiki tools

Wiki tools

Anonymous

Search

FS 342934 WEBFLEET Logon Integration

Functional Overview

Client Requirement

Solution Overview

Scope

Set-up

Pre-requisites

Menu Structure

Data

Functional Description

Database/Data Access Layer

Webservices

Admin

Users Maintenance

Vehicles Maintenance

Import/Export Interface Maintenance

Mobile Device

DB/DAL

Webservices

Login

Appendix A: TEST PLAN

Appendix B: Quote & Document References

Navigation

Wiki tools

Page tools

Categories