FleXipod Interface: Difference between revisions

From CTMS
VisualWikitext
(Updated)
(Updated to latest version - in progress)
 
(One intermediate revision by the same user not shown)
Line 1: Line 1:
This guide is intended to show the configuration and basic functionality of the interface to and from Aptean Proof of Delivery (APOD, or formerly FLeXipod)
{{Incomplete}}
 
This guide shows how the Aptean Proof of Delivery system (APOD or formerly FleXipod) can be configured to be used from CTMS.
 
This require configuration as to when messages are sent, how they are formatted (the FleXipod attributes), at what level are messages sent (orders, stops, etc) and what information is expected to be received.




== Configuration ==
== Configuration ==
=== System Parameters ===
{| class="wikitable apt-searchable"
!Parameter !! Description !! Config By
|-
|FLEXIPOD ||Set to Y to indicate the FlexiPod interface is active ||SYSTEM
|-
|FLEXIPOD_ACID ||Flexipod acid ||SYSTEM
|-
|FLEXIPOD_BREAK_DROPS ||Flexipod include breaks for the drops in the Add API call (Y/N) ||SYSTEM
|-
|FLEXIPOD_CARRIERS ||Set to Y indicates the Carrier can control if a trip is sent to FlexiPod ||SYSTEM
|-
|FLEXIPOD_CLIENTNUM ||FleXipod ClientNum sent in interface ||SYSTEM
|-
|FLEXIPOD_DEPOTS ||Set to Y indicates the Depot can control if a trip is sent to FlexiPod ||SYSTEM
|-
|FLEXIPOD_DIRECT ||Set to Y to indicate the FlexiPod interface is direct and not using Route Execution ||SYSTEM
|-
|FLEXIPOD_DROP ||Determines the Drop level STOP-OMS or ITEM ||SYSTEM
|-
|FLEXIPOD_EXPIRY ||Sets the expiry date for the manifest as a number of days after the end of the trip. ||SYSTEM
|-
|FLEXIPOD_EXTERNALSYSTEMUPDATE ||Flexipod process the External System Update messages in the API call (Y/N) ||SYSTEM
|-
|FLEXIPOD_FORCEITEMSCAN ||Force the items to be scanned separately: 0 to use the ScanLevel or 1 to force the scan by item. ||SYSTEM
|-
|FLEXIPOD_LISTPENDINGMANIFESTS ||Flexipod process the List Pending Manifest Update messages in the API call (Y/N) ||SYSTEM
|-
|FLEXIPOD_MERGE_DROPS ||Flexipod merge the orders on the drop in the Add API call (Y/N) ||SYSTEM
|-
|FLEXIPOD_PASSWORD ||FleXipod Webservice password ||SYSTEM
|-
|FLEXIPOD_PROXY ||Flexipod proxy server ||SYSTEM
|-
|FLEXIPOD_READDROP ||Flexipod process the Read Drop messages in the API call (Y/N) ||SYSTEM
|-
|FLEXIPOD_SCAN_LEVEL ||1,2 or 3 to indicate line or item level scanning ||SYSTEM
|-
|FLEXIPOD_SCAN_TYPE ||Contents and items ||SYSTEM
|-
|FLEXIPOD_SIGNATORY ||Set to Y to store the SignedByName as the actual signatory as information for the order at its collection of delivery location ||SYSTEM
|-
|FLEXIPOD_SPLIT ||Are orders to be split? ||SYSTEM
|-
|FLEXIPOD_SYSTEM ||FleXipod SYSTEM ID sent in interface ||SYSTEM
|-
|FLEXIPOD_TPCLIENTNUM ||FleXipod TPClientNum sent in interface ||SYSTEM
|-
|FLEXIPOD_USERCODE ||FleXipod webservice usercode ||SYSTEM
|-
|FLEXIPOD_USERNAME ||FleXipod webservice username ||SYSTEM
|-
|FLEXIPOD_WEBSERVICE ||Flexipod webservice endpoint URL ||SYSTEM
|-
|FLEXIPOD_WEBSERVICE_TASK ||Flexipod webservice endpoint URL for Tasks ||SYSTEM
|-
|FLEXIPOD_WEBSERVICE_UI ||Flexipod webservice endpoint URL ||SYSTEM
|-
|FLEXIPOD_WEBSERVICE_UI_EXEC ||Flexipod webservice endpoint URL for Route Execution ||SYSTEM
|-
|FLEXIPOD_X_API_KEY ||Flexipod x-api-key for External System Update messages ||SYSTEM
|}
=== Carrier ===
The FLEXIPOD flag must be enabled when configured by carrier (system parameter FLEXIPOD_CARRIERS) for carriers that require the use of FlexiPOD.


