View source for FS 342934 WEBFLEET Logon Integration

<div class="noprint">
{{#vardefine:Client|PROD}}
{{#vardefine:ClientName|OBS Logistics Ltd}}
{{#vardefine:System|''CALIDUS'' ePOD}}
{{#vardefine:Doc_Title|WEBFLEET Logon Integration}}
{{#vardefine:Version|1.0}}
{{#vardefine:Date|31st October 2017}}
{{#vardefine:Reference|342934}}
{{#vardefine:Year|2017}}
</div>
{{Doc_Title
|Client={{#var:ClientName}}
|System={{#var:System}}
|Title={{#var:Doc_Title}}
|Reference=FS {{#var:Reference}}
|Version={{#var:Version}}
|Date={{#var:Date}}
|Year={{#var:Year}}
}} 

<!-- TOC --> 
<div class="noprint">
= 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.


<!-- NEW PAGE --> 
= Set-up  =
== Pre-requisites  ==


== Menu Structure  ==


== Data  ==
An Export configuration will be generated for the device interface to WEBFLEET for Driver and Vehicle Information:
{| border="1"
|- bgcolor="silver"
!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.

<!-- NEW PAGE --> 
= 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.


<!-- MEDIA LANDSCAPE YES --> 
= Appendix A: TEST PLAN  =
{{TestPlan_Header
|Title={{#var:Doc_Title}}
|Log={{#var:Reference}}
|Description=Testing the on-device WEBFLEET integration.
|MenuAccess=Administration/Auto-Export
|Prerequisites=&nbsp;
|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.
}} {{ #vardefine: Cycle | 0 }}{{ #vardefine: SubCycle | 0 }}
{{TestPlan_CycleHeader
|Cycle={{ #vardefineecho: Cycle | {{ #expr: {{ #var: Cycle }} + 1 }} }}{{ #vardefine: SubCycle | {{ #var: Cycle }} }}
|Title=Admin
|Notes=&nbsp;
}} <!--INSERT TESTS HERE --> {{TestPlan_Test
|Test={{ #vardefineecho: SubCycle | {{ #expr: {{ #var: SubCycle }} + 0.01 }} }}
|Action=In the Import/Export configuration screen, test that a Device configuration for TomTom Driver/Device can be created and edited.
|Result=The drop-down list of IDs and Destinations can be entered and edited as expected.
|Remarks=
|PassFail=
}}{{TestPlan_Test
|Test={{ #vardefineecho: SubCycle | {{ #expr: {{ #var: SubCycle }} + 0.01 }} }}
|Action=In the Users maintenance screen, enter a new user and edit an existing user.
|Result=The user can be created and edited with or without the External ID.
|Remarks=
|PassFail=
}}{{TestPlan_Test
|Test={{ #vardefineecho: SubCycle | {{ #expr: {{ #var: SubCycle }} + 0.01 }} }}
|Action=Search for the user by the external ID.
|Result=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.
|Remarks=
|PassFail=
}}{{TestPlan_Test
|Test={{ #vardefineecho: SubCycle | {{ #expr: {{ #var: SubCycle }} + 0.01 }} }}
|Action=In the Vehicles maintenance screen, enter a new vehicle and edit an existing user.
|Result=The vehicle can be created and edited with or without the External ID.
|Remarks=
|PassFail=
}}{{TestPlan_Test
|Test={{ #vardefineecho: SubCycle | {{ #expr: {{ #var: SubCycle }} + 0.01 }} }}
|Action=Search for the vehicle  by the external ID.
|Result=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.
|Remarks=
|PassFail=
}}{{TestPlan_CycleFooter}} 
{{TestPlan_CycleHeader
|Cycle={{ #vardefineecho: Cycle | {{ #expr: {{ #var: Cycle }} + 1 }} }}{{ #vardefine: SubCycle | {{ #var: Cycle }} }}
|Title=Device
|Notes=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).
}} <!--INSERT TESTS HERE --> {{TestPlan_Test
|Test={{ #vardefineecho: SubCycle | {{ #expr: {{ #var: SubCycle }} + 0.01 }} }}
|Action=Using a non-TomTom device, start the EPOD app.
|Result=The log-on works as now, requiring the entry of user, vehicle and password.
|Remarks=
|PassFail=
}}{{TestPlan_Test
|Test={{ #vardefineecho: SubCycle | {{ #expr: {{ #var: SubCycle }} + 0.01 }} }}
|Action=Using a TomTom PRO device, log on to WEBFLEET with a driver an PIN. Start the EPOD App.
|Result=The device recognises the user and picks up the vehicle. The device displays the progress and messages required. The device automatically logs on.
|Remarks=
|PassFail=
}}{{TestPlan_CycleFooter}} 

<!-- MEDIA LANDSCAPE NO --> 
{{Doc_Appendix
|Appendix=B
|Estimate=Y
|Glossary=EPOD
|Ref1=[[REQ 339867 Marshalls Premier Mortars Solution Design]]
|RefV1=1.3
|RefDate1=25/05/2017
|EREQ=0
|EEST=0
|EFS=1.25
|ETS=0
|EDEV=5.0
|ESTT=1.0
|EIMP=0.25
|EPM=0.5
|REQ=0
|EST=0
|FS=1.25
|TS=0
|DEV=5.0
|ST=1.0
|IMP=0.25
|PM=0.5
|Client={{#var:Client}}
|Year={{#var:Year}}
|FSEST=Y
|FOC=N
|Rev1=Matt Turner
|Rev1Title=OBSL Account Manager
|Rev2=Murray Middleton
|Rev2Title=OBSL Project Manager
}}</div> 
[[Category:{{#var:Client}} FS]]