OBS Logistics Ltd

EPOD Server-Side Settings

CALIDUS EPOD

24th July 2015 - 0.1
Reference: FS 328780

Functional Overview

Client Requirement

The Device style settings should not be available to other clients to view. This needs changing with a matter of urgency. (Julie Scott) Feeds into discussions about moving device settings onto the server to allow standardisation of APK and settings across the fleet.

Solution Overview

The mobile device preferences will now be maintained in a new screen in the Admin system.
The style and preferences can now be selected against the Site, showing only those that are applicable to that system (i.e. hiding all other customers' styles).
The POD, POC and Service reports available for the customers to configure will now be limited to only those that are applicable to that system.
The mobile device will start with the default OBS style and logo, until the user successfully connects to the server. At this time, the style set on the server will update the style on the device, and the device will refresh.
The Logo displayed on the device will come from the logo set against the Site on the server.
The mobile device application's preferences will now only contain Site and Webservice, removing the ability for the customer to change settings that adversely affect the running of the app.
When the user logs on to the device, the device will inform the user if the version of the app they are running is unsuitable for that system. This will work with all versions of the system (1.X, 2.X, 3.X) and can be released with a small server update, rather than a device update.
As an additional change in version 3 onwards, a required update of the mobile device application will not allow the user to continue without first updating the app.

Benefits:

Most changes to Style can now be achieved without mobile device application modifications.
Changes to preferences can now be achieved on the server instead on manual entry/scanning a QR code, although setting of Style and Webservice manually and all settings through a QR code will still be supported for those operations that do not set up Preferences through the server. Note that this will no longer allow a customer style to be selected - this must be through the server settings after this development is complete.
The application will be a little smaller (around 300k), potentially improving memory usage on devices.

Scope

This solution requires changes to version 1 and the latest version (version 3) of CALIDUS EPOD. This has been made clear in the sections below. Unless specified, changes apply solely to the latest version of the system.

Set-up

Pre-requisites

Menu Structure

Data

Warning: Metadata setup per customer - Admin Lists

Metadata setup per customer - PDA Styles and Settings

Note: the Logo styles should point to the altLogo.jpg file in the Images directory, identified through the property Ti.Filesystem.applicationDataDirectory.

Set up UpdatesInfo.xml with new Max Version priority

Description of Changes

Database/DAL

Add new table PDA_PREFERENCE.

CREATE TABLE [dbo].[EPOD_PDA_PREFERENCE](
   [EPP_ID] [int] IDENTITY(1,1) NOT NULL,
   [EPP_DESCRIPTION] [varchar](50) NOT NULL,
   [EPP_DEBUG] [varchar](1) NOT NULL,
   [EPP_WSINTERVAL] [int] NOT NULL,
   [EPP_UPINTERVAL] [int] NOT NULL,
   [EPP_GEOTAG] [varchar](1) NOT NULL,
   [EPP_GEOMSGINTERVAL] [int] NOT NULL,
   [EPP_OBSALERT] [varchar](50) NOT NULL,
   [EPP_OBSVIBRATE] [int] NOT NULL,
   [EPP_OBSIMAGESIZE] [int] NOT NULL,
   [EPP_OBSIMAGECOMPRESSION] [float] NOT NULL,
   [EPP_DEBUGMODE] [varchar](1) NOT NULL,
   [EPP_LANGUAGE] [varchar](10) NOT NULL,
   [EPP_LAST_CHANGED_DATE] [int] NOT NULL,
   [EPP_LAST_CHANGED_TIME] [int] NOT NULL,
CONSTRAINT [PK_EPOD_PDA_PREFERENCE] PRIMARY KEY CLUSTERED 
(
   [EPP_ID] ASC
)WITH (PAD_INDEX  = OFF, 
       STATISTICS_NORECOMPUTE  = OFF, 
       IGNORE_DUP_KEY = OFF, 
       ALLOW_ROW_LOCKS  = ON, 
       ALLOW_PAGE_LOCKS  = ON) ON [PRIMARY]

Add new table PDA_STYLE.

CREATE TABLE [dbo].[EPOD_PDA_STYLE](
   [EPS_STYLE_ID] [varchar](10) NOT NULL,
   [EPS_DESCRIPTION] [varchar](50) NOT NULL,
   [EPS_STYLE] [varchar](max) NOT NULL,
CONSTRAINT [PK_EPOD_PDA_STYLE] PRIMARY KEY CLUSTERED 
(
   [EPS_STYLE_ID] ASC
)WITH (PAD_INDEX  = OFF, 
       STATISTICS_NORECOMPUTE  = OFF, 
       IGNORE_DUP_KEY = OFF, 
       ALLOW_ROW_LOCKS  = ON, 
       ALLOW_PAGE_LOCKS  = ON) ON [PRIMARY]

A new DAL object will be created for the EPOD_PDA_PREFERENCE table, from source code EPOD_PDA_PREFERENCE.cs. This will be created following the standards of all other DAL objects in the server. This will be used by the new Admin screen to retrieve, edit, update and add records. As such it will consist of:

Private properties for
- The database connection
- The fields on the database tables
- Existence of the record.
- Last Updated date/time
Public properties for
- Setting and Getting the private properties
- Constructors for creating the object from an ID (to find the record if it exists), or from all fields passed in (to create a new record)
- Public methods to
- Update
- Delete
- GetPDAPreferences
- ToXElement - to return the value of the private toJSON method as a single EPL_PDA_PREFERENCE XML tag.
Private methods for
- Getting parameters
- Getting parameters for insert
- Getting parameters for select - Note: It is only necessary to select against the ID or the description - no other fields need be added to this.
- toJSON - to encapsulate the values in fields other than EPP_ID, EPP_DESCRIPTION, EPP_LAST_CHANGED_DATE and EPP_LAST_CHANGED_TIME into a JSON object similar to the following example:

   {
       "WSINTERVAL":"60",
       "UPINTERVAL":"300",
       "GEOMSGINTERVAL":"0",
       "OBSALERT":"content://media/internal/audio/media/34",
       "GEOTAG":true,
       "OBSIMAGESIZE":"1",
       "OBSIMAGECOMPRESSION":"0.3"
       "DEBUG" : true,
       "OBSVIBRATE" : "1",
       "DEBUGMODE" : false,
       "LANGUAGE" : "en"
   }

Properties expected to be boolean (true or false) will be set to true if their value is "Y", else false. All other properties and all property names will be treated as strings (i.e. encapsulated in quotes).

This DAL object will be supported by database packages:

EPOD_PDA_PREFERENCE_SELECT - Note: It is only necessary to select against the ID or the description - no other fields need be added to this.
EPOD_PDA_PREFERENCE_DELETE
EPOD_PDA_PREFERENCE_UPDATE

Note: It is not necessary to add procedures or packages for exporting to XML, as this table is not intended to be exported itself, but rather part of the existing EPOD_SITE XML Export.

A new DAL object will be created for the EPOD_PDA_STYLE table, from source code EPOD_PDA_STYLE.cs. This will be created following the standards of all other DAL objects in the server. This will be used by the new Admin screen to retrieve, edit, update and add records. As such it will consist of:

Private properties for
- The database connection
- The fields on the database tables
- Existence of the record.
- Last Updated date/time
Public properties for
- Setting and Getting the private properties
- Constructors for creating the object from an ID (to find the record if it exists), or from all fields passed in (to create a new record)
- Public methods to
- Update
- Delete
- GetPDAPreferences
Private methods for
- Getting parameters
- Getting parameters for insert
- Getting parameters for select - Note: It is only necessary to select against the ID or the description - no other fields need be added to this.

This will be supported by database packages:

EPOD_PDA_STYLE_SELECT - Note: It is only necessary to select against the ID or the description - no other fields need be added to this.
EPOD_PDA_STYLE_DELETE
EPOD_PDA_STYLE_UPDATE

Note: It is not necessary to add procedures or packages for exporting to XML, as this table is not intended to be exported itself, but rather part of the existing EPOD_SITE XML Export.

Table EPOD_SITE requires the following modifications:

EPL_PDA_STYLE_ID [nvarchar](10) NOT NULL
EPL_PDA_PREF_ID [nvarchar](10) NOT NULL

Existing packages will be modified to allow the creating, editing and selecting of the new flag, including but not limited to:

EPOD_SITE_INSERT
EPOD_SITE_SELECT
EPOD_SITE_SELECT_UPDATED_DATA
EPOD_SITE_UPDATE

The existing EPOD_SITE DAL object will be changed to:

Read the new fields. Note: It is not necessary to add these fields as search-able items.
Export the new fields as XML.

The existing ToXElement method of this DAL object must be modified to export the EPL_PDA_PREFERENCE and EPL_PDA_STYLE tags. This data is retrieved from the new tables, if the appropriate ID is set against the site. The Style and Preference may be retrieved through the use of the new DAL objects at the point of building the XML, or by optionally linking to the new tables in the EPOD_SITE_SELECT* packages, whichever is more efficient. In the latter case, the building of the JSON element within the EPL_PDA_PREFERENCE tag must then be incorporated here rather than in the EPOD_PDA_PREFERENCE DAL object.

The value in EPL_LOGO must also be exported, but only if the data and time on the request for data (i.e. the LOGIN_REQUEST) is before the last changed date and time. To achieve this, the ToXElement and GetSitesXML methods must be overloaded with versions that receive a ClientLastUpdated DateTime parameter. Method ToXElement will then check this date against the Last Updated Date and Time to decide whether the Logo should be populated. This should be passed through from the calling function GetUpdatedData from MessageProcess.ProcessLogonRequest.

Webservices

Note: To be completed in version 1 and 3 of the CALIDUS EPOD server.

\WebServices\Calidus_ePOD\PDAUpdates\UpdatesInfo.xml

Ensure the contents of this proforma file is updated to add the new maxversion attribute, as follows:

   <?xml version="1.0" encoding="utf-8" ?>
   <UPDATES>
     <EPOD_CLIENT version="1.30.0.0"
     url="http://www.calidus-web.com:9093/EPOD/WebServices/Calidus_ePOD/PDAUpdates/EPODClientInstaller.CAB" 
     required="Y" />
     <EPOD_CLIENT_ANDROID version="3.00.02.7" maxversion="3.99.99.99" 
     url="http://www.calidus-web.com:9093/EPOD/WebServices/Calidus_ePOD/PDAUpdates/CALIDUSePODv3.apk" 
     required="Y" />
     <EPOD_UPDATER version="1.26.2.0"
     url="http://www.calidus-web.com:9093/EPOD/WebServices/Calidus_ePOD/PDAUpdates/ePODUpdaterInstall.CAB" 
     required="Y" />
   </UPDATES>

\Data Classes\MessageProcess.ProcessLogonRequest

Implement 'Max Version Check' in Login Request The Versions Data checks here must be modified to retrieve the EPOD_CLIENT_ANDROID information from the incoming LOGON_REQUEST and compare it to the values held in the UpdatesInfo.xml file - this will require a modification to the EPOD_UTILS.getVersionXML method to compare the Android versions (copying the code almost verbatim from the existing code). This code must also check the versions against the potential maxversion parameter held against the tags in UpdatesInfo.xml. In the case where the value of the version in the message exceeds the value of the version in the xml file, the function must return an error code to the calling function, which must then check this returned data and return a logon error in a similar way to an invalid user:

   if (!pda_user.DBExists)
       return new XDocument(new XDeclaration("1.0", "utf-8", "yes"),
                            new XElement("LOGON_RESPONSE",
                               new XAttribute("ID", Message.Attribute("ID").Value),
                               new XElement("RESULT", "NAK"),
                               new XElement("ERROR", "INVALID VERSION OF THE APPLICATION - MAX VERSION IS XXX")));

The maximum version should be inserted at the appropriate place in the message.

The adding of Logo, PDA_Style_ID, PDA_Style and PDA_Pref to the Site section of the login response will be handled by the changes being made to the DAL object above.

Admin

Job Groups

Warning:

implement lists for POD/POC/Service report

POD Report description in table to be as set up in list

All drop-down list values should not be hard-coded, but set and maintained through the EPOD Lists configuration (through tables EPOD_LIST_ITEMS and EPOD_LISTS in the database).

Site

Warning:

implement lists for POD/POC/Service report

POD Report description in table to be as set up in list

Add DDL settings of Style and Preference IDs (using definable lists)

All drop-down list values should not be hard-coded, but set and maintained through the EPOD Lists configuration (through tables EPOD_LIST_ITEMS and EPOD_LISTS in the database).

PDA System Settings

Add a new PDA System Settings Maintenance screen, and add to the Administration menu.

The PDA Settings screen should be added to the Administration menu.

File:FS 328780 PDA Menu.PNG
Administration Menu, showing the new PDA Settings screen

The PDA Settings screen should be created following the standards of all Admin screens.

There should be a Find button, displaying a Find section. This should allow searching by Description only.

There should be a New button, which will display the pop-up Add screen, described in more detail below.

File:FS 328780 PDA Settings1.PNG
PDA Settings screen

On clicking Search, all records matching the selection should be displayed in a table below.

Each line should allow clicking of a Select button, to show an Edit pop-up screen. This screen is also accessible through pressing the New button on the top bar.

File:FS 328780 PDA Settings2.PNG
PDA Settings Add/Edit pop-up screen

The screen will display:

Description
[EPP_DEBUG] [varchar](1) NOT NULL,
"Sending Message Interval", hint help "The amount of time between checks for pending data to be sent to the server.", linked to EPP_WSINTERVAL, a drop-down list of values:
- "30 Seconds", set as value "30"
- "60 Seconds", set as value "60", the default value
- "90 Seconds", set as value "90"
- "2 Minutes", set as value "120"
- "5 Minutes", set as value "300"
- "10 Minutes", set as value "600"
"Auto-Update Interval", hint help "The amount of time between checks whether your assigned load has been updated by admin staff.", linked to EPP_UPINTERVAL, a drop-down list of values:
- "30 Seconds", set as value "30"
- "60 Seconds", set as value "60"
- "90 Seconds", set as value "90"
- "2 Minutes", set as value "120"
- "5 Minutes", set as value "300", the default value
- "10 Minutes", set as value "600"
"Geo-tag Messages", hint help "Enabled - Messages sent back to the server are tagged with GPS co-ordinates.", linked to EPP_GEOTAG, a check-box, defaulting to Checked.
"Geo-tracking Messages", hint help "Whether and how often GPS tracking messages should be sent back to the server. Note that this will leave the GPS unit enabled and may drain the battery.", linked to EPP_GEOMSGINTERVAL, a drop-down list of values:
- "Disabled", set as value "0", the default value.
- "1 Minute", set as value "60"
- "2 Minutes", set as value "120"
- "5 Minutes", set as value "300"
- "10 Minutes", set as value "600"
"Alert Tone", hint help "The sound made on a critical alert.", linked to EPP_OBSALERT, a freely-keyed text value.
"Vibrate Mode", hint help "Indicates whether critical alerts vibrate the device.", linked to EPP_OBSVIBRATE, a drop-down list of values:
- "Off", set as value "0"
- "Short", set as value "1"
- "Long", set as value "2"
- "Intermittent", set as value "3", the default value
"Debug mode", hint help "Enabled - Additional options will be shown, to view and email errors.", linked to EPP_DEBUGMODE, a check-box, defaulting to unchecked.
"Language", hint help "The language used by the application", linked to EPP_LANGUAGE, a drop-down list of values.

All drop-down list values should not be hard-coded, but set and maintained through the EPOD Lists configuration (through tables EPOD_LIST_ITEMS and EPOD_LISTS in the database).

The allowed list of values for "Language" are the two-character ISO 639-1 codes. At this time, only "en" (English) and zh (Chinese) have language files, and only English is fully available. Although this should be added as a drop-down list, the only applicable language at this time is "en", which is what should be defaulted here.

If this screen is called from the Select button against a line, all values from that configuration will be pre-loaded in the entry fields, all fields will be disabled, and Edit and Delete buttons will be provided on the title bar.

If this screen is called from the New button against a line, all values will be set the the default values, and aSave button will be provided on the title bar.

A Close button will be provided in all instances, to allow the user to close the pop-up screen. If any changes have been made whilst in the screen, the user will be prompted if they wish to discard their changes, and the pop-up screen will only exit if confirmed by the user.

If the Edit button is clicked, all fields will be enabled, and the Edit button will be replaced with a Save and Cancel button.

If the Cancel button is pressed, any changes the user has made will be discarded.

If the Save button is pressed, any changes made by the user will be saved, and the table redisplayed to show the additional record.

If the Delete button is pressed, the user will be asked to confirm if they want to delete. If they do not, the pop-up screen will remain open. If they confirm they are sure, the record will be deleted and the table redisplayed to show the remaining records.

The following fields will not have an ability to have these settings changed, and will default as follows:

[EPP_OBSIMAGESIZE] - 1
[EPP_OBSIMAGECOMPRESSION] - 0.3

These will be set when creating a new record.

Mobile Android Application

Note: All changes to methods and functions below should have the JSDoc comments changed to reflect changes to functionality, if appropriate.

Database/DAL

Add new fields to EPOD_SITE (PDA_Style_ID, PDA_Style, PDA_Pref)

This should be achieved as follows:

\Resources\Database\DBConnection.js

Change the definition of the EPOD_SITE table in function CreateDB to add new fields to the end of the table:

EPL_PDA_STYLE_ID nvarchar(10) NOT NULL DEFAULT \'\'
EPL_PDA_STYLE ntext NULL
EPL_PDA_PREFERENCE ntext NULL

Change the last version changed in function InstallDB to the build number of this change (set in \TiApp.xml).

\Resources\Database\PDA_SITE.js

Add new fields to the DAL object in all places affected:

New fields:

EPL_PDA_STYLE_ID
EPL_PDA_STYLE
EPL_PDA_PREFERENCE

Functions/methods affected:

function PDA_SITE(EPL_SITE_ID)
- Add properties for the new fields, defaulted to .
- When selecting data from the database table EPOD_SITE, populate the values of the new fields. If the record does not exist, these should default to .
method Update
- Add the new fields to the database update SQL and parameters, and to the database insert SQL and parameters.
function InsertPDASite
- Add the new fields as parameters to the function.
- Add the new fields to the database insert SQL and parameters.
function UpdatePDASite
- Add the new fields as parameters to the function.
- Add the new fields to the database update SQL and parameters.
- If EPL_LOGO contains data, convert the logo to an image (using Ti.Utils.base64decode) and store this in the application's data directory, using Ti.Fileystem.getFile(Ti.Filesystem.applicationDataDirectory, 'altLogo.jpg').write().
function InsertAllPDASites
- Change the sample comment to show the new fields
- Add the new fields as parameters to the call to InsertPDASite (through a call to the GetXMLItem function).
- Ensure EPL_LOGO is passed from the incoming XML.
function InsertAllPDASitesJSON
- Change the sample comment to show the new fields
- Add the new fields as parameters to the call to InsertPDASite (through a call to the GetJSONItem function).
- Ensure EPL_LOGO is passed from the incoming JSON.

App Load

Set style and ID on the device from the parsed data in the site table

This should be achieved as follows:

\Resources\ui\common\Login.js

After the object Ti.App.PDA_SITE has been loaded, check the settings of the new fields and action as follows:

Set Ti.App.style.configItems to be the resulting object of parsing the value in EPL_PDA_STYLE as JSON.
Set Ti.App.style._style to the value in EPL_PDA_STYLE_ID. Note: Encapsulate this code in try/catch objects - any errors should set the values above back to their defaults:
- Ti.App.style._style -
- Ti.App.style.configItems - {}
Parse the value in EPL_PDA_PREF and set the system properties from the values contained in the resulting object. This code can be copied from \Resources\ui\common\Config.js, from the successful callback of scanning a QR barcode (Ti.App.Barcode.success).

Preferences

Remove all preferences except Site and Webservice from the mobile device preferences.

This should be achieved as follows:

\platform\android\res\values\array.xml: Remove all entries

\platform\android\res\xml\preferences.xml: Remove all entries except the first 2 (SITEID and WEBSERVICE)

Logon

Change Required version check to force exit the app after issuing the error

\Resources\System\WebServices.js

Change functions ProcessJSONLoginResponse and ProcessLoginResponse, when checking the EPOD_CLIENT_VERSION attribute/value. After the existing code, if the required attribute/value is set to "Y", exit the app (calling function ExitApp).

All changes relating to receiving Settings and Styles in the logon response message are handled by the PDA_SITE changes specified above.

All changes to convert the logo data to an image and store on the device's app folder are handled by the PDA_SITE changes specified above.

All changes to set the style and style ID on the device from the parsed data received are handled by the PDA_SITE changes specified above.

Store the original value of the style and style ID fields from the site before processing. If the values have changed after loading the Site, refresh the Login display, by calling Ti.App.style.restyleItemsEx(win, true);

Style

\Resources\System\style.js

Remove the setting of Ti.App.style.configItems completely - note this is when it is populated with values, not when it is created as {}.
Default Ti.App.style._style to '' (OBS default), rather than the value from the system property.

Remove all altLogo*.* image files from the application directory \Resources\images.

Appendix A: TEST PLAN

Warning:

Test Script / Scenario Reference	EPOD Server-Side Settings	Call Number(s): 328780
Test Script / Scenario Description	description of what is to be achieved	PASS / ISSUES / FAIL
Menu Access	Where on the menus the item can be found
Pre-requisites	The prerequisites of the test	Tested By:
Test Objective	The details of what each group of tests is to achieve	Date:

Step	Action	Result	Remarks	P/F
1	Area being tested in this cycle
	Any notes or prerequisites for the tests following.
1.01	The actions to follow	The expected result
1.02	The actions to follow	The expected result
1.03	The actions to follow	The expected result

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	2.75	2.75	0	£0.00
Technical Specification	0.00	0.00	0	£0.00
Development	11.00	11.00	0	£0.00
Testing and Release	2.25	2.25	0	£0.00
Implementation	1.75	1.75	0	£0.00
Project Management	1.00	1.00	0	£0.00

TOTAL	18.75	18.75		£0.00

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

B.1 References

Ref No	Document Title & ID	Version	Date
1

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

Murray Middleton	OBS Development Manager	_____________________________
Julie Scott	Sponsor	_____________________________

Anonymous

Search

FS 328780 EPOD Server-Side Settings

Namespaces

More

Page actions

Contents

Functional Overview

Client Requirement

Solution Overview

Scope

Set-up

Pre-requisites

Menu Structure

Data

Description of Changes

Database/DAL

Webservices

Admin

Job Groups

Site

PDA System Settings

Mobile Android Application

Database/DAL

App Load

Preferences

Logon

Style

Appendix A: TEST PLAN

Appendix B: Quote & Document References

Navigation

Navigation

Translate

Wiki tools

Wiki tools

Anonymous

Search

FS 328780 EPOD Server-Side Settings

Functional Overview

Client Requirement

Solution Overview

Scope

Set-up

Pre-requisites

Menu Structure

Data

Description of Changes

Database/DAL

Webservices

Admin

Job Groups

Site

PDA System Settings

Mobile Android Application

Database/DAL

App Load

Preferences

Logon

Style

Appendix A: TEST PLAN

Appendix B: Quote & Document References

Navigation

Wiki tools

Page tools

Categories