Partnerlink

TPN - Pallet Network Interface

CALIDUS ePOD

8th March 2016 - 1.0
Reference: FS 333427

Functional Overview

Client Requirement

Partnerlink Partners David Hathaway and R Swain & Sons require an interface to update the POD Delivery details from CALIDUS ePOD into The Pallet Network (TPN).

Solution Overview

Process:

Any new partners will be set up with a new partner code within CALIDUS ePOD, will be configured for their use following the standard configuration. These will be configured for export to the TMS system in use.
An export configuration for TPN will be created and linked to the TPN job code.
New Jobs will be sent to Partnerlink through the existing JobShare format, or directly to the back-end TMSs.
When planned, these jobs will be sent to CALIDUS ePOD through the existing interface in use for the existing partners, and will be identified with a new Job Group e.g. TPN. Note: This will require change to the sending process from the TMS system to accommodate this new Tracking System value. The Consignment number will also be provided.
The Partnerlink Pallet IDs will be generated as now.
The TPN pallet IDs will be generated as an ascending numeric sequence from 1.
The jobs will be completed like any other normal delivery.
When jobs are completed, the existing AutoExport functionality will update the Partners (identified through their Partner Codes) using a flat-file export of the job details in OBS Logistics' XML format, as it does with each existing partner.
The AutoExport process will also export the files to TPN Connect application, identified through the Job's Group and the configuration attached to it.
The AutoExport functionality will store the success or failure of the export, along with any of the returned reasons from the export.

The Admin Export Configuration screen will be changed to allow the parameters for the new TPN extract to be specified against it.

The new TPN Export process will work as follows:

A message will be sent to the TPN Connect application, by connecting through the AddPOD method of their existing ThirdPartyServices webservice. One message will be sent per consignment, to update a pallet and consignment with delivery, signatory and signature information. The pallet ID used for this update will be the TPN pallet ID generated on receipt of the order (the numeric sequence) and the consignment will be set from that provided on the order.

The response will be captured by the process and handled for success or failure.

Scope

Assumptions:

Jobs will be sent to Partnerlink and through to CALIDUS ePOD using the existing JobShare interfaces.
It is expected that pallets for TPN will be labelled with their own network's pallet labels. It is expected that pallets will be created by CALIDUS ePOD in the normal way, identifying the individual pallets by assigning each pallet a unique ID, counting from the 1 to the total number of pallets.
Partners completing jobs for TPN will accept updates into their Transport systems from CALIDUS EPOD in the standard OBS format - the TPN Connect system will be updated separately. This will require a modification to identify consignments as being completed for TPN when jobs are interfaced from the external Transport systems.
The Consignment will already exist within the TPN Connect application, ready for updating with POD information from CALIDUS ePOD.
Any new partners will be assigned a Partner Code by Partnerlink, which will be provided to OBS Logistics prior to implementation of this change.

Note: There are no reason codes required on the interface to TPN Connect for failed deliveries.

Note: Consignment number for TPN jobs may be up to 50 characters. At this time, the maximum job reference length of any type in CALIDUS ePOD is 20 characters. This SCR does not account for any changes in this length in the database, as it is assumed that this will not be required. If this is required, this will increase the development cost.

Changes will be made to latest version (v3.x.x.x) of CALIDUS ePOD only, and will require an update to all application components and full system and user acceptance testing.

This process is dependent on jobs being received into CALIDUS ePOD through the standard Partnerlink interface, changes to which have been specified in FS 326965 Partnerlink EPOD Interface, referenced in Appendix B. This change to the inbound interface may require changes to the Partner TMS systems to allow the new fields to be specified. The changes for this have been specified here for completeness. Note that no changes will be necessary to Partner TMS systems if those systems are used solely by partners that do not complete TPN jobs or have no requirement to specify linked (consolidated) jobs.

Additionally, jobs will be exported through the standard interface (also specified in the same document). As the latest version of the system is being used for the basis of this change, this may require changes to the partner TMS systems to extract the information in the new format. Note that only new fields have been added - fields have not been changed for purpose or function.

Set-up

Pre-requisites

Menu Structure

Data

