FS 312116 Service Cancellation Changes

From Calidus HUB





Aptean Logo.png







Lanemark

Service Cancellation Changes

CALIDUS eSERV

19th September 2013 - 0.1
Reference: FS 312116 309371-13/14











































Functional Overview

Client Requirement

Allow cancellation of an entire Service Job, requiring Customer and Engineer signature. Allow cancellation of a single serviceable item - no signature need be captured for this.

Solution Overview

A Cancel Service button will be added to the bottom of the Job Details tab of the Services screen. If for any reason the user wishes to cancel the service, they can click this button.

This will prompt the user to enter the reason why the service of all serviceable items is being cancelled (through a Picker) - these reasons are fully configurable, and is expected to contain a reason (Risk Assessment Failure).

If the entire job is cancelled in this way, the user will then be prompted to obtain a signature of the customer and for themselves.

If there are multiple serviceable items on this service job, a Cancel Item button will be added to the bottom of the Info screen. If for any reason the user wishes to cancel the service of the particular item shown, they can click this button. This will prompt the user to enter the reason why the item is being cancelled (through a Picker) - these reasons are fully configurable, and is expected to contain a reason (Risk Assessment Failure).

If a single serviceable item is cancelled in this way, the item will be removed from the serviceable items on the Job and the user will be returned to the Job Details display.

Scope

  • These changes will be made in the latest version of the CALIDUS eSERV product only.
  • The changes will be made to the Android eSERV client only.
  • Warning Warning: This change requires that the Multiple Serviceable Items change is complete first - see Appendix B for references.


Set-up

Pre-requisites

Menu Structure

Data

Functional Description

Database/DAL

The EPOD_SERVICE table will be modified to add the following new fields:

  • EPL_REASON_CODE, nvarchar(20)
  • EPL_STATUS, nvarchar(1)
  • EPL_PHOTO_ID, nvarchar(10), nullable

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

  • EPOD_SERVICE_INSERT
  • EPOD_SERVICE_JOB_SEARCH
  • EPOD_SERVICE_JOB_SELECT
  • EPOD_SERVICE_SELECT
  • EPOD_SERVICE_UPDATE

The existing EPOD_SERVICE/SERVICE_JOB DAL object will be changed to:

  • Export the new fields in XML requests
  • Read the new fields

Note Note: It is not necessary to add these fields as searchable items. 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.


Server

Changes will be made when processing a JOB_UPDATE message returned from the PDA, as follows:

  • Store EPL_STATUS and EPL_REASON_CODE, if present in the message.

Changes will be made when processing a PHOTO_REQUEST message returned from the PDA, as follows:

  • If the element EPL_PHOTO_TYPE is "S" (Service):
    • Get the EPOD_SERVICE item through the DAL object, using the passed in tag values of EPL_SITE_ID, EPL_JOB_ID, EPL_SERVICE_ID
    • Process the rest of the photo as normal, but tag the EPL_PHOTO_ID of the record above with the generated EPL_PHOTO_ID.

Admin

Note Note: Serviceable Items that have been cancelled on a completed job are still to be reported on in the Service Reports produced for the Service Job, showing only the Risk Assessment sheet, with the Job Signatures. This is specified elsewhere.

The Service screen (service_job.aspx) will be modified to display the status of individual Service Items on Grid, not Job. This will be achieved by displaying the translated EPL_STATUS from EPOD_SERVICE, not EPOD_JOB.

Note Note: The Job screen will show the status of the Service as a whole, by showing the status of the Job record.

The Service Details screen (service_detail.aspx) will be modified to:

  • Display the status of Service Item under the main Service title. The status should be translated as follows:
    • "C" - Complete
    • "X" - Cancelled
    • " " or "P" - Pending
  • Display the Reason Code from the service record and the description from the Reason Codes table if the serviceable item's status is cancelled. This should be displayed under the main Service title, to the right of the status.
  • Add a Image button, if an image is present on the Service record, floating on the right of the title. When clicked, the screen should display a pop-up window, showing the image associated to the associated service record, with a Close button, to close the window when viewed.

