View source for FS 322073 EPOD WEBFLEET Interface - Orders

<div class="noprint">
{{#vardefine:Client|PROD}}
{{#vardefine:ClientName|OBS Logistics}}
{{#vardefine:System|''CALIDUS'' EPOD}}
{{#vardefine:Doc_Title|WEBFLEET Interface - Orders}}
{{#vardefine:Version|0.3}}
{{#vardefine:Date|6th May 2015}}
{{#vardefine:Reference|322073}}
{{#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  ==
{{#var:System}} needs to get the Mobile Application to trigger the TomTom Nav App with the address of the job the driver is travelling to.


== Solution Overview  ==
The TomTom Nav App on the device does not allow this kind of triggering with an ad-hoc address - it must work through triggering WEBFLEET orders.

The only way to trigger the start/arrive/complete of WEBFLEET orders is:
* Through the device's Pro.CONNECT interface (device-side)
* Through WEBFLEET.CONNECT webservices (server-side)
In order for either of these methods to work, there is a pre-requirement to create the orders in WEBFLEET.

In order for this to work, there is a pre-requirement for all addresses to have a Lat/Long.

The Pro.CONNECT interface is proving too difficult to implement at this time, so the design will fall back on:
* Triggering the display of the webfleet app through Android (which will just display the app, not trigger the start of the job.

Additionally, TomTom state that the requests that are currently being made through TomTom Webservices are not being counted towards OBS Logistics use, as the OBS API Key is not included in current requests. Any solution put in place at this time will ensure this key is utilised. 


This change covers:
* Create/Delete orders in WEBFLEET for the vehicle when required.
* Complete orders in WEBFLEET for the vehicle when required.

In summary:
* A load will be marked as In Progress and assigned to a vehicle when the user retrieves the load on the device, not when the first job is started.
* Whenever a Load is set to be in progress and assigned to a vehicle, all jobs on that load will be assigned to that vehicle in WEBFLEET.
* Any jobs on a load that was previously in progress will remove all jobs from that load from WEBFLEET and will set the load to Pending again.
* Whenever a load is marked as Complete or Cancelled, all jobs on that load will be removed from WEBFLEET
* Whenever a job is removed from an In Progress Load, the order will be deleted from WEBFLEET
* Whenever a job is deleted from an In Progress Load, the order will be deleted from WEBFLEET
* Whenever specific details against a pending job are amended, the order will be updated in WEBFLEET


This change is dependent on the basic WEBFLEET interface developments, referenced in [[#Appendix A: Quote & Document References|Appendix A]].


== Scope  ==
* This change affects the latest version of the {{#var:System}} application only.
* The existing CTMS-TomTom interfaces also need to be modified to use an API key, which will be provided by Matt Turner. This functionality is not part of the scope of this change.
* The functionality described in this document covers only a basic support of jobs consolidated from the server, and does not support manual consolidations on the mobile device at all. This must be dealt with in subsequent revisions of this interface.


<!-- NEW PAGE --> 

= Set-up  =

== Pre-requisites  ==
A working {{#var:System}} implementation.


== Menu Structure  ==
None


== Data  ==
New EPOD_XF_CONFIG configurations will be required:
* EPL_XF_CONFIG_ID - A new configuration name to be applied to sites that do not have an Export Configuration yet, or the Export Configuration ID of the existing configuration.
* EPL_XF_ID - "TO" - TomTom Orders
* EPL_SOAP_ACTION - ""
* EPL_SOAP_NS - "ser"
* EPL_SOAP_NS_PREFIX - <nowiki>"http://connect.webfleet.tomtomwork.com/services"</nowiki>
* EPL_WEB_USER - "admin"
* EPL_WEB_PASSWORD - "Matt3221"
* EPL_XF_RECIPIENT - Account - "logistics-obs"
* EPL_XF_DESTINATION - <nowiki>"https://soap.business.tomtom.com/v1.24/ordersService"</nowiki>
* EPL_XF_MSG_TYPE - API Key - "000fcb2a-6631-477a-b00e-de0505e7c7e3"
* EPL_XF_DIRECTION - "O"
* EPL_XF_TYPE - "SOAP"


[[File:FS_322073_Admin_AutoExport.PNG|border|600px]]
<br />''Import/Export Config Screen''<br />

This configuration should be added to site that requires TomTom interfaces, in the Site Maintenance screen. If a site already has a configuration attached to it, a configuration should be added to the same configuration name.


<!-- NEW PAGE --> 

= Functional Description  =

== Database/DAL  ==
The following triggers will be added to the existing table EPOD_LOAD:
* Trigger setting any other Loads for this vehicle or Driver at status "I" back to status "P". This should be triggered and committed before the following action.
* Trigger write to EPOD_XF_CONTROL for the Load, action "A" if TomTom Orders enabled for the Site when a load is marked as In Progress. 
* Trigger write to EPOD_XF_CONTROL for the Load, action "D" if TomTom Orders Delete enabled for the Site when a load is marked as Pending from status In Progress. 

The following index will be added to EPOD_LOAD to facilitate this:
* Repeating index IX_EPOD_LOAD_VEHICLE_STATUS - EPL_SITE_ID, EPL_VEHICLE_ID, EPL_STATUS

{{Note}} The triggers may be achieved through the database or DAL objects.


The existing table and DAL object EPOD_JOB will be modified to add the following field:
* EPL_EXTERNAL_SYSTEM_ID - nvarchar(20).
{{Note}} It is not necessary to export or import these fields through XML at this time.

The following triggers will be added to the existing table EPOD_JOB:
* Trigger write to EPOD_XF_CONTROL for the Job, action "A" if TomTom Orders enabled for the Site when a job is added to a load that is marked as In Progress. 
* Trigger write to EPOD_XF_CONTROL for the Job, action "D" if TomTom Orders enabled for the Site when a job (or all jobs linked to that job) is removed from a load that is marked as In Progress. 
* Trigger write to EPOD_XF_CONTROL for the Job, action "D" if TomTom Orders enabled for the Site when a job (or all jobs linked to that job) is deleted from a load that is marked as In Progress. 
* Trigger write to EPOD_XF_CONTROL for the Job, action "D" if TomTom Orders enabled for the Site when a job (or all jobs linked to that job) is marked as complete or cancelled from a load that is marked as In Progress. 

The following index will be added to EPOD_JOB to facilitate this:
* Repeating index IX_EPOD_JOB_LINKED - EPL_SITE_ID, EPL_LOAD_ID, EPL_LINKED_ID

{{Note}} The triggers may be achieved through the database or DAL objects.


== Webservices ==
When the device allocates a load to a vehicle, the device will sent through an EPOD_LOAD_REQUEST call to the webservices in the server. The message will now include the Vehicle for which the driver is making the request. The processing of this message will change to mark the load as In Progress status. This will update the Load, which will trigger an update of any other in progress loads for that vehicle to be set back to Pending. It will also trigger messages to be sent to TomTom for the removal of any previously in progress load's orders and adding the orders for the new load in progress. 


== AutoExport ==
The new TomTom message sending procedure should be modified to send order messages from EPOD_XF_CONTROL:
* Messages will be found sorted by External System and ID, only at status Pending.
* Messages will be marked as In Progress when they are started processing.
* The message content will be built up from the authorising parameters in the EPOD_XF_CONFIG table, and the data being sent.
** For Adding Jobs, the data will be built from the Job of the Job Id referenced in EPOD_XF_CONTROL, and any other linked jobs. The SOAP action is "sendDestinationOrder".
** For Deleting Jobs, the data will be built from the Job of the Job Id referenced in EPOD_XF_CONTROL, and any other linked jobs, if all jobs linked to this one have been removed from the load. The SOAP action is "deleteOrder".
** For Adding Loads, a message will be sent as for adding Jobs above, for each incomplete job on the load. 
** For deleting Loads, a message will be sent to remove all jobs from the vehicle. The SOAP action is "clearOrders".
** Notes on data in the messages:
*** objectno - the vehicle external reference of the vehicle assigned to this job's load
*** orderid - From the new TomTom ID field. If blank and this is not consolidated, set to this job's EPL_JOB_ID, else set to EPL_LOAD_ID + "_" + EPL_LINKED_ID. All other jobs with the same EPL_LINKED_ID as this job should be updated to set their EPL_EXTERNAL_SYSTEM_ID to the value of this job's EPL_EXTERNAL_SYSTEM_ID. Of the job is linked to others that have a TomTom ID, this jobs should have it's TomTom ID set to the other jobs' ID.
* The message will be sent based on its Config type - this is expected to be SOAP for WEBFLEET.
* The response will be checked, specific to WEBFLEET webservices:
** Failure - update the status of the message to "F".
** Success - Update the status of the message to "S".
** Limits Exceeded - in this case, the status of the message will be set back to Pending. No further messages of this type and action should be processed. 
* In all cases, the return value should be audited against the standard Audit tables in {{#var:System}}. The value of the EXC_ID field should be written to the Audit tables in the new EPL_EXC_ID.

{{Note}} Changes will be made to the SOAP sending procedure so that:
* If no action is specified, it decides upon the action based on the message being sent (i.e. the System, Type and Action).
* If no parameter is specified, it does not include this tag in the XML
* The response processing is based on the system to whom the message being sent (standard OBS if not specified).


{{Note}} Orders should be added with only with workflow stages that require navigating to the job and indicating arrival - the job may be automatically completed at that stage by TomTom.


{{Note}} WEBFLEET webservices have time- and quantity- based limitations, so there must be a re-process function built into this process. When checking return codes, if the return code from the TomTom webservice shows that the number of requests have been exceeded, then the current record being processed for this message type should be left at Pending status and all processing of further messages of this type and action should be stopped from that point until the next run of the autoexport process. This should allow time for the TomTom webservice to clear before the next request is made, and ensure that orders make it onto WEBFLEET as soon as the webservices will allow them. This return message processing is specific to TomTom webservices and should be built into the SOAP message send functionality based on the new XF_CONFIG IDs "TO" and "TG".


{{Note}} WEBFLEET webservices are covered in detail in the WEBFLEET.connect specification, referenced in [[#Appendix A: Quote & Document References|Appendix A]].


== Mobile Device ==
=== Webservices ===
The EPOD_LOAD_REQUEST webservice call will be modified to add the driver's selected Vehicle to the XML. This will allow the server to mark the load as In Progress and assign it to the vehicle when the user retrieves the load on the device, not when the first job is started. It will also return other loads in progress for that vehicle to Pending status and ensure the correct orders are on the TomTom device associated to that vehicle.


<!-- NEW PAGE --> 
{{Doc_Appendix
|Appendix=A
|Estimate=Y
|Glossary=EPOD
|Ref1=[[FS 322073 EPOD WEBFLEET Interface - Basic]]
|RefV1=0.6
|RefDate1=6/05/2015
|Ref2=[https://uk.support.business.tomtom.com/app/answers/detail/a_id/218 WEBFLEET.connect-en-1.24.0.pdf]
|RefV2=1.24.0
|RefDate2=19/01/2015|REQ=0
|EST=0
|FS=1.75
|TS=1.75
|DEV=9.5
|ST=1.75
|IMP=0.5
|PM=1.25
|Client={{#var:Client}}
|Year={{#var:Year}}
|FSEST=N
|Rev1=Matt Turner
|Rev1Title=OBS {{#var:System}} Product Manager
|Rev2=Murray Middleton
|Rev2Title=OBS {{#var:System}} Development Manager
}}</div> 
[[Category:{{#var:Client}} FS]]