FS 311856 Multiple Serviceable Items
Lanemark
Multiple Serviceable Items
CALIDUS eSERV
19th September 2013 - 0.2
Reference: FS 311856 309371-2
Contents
Functional Overview
Client Requirement
- Multiple engineers assigned to one service job.
- One job with multiple service items.
Solution Overview
NAV can have multiple serviceable items on a single Job, allocated to multiple engineers.
Where multiple engineers are required on a job, for example:
- 3 engineers on site
- 20 gas burners to service
Each engineer will complete the service of several of the burners (the serviceable items) against the service.
In practice, the lead engineer will assign the burners to each engineer on the job, rather than pre-assign.
This will be completed through a link to NAV direct from a mobile unit (i.e. a PC).
On the PDA Info tab, if there are multiple serviceable items on the job, the screen also would have navigation buttons left and right of the title (sections 1 and 2), to allow the user to switch between serviceable items.
A label showing the record being processed (e.g. "1 of 6") would be shown, allowing the user to see how many there are.
The Service Item number (LS Number) of the serviceable item will be displayed on the top of the Info tab, whereas the Service ID (SJ Number) will be displayed on the Job Details tab.
Switching between the serviceable items will change the displayed data on each of the tabs to the next service record - the same affect can be made by swiping left or right on the title label.
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. Note that this change drives change into the Server processes that deal with PDA updates that would mean that the existing Windows Mobile and previous versions of the Android client may be incompatible with this version of the server.
Note: The modifications seen here require NAV functionality to split a service job among several engineers, specifically assigning items to each engineer to complete. Any failure to deliver the required functionality will cause the processes described here to fail.- Note: The changes in SCR 312116 specify some details that will be useful in the completion of this code. This is referenced in Appendix B.
Set-up
Pre-requisites
Menu Structure
Data
Functional Description
Database/DAL
The database table EPOD_SERVICE must have the indexes changed to reflect the new model, as follows:
- The primary key (PK_EPOD_SERVICE_1) should be modified as follows:
- EPL_SITE_ID, ascending
- EPL_JOB_ID, ascending
- EPL_SERVICE_ID, ascending
- The secondary unique index (IX_EPOD_SERVICE) should stay - Service IDs should remain unique under Site.
Note: All database packages must be checked to ensure they reflect this change to the data model.
The DAL object EPOD_JOB will be modified to have an EPOD_SERVICES collection added beneath it, consisting of all the EPOD_SERVICE records found against the EPOD_JOB. This will be completed when creating an EPOD_JOB DAL object for an EPOD_JOB record that already exists. If the EPOD_JOB DAL object created does not exist, an empty collection should be created.
Note: The XML Export of jobs and Services already allows EPOD_SERVICE to iterate within a tag of EPOD_SERVICES, as follows:
<EPOD_JOB>
...
<EPOD_SERVICES>
<EPOD_SERVICE>
...
</EPOD_SERVICE>
<EPOD_SERVICE>
...
</EPOD_SERVICE>
</EPOD_SERVICES>
</EPOD_JOB>
This supports multiple EPOD_SERVICE records, but the EPOD_SERVICES tag must be changed to reflect multiple records, with a maxOccurs property of "unbounded" replacing "1". All XSDs must be modified to reflect this, including but not limited to:
- EPOD_EXPORT_JOB_RESPONSE.xsd
- EPOD_EXPORT_JOB.xsd
- EPOD_EXPORT_LOAD_RESPONSE.xsd
- EPOD_EXPORT_LOAD.xsd
The XML Import process (through the web services ePOD_DataService.asmx and ePOD_DataService2.asmx) must be modified to allow the same functionality when receiving Service Jobs, i.e.:
- Allow an EPOD_SERVICES tag, containing the existing EPOD_SERVICE tag, allowing unbounded occurrences.
Therefore the following changes must be made:
- XMLUpload.xsd must be modified to allow an EPOD_SERVICES tag, containing the existing EPOD_SERVICE tag, allowing unbounded occurrences.
- EPOD_DATASERVICE.ProcessJobs must change to check for this EPOD_SERVICES tag - if it exists, each EPOD_SERVICE tag found inside should be passed to the ProcessService function - see the existing xePRODUCTS code above the EPOD_SERVICE code for an example of how this is achieved.
- Any EPOD_SERVICE objects that have not been found on the XML update should be removed from the EPOD_JOB (i.e. deleted) unless they have already been cancelled.
- Any EPOD_SERVICE tag that does not exist should be created.
- The XMLUpload XSD should also be changed to include an optional EPL_USER_ID tag within the EPOD_JOB section. When an import is received if no load information is provided and the new EPL_USER_ID tag has been populated a check should be made against the Site to ascertain the value of the EPL_AUTO_GEN_LOAD flag, if this value is set a check should be performed to see if there is currently a load assigned to the user at Pending or In progress status, if found the jobs should be allocated to this load. If no load details are found a load should be created using the user id and the current date as the Load id and the jobs assigned to this load.
Server
Changes will be made to the JOB_UPDATE message returned from the PDA, as follows:
- Remove EPL_SITE_ID and EPL_SERVICE_ID from the ACTIVITY tag.
- Add EPL_SERVICE_ID and EPL_SERVICE_TYPE to the top of the SERVICE tag.
Note: For the format of the XML update message, see the Android Client section of this document
In order to match these changes, the function MessageProcess.ProcessJobUpdate must change as follows:
- For each SERVICE tag found in SERVICES, create an EPOD_SERVICE object. Update this object with the details passed in the SERVICE tag from the PDA. This is similar processing to how the EPOD_SERVICE_PRODUCT and EPOD_SERVICE_ACTIVITY updates work in the same process.
Note: The change to EPOD_SERVICE_ACTIVITY (where two elements have been removed) need not be reflected, as these elements are never used.
Admin
The Job and Service Screens will require modification when creating a new job. Those screens affected are:
- ConfigurableJob.aspx
- job_details.aspx
When creating or editing a new Service job, a pop-up screen is displayed. The Service section (lower left) will be modified as follows:
- When editing, all Service records will be loaded upon showing the pop-up form. When adding, only one will be assumed.
- A navigation group will be added to this section, disabled initially, enabled if there are multiple service records for the job.
- An Add button will be added to this section - each time this is pressed, a new service record will be allowed to be created in this section, by adding a navigable item to the navigation group and moving to this item.
- A Delete button will be added to this section - when pressed, this will mark the associated service record as requiring deletion when the page is saved. It will still show on the screen (but will have all fields disabled) until the page is saved.
- When a new item is created, the Service ID should be defaulted to EPL_JOB_CODE + "_" + count.
- Moving between service items on the navigation group should show the details of the salient service record.
- Saving will save all changed service records. Note that Service ID can be modified, and therefore care should be taken in updating each record. This should utilise the Service details on the page in the same sequence as the EPOD_SERVICE records in the EPOD_SERVICES collection in the DAL object. Therefore, even if the Service ID changes, this should update the correct EPOD_SERVICE record with these details.
Note: Time should be taken at this point to re-organise the layout of this pop-up - for example, Dates and Times associated to each other should be concatenated onto the same line:
- Planned Date/Time
- Actual Date/Time
- Order Date/Time
- Expiry Date/Time
- Arrival Date/Time
Additionally, the Service section should be labelled as such and only appear if the job is a Service type.
Note: The Service screen (service_job.aspx) utilises EPOD_SERVICE_JOB, a different DAL mechanism that allows only 1 service record per job. Although it should be possible to maintain and create Service jobs (with all the required fields) on this screen, it is not necessary to change this to allow creation of multiple service items on a single job. The screen itself should allow the searching for and displaying of each item, however.
The Service Details screen (service_detail.aspx) will be modified as follows:
- When retrieving the EPOD_JOB, modifications will need to be made throughout the code to accommodate the fact that the EPOD_SERVICE objects exist only within an EPOD_SERVICES collection and not directly from EPOD_JOB, even if there is only one EPOD_SERVICE record.
- The "Service Details" section should be renamed "Job Details", and the items Service ID and Service Type removed from this section.
- All further sections (Information, Pre-Work, Post-Work, Diagnosis, MC Refs and Products) should be included within another Section, labelled with the items Service ID and Service Type, in a larger, bolder font.
- The Service Details section should be created for each EPOD_SERVICE under the EPOD_SERVICES collection under EPOD_JOB, printed one under each other - the browser scroll-bar can be used to see all the details.
New Job Details screen
Note: This sample also shows fields defined under SCR 312116 (status and reason code, and the Image button). This is referenced in Appendix B.
Note: In the current screen, the Diagnosis and Products sections seem to be less wide than the Information section - this should be corrected on all affected sections.
Android Client
The PDA_SERVICE DAL object will change to:
- Add parameter Service ID on creation of a PDA_SERVICE object.
- If one is provided, this should create a PDA_SERVICE object, retrieve the EPOD_SERVICE record and return the object.
- If one is not provided, this should fetch all EPOD_SERVICE records for the job, create a PDASERVICES array and, for each record found, create a new PDA_SERVICE object (as PDASERVICE) and pass the Site, Job and Service ID parameters to the new object. Once all are created, return the PDASERVICES collection.
- The existing function ProcessServiceUpdate (called when Job Lock Response is processed, on pressing the Start/Arrive/Continue button in Job Details) must change to iterate through a collection of Service records, and update each one separately, by creating a PDA_SERVICE object passing Site, Job ID and Service ID.
All functions that create PDA_SERVICE objects must now be checked that they pass a Service ID correctly, or they are expecting a PDASERVICES collection returned.
The PDA_JOB DAL object will change to:
- hold a collection of PDA_SERVICE record (named PDASERVICES), rather than a single PDA_SERVICE object (PDASERVICE), as it does now.
- On creation of a new Job, create a collection PDASERVICES from a new PDA_SERVICE object - this will return a collection from the instantiation.
Note: No further changes should be necessary on the importing of services - the existing InsertAllPDAServices (called by Job creation functions ) already iterates through a number of EPOD_SERVICE records within the passed XML tag EPOD_SERVICES and adds each record. As these functions delete all service records first before adding new records, no updating functionality should be required.
The method PDA_JOB.ToUpdateXElement will be modified to create a SERVICES tag rather than a SERVICE tag, if there is more than one Service record in the PDASERVICES collection. Each element in the Services collection will then be iterated through, calling PDASERVICE.ToUpdateXElement().
The method PDA_SERVICE.ToUpdateXElement will be modified to add EPL_SERVICE_ID and EPL_SERVICE_TYPE tags before any others.
The method PDA_SERVICE_ACTIVITY.ToUpdateXElement will be modified to remove EPL_SITE_ID and EPL_SERVICE_ID.
The resulting XML extraction for a job should then look as follows:
<EPOD_JOB>
...
<SERVICES>
<SERVICE>
<EPL_SERVICE_ID></EPL_SERVICE_ID>
<EPL_SERVICE_TYPE></EPL_SERVICE_TYPE>
<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>
</SERVICES>
</EPOD_JOB>
Note: This includes the changes made under references 311577, 311636, 311753 and 311801.
If there are multiple serviceable items on the service job, the layout of the Job Details tab will be changed slightly, as follows:
- The main label showing "Service:" will be modified to show the Job Code of the Job here (EPOD_JOB.EPL_JOB_CODE) rather than the Service ID of the Service record (EPOD_SERVICE.EPL_SERVICE_ID).
If there are multiple serviceable items on the service job, the layout of the Info tab will be changed slightly, as follows:
- 2 buttons will be added to the left and right of the main label, labelled as "<" and ">". These will be Previous and Next buttons.
- A new label will be added to the title, under the "Service:" label, in a very small font, showing "Item X of Y", where X is current Service record in the Services collection (vars.lngServiceRecord - see below) and Y is the total number of records in the Services collection (PDAJOB.PDASERVICES.length).
Info tab, showing the position of the new previous/next buttons (1 and 2)
If the user clicks on the Next button, the next service item will be displayed on each of the Service tabs. If there is no next Service record, the first will be displayed instead. The Previous button will work in the same way, showing the previous Service record, or the last. A "swipe" event will also be added to the "Service:" label, to perform the same function.
In order to do this, a function must be written to update each of the tabs with the information from a particular service record. So:
- The screen will be changed to hold a current Service record number (vars.lngServiceRecord) that will be set on creating the screen.
- Any labels that need to be updated with data from the Service record on any of the tabs should be assigned variable items in the vars object, rather that just being added directly to any parent view - this is so that the text value can be updated.
- Any changes to the previous Service will be saved.
- The current Service record (lngServiceRecord) will be changed to the appropriate next Service record, depending on which button was pressed, and where in the Services collection the screen currently is.
- The new function will update:
- Each label, button, picker, text and check variable item in the screen with the appropriate value from the current Service record (for example, PDAJOB.PDASERVICES[vars.lngServiceRecord].PDASERVICE.EPL_SERVICE_ID).
- This new function will be called at start-up (through an "open" event added to the TabGroup object) - all assignations of value and text properties derived from Service data will be removed from each variable declaration, to ensure that only one part of the code sets these values, to make code support easier.
The validateJob function will be modified to check that all PDA_SERVICE items have had all details entered against them. This should be completed by checking the validation of all the service items when pressing the Done button. The validation messages displayed should identify the Service Item with the issues. Note: New field EPL_STATUS of EPOD_SERVICE (specified in SCR 312116, referenced in Appendix B) may be used to check and store the status if required. In this way, validating a service need be done only once. Also, only non-cancelled Service records need be checked.
If this is not the case, a validation message should be displayed - clearing this message will return the user to the Services process.
Appendix A: TEST PLAN
| Test Script / Scenario Reference | Multiple Serviceable Items | Call Number(s): 311856 309371-2 |
| Test Script / Scenario Description | To test that multiple Serviceable Items are supported by CALIDUS eSERV | PASS / ISSUES / FAIL |
| Menu Access | Services | |
| Pre-requisites | As much as possible (as far as has been developed on other Lanemark changes to the point of testing this one), the Services created and configuration allowed should match closely to the Lanemark requirements. | Tested By: |
| Test Objective | To test (for single and multiple serviceable items) that: Import adds and amends Service data correctly; Admin screens add, find and amend Service data correctly; the PDA allows navigation and updating of serviceable items and; the system exports Service data correctly. | Date: |
| Step | Action | Result | Remarks | P/F |
| 1 | Import | |||
| 1.01 | Import a Service job in the new format, with one service record. | The Job should be saved, with the service record associated to the Job ID. | ||
| 1.02 | Import a Service job in the new format, with more than one (ideally three) service records. | The job should be saved, with all service records associated to the Job ID. | ||
| 1.03 | Import the single-service job again, but with an additional service item. | The job should be saved, with all service records associated to the Job ID. | ||
| 1.04 | Import the multiple-service job again, but with one of the original service items removed. | The job should be saved, with all service records associated to the Job ID. The removed Service item should be deleted. |
| Step | Action | Result | Remarks | P/F |
| 2 | Admin | |||
| 2.01 | In the Job screen, create a Service job with a single service. | The Job should be saved, with the service record associated to the Job ID. | ||
| 2.02 | In the Job screen, create a Service job with more than one (ideally three) service records. | The job should be saved, with all service records associated to the Job ID. | ||
| 2.03 | Find these service records again. | All should appear once only on the grid. | ||
| 2.04 | Edit a single-service job and add another service | The job should be saved, with all service records associated to the Job ID. | ||
| 2.05 | Edit a multiple-service job, and delete a service | The job should be saved, with all service records associated to the Job ID, except the deleted one. | ||
| 2.06 | Repeat the above tests on the Configurable Job screen | As expected | ||
| 2.07 | In the Services screen, find all services. | All services created should be found, with a single line for all serviceable items, not one per job. | ||
| 2.08 | Search for a specific Serviceable Item | The service should be found, with a single line for all serviceable items, not one per job. | ||
| 2.09 | Search for a serviceable item (Service ID) that matches multiple serviceable items across multiple jobs. | All services created should be found, with a single line for all serviceable items, not one per job. | ||
| 2.10 | Enter a partial Serial Number that matches multiple serviceable items across multiple jobs. | All services created should be found, with a single line for all serviceable items, not one per job. |
| Step | Action | Result | Remarks | P/F |
| 3 | PDA | |||
| 3.01 | Start a single-service job on the device and complete. | This should operate as before, to the limit of already-coded changes for Lanemark at the point of testing. | ||
| 3.02 | Start a multiple-service job on the device (at least 3 serviceable items). | The Job Details screen will show the Job Code as the Service ID. | ||
| 3.03 | Change to the Info screen. | The details of the first serviceable item are displayed; Previous and Next buttons are present; a sub-title of "1 of 3" is displayed. | ||
| 3.04 | Complete details of the first serviceable item. Press Done. | A validation error should be displayed, showing that not all details have been entered against all Serviceable Items. | ||
| 3.05 | Move to the Info tab and press Next. | The details of the second serviceable item are displayed; Previous and Next buttons are present; a sub-title of "2 of 3" is displayed. No other details have been entered against this item. | ||
| 3.06 | Complete the details of all remaining items (markedly different on all items), finishing on the third. | The details of the third serviceable item are displayed; Previous and Next buttons are present; a sub-title of "3 of 3" is displayed. All details entered against the third item are displayed. | ||
| 3.07 | Press Next. | The details of the first serviceable item are displayed; Previous and Next buttons are present; a sub-title of "1 of 3" is displayed. All details entered against the first item are displayed. | ||
| 3.08 | Press Done | The service should complete (move to signature). | ||
| 3.09 | Complete the service job | The results of all services should be returned to the system. |
| Step | Action | Result | Remarks | P/F |
| 4 | Post-PDA (Admin/Server) | |||
| Ensure that single- and multiple-item jobs have been completed. | ||||
| 4.01 | Check all items on all jobs updated. | All records are updated correctly | ||
| 4.02 | Check the Service Details screen for a Single-item Service Job | The screen has changed layout correctly - only one service item's details are displayed | ||
| 4.03 | Check the Service Details screen for a multiple-item Service Job | The screen has changed layout correctly - all service item's details are displayed on a scrolling screen. |
| Step | Action | Result | Remarks | P/F |
| 5 | Export | |||
| 5.01 | Export a single-item Service Job | The job is exported correctly and the resulting export XML matches the XSD. | ||
| 5.02 | Export a multiple-item Service Job | The job is exported correctly and the resulting export XML matches the XSD. |
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 | 1.25 | 0 | £0.00 |
| Technical Specification | 0.00 | 0 | £0.00 |
| Development | 10.50 | 0 | £0.00 |
| Testing and Release | 2.00 | 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 No | Document Title & ID | Version | Date |
| 1 | UG 291094 EPOD Admin User Guide | 2.0 | 4/4/2012 |
| 2 | UG 291097 EPOD Client User Guide | 3.0 | 23/4/2013 |
| 3 | REQ_309371_Lanemark_eSERV_Requirements | 0.4 | 29/08/2013 |
| 4 | FS_312116_Service_Cancellation_Changes | 0.1 | 19/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 | _____________________________ |
