FS 322073 EPOD WEBFLEET Interface - Orders

From Calidus HUB
Revision as of 17:46, 15 April 2015 by Anw (talk | contribs) (v0.1 - Initial draft.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)





Aptean Logo.png







OBS Logistics

WEBFLEET Interface - Orders

CALIDUS EPOD

15th April 2015 - 0.1
Reference: FS 322073











































Functional Overview

Client Requirement

CALIDUS EPOD 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.


Scope

  • This change affects the latest version of the CALIDUS EPOD 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.


Set-up

Pre-requisites

A working CALIDUS EPOD 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_WEB_USER - "admin"
  • EPL_WEB_PASSWORD - "Matt3221"
  • EPL_XF_RECIPIENT - Account - "logistics-obs"
  • EPL_XF_DESTINATION - "http://connect.webfleet.tomtomwork.com/extern"
  • EPL_WEB_PARAMETER - API Key - "000fcb2a-6631-477a-b00e-de0505e7c7e3"
  • EPL_XF_DIRECTION - "O"
  • EPL_XF_TYPE - "POST"

FS 322073 Admin AutoExport.PNG
Import/Export Config Screen

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.


Functional Description

Database/DAL

The following triggers will be added to the existing table EPOD_LOAD:

  • 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 setting any other Loads for this vehicle or Driver at status "I" back to status "P"
  • Trigger write to EPOD_XF_CONTROL for the Load, action "D" if TomTom Orders 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


The existing table and DAL object EPOD_JOB will be modified to add the following field:

  • EPL_TOMTOM_ID - nvarchar(20).

Note 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 is removed from a load that is marked as In Progress. If this is consolidated (i.e. EPL_LINKED_ID is set), ensure there are no other jobs for this EPL_LINKED_ID on the Load.
  • Trigger write to EPOD_XF_CONTROL for the Job, action "D" if TomTom Orders enabled for the Site when a 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 is marked as complete or cancelled from a load that is marked as In Progress.


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 progresss load's orders and adding the orders for the new load in progress.


AutoExport

The new TomTom procedure should be modified to send order messages from EPOD_INT_CONTROL:

  • Add to the TOMTOM process to pick up messages for TOMTOM, type "L", action "A and "D"
  • Store Site XF_CONFIG settings (or get them as part of the message retrieval)
  • New TOMTOM process to find only messages EXC_STATUS = "P", order by EXC_ID
  • Change message status to "I" - Progress - any failure from this point to change status to "E" and log error.
  • Build URL from parameters in EPOD_XF_CONFIG:
    • EPL_XF_DESTINATION +
    • ?account=EPL_XF_RECIPIENT
    • &username=EPL_WEB_USER
    • &password=EPL_WEB_PASSWORD
    • &apikey=EPL_WEB_PARAMETER
  • Get this job and any others matching this jobs EPL_LINKED_ID.
  • Depending on System TOMTOM, EXC_TYPE "J" action "A", for a job with valid Lat/Long values:
    • &lang=en
    • &action=sendDestinationOrderExtern
    • &objectno=EPOD_VEHICLE.EPL_EXT_REF
    • &orderid=EPOD_JOB.EPL_TOMTOM_ID. 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_TOMTOM_ID to the value of this job's EPL_TOMTOM_ID.
    • &ordertext=The job references (EPL_JOB_CODE/EPL_CUST_REF) from all jobs, comma-delimited
    • &orderautomations=1,3,5,6
    • &latitude=EPL_LAT from EPOD_CUSTOMER/EPOD_JOB_ADDRESS * 1^6, rounded to an integer
    • &longitude=EPL_LONG from EPOD_CUSTOMER/EPOD_JOB_ADDRESS * 1^6, rounded to an integer
    • &country=GB
    • &zip=EPL_POSTCODE
    • &city=EPL_ADDRESS_2
    • &street=EPL_ADDRESS_1
    • &ordertype=EPOD_JOB.EPL_JOB_TYPE converted: S = 1, C = 2, D = 3, default to 3.
    • &useISO8601=true
    • &orderdate=EPOD_JOB.EPL_START_PLANNED_DATE, providing the timezone offset e.g. 2009-01-20T+01:00
    • &ordertime=EPOD_JOB.EPL_START_PLANNED_TIME, local time
    • &arrivaltolerance=15
    • &contact=EPL_CONTACT if present
    • Note: All address and free-text fields should be HTMLSafe
    • Send message
    • Process Response:
    • Failure - update status of message to "E" and audit.
    • Success - update record indicated by EXC_TYPE and mark status of message to "C"
  • Depending on System TOMTOM, EXC_TYPE "J" action "D":
    • &lang=en
    • &action=deleteOrderExtern
    • &objectno=EPOD_VEHICLE.EPL_EXT_REF
    • &orderid=EPOD_JOB.EPL_TOMTOM_ID
    • &mark_deleted=1
    • Send message
    • Process Response:
    • Failure - update status of message to "E" and audit.
    • Success - update record indicated by EXC_TYPE and mark status of message to "C"
  • Depending on System TOMTOM, EXC_TYPE "L" action "A":
    • For each consolidated job on the load, not a loading job, add as per EXC_TYPE "J" action "A" above.
    • Send message
    • Process Response:
    • Failure - update status of message to "E" and audit.
    • Success - update record indicated by EXC_XF_TYPE and mark status of message to "C"
  • Depending on System TOMTOM, EXC_TYPE "L" action "D":
    • For each job on the load, add as per EXC_TYPE "J" action "D" above.
    • Send message
    • Process Response:
    • Failure - update status of message to "E" and audit.
    • Success - update record indicated by EXC_XF_TYPE and mark status of message to "C"
  • Update EPOD Audit records as normal for success or failure, consolidating all results into one record.

Note Note: The webservice action sendDestinationOrderExtern can only cope with 300 requests per 30 minutes, 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 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.


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.


Appendix A: 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 1.25 0 £0.00
Development 6.50 0 £0.00
Testing and Release 1.25 0 £0.00
Implementation 0.50 0 £0.00
Project Management 0.75 0 £0.00
 
TOTAL 11.50   £0.00
Estimate excludes training, release to live and go live support.

A.1 References

Ref NoDocument Title & IDVersionDate
1FS 322073 EPOD WEBFLEET Interface - Basic0.215/04/2015


A.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.


A.3 Authorised By


Matt Turner
OBS CALIDUS EPOD Product Manager		_____________________________

Murray Middleton
OBS CALIDUS EPOD Development Manager		_____________________________
Retrieved from ‘https://calidusassist.adcservices.apteancloud.com/calidus-assist/OBS/index.php?title=FS_322073_EPOD_WEBFLEET_Interface_-_Orders&oldid=1872’