=== Parameters ===
=== Depot Locations ===
Several parameters must be configured:
The FLEXIPOD flag must be enabled when configured by depot (system parameter FLEXIPOD_DEPOTS) for depots that require the use of FlexiPOD.


* FLEXIPOD - Controls whether the FlexiPOD interface is enabled for sending.


* FLEXIPOD_DEPOTS - Controls whether the export to FlexiPOD is configured by Depot Location.
=== EDI Processes ===
* FLEXIPOD_CARRIERS - Controls whether the export to FlexiPOD is configured by Depot Location.


* FLEXIPOD_WEBSERVICE_UI - The FlexiPOD webservice endpoint for updating items
'''FLEXIPOD_OUT'''
* FLEXIPOD_WEBSERVICE - The FlexiPOD webservice endpoint for sending manifests
* FLEXIPOD_USERNAME - The username for the FlexiPOD webservices
* FLEXIPOD_PASSWORD - The password for the FlexiPOD webservices
* FLEXIPOD_SYSTEMID - The system ID for the FlexiPOD webservices
* FLEXIPOD_USERCODE - The usercode for the FlexiPOD webservices
* FLEXIPOD_CLIENTNUM - The Client Number for the FlexiPOD webservices
* FLEXIPOD_SYSTEM - The system for the FlexiPOD webservices


* FLEXIPOD_SCAN_LEVEL - Controls how items are sent to FlexiPOD. Values: "1", "2"
This process sends the triggered manifests to APOD.
* FLEXIPOD_DROP - Controls how drops are updated from FlexiPOD. Values "STOP-OMS", "NONE"
 
* FLEXIPOD_SCAN_TYPE - Controls how items are sent to FlexiPOD. Values: "ITEMS", "CONTENTS"
* Flow Type: PROCESS
* Package Name: PROCESS, DP_FLEXIPOD.PROCESS_FLEXIPOD_OUT
* Process: i_process_name FLEXIPOD_OUT
* Interval: 5 minutes
 
'''FLEXIPOD_SENDLISTPENDING'''
 
This process checks to see if there are any pending updates from the manifests and imports the details.
 
* Flow Type: PROCESS
* Package Name: PROCESS DP_FLEXIPOD.send_listpendingmanifestupdates
* Process: PROCESS FLEXIPOD_SENDLISTPENDING
* Interval: 1 minute


=== Carrier ===
FLEXIPOD flag must be enabled when configured by carrier (system parameter FLEXIPOD_CARRIERS) for carriers that require the use of FlexiPOD.


=== Depot Locations ===
=== Reason Codes and Decodes ===
FLEXIPOD flag must be enabled when configured by depot (system parameter FLEXIPOD_DEPOTS) for depots that require the use of FlexiPOD.


=== EDI Processes ===
A decode of name "FLX_RESULT_CODES" type "REFERENCE" must be configured to map all of the reason codes from APOD into CTMS.


* SOAP Webservice must be set up pointing to DP_FLEXIPOD.flexipod_event_in. This processes the messages from FlexiPOD into an intermediary file and then onto staging files.
Several ITEM_NON_CON reason codes must be created to map to the APOD reason codes.:
* Timed EDI process must be set up based on process get_flexipod_in. This processes the staging files into the system.


