View source for FS 330147 NHSBT Stop Update at Start Job

<div class="noprint">
{{#vardefine:Client|NHS}}
{{#vardefine:ClientName|NHSBT}}
{{#vardefine:System|''CALIDUS'' ePOD}}
{{#vardefine:Doc_Title|NHSBT Tooting Fixes}}
{{#vardefine:Version|1.0}}
{{#vardefine:Date|28th September 2015}}
{{#vardefine:Reference|330147}}
{{#vardefine:Year|2015}}
</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  ==
* Remove the 30 second delay from Start/Arrive/Continue Job when there is a limited data network on the device.
* Stop the Pending Timer when entering a job, and restart only when all jobs at that location are completed.
* Stop loads being assigned to drivers when only half is available
* Stop issue with loads updating and showing 'blank' jobs
* Allow recovery when a half-load is completed.


== Solution Overview  ==
A new flag should be added to Site to control whether online job updates are attempted.

If the new flag is set to "N", the EPOD Mobile Device should NOT attempt to online check for job updates at Start, Arrive and Continue Job, but instead place the message straight onto the pending queue, for sending at a later time.


A new flag should be added to Site to control whether pending data updates are attempted at all times, or just when not processing a job.

If the new flag is set to "N", the EPOD Mobile Device should turn off the pending data timer when starting a job, and re-enable it when the job is complete.


When loads are received into the system from an external source through the webservices (CALIDUS TMS in this case), do not set the Driver and Vehicle against the load until ''after'' all jobs on that load are processed.


Allow loads to be reset from Complete to Pending status, for Administrative users, where the site allows data updates.


== Scope  ==
{{Note}} These changes should be completed in version 2 and 3 of the {{#var:System}} system.


The implications of this change being enabled are that the device will not check for any update the jobs being started, and will be reliant on the job data that was sent to the device in the last background update, which may occur up to every 10 minutes. This could lead to containers being delivered when they should no longer be, or collections not being processed when they should.


<!-- NEW PAGE --> 

= Set-up  =

== Pre-requisites  ==

== Menu Structure  ==

== Data  ==
The new Site flags EPL_JOB_LOCK_ONLINE and EPL_PENDING_ALWAYS must be set to "N" for all NHSBT sites that require this functionality.

The existing Site flag EPL_UPDATE_FUNCTIONS must be set to "Y" for all NHSBT sites that require the ability to reset loads to Pending status.


<!-- NEW PAGE --> 

= Functional Description  =
== Database ==
Table EPOD_SITE requires the following modifications:
* EPL_JOB_LOCK_ONLINE [nvarchar](1) NOT NULL DEFAULT "Y"
* EPL_PENDING_ALWAYS [nvarchar](1) NOT NULL DEFAULT "Y"
Existing packages will be modified to allow the creating, editing and selecting of the new fields, 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 the field as search-able items.
* Export the new fields as XML.


== DAL ==
The EPOD_SITE DAL object will be modified to add these new flags when selecting, updating or adding new EPOD_SITE records.


== Webservices ==

The adding of the new fields to the Site section of the login response (\WebServices\Calidus_ePOD\Calidus_ePOD.asmx and Calidus_json.ashx) will be handled by the changes being made to the DAL object shown above.


When loads are received into the system through the webservices (\WebServices\DataService\ePOD_DataService.asmx and ePOD_DataService2.asmx, method EPOD_XML_IMPORT) from an external source (CALIDUS TMS in this case), do not set the Driver and Vehicle against the load until ''after'' all jobs on that load are processed.

This process calls EPODServer\Data Classes\EPOD_DATASERVICE.cs, method ProcessXMLImport, which calls ProcessLoads in the same file. 

This procedure processes the load and saves all values onto it, then processes all jobs. 

The user (EPOD_LOAD.EPL_USER_ID) and vehicle (EPOD_LOAD.EPL_VEHICLE_ID) are set before processing jobs. The setting of these two properties must be moved to ''after'' processing all jobs. {{Note}} It is not necessary or advised to move the initial creation of the Load, or creation of the EPOD_USER and EPOD_VEHICLE records (if required) from the start, just the population of the two new fields. 

After the jobs have been processed and these two EPOD_LOAD field have been set, the EPOD_LOAD object must be updated. 

{{Note}} The Update for EPOD_LOAD currently happens before processing of jobs. It is believed that this may also be moved to the end of the process, as the EPOD_LOAD object is used by reference in this procedure only, and therefore the Update may be after the creation of the jobs. If it is the case (for technical reasons) that this must be left here, and then a second Update issued after the Job creation/update, then that is accepted, but all efforts must be made to only issue one update, to ensure the process is efficient.


== Admin ==
The EPOD Admin Site screen (site_header.aspx) will be modified to add these flags to the PDA tab, for maintenance.

[[File:FS_330147_SiteMaint1.PNG|border|600px]]
<br />''Site Maintenance Screen''<br />

The new flags should be added as check-boxes in the area indicated, initialising to checked (based on the default value of "Y"). Unchecked will save a value of "N".


The EPOD Admin Load Maintenance screen (load_header.aspx) will be modified to allow loads to be reset from Complete to Pending status, for Administrative users, where the site allows data updates.

Completed or Cancelled loads found in this screen may be edited if the following flags are set as indicated:
* EPL_USER_ADMIN = "Y"
* EPL_UPDATE_FUNCTIONS = "Y"
Therefore, when clicking the '''Select''' button against a completed or cancelled load, the pop-up edit screen should show the '''Edit''' button. When clicked, the user should be prompted with a confirmation alert as follows:
: "This load is at status {status} and should not be changed. Are you sure you want to edit this load?"
Options of "Yes" and "No" should be offered.

If the user clicks "No", the alert should be removed and no further action taken.

If the user clicks "Yes", the alert should be removed and then enable editing of any field on the load, as if editing a pending load, but also allowing changing of the status.


== 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 ===
The device should be modified to add the new Site flags to the database on creation.

The device should populate these flags (defaulting to Y) if the flag does not exist.


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_JOB_LOCK_ONLINE nvarchar(1) NOT NULL DEFAULT \'Y\'
* EPL_PENDING_ALWAYS nvarchar(1) NOT NULL DEFAULT \'Y\'

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_JOB_LOCK_ONLINE
* EPL_PENDING_ALWAYS


Functions/methods affected:
* function PDA_SITE(EPL_SITE_ID)
** Add properties for the new fields, defaulted to 'Y'.
** 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 'Y'.
* 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.
* 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).
* 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).


=== Job Detail ===
The device Job Lock and Job Arrival webservices should be modified to check the Site flag EPL_JOB_LOCK_ONLINE - if set to N, the device should add this message straight to the pending messages, rather than attempting to send them on-line.

This will be achieved as follows:

;\Resources\ui\common\JobDetail.js

Function funStartJob will be modified to check the value of the new Site flag EPL_JOB_LOCK_ONLINE from Ti.App.PDA_SITE, when determining that the device is on-line, i.e.
; if (Titanium.Network.getOnline()&&Ti.App.PDA_SITE.EPL_JOB_LOCK_ONLINE=="Y") {

The message "Checking for Updates on this job..." in this function should become "Please Wait..." for the condition where the new Site flag Ti.App.PDA_SITE.EPL_JOB_LOCK_ONLINE is set to "N" or the device is offline. 

This requires a new i18n translation for this message, which should be added to the following files:
; \i18n\xx\strings.xml


The Pending timer should be be stopped when the job is begun, at the following steps:
* If Start Job is clicked and the job does not require Arrival times.
* If Arriver Job is clicked
* If Continue Job is clicked.
This will ''only'' be done if the new flag EPL_PENDING_ALWAYS is set to "N"

This is all in function actionJobs, at the same time that the AutoUpdate timer is stopped with the following code:
: Ti.App.AutoUpdateTimer.StopTimer();


The Pending Data Timer should be restarted once the call-back procedure is called for the Job Details screen. This is in the definition of function funJDCallbackDet, defined in two places in function actionJobs. The Pending timer should be restarted when the Update timer is started, with the following code:
: Ti.App.AutoUpdateTimer.StartTimer();
{{Note}} It is not necessary to enclose this starting of the timer in a check for the new Site flag - further changes to the timer itself (below) will check whether the timer is already started, and this will be used as a failsafe at times when then Pending Data Timer stops for other reasons.


=== WebServices ===
The current method of enqueuing messages to the pending queue from the JobLockRequest function is to immediately trigger a send in the background. This is undesirable. Furthermore, the previous temporary change to this function (under change 330146) must be removed, as it is replaced by the changes to JobDetail above.

;\Resources\System\WebServices.js

Function JobLockRequest will be modified as follows:

The setting of p_blnUpdateRequired will be reinstated to the previous code, as follows:
: p_blnUpdateRequired = p_blnUpdateRequired&&!IsWebServiceActive;


If the parameter p_blnUpdateRequired is set to false, the function currently sends the message through a call to WriteToQueue. This will be modified to add the existing parameter p_blnTriggerSend to this call as the value false, as follows:
: WriteToQueue(strXML, 0, false);


{{Note}} All other WriteToQueue calls should be changed, ensuring that the timer is not triggered. In total this is as follows:
* LoginRequest - leave triggering the pending send
* LogoffRequest - leave triggering the pending send
* JobLockRequest - being changed to false at all times
* JobUpdateRequest - already false
* JobUpdateRequests - already false
* GPSStatusRequest - make false at all times
* PhotoUploadRequest - make false (twice in procedure) at all times
* LoadUpdateRequest - leave triggering the pending send
* VehicleCheckRequest - make false at all times.

{{Note}} For JobUpdateRequest and JobUpdateRequest, the function triggers a send on the pending queue at the end, through a call to Ti.App.PendingDataTimer.TriggerSend(). This should be called ''only'' if the new Site flag EPL_PENDING_ALWAYS is set to "Y".


The PendingDataTimer should be modified to have a new Started property added to it, defaulting to false. This should checked that this is false when starting the timer in the StartTimer method, and set to true when the timer is started in this function. The Started property should be set to false in the StopTimer method, after clearing the interval. This is exactly how the existing AutoUpdateTimer works, and this code should be checked for details of how to implement this.


<!-- NEW PAGE --> 
{{Doc_Appendix
|Appendix=A
|Estimate=Y
|Glossary=EPOD
|Ref1=&nbsp;
|RefV1=&nbsp;
|RefDate1=&nbsp;
|REQ=0
|EST=0
|FS=1.25
|TS=0
|DEV=4.75
|ST=1
|IMP=1
|PM=0.25
|Client={{#var:Client}}
|Year={{#var:Year}}
|FSEST=N
|FOC=Y
|Rev1=Murray Middleton
|Rev1Title=OBSL Product Development Manager
}}</div> 
[[Category:{{#var:Client}} FS]]