New Sites will be set up and configured for all new Partner Codes. This will be as Partnerlink standard.
A new Job Group "TPN" will be set up for TPN jobs. This will initially be a copy of the Pall-Ex job group "PALLEX".
A new Auto-Export configuration will be created, linked to the job group TPN:
- EPL_XF_ID - "TPN"
- EPL_XF_TYPE - "SOAP"
- EPL_XF_DIRECTION - "O"
- EPL_WEB_USER - "203obs" (test)
- EPL_WEB_PASSWORD - "obs" (test)
- EPL_XF_DESTINATION - "http://dev.tpnconnect.com/" (test) or "http://pilot.tpnconnect.com/" (live)
- EPL_SOAP_NS - "http://schemas.datacontract.org/2004/07/ConnectSystem.Models.Integration"
- EPL_SOAP_NS_PREFIX - "con"
- EPL_EXPORT_JOB_TYPES - "D"

The interface of job data from the host TMS systems will be modified to identify the Pallet System in use (for example, Palletforce, Pall-Ex, Fortec, TPN). This will also pass in the Consignment Number. For TPN jobs, this will be:

PF Tracking Number - Consignment Number
Tracking System - "TPN"

Functional Description

Database

The database package used to retrieve the job transfer configurations must be modified.

The package EPOD_JOB_GROUP_CONFIGS retrieves the transfer configurations for each job, for each possible transfer, namely:

OWNER - the owning site.
OPERATOR - the operating site.
PALLET - any pallet network configuration

Each of these configurations if present are retrieved sequentially and grouped together and returned to the calling process.

The additional selection will be added to this and returned with the others, looking for transfer configurations for TPN.

Note: Suggested amendment to SQL:

   union all
   SELECT c.*, 'PALLET' PARTNER_TYPE FROM
   EPOD_JOB j
   INNER JOIN EPOD_SITE s
   ON s.EPL_SITE_ID = j.EPL_SITE_ID
   INNER JOIN EPOD_JOB_GROUPS jg
   ON jg.EPL_SITE_ID = j.EPL_SITE_ID 
   AND jg.EPL_JOB_GROUP = j.EPL_JOB_GROUP
   LEFT JOIN EPOD_XF_CONFIG cjg
   ON cjg.EPL_XF_CONFIG_ID = jg.EPL_XF_CONFIG
   AND cjg.EPL_XF_ID IN ('PALLEX','FORTRACK', 'TPN') 
   AND CHARINDEX(J.EPL_JOB_TYPE ,cjg.EPL_EXPORT_JOB_TYPES)>0
   LEFT JOIN EPOD_XF_CONFIG cs
   ON cs.EPL_XF_CONFIG_ID = s.EPL_XF_CONFIG
   AND cs.EPL_XF_ID IN ('PALLEX','FORTRACK', 'TPN') 
   AND CHARINDEX(J.EPL_JOB_TYPE ,cs.EPL_EXPORT_JOB_TYPES)>0
   INNER JOIN EPOD_XF_CONFIG c
   ON c.EPL_XF_CONFIG_ID = CASE
       WHEN (cjg.EPL_XF_CONFIG_ID IS NOT NULL) THEN cjg.EPL_XF_CONFIG_ID
       ELSE cs.EPL_XF_CONFIG_ID
   END
   AND c.EPL_XF_ID IN ('PALLEX','FORTRACK', 'TPN') 
   AND CHARINDEX(J.EPL_JOB_TYPE ,c.EPL_EXPORT_JOB_TYPES)>0
   WHERE J.EPL_JOB_ID=@EPL_JOB_ID  and J.EPL_SITE_ID=@EPL_SITE_ID

Admin

Export Configuration Screen

The Admin Export Configuration screen will be changed to allow the parameters for the new TPN extract to be specified against it.

Export Configuration Maintenance

The ID drop-down list will be modified to allow the new values below when entering a new configuration:

TPN

Auto-Import

The Partnerlink Import process will be modified to add a field to the import process to identify the Pallet System in use (for example, Palletforce, Pall-Ex, Fortec, TPN). This has been specified in full in FS 326965 Partnerlink EPOD Interface, referenced in Appendix B. The changes are as follows:

#	Field Name	Type	Max Length	Notes
63	PF Depot	C	10	Pallet Tracking System depot code, used when generating Pallet IDs for this pallet network.
64	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", "TPN". 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: 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: Those items marked with * above have been added since the last implementation of this interface. The other items above already existed but have had their length changed.

If the new fields Linked ID and Load Information are not passed, the system will not populate the data within CALIDUS ePOD.

If the new field Tracking System is not passed, the system will operate as it does now (assuming PalletForce). If passed in, this will be used to set the Job Group against the incoming job.

