View source for FS 312817 AUNZ-017 LFS Job Swap

<div class="noprint">
{{#vardefine:Client|LFS}}
{{#vardefine:ClientName|LFS}}
{{#vardefine:System|''CALIDUS'' ePOD}}
{{#vardefine:Doc_Title|LFS Job Swap}}
{{#vardefine:Version|0.3}}
{{#vardefine:Date|28th March 2014}}
{{#vardefine:Reference|312817 AUNZ-017}}
{{#vardefine:Year|2014}}
</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  ==
The process of swapping jobs/orders between drivers is outlined in two areas:

1)	'Park' swapping process of several orders being moved out to a remote distribution location and then distributed between several drivers/routes - this could be dealt with in two ways:
:a.	New functionality to enable 'on-the-fly load building' to create new loads/trips from the EPOD device and allow 'on-the-fly load editing' to remove an order from a load. This would allow drivers to dynamically select which packages they wanted to deliver.
:b.	A more rigid 'pre-planned' approach utilising the standard scheduling engine and/or manual planning to create a trunk movement to push all the goods out to the remote location and the separate radial delivery runs. The distribution process would then just be around handing the appropriate order packages to the driver conducting the run. No driver decision would be allowed with this approach. The standard POD unload scan could then be carried out by the first driver of all boxes off the trunk trip and then a standard POC load scan onto the respective new radial delivery trips. In this scenario signatures may need to be suppressed.

Important point here is that option a) requires complex development and in option b) development is minimal. At this point it has been assumed that option b) is the required approach.

2)	'Ad-hoc' swapping of jobs between two existing vehicle runs (trips) that are currently in execution at an 'unknown' dynamic location. For this, the following is assumed:
*	This occurs for all remaining order packages on the current run
*	Packages are is only transferred one way (i.e. from one driver to another, not both drivers exchanging each way)
*	That only items destined for delivery to end customer are swapped (i.e. swapped items are not collections to be returned to depot). 
*	This assumes that for job swapping, both trips already exist and have been generated from C-TMS and sent to the EPOD device as per standard planning functionality - i.e. new load building and new trip creation is not required.

This requires functionality to effectively handle both trips as being cross-docked at the new dynamic location, allowing unload confirmation from the first planned run and load confirmation onto the second:

:a.	Generate a new location in master data based on the latitude and longitude of the location at which the swap is occurring
:b.	Convert the first trip from which packages are being removed into cross-dock leg and add the new stop - unloading all remaining orders at this new stop
:c.	Convert the second trip into a cross-dock delivery and add a new stop - loading all orders at this new stop

The above actions on C-TMS need to be carried out based on new message instructions to be received from EPOD.


The driver receiving the job will click an assign job button which will allow the driver to either enter the job ID that they wish to assign to themselves or launch the barcode scanner and scan one of the packages to then assign the job to themselves. This will then send a message back to the CTMS to say that the driver has taken the job. The job will then be placed on the drivers' workload for the day.


NOTE: As CTMS allows for complete planning of trips for the day, it could potentially be planned in such a way that this functionality is not required. There is also the more secure option to allow the LFS planners to assign and de-assign jobs from drivers.


Further discussions with the customer drove an extension to the Ad-hoc Swap process, with the following requirements:
* Swap at any time (loading at depot, before departure, when en-route with a load)
* Swap for any reason (late driver, late running, incorrect planning, sickness)
* Swap all or some jobs, with or without existing trip)
* Swap without CALIDUS EPOD (i.e. manually in CALIDUS TMS)
* Swap with planned trip
* Swap between trips (bi-directional)
* Swap to unplanned trip (i.e. no trip on "To" device)
* Individual swap via Scanning Packages
* Mass swap (i.e. via keypress on device, no scanning)
* A single successfully-scanned package identifies the whole order, even if there are multiple packages.
* Swap Deliveries
* Swap Collections


== Solution Overview ==
{{Note}} See [[#Appendix A: Process Flows|Appendix A]] for process flows, a visual indication of how the systems handle transferring a job from one load to another, both on the device and within ''CALIDUS'' TMS. 

The existing ''CALIDUS'' TMS system requires strong planning of orders onto a trip, so that driver performance can be measured from planned versus actual times. As such, the core process within ''CALIDUS'' TMS to achieve the requested functionality is to re-plan orders from one trip to another, passing the modified trip information out to {{#var:System}}. As the LFS operation has stated that the office administers do not have time to do this, a Job Transfer process has been designed to allow the drivers to transfer or swap jobs between themselves at any time. This process allows drivers already with a load and drivers without a load allocated to them to transfer jobs from another existing load. In both cases, this Swap mechanism will not be allowed unless the system has been configured to allow it.

===With a Load===
When in the Job List screen on the device, the driver may push the '''Menu''' button and select the new option ''Job Swap''. This will start the Job Swap process below.

===Without a load===
When requesting a Load, the device will inform the user that none was found. If the system is configured for Job Transfer, the device will offer an option on this pop-up message to allow the user to start the Job Swap process.


===Job Swap Process===
When the Job Swap process has been started, the device will first prompt for a Load ID. This is the Load ID of the Driver from whom jobs are to be transferred. The device will supply no prompts to enable the driver to select from a list or pattern-match - the exact Load ID must be entered for this to be successful. This is to prevent abuse of the system - the driver must have prior knowledge of the exact Load ID, or read the Load ID from the source driver's device.

{{#var:System}} will return the jobs for this Load. If the load is not found, an error message will be displayed on the device and the device will return to the prompt for Load ID.

Once a valid load is returned, the device will build this into a list of jobs, not dissimilar to the existing Job List screen. It will display:
* The Load ID swapping from
* a table with one row per order. This table will be scrolling. Note that a direct delivery (i.e. pick up from X, deliver to Y) will appear as one item on the list, as both will be selected together. The list will not consolidate orders together, but will instead list all the individual orders separately. The list will display the same details as the Job List
* A text box for scanning of container barcodes - this is for manual or scan entry of containers, to identify jobs.
* A '''Finished''' button to complete transferring jobs.

When selecting an order from the list (by clicking on it), the screen will highlight that line (by changing the background colour) to show that it is selected. 

When scanning or entering a package ID (a container) in the text box provided, the device will search for a container that matches the entry once the button is pressed. If scanning with a device with an integrated scanner (such as the Intermec CN51, expected to be in use for this operation), this will immediately enter the item once scanned. This requires the scanned to be configured correctly (i.e. to have a Return tagged on the end of the barcode content). Note that this functionality will also work if the user presses the Enter button on the keyboard. If there are multiple containers that match that ID, the first will be chosen. The Order for this container will be found on the list and highlighted. 

Regardless of how orders are selected for transferring (i.e by selecting from the table or scanning), any jobs that have been linked to that order (i.e. consolidated) will also be highlighted at this time. If the order selected is already highlighted (i.e. marked for transferring), the that order ''only'' will be marked as not being transferred - any other jobs that are consolidated with it shall be left marked as being transferred.

Once the driver has selected all the jobs that are being transferred, they can press the '''Finished''' button - this will inform {{#var:System}} to transfer the selected jobs from the selected load onto the driver's load.


===Onward Processing of Jobs===
{{#var:System}} will send a message to ''CALIDUS'' TMS, directing it to transfer jobs from the selected load to the new driver's load - the list of jobs will be provided. For drivers who did not have a load initially, {{#var:System}} will have created one for them and will inform ''CALIDUS'' TMS to create it as part of this message. Independently, {{#var:System}} will also return an amended (or created) load to the driver. Both systems will follow the same logic, as follows:
* Loading tasks will be created on the destination load at the point of job transfer.
* The Collection and Delivery jobs will be transferred onto the destination load at the end of the load.
* The jobs will be removed from the source load.
* ''CALIDUS'' TMS will also annotate the source load at the point of transfer that the selected jobs were cross-docked.
* ''CALIDUS'' TMS will create audit records for each job, that they were transferred.

The driver from whom the job was swapped will be informed that the identified jobs have been removed from their list the next time that the Job List refreshes. This can be initiated faster by the driver pressing the '''Menu''' button on the device and selecting ''Refresh'' from the pop-up menu. The device will display all of the jobs removed from the load in the normal fashion. 

The driver who requested the jobs will receive an updated load list immediately. The device will not consolidate the transferred jobs with the jobs already on the job list, nor will those jobs be sequenced. The new job list will show:
* A consolidated Loading task, for each of the jobs selected to be transferred to be scanned onto the driver's vehicle.
* Any jobs (Loading, Collection, Delivery, Unloading) that existed on the driver's job list before any transfers.
* Collection and Delivery tasks appended to the end of the current Job List. If any of these jobs selected were already highlighted with each other, this consolidation will be reflected and a single line will be displayed. {{Note}} Any jobs that were manually consolidated by the previous driver will ''not'' be reflected.
* Unloading tasks for any Collections being brought into the network after this.

{{Note}} For drivers who did not have a load initially, one will have been created for them as part of this process.

The driver will then be able to scan the orders onto the vehicle. All items must be scanned, like any normal loading or collection task. The jobs will be configured in such a way as to not require customer or driver signatures at this time.


The driver can elect to cancel any of the jobs, at loading or at any later stage. {{Note}} Cancelling transferred jobs on the driver's device will not cancel the loading or the job transfer, it will cancel the job completely as if it did not take place. If the jobs is required to be passed to someone else, or passed back to the original driver, the job transfer process above can be followed again. Again, note that transferring a job back to the original load will not consolidate or sequence the transferred job back into it's original position or consolidation on the original load - it will be added to the end of the list as described above.


Transferred jobs that are completed by this driver will be updated in ''CALIDUS'' TMS in the same way that normal jobs are completed - all arrival and departure times will be captured. The signature and POD/POC documents produced will be unaffected by the transfer of the job. The only difference will be that these jobs will be shown to have been completed by the driver who transferred the jobs, rather than the driver of the original load.


Notes:
* Multiple drivers may be selecting orders to transfer to themselves from the same source load at the same time - {{#var:System}} will allow this, but will not validate whether the drivers are attempting to take the same orders at the same time - only the driver who successfully indicates the job first will obtain the jobs to deliver or collect.
* Drivers can swap jobs by transferring in the above fashion from each other's loads at the same time - {{#var:System}} will allow this.


== Scope ==
* This functionality will be developed in the Android application only and will not be available in the Windows Mobile application.
* ''CALIDUS'' TMS functionality is mentioned only by reference in this solution - see elsewhere for specification of the changes to that system.
* A data connection is required on the device to transfer a job from one driver to another.
* There must be an existing Load from which to transfer - unassigned jobs will not be transferable. These jobs should be manually assigned.
* No sequencing or consolidation of jobs with existing jobs on the To driver’s Load - this will be completed manually by the driver.
* "From" Load driver will wait for an automated refresh from Server, or can manually refresh if they want an update quicker.
* Collections that have not yet been completed will be swapped by selecting the order on the list, as the packages have not yet been collected and therefore there are no barcodes to scan.
* Bi-directional swapping can be achieved by both drivers following this process simultaneously.
* Manual swapping is achieved through the existing ''CALIDUS'' TMS Cross-dock re-planning mechanism.


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

== Pre-requisites  ==
* A working {{#var:System}} system.
* A working ''CALIDUS'' TMS system, accessible to the {{#var:System}} system.
* ''CALIDUS'' TMS Changes to be completed (specified elsewhere):
** Processing the new Job Swap Request message
** Trip ID will be generated by {{#var:System}} in the format "EPL-00000000" - ''CALIDUS'' TMS must check if any code extracts the sequence from this trip id and checks for uniqueness.
** On processing Job Swap messages, ''CALIDUS'' TMS must generate Cross-dock style drops, as follows: 
*** Generate (for the destination trip) loading tasks for the deliveries taken at the point listed here, and Unloading tasks for them after the last drop, similarly to as described here for the Server Import/Export modifications.
*** Generate (for the source trip) unloading tasks for the deliveries taken at the point listed here. Uncompleted direct deliveries (i.e. Collect/Deliver pairs) will simply be removed.
** No updates will be set to {{#var:System}} for these re-planned trips as a direct result of the processing of the Job Swap message, although further planning changes must be reflected back to {{#var:System}}.
** When swapping orders back to the original loads, the process must undo the cross-dock rather than re-plan another cross-dock for the order.
** Maintain Audit records of the swaps.


== Menu Structure  ==
None


== Data  ==
The new configuration flag EPL_JOB_TRANSFER must be set to enabled ("Y") on the EPOD_SITE record.

Create an EPOD_JOB_GROUP of "_JOBSWAP_" with the following settings:
* EPL_SITE_ID - As required
* EPL_JOB_GROUP - "_JOBSWAP_"
* EPL_DESCRIPTION "Job Swap Job Group"
* EPL_DEL_DRIVER_SIGN - As required, expected to be "N"
* EPL_COL_DRIVER_SIGN - As required, expected to be "N"
* EPL_DELIVERY_PAYMENT - "N"
* EPL_DOCUMENT_PHOTO - As required, expected to be "N"
* EPL_CONTAINER_ONLY - As required, expected to be "N"
* EPL_METRICS_ENTRY - "N"
* EPL_NOTES - As required, expected to be "Y"
* EPL_DEL_CUST_SIGN - As required, expected to be "N"
* EPL_COL_CUST_SIGN - As required, expected to be "N"
* EPL_CONSOLIDATION - As required, expected to be "Y"
* EPL_CANC_IMAGE_REQ - As required, expected to be "N"
All other fields may be set to their default values.



<!-- NEW PAGE --> 
= Functional Description  =
== Database/DAL ==
Table EPOD_SITE requires the following modification:
* EPL_JOB_TRANSFER - nvarchar(1), NOT NULL DEFAULT 'N', values 'Y' or 'N'.
* EPL_LOAD_PREFIX - nvarchar(5).
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
* Export the XML format, adding the flag ONLY.
{{Note}} It is not necessary to add this flag as a search-able item. However, if allowing this keeps the packages and DAL objects standard in design, then this can also be done, within the DAL and the packages.

The XML Export of EPOD_SITE records will look as follows: 
  <EPOD_SITE>
    <EPL_SITE_ID></EPL_SITE_ID>
    <EPL_DESCRIPTION></EPL_DESCRIPTION>
    <EPL_SERVICE_POD_FORMAT></EPL_SERVICE_POD_FORMAT>
    <EPL_DELIVERY_POD_FORMAT></EPL_DELIVERY_POD_FORMAT>
    <EPL_COLLECTION_POD_FORMAT></EPL_COLLECTION_POD_FORMAT>
    <EPL_SERVICE_ACTIVITIES></EPL_SERVICE_ACTIVITIES>
    <EPL_SERVICE_PREWORK></EPL_SERVICE_PREWORK>
    <EPL_SERVICE_INFO></EPL_SERVICE_INFO>
    <EPL_SERVICE_PRODUCTS></EPL_SERVICE_PRODUCTS>
    <EPL_SERVICE_MC_REF></EPL_SERVICE_MC_REF>
    <EPL_SERVICE_DIAGNOSIS></EPL_SERVICE_DIAGNOSIS>
    <EPL_SERVICE_POSTWORK></EPL_SERVICE_POSTWORK>
    <EPL_AUTO_COMPLETE_EMAIL></EPL_AUTO_COMPLETE_EMAIL>
    <EPL_AD_HOC_COLLECTION></EPL_AD_HOC_COLLECTION>
    <EPL_DEL_DRIVER_SIGN></EPL_DEL_DRIVER_SIGN>
    <EPL_COL_DRIVER_SIGN></EPL_COL_DRIVER_SIGN>
    <EPL_DELIVERY_PAYMENT></EPL_DELIVERY_PAYMENT>
    <EPL_DOCUMENT_PHOTO></EPL_DOCUMENT_PHOTO>
    <EPL_CONTAINER_ONLY></EPL_CONTAINER_ONLY>
    <EPL_PDA_DIS_JOB_CODE></EPL_PDA_DIS_JOB_CODE>
    <EPL_LINKED_C_D></EPL_LINKED_C_D>
    <EPL_METRICS_ENTRY></EPL_METRICS_ENTRY>
    <EPL_NOTES></EPL_NOTES>
    <EPL_FORCED_ENTRY></EPL_FORCED_ENTRY>
    <EPL_SYSTEM_TYPE></EPL_SYSTEM_TYPE>
    <EPL_UPDATE_FUNCTIONS></EPL_UPDATE_FUNCTIONS>
    <EPL_VEHICLE_CHECK_CONFIG></EPL_VEHICLE_CHECK_CONFIG>
    <EPL_JOB_LIST_CFG></EPL_JOB_LIST_CFG>
    <EPL_ARRIVAL_FLAG></EPL_ARRIVAL_FLAG>
    <EPL_SCAN_ERROR_FLAG></EPL_SCAN_ERROR_FLAG>
    <EPL_LAST_CHANGED_DATE></EPL_LAST_CHANGED_DATE>
    <EPL_LAST_CHANGED_TIME></EPL_LAST_CHANGED_TIME>
    <EPL_RESEQUENCE></EPL_RESEQUENCE>
    <EPL_CLAUSE_DELIVERY></EPL_CLAUSE_DELIVERY>
    <EPL_JOB_STATUS></EPL_JOB_STATUS>
    <EPL_CONSOLIDATION></EPL_CONSOLIDATION>
    <EPL_VEHICLE_STOCK_FLAG></EPL_VEHICLE_STOCK_FLAG>
    <EPL_SCAN_AT_VEHICLE></EPL_SCAN_AT_VEHICLE>
    <EPL_JOB_TRANSFER></EPL_JOB_TRANSFER>
  </EPOD_SITE>

The existing database package EPOD_SETUP will be modified to ensure that the new flags are defaulted appropriately


The EPOD_LOAD DAL object will be modified to call a new Trip ID generation package as part of a new constructor. This will be used when creating a load for the job swap process where no destination load is in place. The Load ID will be generated by selecting loads where the ID matches the new EPL_LOAD_PREFIX parameter for the site, adding a dash (if there is a prefix), followed by an 8-digit number, generated as the highest number found + 1. If no Prefix is found, the standard Load ID generation mechanism should be used.


The existing table EPOD_USER_AUDIT will be modified to add the following field:
* EPL_MESSAGE_CONTENT, nvarchar(max) default null.
Existing packages will be modified to allow the creating, editing and selecting of the new fields, including but not limited to:
*EPOD_USER_AUDIT_INSERT
*EPOD_USER_AUDIT_SEARCH
*EPOD_USER_AUDIT_SELECT
*EPOD_USER_AUDIT_UPDATE
The existing EPOD_USER_AUDIT DAL object will be changed to:
* Read the new field
{{Note}} It is not necessary to add this flag as a search-able item.

A new database procedure EPOD_XFER_SELECT_JOB_SWAP will be written to allow selection of EPOD_USER_AUDIT records that are:
*    Job Swap records (EPL_MESSAGE_TYPE = "JOB_SWAP_REQUEST").
*    with EPL_XFER_TTM_FLAG = "N" or "". 

This procedure should link to EPOD_SITE and select all fields from EPOD_USER_AUDIT and EPOD_XF_CONFIG that match the criteria above.

EPOD_XF_CONFIG should be optionally linked to from any configuration set up against the Site, using EPL_XF_CONFIG of EPOD_SITE to link to the table, ensuring that only configurations for EPL_XF_ID of 'JOBSWAP' are found.

This package will be added to a new method of the EPOD_USER_AUDIT DAL object, to retrieve the messages.


== Import/Export Messages ==
A new Job Swap Request processor will be created in Calidus_ePOD.asmx, processing messages in the following format.
  <JOB_SWAP_REQUEST ID="0" SITE="EPL_SITE_ID" USER="EPL_USER_ID" PASSWORD="*****" DEVICE_ID="" 
   GPS_STAMP="53.3487735,-2.8517232" DEVICE_OS="android 4.1.2" DEVICE_TYPE="GT-I8190N">
    <EPL_SITE_ID></EPL_SITE_ID>
    <EPL_LOAD_ID_FROM></EPL_LOAD_ID_FROM>
    <EPL_LOAD_ID_TO></EPL_LOAD_ID_TO>
    <EPL_VEHICLE_ID></EPL_VEHICLE_ID>
    <EPL_USER_ID></EPL_USER_ID>
    <EPL_GPS_COORDS></EPL_GPS_COORDS>
    <EPOD_JOBS>
      <EPOD_JOB>
        <EPL_JOB_ID></EPL_JOB_ID>
        <EPL_JOB_CODE></EPL_JOB_CODE>
        <EPL_JOB_TYPE></EPL_JOB_TYPE>
      </EPOD_JOB>
      ...
    </EPOD_JOBS>
    <EPL_START_ACTUAL_DATE></EPL_START_ACTUAL_DATE>
    <EPL_START_ACTUAL_TIME></EPL_START_ACTUAL_TIME>
    <EPL_END_ACTUAL_DATE></EPL_END_ACTUAL_DATE>
    <EPL_END_ACTUAL_TIME></EPL_END_ACTUAL_TIME>
  </JOB_SWAP_REQUEST>
{{Note}} The EPOD_USER_AUDIT record for this message should be written with the payload of the message (i.e. the content of the JOB_SWAP_REQUEST tag) written to the new field EPL_MESSAGE_CONTENT.

{{#var:System}} will validate that the message is from a valid User, Password, driver and Site as normal, then take the following actions:
* If there is no EPL_LOAD_ID_TOP value or tag, generate a new Load through the EPOD_LOAD DAL created above.
* For all the orders identified (i.e. delivery jobs of EPL_JOB_CODE without a collection job), add a collection (loading) job (with sequence 0). The value of EPL_LINKED_ID should be set to the maximum value + 1 of EPL_LINKED_ID on the existing load (i.e. EPL_LOAD_ID_TO).
* For these loading jobs:
** a customer record should be created, called "JOBSWAP"
** Create an EPOD_JOB_GROUP of "_JOBSWAP_" - configured for no signatures, see ''Data'' section for details. Update the Loading jobs with this Job Group.
** Create an EPOD_CUSTOMER record of "_JOBSWAP_" if it does not exist - Name "JOB SWAP", with no address information. Update the Loading jobs with this customer code.
** Set EPL_START_ACTUAL_DATE/TIME to the XML value EPL_START_ACTUAL_DATE/TIME. Set EPL_ARRIVAL_DATE/TIME to the XML value EPL_END_ACTUAL_DATE/TIME. Set EPL_STATUS for each job to "I" (In Progress).
* Change the Load ID for all the jobs identified (by EPL_SITE and EPL_JOB_ID) to the new Load ID.
* Set the EPL_SEQUENCE of all jobs to be 999, plus the numeric value already in the sequence. So, if there is no value, these should be set to 999.
* Set the EPL_LINKED_ID of all jobs to be the maximum value of EPL_LINKED_ID of the existing load, + 1, + EPL_LINKED_ID of the job.

The successful response to this shall be a standard message response, in the format:
  <JOB_SWAP_RESPONSE ID="0">
    <RESULT>ACK</RESULT>
  <JOB_SWAP_RESPONSE>

If there are any errors, the message should be returned in the standard error response format, as follows:
 <MESSAGE_RESPONSE ID="0">
   <RESULT>NAK</RESULT>
   <ERROR>error text</ERROR>
 </MESSAGE_RESPONSE>


The existing Load Request message processor in Calidus_ePOD.asmx will be modified to check for the new tags EPL_LOAD_ID (with a value) and EPL_JOB_SWAP (with a value of "Y"), as follows:
 <LOAD_REQUEST ID="0" SITE="SITE" USER="USER" PASSWORD="PASSWORD" 
   DEVICE_ID="DEVICE_ID" GPS_STAMP="LATLON" 
   DEVICE_OS="OSNAME OSVERSION" DEVICE_TYPE="MODEL">
   <EPL_SITE_ID>SITE</EPL_SITE_ID>
   <EPL_USER_ID>USER</EPL_USER_ID>
   <EPL_LOAD_ID>LOAD</EPL_LOAD_ID>
   <EPL_JOB_SWAP>Y<EPL_JOB_SWAP>
   <REQUEST_TIME_DATE>DATETIME</REQUEST_TIME_DATE>
 </LOAD_REQUEST>


The processing will be as follows:
* If EPL_LOAD_ID present, search for a load matching this EPL_SITE_ID and EPL_LOAD_ID.
* If EPL_LOAD_ID is not present or the previous search fails, search for a load as the process does now

If the EPL_JOB_SWAP tag is not set to "Y" or is not present, the Load will be returned to the user in a LOAD_RESPONSE message as now.

If the EPL_JOB_SWAP tag is set to "Y", {{#var:System}} will return the Load, the jobs for this Load and containers only in a LOAD_RESPONSE message, with records from any table that are at Pending or In Progress status ''only''. This returned message will have vastly reduced details to a normal Load Response message, and will also include the new EPL_JOB_SWAP tag, as follows:
    <LOAD_RESPONSE ID="0">
      <RESULT></RESULT>
      <EPL_JOB_SWAP>Y<EPL_JOB_SWAP>
      <EPOD_LOAD>
        <EPL_SITE_ID></EPL_SITE_ID>
        <EPL_LOAD_ID></EPL_LOAD_ID>
        <EPL_LOAD_START_PLANNED_DATE></EPL_LOAD_START_PLANNED_DATE>
        <EPL_LOAD_START_PLANNED_TIME></EPL_LOAD_START_PLANNED_TIME>
        <EPL_LOAD_END_PLANNED_DATE></EPL_LOAD_END_PLANNED_DATE>
        <EPL_LOAD_END_PLANNED_TIME></EPL_LOAD_END_PLANNED_TIME>
        <EPL_VEHICLE_ID></EPL_VEHICLE_ID>
        <EPL_USER_ID></EPL_USER_ID>
        <EPOD_JOBS>
          <EPOD_JOB>
            <EPL_SITE_ID></EPL_SITE_ID>
            <EPL_JOB_ID></EPL_JOB_ID>
            <EPL_LOAD_ID></EPL_LOAD_ID>
            <EPL_JOB_TYPE></EPL_JOB_TYPE>
            <EPL_JOB_GROUP></EPL_JOB_GROUP>
            <EPL_CUSTOMER_CODE></EPL_CUSTOMER_CODE>
            <EPL_SEQUENCE></EPL_SEQUENCE>
            <EPL_START_PLANNED_DATE></EPL_START_PLANNED_DATE>
            <EPL_START_PLANNED_TIME></EPL_START_PLANNED_TIME>
            <EPL_END_PLANNED_DATE></EPL_END_PLANNED_DATE>
            <EPL_END_PLANNED_TIME></EPL_END_PLANNED_TIME>
            <EPL_CUSTOMER_NAME></EPL_CUSTOMER_NAME>
            <EPL_JOB_ADDRESS></EPL_JOB_ADDRESS>
            <EPL_ADDRESS_1></EPL_ADDRESS_1>
            <EPL_ADDRESS_2></EPL_ADDRESS_2>
            <EPL_ADDRESS_3></EPL_ADDRESS_3>
            <EPL_ADDRESS_4></EPL_ADDRESS_4>
            <EPL_ADDRESS_5></EPL_ADDRESS_5>
            <EPL_POSTCODE></EPL_POSTCODE>
            <EPL_JOB_CODE></EPL_JOB_CODE>
            <EPL_CUST_REF></EPL_CUST_REF>
            <EPL_SO_NUMBER></EPL_SO_NUMBER>
            <EPL_ORDER_DATE></EPL_ORDER_DATE>
            <EPL_OWNER_NAME></EPL_OWNER_NAME>
            <EPL_EXT_REF></EPL_EXT_REF>
            <EPOD_CONTAINERS>
              <EPOD_CONTAINER>
                <EPL_SITE_ID></EPL_SITE_ID>
                <EPL_JOB_ID></EPL_JOB_ID>
                <EPL_CONTAINER_ID></EPL_CONTAINER_ID>
              </EPOD_CONTAINER>
            </EPOD_CONTAINERS>
          </EPOD_JOB>
        </EPOD_JOBS>
      </EPOD_LOAD>
    </LOAD_RESPONSE>
{{Note}} The existing XSD format documentation for this message must also be modified.

 
The Auto-Export process will be modified to allow exporting of Job Swap messages. This will be added as a new export type "JOBSWAP". 

The process will check for un-interfaced JOB_SWAP_REQUEST messages found on the EPOD_USER_AUDIT table (i.e. EPL_XFER_TTM_FLAG <> "Y") using the new EPOD_USER_AUDIT DAL method and new database procedure created above for this purpose. and send the messages to ''CALIDUS'' TMS, if the Site has been configured to send "JOBSWAP" messages. The process will send the message built by wrapping the content of EPL_MESSAGE_CONTENT of EPOD_USER_AUDIT in JOB_SWAP_REQUEST tags, as follows:
  <JOB_SWAP_REQUEST>
    <EPL_SITE_ID></EPL_SITE_ID>
    <EPL_LOAD_ID_FROM></EPL_LOAD_ID_FROM>
    <EPL_LOAD_ID_TO></EPL_LOAD_ID_TO>
    <EPL_VEHICLE_ID></EPL_VEHICLE_ID>
    <EPL_USER_ID></EPL_USER_ID>
    <EPL_GPS_COORDS></EPL_GPS_COORDS>
    <EPOD_JOBS>
      <EPOD_JOB>
        <EPL_JOB_ID></EPL_JOB_ID>
        <EPL_JOB_CODE></EPL_JOB_CODE>
        <EPL_JOB_TYPE></EPL_JOB_TYPE>
      </EPOD_JOB>
    </EPOD_JOBS>
    <EPL_START_ACTUAL_DATE></EPL_START_ACTUAL_DATE>
    <EPL_START_ACTUAL_TIME></EPL_START_ACTUAL_TIME>
    <EPL_END_ACTUAL_DATE></EPL_END_ACTUAL_DATE>
    <EPL_END_ACTUAL_TIME></EPL_END_ACTUAL_TIME>
  </JOB_SWAP_REQUEST>


== Admin Changes ==
The Site maintenance screen site_header.aspx will be modified to allow the system to be configured for:
*    "Job Transfer" - add field EPL_JOB_TRANSFER to the PDA tab as a check-box. 
{{Note}} Ensure as part of this change that the existing check-boxes line up. 


The existing Auto Export Configuration screen XF_Config.aspx will be modified to add a new Type "JOBSWAP", used when adding, editing or displaying configuration details on the screen. 


== PDA Changes ==
=== PDA DAL/Database Changes ===
The existing EPOD_SITE table will be modified to add the new field as follows:
* EPL_JOB_TRANSFER - This will be a one character field with of Values 'Y' and 'N'. The default value is 'N'. 
This new field should be added to every procedure as part of the PDA_SITE DAL object. 


=== Job List ===
In both of the below cases, this Swap mechanism will not be allowed unless the system has been configured to allow it, through the new flag EPL_JOB_TRANSFER on EPOD_SITE.

;With a Load
When in the Job List screen on the device, the driver may push the '''Menu''' button - a new option ''Job Swap'' will be added to this menu. This will call the Job Swap process being created below.

;Without a load
When requesting a Load, the device will inform the user that none was found. If the system is configured for Job Transfer, a new option will be added to this pop-up message, labelled 'Job Swap' to allow the user to start the Job Swap process.

When the Job Swap process has been started, the device will display a pop-up prompt for a Load ID. This is the Load ID of the Driver from whom jobs are to be transferred. The device will supply no prompts to enable the driver to select from a list or pattern-match - the exact Load ID must be entered for this to be successful. 

The pop-up prompt will include an '''OK''' and a '''Cancel''' button. If the '''Cancel''' or '''Back''' button is pressed, the device will return to the Job List.

If the '''OK''' button is pressed, the device will request the Load details from {{#var:System}}, through the existing LOAD_REQUEST message, which will be altered to indicate that this message is a Job Swap Load request, by adding a new tag to the message, and request the actual Load Id entered, in the following format:
 <LOAD_REQUEST ID="0" SITE="SITE" USER="USER" PASSWORD="PASSWORD" 
   DEVICE_ID="DEVICE_ID" GPS_STAMP="LATLON" 
   DEVICE_OS="OSNAME OSVERSION" DEVICE_TYPE="MODEL">
   <EPL_SITE_ID>SITE</EPL_SITE_ID>
   <EPL_USER_ID>USER</EPL_USER_ID>
   <EPL_LOAD_ID>LOAD</EPL_LOAD_ID>
   <EPL_JOB_SWAP>Y<EPL_JOB_SWAP>
   <REQUEST_TIME_DATE>DATETIME</REQUEST_TIME_DATE>
 </LOAD_REQUEST>
The existing function for handing these messages (WebServices.LoadRequest) will be modified to receive new parameters to indicate this.

{{#var:System}} will return the jobs for this Load. This returned message will have vastly reduced details to a normal Load Response message, but may be handled by the existing processor function WebServices.ProcessLoadResponse. 

Error handling will be as follows:
* No data connection - a pop-up (toast) message will be displayed as follows: "No Data Connection - jobs cannot be transferred at this time".
* Fundamental Error (malformed response) or Timeout (return value -1) - a pop-up (toast) message will be displayed as follows: "Time-out - jobs cannot be transferred at this time".
* Server Error (NAK - return value -2) -  a pop-up (toast) message will be displayed as follows: "Server Error - jobs cannot be transferred at this time".

In the instance of a good response (i.e. return value 0), the message will also be returned with the new EPL_JOB_SWAP tag present and set. In this case, all functions that are called from this will have a new parameter passed to them to indicate that this is a Job Swap Load Request. The functions affected are:
* InsertAllPDALoad
* InsertPDALoad
* InsertAllPDAJobs
The result will be that the value of EPL_SITE_ID on all these records shall be set to blank, which is an invalid value for EPL_SITE_ID. This will prevent them being accessed inadvertently for any purpose other than Job Swap.

If the load is not found, the device will display an error message "Transfer Load EPL_LOAD_ID not found". The device will return to the prompt for Load ID.

Once a valid load is returned, the device will display the Job Swap screen.


=== Job Swap ===
{{Note}} The Job Swap screen is not a separate screen in its own right, but instead a mode of the Job List screen. The layout and function is almost identical.

The differences are primarily in the building and operation of the table of jobs.

When called, the screen will switch modes into Job Swap mode. When in this mode, the device's '''Menu''' button must not be active. This will be re-enabled when the user returns to standard Job List functionality.

The Title shall be redisplayed with the Load ID of the load from which jobs are being transferred.

The Load information panel shall be refreshed from this load as well. Any Information icons shall be hidden at this time.

The new Scan entry fields shall be added to this view, as well as a '''Finished''' button.

<gallery widths=400px heights=400px perrow=3>
File:FS_312817_Job_Swap.PNG|Job Swap (Portrait)
File:FS_312817_Job_Swap_Land.PNG|Job Swap (Landscape)
</gallery><br />

The process that builds the Job List table will be modified to:
* Build the list as views rather than a table (for efficiency)
* When building for the Job Swap function only:
** Build the rows as normal, but ''without'' consolidating jobs together based on EPL_LINKED_ID - one row will be shown per order
** Orders that have a collect an deliver job should be listed once only, showing the Collection job information.

The 'Click' function will be modified in this mode to:
* Set or unset a 'Selected' flag against the order in the row
* Set or unset a background colour against the row, so show selected status.
* If selecting a row, all orders linked to it with the same value of EPL_LINKED_ID should also be marked as selected.
* If de-selecting a row, only this row need be deselected.

In this mode, any Long Press events on the table will be suppressed.

The Container (Package) entry field will have a default help text of "Scan/Enter Packages" for the LFS style.

The Package entry field will trigger an automatic click of the '''Select''' button, to ensure that those devices with a scanner (such as the Intermec CN51, expected to be in use for this operation) will immediately enter the item once scanned. This requires the scanned to be configured correctly (i.e. to have a Return tagged on the end of the barcode content). Note that this functionality will also work if the user presses the Enter button on the keyboard. 

The ''Select'' button will have a 'Click' event to check through a list of containers for all jobs, looking for a matching container. If one is not found, the entry will be cleared and a pop-up (toast) message will be displayed saying "Job not found for that Container". If at least one is found, the process should find the first job that matches, then highlight this order (EPL_JOB_CODE) on the list. All orders linked to it with the same value of EPL_LINKED_ID should also be marked as selected. If the order is already selected, only the row pertaining to this order shall be deselected. A pop-up (toast) message will be displayed ("Order EPL_DISP_JOB_ID selected/deselected for transfer") 


When the '''Finished''' button is pressed, the device shall obtain a list of all selected orders and pass this back to {{#var:System}} in a new Job Swap message, formed in a new function in webservices.js, as follows:
  <JOB_SWAP_REQUEST ID="0" SITE="EPL_SITE_ID" USER="EPL_USER_ID" PASSWORD="*****" DEVICE_ID="" 
   GPS_STAMP="53.3487735,-2.8517232" DEVICE_OS="android 4.1.2" DEVICE_TYPE="GT-I8190N">
    <EPL_SITE_ID></EPL_SITE_ID>
    <EPL_LOAD_ID_FROM></EPL_LOAD_ID_FROM>
    <EPL_LOAD_ID_TO></EPL_LOAD_ID_TO>
    <EPL_VEHICLE_ID></EPL_VEHICLE_ID>
    <EPL_USER_ID></EPL_USER_ID>
    <EPL_GPS_COORDS></EPL_GPS_COORDS>
    <EPOD_JOBS>
      <EPOD_JOB>
        <EPL_JOB_ID></EPL_JOB_ID>
        <EPL_JOB_CODE></EPL_JOB_CODE>
        <EPL_JOB_TYPE></EPL_JOB_TYPE>
      </EPOD_JOB>
      ...
    </EPOD_JOBS>
    <EPL_START_ACTUAL_DATE></EPL_START_ACTUAL_DATE>
    <EPL_START_ACTUAL_TIME></EPL_START_ACTUAL_TIME>
    <EPL_END_ACTUAL_DATE></EPL_END_ACTUAL_DATE>
    <EPL_END_ACTUAL_TIME></EPL_END_ACTUAL_TIME>
  </JOB_SWAP_REQUEST>
{{Note}} The Dates and Times shall be set from the time the Job Swap process is started (i.e. selecting the ''Job Swap'' option), to the point when the jobs are identified and the '''Finished''' button is pushed.

If the driver does not have a Load ID at this time, the EPL_LOAD_ID_TO tag shall be sent empty.

Once sent, the device will wait for a response to this from the webservice. The response will simply be a generic ACK or NAK message, to confirm that the swap was successful - the standard processing function ProcessUpdateResponse can be used for this, added into the ProcessResponse and ProcessJSONResponse functions, for case "JOB_SWAP_RESPONSE". 
* If there is no data connection at this time, the device shall display a pop-up (toast) message to show this ("No data connection - please try again when one is established") and stay in Job Swap mode.
* If the message has an error when processing on the server (return value -2), display a message "Job Swap unsuccessful - please check with your administrators" and return to the normal Job List screen. The process will also delete any Job Swap loads that are present in the database.
* If the message times out or other wise causes the XHR object to fail (return value -1), display a message "Problems waiting for server - please check your job list" and return to the normal Job List screen. The process will also delete any Job Swap loads that are present in the database.
* If successful (return value 0), the device should exit the job swapping mode and request either an update to it's current Load  from the server through an Auto-update Request, or, if the device does not have a current load, request a new load through the current Load Request. The process will also delete any Job Swap loads that are present in the database.


<!--
 MEDIA LANDSCAPE YES
= Appendix A: TEST PLAN  =

{{TestPlan_Header
|Title={{#var:Doc_Title}}
|Log={{#var:Reference}}
|Description=Test the ...
|MenuAccess=None
|Prerequisites=None
|Objective=To test that: ...
}} 
{{ #vardefine: Cycle | 0 }}{{ #vardefine: SubCycle | 0 }}
{{TestPlan_CycleHeader
|Cycle={{ #vardefineecho: Cycle | {{ #expr: {{ #var: Cycle }} + 1 }} }}{{ #vardefine: SubCycle | {{ #var: Cycle }} }}
|Title=Test Title
|Notes=
}} {{TestPlan_Test
|Test={{ #vardefineecho: SubCycle | {{ #expr: {{ #var: SubCycle }} + 0.01 }} }}
|Action=Do something
|Result=Some expected results
|Remarks=
|PassFail=
}} {{TestPlan_CycleFooter}} 

MEDIA LANDSCAPE NO
--> 
<!-- NEW PAGE --> 
= Appendix A: Process Flows =
== Transferring to an Existing Load==
[[File:FS_312817_Job_Swap_WT.PNG|border|600px]]
<!-- NEW PAGE --> 
== Transferring without an Existing Load ==
[[File:FS_312817_Job_Swap_WOT.PNG|border|600px]]
<!-- NEW PAGE --> 
== PDA Device Process ==
[[File:FS_312817_Job_Swap_PDA.PNG|border|600px]]
<!-- NEW PAGE --> 
{{Doc_Appendix
|Appendix=B
|Estimate=Y
|Glossary=EPOD
|Ref1=
|RefV1=
|RefDate1=
|REQ=0
|EST=0
|FS=6.0
|TS=0
|DEV=12.0
|ST=1.5
|IMP=0.25
|EREQ=0
|EEST=0
|EFS=0
|ETS=0
|EDEV=0
|ESTT=0
|EIMP=0
|Client={{#var:Client}}
|Year={{#var:Year}}
|FSEST=Y
|FOC=Y
|Rev1=Matt Tipping
|Rev1Title=Project Manager
|Rev2Title=Client Representative
}}</div> 
[[Category:{{#var:Client}} FS]]