FS 342934 WEBFLEET Logon Integration: Difference between revisions
(v0.1 - Initial Draft) |
(No difference)
|
Revision as of 11:21, 21 August 2017
OBS Logistics Ltd
WEBFLEET Logon Integration
CALIDUS ePOD
21st August 2017 - 0.1
Reference: FS 342934
Contents
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 fields 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 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>
</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, 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 \'\'
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 how 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 user 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.
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 | _____________________________ |