If the Tracking System has been set to "TPN", the procedure should generate the pallet IDs at the same time as generating the Container IDs, by generating a 2-digit counter, incremented per pallet to be created, non-zero-filled. This should be saved onto the container in the field EPL_CODE_1.

Auto-Export

The auto-export process retrieves all completed jobs that have not yet been transferred out of the system, and checks whether they require transfer.

Any that do not require transfer will be marked as transferred.

Any that have an applicable export configuration (see the database package modification above) will be passed to a procedure to transfer out according to the type (XF_ID) and parameters set against the configuration.

This function (EPOD_SYS_EXPORT.ExportJob) will be modified when checking EPOD_PARTNER_XF_CONFIG.EPL_XF_ID, to convert to a switch statement rather than a compound if statement. The cases are:

PF - PalletForce (existing code) - calls EPOD_SYS_EXPORT.GeneratePalletForceContent
PALLEX - for Pall-Ex exports (existing code) - calls EPOD_SYS_EXPORT.GeneratePallExContent.
FORTRACK - for ForTec exports - This is added to support future development, and should drop through to the default processing with an appropriate comment.
TPN - for TPN exports (see next section) - calls new function EPOD_SYS_EXPORT.GenerateTPNContent, defined below. The call to this function will be similar to that of the PALLEX export above.
Default - default processing - calls EPOD_SYS_EXPORT.GenerateJobExportContent

All code will be placed in a switch statement rather than a compound if statement.

Once all the data is created, the function then sends the message in the format specified on the transfer configuration record. For TPN messages, this will require a change to the standard SOAP message processing. The function will be changed to add a section specific to Export ID "TPN", with all existing codes enclosed as the default processing. Essentially, the SOAP message should be constructed as normal for the POD section, then the username and password added afterwards manually.

For Export ID TPN, the function will loop through each item in the list and send this through a specific SendExportAsSoap function. Note: This procedure may need a slight modification to ensure that the messages are sent in the correct format - if this is the case, existing code function should be maintained for all other messages.

The resulting messages will use the AddPOD format:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
  xmlns:tem="http://tempuri.org/" 
  xmlns:con="http://schemas.datacontract.org/2004/07/ConnectSystem.Models.Integration">
  <soapenv:Header/>
  <soapenv:Body>
     <tem:AddPOD>
        <tem:userName>?</tem:userName>
        <tem:password>?</tem:password>
        <tem:pod>
           <con:ConsignmentNumber>?</con:ConsignmentNumber>
           <con:Delivered>?</con:Delivered>
           <con:DeliveryDateTime>?</con:DeliveryDateTime>
           <con:Notes>?</con:Notes>
           <con:PODImage>?</con:PODImage>
           <con:SigneeName>?</con:SigneeName>
           <con:SignatureOnly>?</con:SignatureOnly>
           <con:ClauseNotes>?</con:ClauseNotes>
           <con:PODType>?</con:PODType>
           <con:Pallets>
              <con:POD_Pallet>
                 <con:Delivered>1</con:Delivered>
                 <con:PalletNumber>?</con:PalletNumber>
              </con:POD_Pallet>
           </con:Pallets>
        </tem:pod>
     </tem:AddPOD>
  </soapenv:Body>
</soapenv:Envelope>

These messages will be sent to the webservice through the standard mechanism in the system, and the resulting response returned to this function.

This function will check the response and, if this is a failure, will mark the job as having failed export (exactly as it does in the existing SOAP code). The responses, if successful will follow the format of:

Tag "whatevermethodResponse" containing tag "whatevermethodResult"

containing at least the text "Success", as below for example:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <AddPODResponse xmlns="http://tempuri.org/">
      <AddPODResult>Error: Unable to authenticate with provided credentials</AddPODResult>
   </AddPODResponse>
  </s:Body>
</s:Envelope>

As long as the result tag exists, and the text within contains "Success", this will be seen as a successful send. Anything else (i.e. no Result tag or "Success" not contained within) will be seen as a failure.

Note: This is functionally identical to the method of acknowledging Pall-Ex results and should be combined with this type.

Once this is complete, the job will be marked as having been exported for each successful export type (OPERATOR, OWNER and PALLET), based on the success of the send above. The new TPN export is seen as a PALLET export type.

When all exports have been successful, the job is marked as completely exported and will not be exported again.

The result (success or fail) and the response will be logged to the Audit table.

New TPN Auto-Export Process