FS 311856 1.PNG
New Job Details screen

Note Note: This sample shows the modification defined under SCR 311856, referenced in Appendix B.

Android Client

The EPOD_SERVICE table should be modified to add the following fields:

  • EPL_REASON_CODE, nvarchar(20)
  • EPL_STATUS, nvarchar(1)
  • EPL_PHOTO_ID, nvarchar(10)

Note Note: As the database structure is changing with this version, the default values must be carefully set and the database creation script modified to ensure that the standing data is re-downloaded from the server after the changes have been made. This is achieved by setting the "last version changed" variable (lngLastVersionDB) in DBConnection to the latest version number.

The method PDA_SERVICE.ToUpdateXElement will be modified to add EPL_STATUS and EPL_REASON_CODE tags after EPL_SERVICE_TYPE.

The resulting XML extraction for a job should then look as follows (for each EPOD_SERVICE record found): 

   <SERVICE>
     <EPL_SERVICE_ID></EPL_SERVICE_ID>
     <EPL_SERVICE_TYPE></EPL_SERVICE_TYPE>
     <EPL_REASON_CODE></EPL_REASON_CODE>
     <EPL_STATUS></EPL_STATUS>
     <EPL_REASON_CODE></EPL_REASON_CODE>
     <PREWORK>
       <EPL_PREWORK_INTERIOR></EPL_PREWORK_INTERIOR>
       <EPL_PREWORK_EXTERIOR></EPL_PREWORK_EXTERIOR>
       <EPL_PREWORK_ELECTRIC></EPL_PREWORK_ELECTRIC>
       <EPL_UDF_PREWORK></EPL_UDF_PREWORK>
     </PREWORK>
     <POSTWORK>
       <EPL_POSTWORK_INTERIOR></EPL_POSTWORK_INTERIOR>
       <EPL_POSTWORK_EXTERIOR></EPL_POSTWORK_EXTERIOR>
       <EPL_POSTWORK_ELECTRIC></EPL_POSTWORK_ELECTRIC>
       <EPL_UDF_POSTWORK></EPL_UDF_POSTWORK>
     </POSTWORK>
     <INFO>
       <EPL_UNIT_TYPE></EPL_UNIT_TYPE>
       <EPL_CODE_2></EPL_CODE_2>
       <EPL_CODE_1></EPL_CODE_1>
       <EPL_MILEAGE></EPL_MILEAGE>
       <EPL_CODE_3></EPL_CODE_3>
       <EPL_SPEC_REQUIRED></EPL_SPEC_REQUIRED>
       <EPL_SERVICE_GROUP></EPL_SERVICE_GROUP>
       <EPL_SYSTEM_TYPE></EPL_SYSTEM_TYPE>
       <EPL_UDF_INFO></EPL_UDF_INFO>
     </INFO>
     <MC_REF>
       <EPL_MC_REF_1></EPL_MC_REF_1>
       <EPL_MC_REF_2></EPL_MC_REF_2>
       <EPL_MC_REF_3><EPL_MC_REF_3>
       <EPL_MC_REF_4></EPL_MC_REF_4>
       <EPL_MC_REF_NARRATIVE></EPL_MC_REF_NARRATIVE>
     </MC_REF>
     <DIAGNOSIS>
       <EPL_DIAGNOSIS_NARRATIVE></EPL_DIAGNOSIS_NARRATIVE>
       <EPL_CUSTOMER_DAMAGE></EPL_CUSTOMER_DAMAGE>
       <EPL_VNOS></EPL_VNOS>
       <EPL_CHECKBOX_1></EPL_CHECKBOX_1>
       <EPL_CHECKBOX_2></EPL_CHECKBOX_2>
       <EPL_CHECKBOX_3></EPL_CHECKBOX_3>
       <EPL_UDF_DIAGNOSIS></EPL_UDF_DIAGNOSIS>
     </DIAGNOSIS>
     <PRODUCT>
       <EPL_PRODUCT_ID></EPL_PRODUCT_ID>
       <EPL_QUANTITY></EPL_QUANTITY>
       <EPL_DIRECTION></EPL_DIRECTION>
       <EPL_RETURN></EPL_RETURN>
       <EPL_DESCRIPTION></EPL_DESCRIPTION>
       <EPL_VEHICLE_ID></EPL_VEHICLE_ID>
     </PRODUCT>
     <ACTIVITY>
       <EPL_ACTIVITY_CODE></EPL_ACTIVITY_CODE>
       <EPL_QUANTITY></EPL_QUANTITY>
     </ACTIVITY>
   </SERVICE>