=== Reason Codes ===
Examples:
Several ITEM_NON_CON reason codes must be created:
{| class="wikitable"
* "SKP" - "Items Skipped on Device"
!APOD !! CTMS !! Description || At Fault !! Action !! Type !! CBR
* "WIP" - "Route in Progress"
|-
* "OD" - "Out for delivery"
|1 ||SD ||Successful Delivery || || || ||
* "RM" - "Removed from Route"
|-
|10 ||SD ||Successful Delivery || || || ||
|-
|2 ||FV ||Failed Visit || || ||FAILURE ||Y
|-
|3 ||SD ||Successful Delivery || || || ||
|-
|4 ||UD ||Unsuccessful Delivery || || ||FAILURE ||
|-
|5 ||SC ||Successful Collection || || || ||
|-
|6 ||SJ ||Skipped Job || || ||FAILURE ||Y
|-
|7 ||NR ||No Longer Required || || ||FAILURE ||
|-
|8 ||PR ||Payment Refused || || || ||
|}


Plus any reason codes created in FlexiPOD must be created within TMS for the audit history to accurately represent any reasons selected by the driver.
Plus any reason codes created in FlexiPOD must be created within TMS for the audit history to accurately represent any reasons selected by the driver.
=== Attribute Configuration ===
Attributes against Manifests, Drops and Items can be configured by your Aptean implementation team. Up to {{Warning}} 10 attributes may be defined at every level.
In general, the following is allowed at each level:
* Manifest
** Information derived directly from the trip, such as route code, trailer type, driver, etc.
* Drop
** Information derived from the transport order header, such as the main references, instructions
** Information derived from the customer of the transport order, such as parameters against that customer.
** Any sub-reference held against that transport order.
** Any sub-reference held against the transport order's destination location.
* Item
** Information derived from the order items.
An example is below:
{| class="wikitable apt-searchable"
!Project Name !!Level !!Number !!Source !!Target
|-
|Stapletons ||Drop ||1 ||so.booking_ref ||
|-
|Stapletons ||Drop ||2 ||so.del_point_ref ||
|-
|Stapletons ||Drop ||3 ||dp_flexipod.get_order_val('ORDER','PRICE', ||
|-
|Stapletons ||Drop ||4 || ||
|-
|Stapletons ||Drop ||5 || ||
|-
|Stapletons ||Drop ||6 ||dp_flexipod.get_ref('LOCATION','PERMIT_NUMBER', ||
|-
|Stapletons ||Drop ||7 ||oc.free_text1 ||
|-
|Stapletons ||Drop ||8 ||dp_flexipod.get_ref('LOCATION','UNITARY_AUTHORITY', ||
|-
|Stapletons ||Drop ||9 ||dp_flexipod.get_ref('LOCATION','LICENCE_NUMBER', ||
|-
|Stapletons ||Drop ||10 ||so.total_weight ||
|-
|Stapletons ||Drop ||11 ||so.total_pieces ||
|-
|Stapletons ||Drop ||12 ||oc.pay_on_delivery ||
|-
|Stapletons ||Drop ||13 ||oc.collect_casings ||
|-
|Stapletons ||Drop ||14 || ||
|-
|Stapletons ||Drop ||15 || ||
|-
|Stapletons ||ItemAttributes ||1 ||soi.du_type ||
|-
|Stapletons ||ItemAttributes ||2 ||soi.weight ||
|-
|Stapletons ||ItemAttributes ||3 ||dp_flexipod.get_order_val('ITEM','UNIT_WEIGHT', ||
|-
|Stapletons ||ItemAttributes ||4 ||dp_flexipod.get_order_val('ITEM','UNIT_PRICE', ||
|-
|Stapletons ||Manifest ||1 ||st.route_code ||
|-
|Stapletons ||Manifest ||2 ||st.trailer_type ||
|}




== Sending Trips to FlexiPOD ==
== Sending Trips to FlexiPOD ==
{{Warning}} This has changed
This happens automatically when:
This happens automatically when:
* the trip is set to status "ACCEPTED" or "EN-ROUTE"
* the trip is set to status "ACCEPTED" or "EN-ROUTE"
Line 54: Line 206:


== Actions Taken on Update ==
== Actions Taken on Update ==
Gets updates from FleXipod drops and processes them
Marks message as collected
Stores order references
* TrackingID
* TrackingURL
* JobReportName
Stores signatory and filename if present
* As ord_information
* As References
**  SignedByName
**  SignedByFilename
**  SiteImageFilename
If item details provided:
* Updates stop Actual Arrive and Actual Depart
* If scan_type = 'I'
**  Creates Order Item Reasons from decoded reason code for actions against the drops and items (such as successful delivery, etc).
**  Creates Order Item Reasons from decoded reason code if there are non-conformities
**  Updates item delivered quantities
**  Updates order line quantities
**  Updates POC/POD flag against the order
* If scan_type = 'P'
**  Same for each item in the pallet.
If event_name = 'Pre-Departure'
* Updates SU stop actual arrive


Several general status change messages can be sent to CTMS from FlexiPOD with item level information.
If event_name = 'Depot Depart'
* Updates SU stop actual arrive and actual depart
* Sets the trip status
* Updates items as despatched
* Updates lines as despatched
* Validates the order


=== 105 - Complete/Cancelled ===
If event_name = 'Depot Return'
* Updates the stop actual arrive time and sets the actual depart time to that plus 10 minutes, when no item is specified (i.e. an update just for the stop.
* Updates CL stop actual arrive
* Updates stop actual depart time to the last time of the last item on the order.
* Adds an item reason code for the reason code supplied, which should be set up across both systems
* Updates the item quantity delivered to the quantity in the message
* Validates the order (which may set the order to COMPLETE status)


=== 104 - Items Skipped on Device ===
If event_name = 'End of Trip'
* Adds an item reason code for reason code "SKP" - "Items Skipped on Device"
* Updates CL stop actual arrive and actual depart
* Sets the trip status


=== 103 - Route in Progress ===
For all order updates:
* Adds an item reason code for reason code "WIP" - "Route in Progress"
* Change order status to DELIVERED if anything delivered
* Change order status to FAILED if nothing delivered


=== 102 - Out for Delivery ===
{{Note}} All changes to order are audited.
* Adds an item reason code for reason code "OD" - "Out for delivery"
* Updates the stop actual depart time to the last time of the last item on the order.
* Sets Trip Status to "EN-ROUTE".


=== 101 - Removed from Route ===
* Adds an item reason code for reason code "RM" - "Removed from Route"


[[Category:Interfaces]]
[[Category:Interfaces]]

Latest revision as of 12:51, 17 April 2025

Warning Warning: This is an incomplete guide.


This guide shows how the Aptean Proof of Delivery system (APOD or formerly FleXipod) can be configured to be used from CTMS.

This require configuration as to when messages are sent, how they are formatted (the FleXipod attributes), at what level are messages sent (orders, stops, etc) and what information is expected to be received.


Configuration

System Parameters

Parameter Description Config By
FLEXIPOD Set to Y to indicate the FlexiPod interface is active SYSTEM
FLEXIPOD_ACID Flexipod acid SYSTEM
FLEXIPOD_BREAK_DROPS Flexipod include breaks for the drops in the Add API call (Y/N) SYSTEM
FLEXIPOD_CARRIERS Set to Y indicates the Carrier can control if a trip is sent to FlexiPod SYSTEM
FLEXIPOD_CLIENTNUM FleXipod ClientNum sent in interface SYSTEM
FLEXIPOD_DEPOTS Set to Y indicates the Depot can control if a trip is sent to FlexiPod SYSTEM
FLEXIPOD_DIRECT Set to Y to indicate the FlexiPod interface is direct and not using Route Execution SYSTEM
FLEXIPOD_DROP Determines the Drop level STOP-OMS or ITEM SYSTEM
FLEXIPOD_EXPIRY Sets the expiry date for the manifest as a number of days after the end of the trip. SYSTEM
FLEXIPOD_EXTERNALSYSTEMUPDATE Flexipod process the External System Update messages in the API call (Y/N) SYSTEM
FLEXIPOD_FORCEITEMSCAN Force the items to be scanned separately: 0 to use the ScanLevel or 1 to force the scan by item. SYSTEM
FLEXIPOD_LISTPENDINGMANIFESTS Flexipod process the List Pending Manifest Update messages in the API call (Y/N) SYSTEM
FLEXIPOD_MERGE_DROPS Flexipod merge the orders on the drop in the Add API call (Y/N) SYSTEM
FLEXIPOD_PASSWORD FleXipod Webservice password SYSTEM
FLEXIPOD_PROXY Flexipod proxy server SYSTEM
FLEXIPOD_READDROP Flexipod process the Read Drop messages in the API call (Y/N) SYSTEM
FLEXIPOD_SCAN_LEVEL 1,2 or 3 to indicate line or item level scanning SYSTEM
FLEXIPOD_SCAN_TYPE Contents and items SYSTEM
FLEXIPOD_SIGNATORY Set to Y to store the SignedByName as the actual signatory as information for the order at its collection of delivery location SYSTEM
FLEXIPOD_SPLIT Are orders to be split? SYSTEM
FLEXIPOD_SYSTEM FleXipod SYSTEM ID sent in interface SYSTEM
FLEXIPOD_TPCLIENTNUM FleXipod TPClientNum sent in interface SYSTEM
FLEXIPOD_USERCODE FleXipod webservice usercode SYSTEM
FLEXIPOD_USERNAME FleXipod webservice username SYSTEM
FLEXIPOD_WEBSERVICE Flexipod webservice endpoint URL SYSTEM
FLEXIPOD_WEBSERVICE_TASK Flexipod webservice endpoint URL for Tasks SYSTEM
FLEXIPOD_WEBSERVICE_UI Flexipod webservice endpoint URL SYSTEM
FLEXIPOD_WEBSERVICE_UI_EXEC Flexipod webservice endpoint URL for Route Execution SYSTEM
FLEXIPOD_X_API_KEY Flexipod x-api-key for External System Update messages SYSTEM


Carrier

The FLEXIPOD flag must be enabled when configured by carrier (system parameter FLEXIPOD_CARRIERS) for carriers that require the use of FlexiPOD.


Depot Locations

The FLEXIPOD flag must be enabled when configured by depot (system parameter FLEXIPOD_DEPOTS) for depots that require the use of FlexiPOD.


EDI Processes

FLEXIPOD_OUT

This process sends the triggered manifests to APOD.

  • Flow Type: PROCESS
  • Package Name: PROCESS, DP_FLEXIPOD.PROCESS_FLEXIPOD_OUT
  • Process: i_process_name FLEXIPOD_OUT
  • Interval: 5 minutes

FLEXIPOD_SENDLISTPENDING

This process checks to see if there are any pending updates from the manifests and imports the details.

  • Flow Type: PROCESS
  • Package Name: PROCESS DP_FLEXIPOD.send_listpendingmanifestupdates
  • Process: PROCESS FLEXIPOD_SENDLISTPENDING
  • Interval: 1 minute


Reason Codes and Decodes

A decode of name "FLX_RESULT_CODES" type "REFERENCE" must be configured to map all of the reason codes from APOD into CTMS.

Several ITEM_NON_CON reason codes must be created to map to the APOD reason codes.:

Examples:

APOD CTMS Description At Fault Action Type CBR
1 SD Successful Delivery
10 SD Successful Delivery
2 FV Failed Visit FAILURE Y
3 SD Successful Delivery
4 UD Unsuccessful Delivery FAILURE
5 SC Successful Collection
6 SJ Skipped Job FAILURE Y
7 NR No Longer Required FAILURE
8 PR Payment Refused

Plus any reason codes created in FlexiPOD must be created within TMS for the audit history to accurately represent any reasons selected by the driver.


Attribute Configuration

Attributes against Manifests, Drops and Items can be configured by your Aptean implementation team. Up to Warning Warning: 10 attributes may be defined at every level.

In general, the following is allowed at each level:

  • Manifest
    • Information derived directly from the trip, such as route code, trailer type, driver, etc.
  • Drop
    • Information derived from the transport order header, such as the main references, instructions
    • Information derived from the customer of the transport order, such as parameters against that customer.
    • Any sub-reference held against that transport order.
    • Any sub-reference held against the transport order's destination location.
  • Item
    • Information derived from the order items.


An example is below:

Project Name Level Number Source Target
Stapletons Drop 1 so.booking_ref
Stapletons Drop 2 so.del_point_ref
Stapletons Drop 3 dp_flexipod.get_order_val('ORDER','PRICE',
Stapletons Drop 4
Stapletons Drop 5
Stapletons Drop 6 dp_flexipod.get_ref('LOCATION','PERMIT_NUMBER',
Stapletons Drop 7 oc.free_text1
Stapletons Drop 8 dp_flexipod.get_ref('LOCATION','UNITARY_AUTHORITY',
Stapletons Drop 9 dp_flexipod.get_ref('LOCATION','LICENCE_NUMBER',
Stapletons Drop 10 so.total_weight
Stapletons Drop 11 so.total_pieces
Stapletons Drop 12 oc.pay_on_delivery
Stapletons Drop 13 oc.collect_casings
Stapletons Drop 14
Stapletons Drop 15
Stapletons ItemAttributes 1 soi.du_type
Stapletons ItemAttributes 2 soi.weight
Stapletons ItemAttributes 3 dp_flexipod.get_order_val('ITEM','UNIT_WEIGHT',
Stapletons ItemAttributes 4 dp_flexipod.get_order_val('ITEM','UNIT_PRICE',
Stapletons Manifest 1 st.route_code
Stapletons Manifest 2 st.trailer_type


Sending Trips to FlexiPOD

Warning Warning: This has changed

This happens automatically when:

  • the trip is set to status "ACCEPTED" or "EN-ROUTE"
  • when any changes happen to the trip i.e. orders are added, removed or moved on a trip that is at those statuses.
  • When the driver, carrier or tractor has been added or changed on a trip that is at those statuses.


Actions Taken on Update

Gets updates from FleXipod drops and processes them

Marks message as collected

Stores order references

  • TrackingID
  • TrackingURL
  • JobReportName

Stores signatory and filename if present

  • As ord_information
  • As References
    • SignedByName
    • SignedByFilename
    • SiteImageFilename

If item details provided:

  • Updates stop Actual Arrive and Actual Depart
  • If scan_type = 'I'
    • Creates Order Item Reasons from decoded reason code for actions against the drops and items (such as successful delivery, etc).
    • Creates Order Item Reasons from decoded reason code if there are non-conformities
    • Updates item delivered quantities
    • Updates order line quantities
    • Updates POC/POD flag against the order
  • If scan_type = 'P'
    • Same for each item in the pallet.


If event_name = 'Pre-Departure'

  • Updates SU stop actual arrive

If event_name = 'Depot Depart'

  • Updates SU stop actual arrive and actual depart
  • Sets the trip status
  • Updates items as despatched
  • Updates lines as despatched
  • Validates the order

If event_name = 'Depot Return'

  • Updates CL stop actual arrive

If event_name = 'End of Trip'

  • Updates CL stop actual arrive and actual depart
  • Sets the trip status

For all order updates:

  • Change order status to DELIVERED if anything delivered
  • Change order status to FAILED if nothing delivered

Note Note: All changes to order are audited.

Retrieved from ‘https://calidusassist.adcservices.apteancloud.com/calidus-assist/MTS/index.php?title=FleXipod_Interface&oldid=7781’