Note: This function will be heavily based on the existing function EPOD_SYS_EXPORT.GeneratePallExContent and will be called EPOD_SYS_EXPORT.GenerateTPNContent.

The process will then make a call to the CONNECT webservice for the method AddPOD, the root of which will be defined in the transfer configuration:

One message will be sent for the whole consignment with each pallet number contained within the message. The consignment will be updated with the appropriate status, time, image and signatory. Each pallet will be marked as either Delivered or not.

Note: Note that there will be no facility to indicate to the CONNECT webservice the reason code for each claused pallet delivery. A pallet that has been delivered with a Claused Reason code will be sent as being delivered.

For the AddPOD message, this should be placed within an AddPOD tag with the following tags:

Parameter	Description	Details	Notes
userName	Username provided by TPN	Required	EPOD_XF_CONFIG.EPL_WEB_USER.
password	Password provided by TPN	Required	EPOD_XF_CONFIG.EPL_WEB_PASSWORD
pod	The POD information, containing the following tags
ConsignmentNumber	The Consignment Number	String (50)	EPOD_JOB.EPL_PF_TRACKING_NO.
DeliveryDateTime	The time of Delivery	XML Date Time format	EPOD_JOB.EPL_ACTUAL_END_DATE/TIME
Notes	Free text relating to the proof of delivery	String	EPOD_JOB.EPL_USER_NOTES
PODImage	The Signature image in PNG format	Bytes	EPOD_JOB.EPL_JOB_SIGNATURE
SigneeName	Name of person who signed the proof of delivery	String (50)	EPOD_JOB.EPL_CUST_SIGNATORY
SignatureOnly	Boolean. If true, then the image only contains a signature and not a TPN POD form	Boolean	set to true at all times.
ClauseNotes	String. Notes for a claused delivery	String	Set to the clause text or a clause reason code description, if a pallet on the consignment has been claused.
PODType	Enum. One of Delivered, DeliveredClaused or RefusedByConsignee	Enum	Set based on Status or clause code.
Pallets Repeating Object
PalletNumber	The TPN Pallet Number.	Integer	EPOD_CONTAINER.EPL_CODE_1.
Delivered	Whether the pallet was delivered (true) or not (false)	boolean	(EPOD_JOB.EPL_STATUS=="C")
End of Pallets Repeating Object

The process should first convert the Signature for the job to a PNG format.

The process should loop through all containers for the job.

Note: Cancelled pallets will be marked within the AddPOD message as being not Delivered. A message will NOT be sent to delete the pallet from the Connect system via the UpdateConsignmentPalletDelete message. Since Calidus Epod is not receiving information regarding individual pallet numbers, there is no way of identifying multiple delivery attempts for the same pallet. Therefore the system cannot determine whether a re-delivery attempt of pallet has occurred.

Then a list of the other Pallet Numbers to send should be built.

All fields other than those following should be set as described above.

If all pallets that have been successfully delivered, set the PODType to Delivered. The Pallet repeating object should contain one record per container. Set the Delivered flag against each pallet to true.
If some pallets have been delivered claused, set the PODType to DeliveredClaused. Set the ClauseNotes to the notes against the Claused pallets or the clause reason descriptions. The Pallet repeating object should contain one record per container. Set the Delivered against each pallet to true.
If some pallets have been cancelled, set the PODType to Delivered. Set the ClauseNotes to the clause reason descriptions. The Pallet repeating object should contain one record per container. Set the Delivered against each pallet to false.
If all pallets were cancelled, set the PODType to RefusedByConsignee. The Pallet repeating object should contain one record per container. Set the Delivered against each pallet to false. Set the ClauseNotes to the clause reason descriptions. The signature should not be set.

A single AddPOD message should be sent for the whole consignment. The Pallet repeating object should contain one record per container.

Note: If a consignment contains deliveries that have been claused for different reasons, the ClauseNotes will be set to the notes against the Claused pallets or the reason code descriptions for all of claused pallets on the consignment.The trailing spaces should be removed from each field and then appended together into a single string.

The resulting XML (per message to be sent) should be placed in a list for returning to the calling function and sending to the CONNECT webservice.

Appendix A: TEST PLAN

Test Script / Scenario Reference	TPN - Pallet Network Interface	Call Number(s): 333427
Test Script / Scenario Description	Testing Exports out to the TPN CONNECT system from CALIDUS ePOD.	PASS / ISSUES / FAIL
Menu Access	Administration/Auto-Export
Pre-requisites	A system configured as Partnerlink Test.	Tested By:
Test Objective	To test: Auto-Export may be configured for TPN exports and; Auto-Export exports the jobs correctly to the TPN Connect system.	Date:

