FS 326965 Partnerlink EPOD Interface: Difference between revisions

From Calidus HUB
VisualWikitext
(v0.3 - After internal review)
(v1.0 Ready for issue)
 
(3 intermediate revisions by one other user not shown)
Line 4: Line 4:
{{#vardefine:System|''CALIDUS'' ePOD}}
{{#vardefine:System|''CALIDUS'' ePOD}}
{{#vardefine:Doc_Title|EPOD-Partner System Interface}}
{{#vardefine:Doc_Title|EPOD-Partner System Interface}}
{{#vardefine:Version|0.3}}
{{#vardefine:Version|1.0}}
{{#vardefine:Date|20th May 2015}}
{{#vardefine:Date|22nd May 2015}}
{{#vardefine:Reference|326965}}
{{#vardefine:Reference|326965}}
{{#vardefine:Year|2015}}
{{#vardefine:Year|2015}}
Line 119: Line 119:
|5 ||PartnerJobID ||C ||14 || Partnerlink Job ID. This is used to form the pallet ID of the pallets to be delivered (this field plus 2-digit count from 01 to Total Pallets)
|5 ||PartnerJobID ||C ||14 || Partnerlink Job ID. This is used to form the pallet ID of the pallets to be delivered (this field plus 2-digit count from 01 to Total Pallets)
|-
|-
|6 ||Job Date ||C ||8 ||
|6 ||Job Date ||C ||8 || 
|-
|-
|7 ||Collection Name ||C ||30 ||Collection details - required for POD note (Consignor address)
|7 ||Collection Name ||C ||30 ||Collection details - required for POD note (Consignor address)
Line 157: Line 157:
|24 ||Delivery Contact ||C ||30 || This field is always to be sent blank, to force the users to enter a signatory on the Mobile Device application.
|24 ||Delivery Contact ||C ||30 || This field is always to be sent blank, to force the users to enter a signatory on the Mobile Device application.
|-
|-
|25 ||Delivery Phone Number ||C ||16 ||
|25 ||Delivery Phone Number ||C ||16 || 
|-
|-
|26 ||Delivery Partner ||C ||3 ||Partner code of the partner executing the job (if it's a delivery job type)
|26 ||Delivery Partner ||C ||3 ||Partner code of the partner executing the job (if it's a delivery job type)
Line 312: Line 312:
{| border="1"
{| border="1"
|- bgcolor="silver"
|- bgcolor="silver"
!Name !!width="45%"|Description !! Notes
!Name !!width="50%"|Description !! Notes
|-
|-
|EPL_SITE_ID ||Unique Reference for the Site that the Job belongs to ||The assigned Partner Code
|EPL_SITE_ID ||Unique Reference for the Site that the Job belongs to ||The assigned Partner Code
Line 326: Line 326:
|EPL_JOB_INSTRUCTION ||Instructions for the Driver || As Sent
|EPL_JOB_INSTRUCTION ||Instructions for the Driver || As Sent
|-
|-
|EPL_JOB_SIGNATURE ||The signature taken from the customer when the job was completed. This is in the form of a Base64-encrypted Jpeg file ||
|EPL_JOB_SIGNATURE ||The signature taken from the customer when the job was completed. This is in the form of a Base64-encrypted Jpeg file || 
|-
|-
|EPL_REASON_CODE ||If a job has been cancelled, the Job-level reason code entered by the user is held here. ||
|EPL_REASON_CODE ||If a job has been cancelled, the Job-level reason code entered by the user is held here. ||  
|-
|-
|EPL_LINKED_REASON ||If the job is a delivery, and a collection of the same load with the same EPL_JOB_CODE is cancelled, this delivery will be cancelled, and this field will be set to "Y" || N/A
|EPL_LINKED_REASON ||If the job is a delivery, and a collection of the same load with the same EPL_JOB_CODE is cancelled, this delivery will be cancelled, and this field will be set to "Y" || N/A
|-
|-
|EPL_STATUS ||EPL_STATUS: Status of the job. "C" for any items delivered/collected with any quantity, "X" if cancelled. ||
|EPL_STATUS ||EPL_STATUS: Status of the job. "C" for any items delivered/collected with any quantity, "X" if cancelled. ||  
|-
|-
|EPL_CUSTOMER_CODE ||Customer Code from external system. If not provided, one will be generated from EPL_CUSTOMER_NAME || As Sent
|EPL_CUSTOMER_CODE ||Customer Code from external system. If not provided, one will be generated from EPL_CUSTOMER_NAME || As Sent
Line 338: Line 338:
|EPL_PHOTO_ID ||If cancelled, a photo may have been taken by the user. If so, this field is populated with a unique ID. || N/A
|EPL_PHOTO_ID ||If cancelled, a photo may have been taken by the user. If so, this field is populated with a unique ID. || N/A
|-
|-
|EPL_PHOTO ||The photo taken for the exception. This is in the form of a Base64-encrypted Jpeg file ||
|EPL_PHOTO ||The photo taken for the exception. This is in the form of a Base64-encrypted Jpeg file ||  
|-
|-
|EPL_ENG_SIGNATURE ||The signature taken from the driver/engineer when the job was completed, if required. This is in the form of a Base64-encrypted Jpeg file ||
|EPL_ENG_SIGNATURE ||The signature taken from the driver/engineer when the job was completed, if required. This is in the form of a Base64-encrypted Jpeg file ||  
|-
|-
|EPL_SEQUENCE ||The sequence of the job. This could be the sequence sent on Import, a pre-defined sequence (if one was not provided) or a user-changed value (if enabled) || As Sent
|EPL_SEQUENCE ||The sequence of the job. This could be the sequence sent on Import, a pre-defined sequence (if one was not provided) or a user-changed value (if enabled) || As Sent
Line 352: Line 352:
|EPL_END_PLANNED_TIME ||Collection/Delivery Window || As Sent
|EPL_END_PLANNED_TIME ||Collection/Delivery Window || As Sent
|-
|-
|EPL_START_ACTUAL_DATE ||The date the user actually chose to start the job. Format: YYYYMMDD ||
|EPL_START_ACTUAL_DATE ||The date the user actually chose to start the job. Format: YYYYMMDD ||  
|-
|-
|EPL_START_ACTUAL_TIME ||The time the user actually chose to start the job. Format HHMMSSNN ||
|EPL_START_ACTUAL_TIME ||The time the user actually chose to start the job. Format HHMMSSNN ||  
|-
|-
|EPL_ARRIVAL_DATE ||The date the user indicated they arrived at the destination. Format: YYYYMMDD ||
|EPL_ARRIVAL_DATE ||The date the user indicated they arrived at the destination. Format: YYYYMMDD ||  
|-
|-
|EPL_ARRIVAL_TIME ||The time the user indicated they arrived at the destination. Format HHMMSSNN ||
|EPL_ARRIVAL_TIME ||The time the user indicated they arrived at the destination. Format HHMMSSNN ||  
|-
|-
|EPL_END_ACTUAL_DATE ||The date the user completed or cancelled the job. Format: YYYYMMDD ||
|EPL_END_ACTUAL_DATE ||The date the user completed or cancelled the job. Format: YYYYMMDD ||  
|-
|-
|EPL_END_ACTUAL_TIME ||The time the user completed or cancelled the job. Format HHMMSSNN ||
|EPL_END_ACTUAL_TIME ||The time the user completed or cancelled the job. Format HHMMSSNN || 
|-
|-
|EPL_DISTANCE_PLANNED ||  || N/A
|EPL_DISTANCE_PLANNED ||  || N/A
Line 392: Line 392:
|EPL_EMAIL ||  || As Sent
|EPL_EMAIL ||  || As Sent
|-
|-
||EPL_INVOICED ||A flag indicating the driver ticked an Invoiced box when completing the job. ||
||EPL_INVOICED ||A flag indicating the driver ticked an Invoiced box when completing the job. ||  
|-
|-
|EPL_CUST_SIGNATORY ||The name of the customer signatory on the job. ||
|EPL_CUST_SIGNATORY ||The name of the customer signatory on the job. ||  
|-
|-
|EPL_JOB_CODE ||External reference for the Job. This element can be used to link a collection and delivery together under the same reference. So, if an order is being collected at A and delivered at B, there are 2 jobs, each with a unique Job ID, but with the same Job Code. Optionally, EPOD will keep the Delivery leg of a linked job updated with the information captured from the collection. || As Sent
|EPL_JOB_CODE ||External reference for the Job. This element can be used to link a collection and delivery together under the same reference. So, if an order is being collected at A and delivered at B, there are 2 jobs, each with a unique Job ID, but with the same Job Code. Optionally, EPOD will keep the Delivery leg of a linked job updated with the information captured from the collection. || As Sent
Line 402: Line 402:
|EPL_OFFICE_INSTRUCTION ||Instructions for Admin staff || As Sent
|EPL_OFFICE_INSTRUCTION ||Instructions for Admin staff || As Sent
|-
|-
|EPL_SIGNED_UNCHECKED ||An indication whether the customer signed for the goods without checking them first. Note that this field can be used for any check-box entry, as this is configurable. ||
|EPL_SIGNED_UNCHECKED ||An indication whether the customer signed for the goods without checking them first. Note that this field can be used for any check-box entry, as this is configurable. ||  
|-
|-
|EPL_SO_NUMBER ||Sales Order Reference. || As Sent
|EPL_SO_NUMBER ||Sales Order Reference. || As Sent
|-
|-
|EPL_TNCS ||An XML fragment, displaying the Terms and Conditions agreed to by the customer when signing for the goods. This can also include up to 3 configurable check-boxes that the user may check. ||
|EPL_TNCS ||An XML fragment, displaying the Terms and Conditions agreed to by the customer when signing for the goods. This can also include up to 3 configurable check-boxes that the user may check. ||  
|-
|-
|EPL_ORDER_DATE ||Date Order created - defaulted to the date the order was received if not provided || As Sent
|EPL_ORDER_DATE ||Date Order created - defaulted to the date the order was received if not provided || As Sent
Line 414: Line 414:
|EPL_SALES_CONTACT ||The operative who took the order. Can be used as a display field for documentation || As Sent
|EPL_SALES_CONTACT ||The operative who took the order. Can be used as a display field for documentation || As Sent
|-
|-
|EPL_USER_NOTES ||Optional Notes entered by the driver while completing the job. ||
|EPL_USER_NOTES ||Optional Notes entered by the driver while completing the job. ||  
|-
|-
|EPL_OWNER_NAME ||Can be used as a display field for documentation, or indicating another Site ID that owns the job that is being executed by this site. || As Sent
|EPL_OWNER_NAME ||Can be used as a display field for documentation, or indicating another Site ID that owns the job that is being executed by this site. || As Sent
Line 420: Line 420:
|EPL_SERVICE_LEVEL ||Display field, containing Service Level text || As Sent
|EPL_SERVICE_LEVEL ||Display field, containing Service Level text || As Sent
|-
|-
|EPL_TRAILER_ID ||To be used if the vehicle being used to fulfil the job is a Tractor unit, and a trailer ID has been entered by the user. ||
|EPL_TRAILER_ID ||To be used if the vehicle being used to fulfil the job is a Tractor unit, and a trailer ID has been entered by the user. ||  
|-
|-
|EPL_PF_DEPOT ||External Pallet System Depot Code || As Sent
|EPL_PF_DEPOT ||External Pallet System Depot Code || As Sent
Line 428: Line 428:
|EPL_EXT_REF ||An external reference for the host system if required. For Partnerlink, this will be the PartnerJobID. || As Sent
|EPL_EXT_REF ||An external reference for the host system if required. For Partnerlink, this will be the PartnerJobID. || As Sent
|-
|-
|EPL_LAST_CHANGED_DATE ||  ||
|EPL_LAST_CHANGED_DATE ||  ||  
|-
|-
|EPL_LAST_CHANGED_TIME ||  ||
|EPL_LAST_CHANGED_TIME ||  ||  
|-
|-
|EPL_JOB_STATUS ||A Job Status entered by the driver, usually to indicate whether a job should be re-scheduled. Optional. ||
|EPL_JOB_STATUS ||A Job Status entered by the driver, usually to indicate whether a job should be re-scheduled. Optional. ||  
|-
|-
|EPL_COL_DATE ||Collection Date || As Sent
|EPL_COL_DATE ||Collection Date || As Sent
Line 472: Line 472:
|EPL_EMAIL ||  || As Sent
|EPL_EMAIL ||  || As Sent
|-
|-
|EPOD_CONTAINERS ||Contains a series of EPOD_CONTAINER objects, detailing all the deliverable items on this load. If there are loose products, there will also be a container with ID '000000000000000' holding these products. ||
|EPOD_CONTAINERS ||Contains a series of EPOD_CONTAINER objects, detailing all the deliverable items on this load. If there are loose products, there will also be a container with ID '000000000000000' holding these products. ||  
|-
|-
|EPOD_SERVICES ||If the job is a Service, this object contains a series of EPOD_SERVICE objects, each holding all the service-related information for each service item. In that case, no containers or products will be specified against the job. || N/A  
|EPOD_SERVICES ||If the job is a Service, this object contains a series of EPOD_SERVICE objects, each holding all the service-related information for each service item. In that case, no containers or products will be specified against the job. || N/A  
Line 482: Line 482:
|+ align="bottom"|''Sample Code Setup''
|+ align="bottom"|''Sample Code Setup''
|- bgcolor="silver"
|- bgcolor="silver"
!Name !!width="45%"|Description !!External Field !! Notes
!Name !!width="50%"|Description !! Notes
|-
|-
|EPL_SITE_ID ||Unique Reference for the Site that the Job belongs to || As Containing Job
|EPL_SITE_ID ||Unique Reference for the Site that the Job belongs to || As Containing Job
Line 490: Line 490:
|EPL_CONTAINER_ID ||EPL_CONTAINER_ID: The unique identifier for a container. || The Partnerlink Pallet ID, as generated from the import file (dependent on pallet network).
|EPL_CONTAINER_ID ||EPL_CONTAINER_ID: The unique identifier for a container. || The Partnerlink Pallet ID, as generated from the import file (dependent on pallet network).
|-
|-
|EPL_STATUS ||EPL_STATUS: Status of the current Container. C-Completed, X-Cancelled. ||  
|EPL_STATUS ||EPL_STATUS: Status of the current Container. C-Completed, X-Cancelled. ||  
|-
|-
|EPL_SEQUENCE ||A sequence for the containers to be shown on the user's device. || As Sent
|EPL_SEQUENCE ||A sequence for the containers to be shown on the user's device. || As Sent
Line 498: Line 498:
|EPL_CONTAINER_PACKAGE_DESC ||  || As Sent
|EPL_CONTAINER_PACKAGE_DESC ||  || As Sent
|-
|-
|EPL_REASON_CODE ||If a job has been cancelled, the reason code entered by the user is held here. ||  
|EPL_REASON_CODE ||If a job has been cancelled, the reason code entered by the user is held here. ||  
|-
|-
|EPL_LINKED_REASON ||If the job is a delivery, and a collection of this container on the same load with the same EPL_JOB_CODE is cancelled, this container will be cancelled, and this field will be set to "Y" || N/A
|EPL_LINKED_REASON ||If the job is a delivery, and a collection of this container on the same load with the same EPL_JOB_CODE is cancelled, this container will be cancelled, and this field will be set to "Y" || N/A
Line 504: Line 504:
|EPL_PHOTO_ID ||If cancelled, or received with a clause, a photo may have been taken by the user. If so, this field is populated with a unique ID. || N/A
|EPL_PHOTO_ID ||If cancelled, or received with a clause, a photo may have been taken by the user. If so, this field is populated with a unique ID. || N/A
|-
|-
|EPL_PHOTO ||The photo taken for the exception. This is in the form of a Base64-encrypted Jpeg file ||  
|EPL_PHOTO ||The photo taken for the exception. This is in the form of a Base64-encrypted Jpeg file ||  
|-
|-
|EPL_GROSS_WEIGHT ||Gross Weight || As Sent
|EPL_GROSS_WEIGHT ||Gross Weight || As Sent
Line 520: Line 520:
|EPL_LAST_CHANGED_TIME ||  || N/A
|EPL_LAST_CHANGED_TIME ||  || N/A
|-
|-
|EPL_CUST_COMMENTS ||Optional entry by the user, indicating whether the customer has identified an issue with the received item (a claused receipt). If present, the customer may have requested an image, which would be contained in EPL_PHOTO. ||  
|EPL_CUST_COMMENTS ||Optional entry by the user, indicating whether the customer has identified an issue with the received item (a claused receipt). If present, the customer may have requested an image, which would be contained in EPL_PHOTO. ||  
|-
|-
|EPL_VALID_DATE ||The date up until the contents of the package are valid - controls warnings at delivery. || N/A
|EPL_VALID_DATE ||The date up until the contents of the package are valid - controls warnings at delivery. || N/A

Latest revision as of 17:52, 22 May 2015





Aptean Logo.png







PartnerLink

EPOD-Partner System Interface

CALIDUS ePOD

22nd May 2015 - 1.0
Reference: FS 326965











































Functional Overview

The document is intended to describe the import and export formats for the Partnerlink Partner systems connecting to the CALIDUS ePOD system.

Client Requirement

  • The Partner system will send messages to the CALIDUS ePOD system to define Loads and Trips to be completed, as well as indicators of whether this is a pallet network job.
  • CALIDUS ePOD will inform the Partner system that the jobs are completed or cancelled.
  • CALIDUS ePOD will inform any Pallet Network systems that the jobs are completed or cancelled, and send the signature.


Solution Overview

A bespoke interface to and from CALIDUS EPOD exists for this purpose. This is heavily based around the existing JobShare interface used by the partners.

The summary of the solution requirements are:

  1. Standing Data (Vehicles, Users, Reason Codes, Job Groups, Sites) will be manually set up within CALIDUS ePOD - no automated drip-feed of this data will be entered into.
  2. Sending of data to CALIDUS ePOD will be through the Partnerlink CSV format.
  3. Receiving data from CALIDUS ePOD will be through the OBS XML format.
  4. The mechanism of sending data will be through Flat File transfer via a shared folder or FTP.
  5. The mechanism of receiving data will be through webservices (pushed or pulled), Flat File transfer via a shared folder or FTP.
  6. The sending of data to CALIDUS ePOD will be controlled through the partner's TMS, at an appropriate trigger point (i.e. when the trips/loads/routes have been confirmed and/or resource-allocated.
  7. Delivery and Collection jobs for a single load will be merged into a single load when sending data to CALIDUS ePOD.
  8. The partner TMS must sort the data in the planned start time, if available, or sequence to be completed, as required by the customer (Partnerlink).
  9. Amendments to the manifests should be automatically re-exported to CALIDUS ePOD using the same transfer format.
  10. CALIDUS ePOD exporting of completed or cancelled jobs will be through a timed process, expected to be every 5 minutes.
  11. A Partner code must be assigned and used for the jobs.


The Partnerlink CSV format allows for:

  • Collection and Delivery jobs.
  • The pallet network and additional pallet network parameters to be identified.
  • Automatic creation of pallet identifiers, based on the Partner Job ID and a sequence counting for the number of pallets e.g. a job of 3 pallets for Partner Job ID L0100004573083 for partner L01 will have pallets automatically generated as L010000457308301, L010000457308302 and L010000457308303.
  • Automatic creation of pallet identifiers, based on the pallet network parameters provided (currently only Palletforce formats are present - all other formats are assumed to be as standard Partnerlink formats).


This will require the Partner TMS systems to be modified as follows:

  • Ensure a single load is created for any manifests for the same vehicle/day/driver.
  • Pass the load and job information into CALIDUS ePOD in the agreed CSV format (described in this document) at trigger points (e.g. Load confirmed, Load amended, etc).
  • FTP or copy the file containing the CSV-formatted payload to an agreed folder.
  • Create a process for importing data back from the OBS XML format through flat file or webservices.


Note Note: For details of the standard CALIDUS ePOD webservices, see the standard documentation referenced in Appendix A.


Scope

Note Note: There are modifications being made to the CALIDUS ePOD system, both for product enhancement and specifically for the Partnerlink customer that are driving changes into both the import and export functionality described here. Some have not yet been finalised. All known modifications to the schemas have been added to this document. Should any further requirements be known after this document is issued, this document will be revised and reissued at that time.

Note Note: Future modifications may be made to the exporting of data from CALIDUS ePOD to the partner TMS systems. When modifications of this nature are made, a new validation schema (XSD) for the XML payload will be issued. The modifications to the partner TMS systems to import this data should be made in such a way that this new XSD can be replaced into the system without program modifications in the future.

Note Note: It is not deemed necessary at this time to map interfaces from partner TMS systems for Standing Data, as it was agreed that this would be maintained separately and manually within CALIDUS ePOD. Those flows are:

  • Vehicles
  • Reason Codes (used when cancelling jobs or pallets, or clausing deliveries)
  • Users (Drivers)
  • Customers


Set-up

Pre-requisites

  • Working Partner TMS systems and CALIDUS ePOD system must be in place and configured as agreed.
  • At a minimum, the systems must be able to connect via a shared folder, either through an internet or LAN connection. This must be accessible directly, without user and password information, through a shared user-name on the two servers or domain. This will be coordinated and configured by the Partnerlink IT team.


Menu Structure

None


Data

As described below.


Functional Description

Creating the Messages to CALIDUS ePOD

The sending of data to CALIDUS ePOD will be controlled through the partner's TMS, at an appropriate trigger point (i.e. when the trips/loads/routes have been confirmed and/or resource-allocated.


A list of all the fields in the interface for Load (Manifest) and Job follows. A full spreadsheet of all the import flows and fields containing all the limitations on length and defaulted values is provided separately.

# Field Name Type Max Length Notes
1 Requestor C 3 Owning Partner - the Partner that owns the JobShare job (if present), else the Delivery or Collection Partner, depending on Job Type
2 Reference 1 C 7 Partner Job Number
3 Reference 2 C 16 Customer Reference
4 Reference 3 C 16 Additional Reference
5 PartnerJobID C 14 Partnerlink Job ID. This is used to form the pallet ID of the pallets to be delivered (this field plus 2-digit count from 01 to Total Pallets)
6 Job Date C 8  
7 Collection Name C 30 Collection details - required for POD note (Consignor address)
8 Collection Address 1 C 30 Collection details - required for POD note (Consignor address)
9 Collection Address 2 C 30 Collection details - required for POD note (Consignor address)
10 Collection Address 3 C 30 Collection details - required for POD note (Consignor address)
11 Collection Address 4 C 30 Collection details - required for POD note (Consignor address)
12 Collection Postcode C 10 Collection details - required for POD note (Consignor address)
13 Collection Contact C 30 This field is always to be sent blank, to force the users to enter a signatory on the Mobile Device application.
14 Collection Phone Number C 16 Collection details - required for POD note (Consignor address)
15 Collecting Partner C 3 Partner code of the partner executing the job (if it is a collection job type)
16 Collection Date C 8 Planned Start Date
17 Collection Time C 5 Planned Start Time
18 Delivery Name C 30 Customer or Job Address
19 Delivery Address 1 C 30 Customer or Job Address
20 Delivery Address 2 C 30 Customer or Job Address
21 Delivery Address 3 C 30 Customer or Job Address
22 Delivery Address 4 C 30 Customer or Job Address
23 Delivery Postcode C 10 Customer or Job Address
24 Delivery Contact C 30 This field is always to be sent blank, to force the users to enter a signatory on the Mobile Device application.
25 Delivery Phone Number C 16  
26 Delivery Partner C 3 Partner code of the partner executing the job (if it's a delivery job type)
27 Delivery Date C 8 Planned Start Date
28 Delivery Time C 5 Planned Start Time
29 Number of Full Pallets N   Added to form Total Pallets
30 Number of Half Pallets N   Added to form Total Pallets
31 Number of Quarter Pallets N   Added to form Total Pallets
32 Number of OverSize Pallets N   Added to form Total Pallets
33 Weight in Kilos N   Divided by Total Pallets to create a Weight per pallet
34 Manifest Notes 1 C 48 Job Instructions
35 Manifest Notes 1 C 48 Job Instructions
36 Manifest Notes 1 C 48 Office Instructions
37 Manifest Notes 1 C 48 Office Instructions
38 Service C 2 Service Level
39 Surcharges C 16 N/A
40 Pallet Spaces N   N/A
41 Number of Chep pallets N   N/A
42 Hazardous C 1 N/A
43 ADR Number N 5.2 N/A
44 Packing Group C 10 N/A
45 Category C 10 N/A
46 Product name C 10 N/A
47 UN Number C 10 N/A
48 24 Hour Phone Number C 10 N/A
49 Number of Packs N   N/A
50 Number of Litres N   N/A
51 Weight in Kilos N   N/A
52 Value 1 N   N/A
53 Value 2 N   N/A
54 Value 3 N   N/A
55 Spare Text 1 C 6 N/A
56 Job Bar Code C 16 N/A
57 Manifest Number C 20 The unique Load ID
58 Account Code C 12 Used for display in the POD format
59 Trailer Number C 10 Trailer ID
60 Driver ID C 10 Driver to whom the job has been assigned
61 Vehicle ID C 10 Vehicle to which the job has been assigned, or blank
62 Job Type C 2 Identifying Collection "C" or Delivery "D"
* PF Depot C 10 Pallet Tracking System depot code, used when generating Pallet IDs for this pallet network.
* PF Tracking Number C 30 Pallet Tracking System tracking number, used when generating Pallet IDs for this pallet network.
* Tracking System C 29 This identifies any external pallet tracking system in use for this job. Currently values of "PALLET", "PALLEX", "FORTRACK". If this is not set, and Pallet Tracking System Depot Code and Tracking number are set, defaults to "PALLET" (for the Palletforce network).
* Linked ID C 40 If this is set, any jobs with the same linked ID on the same load will be consolidated into a single delivery or collection. Note Note: Only link jobs of the same type and partner or pallet network.
* Load Information C 500 If this is set, shown on the ePOD Device Load Information pop-up.

Note Note: Those items marked with * above have changed or been added since the last implementation of this interface, or are subject to change at this time.


Notes:

  • Job planned start dates and times should be sent through on the message.
  • Jobs without planned start dates and times, but with a service level agreement against them i.e. AM or PM deliveries, should have the time defaulted appropriately. For example:
    • AM - set to 11:59
    • PM - set to 16:59
  • The jobs should be sent through in the order in which they should be completed on the manifest.


Transferring messages to CALIDUS ePOD

The files can be :

  • Sent by the partner TMS systems via FTP to an FTP service hosted by OBS Logistics or the partner.
  • Pulled by CALIDUS ePOD via FTP from an FTP service hosted by the partner.
  • Copied by CALIDUS ePOD from a shared folder on the partner TMS systems.
  • Copied by the partner TMS systems to a shared folder on CALIDUS ePOD.

Note Note: It is expected that this transfer will be via file transfer though a shared folder on the partner TMS systems.

If a flat-file transfer mechanism is chosen, the final destination folder should contain only completed files in the agreed naming convention, not files in the process of being built. The files should be built and copied under a temporary naming convention, before renaming to CSV file (i.e. .tmp files).

The files to be picked up will be named as follows:

  • <SENDER>_<RECEIVER>_<OPERATING_PARTNER>_<DATE>_

where

  • <SENDER> is the system sending the file - expected to be the name of the partner TMS systems
  • <RECEIVER> is the system receiving the file - expected to be "epod"
  • <OPERATING_PARTNER> is the operating partner code, i.e. L02, L03, etc.
  • <DATE> is the date in YYYYMMDD format
  • <SEQ> is a unique counting sequence for each file created in a run.

No responses to the files shall be given - the receiving system (CALIDUS ePOD in this case) will maintain an audit trail to be examined by the user on event of failure. It is the originating partner's responsibility to monitor their export process for success or failure.

Each manifest should be sent in a separate file, to minimise disruption if a single file fails.

The entire content of the file will fail if there is any issue with the format of the file. A single job will fail if there is an issue with the content of that job - all other jobs will process if they are valid.


Importing into CALIDUS ePOD

A load will be created for the manifest and assigned to the driver and vehicle.

Load start and end times will be set based on the earliest and latest planned start and end times specified against the jobs for that load.

If Load information is provided, this will be added.

If the vehicle does not exist, one will be created with basic information.

Customers will be created for all jobs if they do not already exist. If a customer already exists with a different address, a job-specific address will be created, and the original customer address will not be updated.

Jobs will be created with a specific group per partner (to control partner-specific configuration), unless the job is marked as part of a pallet network, when the configuration will change to that required for the pallet network.

If a linked ID is provided, the jobs with the same linked ID on the load will be consolidated for delivery/collection.

Pallets will be created for the total number of pallets (totalled from the Full, Half, Quarter and Oversize pallets fields), based on the Partner Job ID and a sequence counting for the number of pallets. For example, a job of 3 pallets for Partner Job ID L0100004573083 for partner L01 will have pallets automatically generated as L0100004573083001, L0100004573083002 and L0100004573083003.

Pallets will be generated through different mechanisms, depending on the Pallet Network in use. For example, for Palletforce jobs, these will be created as "506" + PF Depot + ServiceLevel + PF Tracking No + 2-digit sequence. It is expected that any other pallet network/tracking system may employ different naming mechanisms, but these PF fields may be used for any extra data required to be used in the generation of pallet IDs for that system. Note Note: At this time, only one standard generation mechanism (for Partnerlink) and one bespoke generation mechanism (for Palletforce) exists. If any others are required, these will be undertaken as a change request to the system and charged appropriately.


Receiving Job Updates from CALIDUS ePOD

A process runs on a timed schedule within the CALIDUS EPOD application, to pick up any jobs that have been completed and export them to external systems. Alternatively, a data webservice is hosted within CALIDUS ePOD so that these can be requested on demand, by Job or Date.


CALIDUS ePOD Export Message Content

A list of all the fields in the interface for Job follows. A full spreadsheet of all the export flows and fields containing all the limitations on length and defaulted values is provided separately.

EPOD_JOB

Name Description Notes
EPL_SITE_ID Unique Reference for the Site that the Job belongs to The assigned Partner Code
EPL_JOB_ID Unique reference for the job. If not provided on Import, this will be generated by EPOD N/A
EPL_LOAD_ID Unique Reference for the Load that the Job belongs to. If not provided, defaulted from the enclosing EPOD_LOAD As Sent
EPL_JOB_TYPE D=Delivery, C=Collection, S=Service As Sent
EPL_JOB_GROUP EPL_JOB_GROUP: This is setup within the Admin system. Each job group has its own settings and will determine how the Job is processed dependant on these settings. As Sent
EPL_JOB_INSTRUCTION Instructions for the Driver As Sent
EPL_JOB_SIGNATURE The signature taken from the customer when the job was completed. This is in the form of a Base64-encrypted Jpeg file  
EPL_REASON_CODE If a job has been cancelled, the Job-level reason code entered by the user is held here.  
EPL_LINKED_REASON If the job is a delivery, and a collection of the same load with the same EPL_JOB_CODE is cancelled, this delivery will be cancelled, and this field will be set to "Y" N/A
EPL_STATUS EPL_STATUS: Status of the job. "C" for any items delivered/collected with any quantity, "X" if cancelled.  
EPL_CUSTOMER_CODE Customer Code from external system. If not provided, one will be generated from EPL_CUSTOMER_NAME As Sent
EPL_PHOTO_ID If cancelled, a photo may have been taken by the user. If so, this field is populated with a unique ID. N/A
EPL_PHOTO The photo taken for the exception. This is in the form of a Base64-encrypted Jpeg file  
EPL_ENG_SIGNATURE The signature taken from the driver/engineer when the job was completed, if required. This is in the form of a Base64-encrypted Jpeg file  
EPL_SEQUENCE The sequence of the job. This could be the sequence sent on Import, a pre-defined sequence (if one was not provided) or a user-changed value (if enabled) As Sent
EPL_START_PLANNED_DATE Collection/Delivery Window As Sent
EPL_START_PLANNED_TIME Collection/Delivery Window As Sent
EPL_END_PLANNED_DATE Collection/Delivery Window As Sent
EPL_END_PLANNED_TIME Collection/Delivery Window As Sent
EPL_START_ACTUAL_DATE The date the user actually chose to start the job. Format: YYYYMMDD  
EPL_START_ACTUAL_TIME The time the user actually chose to start the job. Format HHMMSSNN  
EPL_ARRIVAL_DATE The date the user indicated they arrived at the destination. Format: YYYYMMDD  
EPL_ARRIVAL_TIME The time the user indicated they arrived at the destination. Format HHMMSSNN  
EPL_END_ACTUAL_DATE The date the user completed or cancelled the job. Format: YYYYMMDD  
EPL_END_ACTUAL_TIME The time the user completed or cancelled the job. Format HHMMSSNN  
EPL_DISTANCE_PLANNED   N/A
EPL_DISTANCE_ACTUAL   N/A
EPL_DRIVING_TIME   N/A
EPL_CUSTOMER_NAME The Name of the customer As Sent
EPL_JOB_ADDRESS A flag indicating whether this is a default Customer Address or a specific address for this job alone. As Sent
EPL_ADDRESS_1   As Sent
EPL_ADDRESS_2   As Sent
EPL_ADDRESS_3   As Sent
EPL_ADDRESS_4   As Sent
EPL_ADDRESS_5   As Sent
EPL_POSTCODE   As Sent
EPL_CONTACT   As Sent
EPL_TELEPHONE   As Sent
EPL_EMAIL   As Sent
EPL_INVOICED A flag indicating the driver ticked an Invoiced box when completing the job.  
EPL_CUST_SIGNATORY The name of the customer signatory on the job.  
EPL_JOB_CODE External reference for the Job. This element can be used to link a collection and delivery together under the same reference. So, if an order is being collected at A and delivered at B, there are 2 jobs, each with a unique Job ID, but with the same Job Code. Optionally, EPOD will keep the Delivery leg of a linked job updated with the information captured from the collection. As Sent
EPL_CUST_REF Customer's Order Reference As Sent
EPL_OFFICE_INSTRUCTION Instructions for Admin staff As Sent
EPL_SIGNED_UNCHECKED An indication whether the customer signed for the goods without checking them first. Note that this field can be used for any check-box entry, as this is configurable.  
EPL_SO_NUMBER Sales Order Reference. As Sent
EPL_TNCS An XML fragment, displaying the Terms and Conditions agreed to by the customer when signing for the goods. This can also include up to 3 configurable check-boxes that the user may check.  
EPL_ORDER_DATE Date Order created - defaulted to the date the order was received if not provided As Sent
EPL_ORDER_TIME Time Order Created As Sent
EPL_SALES_CONTACT The operative who took the order. Can be used as a display field for documentation As Sent
EPL_USER_NOTES Optional Notes entered by the driver while completing the job.  
EPL_OWNER_NAME Can be used as a display field for documentation, or indicating another Site ID that owns the job that is being executed by this site. As Sent
EPL_SERVICE_LEVEL Display field, containing Service Level text As Sent
EPL_TRAILER_ID To be used if the vehicle being used to fulfil the job is a Tractor unit, and a trailer ID has been entered by the user.  
EPL_PF_DEPOT External Pallet System Depot Code As Sent
EPL_PF_TRACKING_NO External Pallet System Tracking code, used to generate External Pallet System Pallet IDs As Sent
EPL_EXT_REF An external reference for the host system if required. For Partnerlink, this will be the PartnerJobID. As Sent
EPL_LAST_CHANGED_DATE    
EPL_LAST_CHANGED_TIME    
EPL_JOB_STATUS A Job Status entered by the driver, usually to indicate whether a job should be re-scheduled. Optional.  
EPL_COL_DATE Collection Date As Sent
EPL_UDF_JOBDETS Contains user-defined fields entered when processing Collections and Deliveries on the Job Details tab, in UDF formatted XML N/A
EPL_ACCOUNT Account Name N/A
EPL_LINKED_ID An identifier that informs the system that this job has been linked (consolidated) with other jobs manually by the driver. The format is irrelevant - if multiple jobs on the same load have the same linked ID, they were consolidated. As Sent
EPL_TIMEZONE TimeZone N/A
EPL_LOADING_TYPE Controls whether this job is seen to be a Loading task at a depot (Job Type = "C") or unloading at a depot (Job Type = "D"). Values can be "Y" or "N" or "" - only "Y" indicates whether the job is a loading/unloading task. As Sent
EPL_GENERATED Indicates whether the job is generated within C-EPOD. N/A
EPL_SWAP_VEHICLE Whether the vehicle was swapped N/A
EPOD_JOB_ADDRESS Any Job address against the job, if different to the customer address. Consisting of the following tags if present: As Sent
EPL_ADDRESS_TYPE "D" or "C" As Sent
EPL_ADDRESS_1   As Sent
EPL_ADDRESS_2   As Sent
EPL_ADDRESS_3   As Sent
EPL_ADDRESS_4   As Sent
EPL_ADDRESS_5   As Sent
EPL_POSTCODE   As Sent
EPL_CONTACT   As Sent
EPL_TELEPHONE   As Sent
EPL_EMAIL   As Sent
EPOD_CONTAINERS Contains a series of EPOD_CONTAINER objects, detailing all the deliverable items on this load. If there are loose products, there will also be a container with ID '000000000000000' holding these products.  
EPOD_SERVICES If the job is a Service, this object contains a series of EPOD_SERVICE objects, each holding all the service-related information for each service item. In that case, no containers or products will be specified against the job. N/A


EPOD_CONTAINER

Sample Code Setup
Name Description Notes
EPL_SITE_ID Unique Reference for the Site that the Job belongs to As Containing Job
EPL_JOB_ID Unique reference for the job. If not provided on Import, this will be generated by EPOD As Containing Job
EPL_CONTAINER_ID EPL_CONTAINER_ID: The unique identifier for a container. The Partnerlink Pallet ID, as generated from the import file (dependent on pallet network).
EPL_STATUS EPL_STATUS: Status of the current Container. C-Completed, X-Cancelled.  
EPL_SEQUENCE A sequence for the containers to be shown on the user's device. As Sent
EPL_CONTAINER_PACKAGE_CODE   As Sent
EPL_CONTAINER_PACKAGE_DESC   As Sent
EPL_REASON_CODE If a job has been cancelled, the reason code entered by the user is held here.  
EPL_LINKED_REASON If the job is a delivery, and a collection of this container on the same load with the same EPL_JOB_CODE is cancelled, this container will be cancelled, and this field will be set to "Y" N/A
EPL_PHOTO_ID If cancelled, or received with a clause, a photo may have been taken by the user. If so, this field is populated with a unique ID. N/A
EPL_PHOTO The photo taken for the exception. This is in the form of a Base64-encrypted Jpeg file  
EPL_GROSS_WEIGHT Gross Weight As Sent
EPL_DESCRIPTION_LONG   As Sent
EPL_CODE_1 Multi-purpose field As Sent
EPL_CODE_2 Multi-purpose field As Sent
EPL_CODE_3 Multi-purpose field As Sent
EPL_LAST_CHANGED_DATE   N/A
EPL_LAST_CHANGED_TIME   N/A
EPL_CUST_COMMENTS Optional entry by the user, indicating whether the customer has identified an issue with the received item (a claused receipt). If present, the customer may have requested an image, which would be contained in EPL_PHOTO.  
EPL_VALID_DATE The date up until the contents of the package are valid - controls warnings at delivery. N/A
EPL_VALID_TIME The time up until the contents of the package are valid - controls warnings at delivery. N/A
EPL_TYPE Shows whether this container was Ad Hoc Scanned ("A") or was preplanned (blank) N/A
EPOD_PRODUCTS Contains a series of EPOD_PRODUCTS objects, detailing the products within the container, or loose products N/A

Note Note: Regarding Signature and Photo data formats in this message: This data is stored and transmitted as a text string, Base64-encrypted. This data can be decoded and saved as binary data once received if required.

A sample of a single job with a single pallet is shown below: 

<EPOD_EXPORT_JOB>
  <EPOD_JOBS>
    <EPOD_JOB>
      <EPL_SITE_ID>L03</EPL_SITE_ID>
      <EPL_JOB_ID>0000000001</EPL_JOB_ID>
      <EPL_LOAD_ID>000000000002</EPL_LOAD_ID>
      <EPL_JOB_TYPE>D</EPL_JOB_TYPE>
      <EPL_JOB_GROUP>L03</EPL_JOB_GROUP>
      <EPL_JOB_INSTRUCTION>Very Fragile Parcel..Please handle with Care</EPL_JOB_INSTRUCTION>
      <EPL_JOB_SIGNATURE>R0lGODlh4AB4APcA...NKdJTY4EBAA7</EPL_JOB_SIGNATURE>
      <EPL_REASON_CODE></EPL_REASON_CODE>
      <EPL_LINKED_REASON>N</EPL_LINKED_REASON>
      <EPL_STATUS>C</EPL_STATUS>
      <EPL_CUSTOMER_CODE>OBS</EPL_CUSTOMER_CODE>
      <EPL_PHOTO_ID></EPL_PHOTO_ID>
      <EPL_ENG_SIGNATURE></EPL_ENG_SIGNATURE>
      <EPL_SEQUENCE>1</EPL_SEQUENCE>
      <EPL_START_PLANNED_DATE>20111108</EPL_START_PLANNED_DATE>
      <EPL_START_PLANNED_TIME>12000000</EPL_START_PLANNED_TIME>
      <EPL_END_PLANNED_DATE>0</EPL_END_PLANNED_DATE>
      <EPL_END_PLANNED_TIME>0</EPL_END_PLANNED_TIME>
      <EPL_START_ACTUAL_DATE>20111108</EPL_START_ACTUAL_DATE>
      <EPL_START_ACTUAL_TIME>10490000</EPL_START_ACTUAL_TIME>
      <EPL_END_ACTUAL_DATE>20111108</EPL_END_ACTUAL_DATE>
      <EPL_END_ACTUAL_TIME>10520000</EPL_END_ACTUAL_TIME>
      <EPL_DISTANCE_PLANNED>0</EPL_DISTANCE_PLANNED>
      <EPL_DISTANCE_ACTUAL>0</EPL_DISTANCE_ACTUAL>
      <EPL_DRIVING_TIME>0</EPL_DRIVING_TIME>
      <EPL_CUSTOMER_NAME>OBS Logistics</EPL_CUSTOMER_NAME>
      <EPL_JOB_ADDRESS>N</EPL_JOB_ADDRESS>
      <EPL_ADDRESS_1>Southern Gateway</EPL_ADDRESS_1>
      <EPL_ADDRESS_2>Speke Boulevard</EPL_ADDRESS_2>
      <EPL_ADDRESS_3>Liverpool</EPL_ADDRESS_3>
      <EPL_ADDRESS_4>Merseyside</EPL_ADDRESS_4>
      <EPL_ADDRESS_5></EPL_ADDRESS_5>
      <EPL_POSTCODE>L24 9HZ</EPL_POSTCODE>
      <EPL_CONTACT>Xavier Wai</EPL_CONTACT>
      <EPL_TELEPHONE>01514480331</EPL_TELEPHONE>
      <EPL_EMAIL>[email protected]</EPL_EMAIL>
      <EPL_INVOICED></EPL_INVOICED>
      <EPL_CUST_SIGNATORY></EPL_CUST_SIGNATORY>
      <EPL_JOB_CODE>L03</EPL_JOB_CODE>
      <EPL_CUST_REF></EPL_CUST_REF>
      <EPL_OFFICE_INSTRUCTION></EPL_OFFICE_INSTRUCTION>
      <EPL_SIGNED_UNCHECKED></EPL_SIGNED_UNCHECKED>
      <EPL_SO_NUMBER></EPL_SO_NUMBER>
      <EPL_TNCS></EPL_TNCS>
      <EPL_ORDER_DATE>0</EPL_ORDER_DATE>
      <EPL_SALES_CONTACT></EPL_SALES_CONTACT>
      <EPL_USER_NOTES></EPL_USER_NOTES>
      <EPL_OWNER_NAME></EPL_OWNER_NAME>
      <EPL_SERVICE_LEVEL></EPL_SERVICE_LEVEL>
      <EPL_TRAILER_ID></EPL_TRAILER_ID>
      <EPL_EXT_REF></EPL_EXT_REF>
      <EPL_LAST_CHANGED_DATE>20120314</EPL_LAST_CHANGED_DATE>
      <EPL_LAST_CHANGED_TIME>9420098</EPL_LAST_CHANGED_TIME>
      <EPOD_CONTAINERS>
        <EPOD_CONTAINER>
          <EPL_SITE_ID>L03</EPL_SITE_ID>
          <EPL_JOB_ID>0000000001</EPL_JOB_ID>
          <EPL_CONTAINER_ID>000000000000001</EPL_CONTAINER_ID>
          <EPL_SEQUENCE>0</EPL_SEQUENCE>
          <EPL_CONTAINER_PACKAGE_CODE>XX</EPL_CONTAINER_PACKAGE_CODE>
          <EPL_CONTAINER_PACKAGE_DESC>Pallet</EPL_CONTAINER_PACKAGE_DESC>
          <EPL_REASON_CODE></EPL_REASON_CODE>
          <EPL_LINKED_REASON></EPL_LINKED_REASON>
          <EPL_STATUS>C</EPL_STATUS>
          <EPL_PHOTO_ID></EPL_PHOTO_ID>
          <EPL_CUST_COMMENTS></EPL_CUST_COMMENTS>
          <EPL_GROSS_WEIGHT>120</EPL_GROSS_WEIGHT>
          <EPL_DESCRIPTION_LONG></EPL_DESCRIPTION_LONG>
          <EPL_CODE_1>1</EPL_CODE_1>
          <EPL_CODE_2></EPL_CODE_2>
          <EPL_CODE_3></EPL_CODE_3>
          <EPL_LAST_CHANGED_DATE>20120614</EPL_LAST_CHANGED_DATE>
          <EPL_LAST_CHANGED_TIME>16362322</EPL_LAST_CHANGED_TIME>
        </EPOD_CONTAINER>
      </EPOD_CONTAINERS>
      <EPOD_SERVICES></EPOD_SERVICES>
    </EPOD_JOB>
  </EPOD_JOBS>
</EPOD_EXPORT_JOB>

Note Note: The signature has been shortened for the purposes of this document.

CALIDUS ePOD Export Mechanism

The files can be:

  • Pulled by the partner TMS system via FTP from an FTP service hosted by OBS.
  • Sent by CALIDUS ePOD via FTP to an FTP service hosted by OBS Logistics or the partner TMS provider.
  • Copied by CALIDUS ePOD to a shared folder between CALIDUS ePOD and the partner TMS system.
  • Copied by the partner TMS system from a shared folder between CALIDUS ePOD and the partner TMS system.
  • Pushed to a webservice hosted by the partner TMS system.

Note Note: It is expected that this transfer will be via file transfer though a shared folder on the partner TMS system.

Regardless of the mechanism chosen above, the final destination folder should contain only completed files in the agreed naming convention, not files being built. The files should be built and copied under a temporary naming convention, before renaming to CSV file (i.e. .tmp files).

The files to be picked up will be named as follows:

  • <SENDER>_<RECEIVER>_<OPERATING_PARTNER>_<DATE>_

where

  • <SENDER> is the system sending the file - expected to be "epod".
  • <RECEIVER> is the system receiving the file - expected to be the name of the partner TMS systems.
  • <OPERATING_PARTNER> is the operating partner code, i.e. L02, L03, etc.
  • <DATE> is the date in YYYYMMDD format
  • <SEQ> is a unique counting sequence for each file created in a run.

No responses to the files shall be given - the receiving system (the partner TMS system in this case) will maintain an audit trail to be examined by the user on event of failure.

CALIDUS ePOD export mechanism includes facility to automatically resend failed transmissions.

Each job will be sent in a separate file, to minimise disruption if a single file fails.


Appendix A: Document References

A.1 References

Ref NoDocument Title & IDVersionDate
1JobShare Mapping v1.1.xlsx1.120/05/2015
2EPOD Export Mapping v3.11.xlsx3.1120/05/2015
3FS 291096 Interface with CALIDUS ePOD v1.0.pdf1.05/02/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 Account Manager		_____________________________

Murray Middleton
OBS Product Development Manager		_____________________________
Retrieved from ‘https://calidusassist.adcservices.apteancloud.com/calidus-assist/OBS/index.php?title=FS_326965_Partnerlink_EPOD_Interface&oldid=1949’