Note Note: This includes the changes made under references 311577, 311636, 311753, 311801 and 311856.

The PDA_SERVICE DAL object should be modified to add these parameters, and add these fields to all functions.

The PDA_SERVICE DAL method should also be modified to add a Cancel method, receiving a Reason Code parameter. This should:

  • Set EPL_STATUS to "X"
  • Set EPL_REASON_CODE to the Reason Code parameter passed in.
  • Update the record (through this.Update)

The PDA_JOB DAL Cancel method will be modified to loop through any PDA_SERVICE objects in the PDASERVICE collection and call the new Cancel method on these objects, regardless of their current status.


A Cancel Service button will be added to the bottom of the Job Details tab of the Services screen. If for any reason the user wishes to cancel the service (i.e. the whole job with all Serviceable Items), they can click this button.

This will start the Cancellation form (from Cancellation.js) through a new helper function CancelService. This will call Cancellation with a Job type of "SERVICE_JOB". The callback function passed to this helper function should simply check whether the service has been cancelled and if so, close the window and call the callback function passed to it from the Job Details screen.

The Cancellation function will be modified to recognise the new Job type and do the following:

  • Change the labels to appropriate text (similar to JOB cancellation) as follows:
    • Cancellation_jobIDHeaderLB = "Cancel Service"
    • Cancellation_jobCancelLB = "Are you sure you wish to cancel service " + EPL_JOB_CODE + " - all items will be cancelled."
  • On clicking the OK button, the process should require the user to enter the signatures if configured to do so. The code required to do this can be seen when completing a service normally in SM_Service.js, in the code for the click event of vars.completeBt. On completion of this code (through a callback) the Job should then be cancelled (through PDA_JOB.Cancel), and the callback routine of the Services screen called.

The result of these changes should be as described in the test plan, as seen in Appendix A.


If there are multiple serviceable items on this service job, a Cancel Item button will be added to the bottom of the Info tab on the Services screen, above the existing Pre-work Checks button. If for any reason the user wishes to cancel the service of the particular item shown, they can click this button.

This will start the Cancellation form (from Cancellation.js) through a new helper function CancelServiceItem. This will call Cancellation with a Job type of "SERVICE_ITEM". The data item passed to this function should be the current PDA_SERVICE DAL object. The callback function passed to this helper function should simply check whether the service item has been cancelled and if so, refresh the Job and refresh the Service window, moving to the first Serviceable Item in the PDA_SERVICES collection - use the function created for the Multiple Serviceable Items development for this.

Note Note: If the result of cancelling a Serviceable Item is that there is only one serviceable item left on the job, remove the "Cancel Item" button and any navigation buttons and information from the Services screen.