Step	Action	Result	Remarks	P/F
1	Admin System

1.01	Ensure that TPN exports may be configured through the Auto-Export screen.	New Export Configurations may be created of ID TPN, allowing selection of this through the drop-down grid and displayed on the table on the screen.

Step	Action	Result	Remarks	P/F
2	Auto-Export
	Ensure that the job groups and sites are configured to export to the TPN Connect test system. Set up 5 orders in TPN Connect, each with 2 pallets. Set up 7 jobs that are for a TPN export. Ensure that 2 of these jobs have a value in EPL_PF_TRACKING_NO that does not match a pre-created consignment in TPN Connect. Start the Auto-Export process.
2.01	Successfully complete a job with a correct consignment number and all pallets delivered.	The export should show as exported successfully. The consignment should be updated to Epod Confirmed with a signature in TPN Connect, showing the signature.
2.02	Cancel a job with a correct consignment number.	The export should show as exported successfully. The consignment should show in TPN Connect as Refused. No signature should be sent.
2.03	Successfully complete a job with an incorrect consignment number.	The export should show as an error when exported. The consignment should not be updated in TPN Connect.
2.04	Cancel a job with an incorrect consignment number.	The export should show as an error when exported. The consignment should not be updated in TPN Connect.
2.05	Complete a job with a correct consignment number, but clause a pallet with a reason code.	The export should show as exported successfully. The consignment should show in TPN Connect as Claused. The pallets should show as being delivered. A signature should be sent.
2.06	Complete a job with a correct consignment number, but clause a pallet with text.	The export should show as exported successfully. The consignment should show in TPN Connect as Claused. The pallets should show as being delivered. A signature should be sent.
2.07	Complete a job with a correct consignment number, but cancel a pallet.	The export should show as exported successfully. The consignment should show in TPN Connect as Delivered. One pallet should show as delivered, and one shown as refused. A signature should be sent on the delivered pallet.
2.08	Change the export configuration to point to an incorrect URL for the TPN Connect webservice. Successfully complete a job with a correct consignment number.	The export should show as an error when exported. The consignment should not be updated in TPN Connect.

Appendix B: Quote & Document References

Cost Details
Activity	Estimate No. of Days	No. of Days	Rate per Day (£)	Cost (£ Exc. VAT)
Requirements	0.00	0.00	650	£0.00
Change Request Evaluation	0.25	0.25	650	£162.50
Functional Specification	1.00	1.50	650	£975.00
Technical Specification	1.00	1.00	650	£650.00
Development	4.50	4.50	650	£2,925.00
Testing and Release	0.75	0.75	650	£487.50
Implementation	0.25	0.25	650	£162.50
Project Management	0.25	0.25	650	£162.50

TOTAL	8.00	8.50		£5,525.00

Estimate excludes training, release to live and go live support.

B.1 References

Ref No	Document Title & ID	Version	Date
1	EST 333427 PART TPN - Pallet Network Interface	1.0	18/02/2015
2	FS 318572 PART Job Group Level Clausing	1.0	08/04/2015
3	FS 326965 Partnerlink EPOD Interface	1.0	22/05/2015
4	ThirdPartyServices.docx	N/A	2015

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

Murray Middleton	OBS Product Manager	_____________________________
John Davidson	Partnerlink Director	_____________________________

Anonymous

Search

FS 333427 PART TPN - Pallet Network Interface

Namespaces

More

Page actions

Contents

Functional Overview

Client Requirement

Solution Overview

Scope

Set-up

Pre-requisites

Menu Structure

Data

Functional Description

Database

Admin

Export Configuration Screen

Auto-Import

Auto-Export

New TPN Auto-Export Process

Appendix A: TEST PLAN

Appendix B: Quote & Document References

Navigation

Navigation

Translate

Wiki tools

Wiki tools

Anonymous

Search

FS 333427 PART TPN - Pallet Network Interface

Functional Overview

Client Requirement

Solution Overview

Scope

Set-up

Pre-requisites

Menu Structure

Data

Functional Description

Database

Admin

Export Configuration Screen

Auto-Import

Auto-Export

New TPN Auto-Export Process

Appendix A: TEST PLAN

Appendix B: Quote & Document References

Navigation

Wiki tools

Page tools

Categories