The Cancellation function will be modified to recognise the new Job type and do the following:

  • Change the labels to appropriate text (similar to JOB cancellation) as follows:
    • Cancellation_jobIDHeaderLB = "Cancel Service Item"
    • Cancellation_jobCancelLB = "Are you sure you wish to cancel service item " + EPL_SERVICE_ID.
  • On clicking the OK button, the Serviceable Item should then be cancelled (through the new EPOD_SERVICE DAL method Cancel) and the callback routine of the Services screen called. Note Note: Any image taken against the cancelled Service will be tagged against the service record by the already-existing code (when updating pDataObj.EPL_PHOTO_ID in the click event of vars.btnOK.

The result of these changes should be as described in the test plan, as seen in Appendix A.


Note Note: The Cancel Job button on the Job Details screen will not be modified, as this is intended for use when the user is unable to complete the job because of situation not caused by the customer or site (e.g. Road conditions, Breakdown, No Access, etc).


When confirming that a Service has been completed, the validateService function of SM_Service.js will change to ensure that only Serviceable Items with an EPL_SERVICE_ID not "X" are validated against.

Standard processing on a Serviceable item when completing a Job (in the existing function saveService in SM_Services.js) should be to set the EPL_STATUS of any PDA_SERVICE record that is not already Cancelled to "C", to show that it is complete.

Note Note: The above simplifies the processing specified within the Multiple Service Items change, and should be referenced there when that is being completed.


When processing a Job Update back to the EPOD Server (called in this case when a whole Service Job is Cancelled or Completed), the process must be modified to check for any images associated to Service records.

This means that the existing function ProcessPhotos in Webservices.js to loop through all EPOD_SERVICE records and check for any with a non-blank value of EPL_PHOTO_ID and, if found, call PhotoUploadRequest. The parameters passed to this function will be:

  • SITE = SITE
  • USER = USER
  • PASSWORD = PASSWORD
  • EPL_SITE_ID = PDAJOB.EPL_SITE_ID
  • EPL_JOB_ID = PDAJOB.EPL_JOB_ID
  • EPL_SERVICE_ID = PDASERVICES[x].PDA_SERVICE.EPL_SERVICE_ID
  • EPL_PHOTO_TYPE = "S"
  • All other parameters =

Note Note: The code for this can be copied almost directly from the containers and products processing in the same function. Also, ensure that all existing calls to this function set the EPL_SERVICE_ID parameter to a zero-length string.

The existing function PhotoUploadRequest must be modified as follows:

  • A new parameter EPL_SERVICE_ID added after EPL_JOB_ID
  • A new tag (EPL_SERVICE_ID) added after EPL_JOB_ID, populated using the passed-in parameter

The new Photo Request XML structure will look as follows: 

<PHOTO_REQUEST ID="0" SITE="SITE" USER="USER" PASSWORD="PASSWORD" 
    DEVICE_ID="DEVICE_ID" GPS_STAMP="latlon" 
    DEVICE_OS="osname version" DEVICE_TYPE="model">
  <EPL_SITE_ID></EPL_SITE_ID>
  <EPL_JOB_ID></EPL_JOB_ID>
  <EPL_SERVICE_ID></EPL_SERVICE_ID>
  <EPL_CONTAINER_ID></EPL_CONTAINER_ID>
  <EPL_PRODUCT_CODE></EPL_PRODUCT_CODE>
  <EPL_SEQUENCE></EPL_SEQUENCE>
  <EPL_PHOTO></EPL_PHOTO>
  <EPL_DESCRIPTION></EPL_DESCRIPTION>
  <EPL_PHOTO_TYPE>J|C|P|S</EPL_PHOTO_TYPE>
  <EPL_PACKET>/EPL_PACKET> - only if message sent in chunks
  <EPL_PACKET_TOTAL>10/EPL_PACKET_TOTAL> - only if message sent in chunks
  <REQUEST_TIME_DATE>YYYY-MM-DDTHH:MM:SS</REQUEST_TIME_DATE>
</PHOTO_REQUEST>


Appendix A: TEST PLAN

Test Script / Scenario ReferenceService Cancellation ChangesCall Number(s): 312116 309371-13/14
Test Script / Scenario DescriptionTo test cancellation functionality within the Services process.PASS / ISSUES / FAIL
Menu AccessServices 
Pre-requisitesEnsure there are single- and multiple-item jobs (with at least 3 items) to check.Tested By:
 
Test ObjectiveTo test that: single-item jobs can be cancelled, multiple item jobs can be cancelled; individual items can be cancelled from a multiple-item job and; cancelled service jobs and items (and associated status, reasons and images) can be viewed in Admin.Date:
 


Step Action Result Remarks P/F
1 PDA      
       
1.01 Click Cancel Job on a single-item service job from the Job Details tab of the Service screen. The Cancellation form should be shown.    
1.02 Click Back The Job Details tab should be shown again    
1.03 Click Cancel Job again. Enter a reason code. Click OK. The Signature forms should be shown.    
1.04 Complete the signatures required. The job should be cancelled. You should be returned to the Job List screen and informed of this. The job should be removed from the list.    
1.05 Click Cancel Job on a multiple-item service job from the Job Details tab of the Service screen. The Cancellation form should be shown.    
1.06 Click the Image button and take an image. Enter a description. Choose a reason, click OK, enter all signatures and confirm. The job should be cancelled. You should be returned to the Job List screen and informed of this. The job should be removed from the list.    
1.07 Start a multiple-item service job. Click the Info tab. A Cancel Item button should be present.    
1.08 Click the Cancel Item button. The Cancellation form should be shown.    
1.09 Click Back The Info tab should be shown again, on the same item.    
1.10 Click Cancel Item again. Choose a reason, click OK The item should be cancelled. You should be returned to the Info tab and informed of this. The item should be removed from the service and the count shown as "1 / 2".    
1.11 Click Next. Click Cancel Item again. Click the Image button and take an image. Enter a description. Choose a reason, click OK The item should be cancelled. You should be returned to the Info tab and informed of this. The item should be removed from the service. The Cancel Item button should be removed, as well as the navigation buttons and count.    
1.12 Complete the last Item (originally item 2) normally. The item is completed. You should be returned to the Job List screen and informed of this. The job should be removed from the list.    
1.13 Check all returned data (in the server-side log) The XML includes the status and reason code tags. Cancelled items have these populated correctly. These are blank for completed items. Any images have been sent back associated to the correct Service ID.    
1.14 Check the jobs in the database. All have been updated as expected.    


Step Action Result Remarks P/F
2 Admin      
       
2.01 Use the Services screen to find a service job with multiple serviceable items, that has had some items cancelled (plus one with an image) All items are shown on the grid, with the cancelled items showing with that status.    
2.02 Use the Services screen to find a cancelled service job with multiple serviceable items All items are shown on the grid, with all items showing as cancelled.    
2.03 Use the Job screen to find a service job with multiple serviceable items, that has had some items cancelled (plus one with an image) One line should show per job, with the status shown as Completed.    
2.04 Click Details The Service Details screen should be shown. The Job Details section should show the status as Complete. A Service section should appear for each service item. Cancelled Service items should display the status as Cancelled, with the reason code and description shown. Completed Service items should display the status as Completed, with no reason code displayed. Any cancelled items with an Image should show an Image button.    
2.05 Click Image The image taken for the cancellation is shown.    
2.06 Use the Job screen to find a cancelled service job with multiple serviceable items One line should show per job, with the status shown as Completed.    
2.07 Click Details As before, but the each service item's status should be shown as Cancelled.    


Appendix B: Quote & Document References

Cost Details
Activity No. of Days Rate per Day (£) Cost (£ Exc. VAT)
Requirements 0.00 0 £0.00
Change Request Evaluation 0.00 0 £0.00
Functional Specification 0.75 0 £0.00
Technical Specification 0.00 0 £0.00
Development 3.25 0 £0.00
Testing and Release 0.50 0 £0.00
Implementation 0.00 0 £0.00
Project Management First argument to "number_format" must be a number. 0 £First argument to "number_format" must be a number.
 
TOTAL First argument to "number_format" must be a number.   £First argument to "number_format" must be a number.
Estimate excludes training, release to live and go live support.

B.1 References

Ref NoDocument Title & IDVersionDate
1UG 291094 EPOD Admin User Guide2.04/4/2012
2UG 291097 EPOD Client User Guide3.023/4/2013
3REQ 309371 Lanemark eSERV Requirements0.429/08/2013
4FS 311856 Multiple Serviceable Items0.219/09/2013


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


Julie Taylor
OBS Project Manager		_____________________________

Jeff Foster
Client Representative		_____________________________

Alan Thompson
Client Representative		_____________________________
Retrieved from ‘https://calidusassist.adcservices.apteancloud.com/calidus-assist/OBS/index.php?title=FS_312116_Service_Cancellation_Changes&oldid=1233’