Action-Based Integration - Revision history

Jgreco at 21:31, 4 November 2021

2021-11-04T21:31:59Z

Lsilverman: /* Message Statuses */

2016-10-21T16:35:48Z

Message Statuses

Lsilverman: /* Message Statuses */

2016-10-21T16:35:37Z

Message Statuses

Jgullickson at 15:55, 12 October 2016

2016-10-12T15:55:29Z

Jwolbert: Created page with "==Overview== What is Action-Based Integration? These are push messages (aka callbacks, webhooks) sent from the trackabout server to a client's listening web service. The clie..."

2016-07-05T02:24:18Z

Created page with "==Overview== What is Action-Based Integration? These are push messages (aka callbacks, webhooks) sent from the trackabout server to a client's listening web service. The clie..."

New page

==Overview==
What is Action-Based Integration?

These are push messages (aka callbacks, webhooks) sent from the trackabout server to a client's listening web service. The client gives us the URL and we POST data to it. The messages are triggered by actions (records) being saved to the site, or other user actions in the AWS. The whole point is to let the client keep another system in sync with changes in trackabout.

== How it Works ==
As of 2014, we introduced a new message format called 'RecordMessage'. This is a single XML format that wraps the various message types shown below. This single message format will unify all of the push integration messages so clients only need to have a single endpoint to accept messages. Previously, each message type had a unique endpoint. This also simplifies the code for record saving, we only need to publish a single message, rather than checking for each type.

==Set up and Configuration ==

You will need to work with TrackAbout Support and Implementation staff to set up this integration format. The main setup will require a URL endpoint. This URL would be supplied to TrackAbout by the customer, and should be set up to accept a POST request with the body containing the RecordMessage XML. The client configuration for this setting is called Record Message POST URL.

'''NOTE:'''The URL endpoint you provide to TrackAbout must support TLS (start with https). TrackAbout does not support non-TLS connections for this integration.

You will also need to provide TrackAbout with credentials to successfully access the URL endpoint you provide.

===Detail vs. Summary Message Types===
Many, though not all, message types have both detail and summary versions. In general, the detail messages will list all the individual assets on the record, while summary messages will list asset count by product code (or whatever makes sense for that action). Clients can choose one or the other depending on what data they need.

=== Supported Actions ===

The following actions can be set up to trigger Action-Based Integration messages:

====Fill====

A fill can kick off several integration messages during and after a fill takes place:

'''Product / Ramp Lot Opened''': If a new lot number is needed, a message is sent indicating the lot number, the asset family and the parent lot information.

'''Product / Ramp Lot Closed''': If a lot number is closed as a result of the fill, a message is sent indicating the lot number, the asset family, the parent lot information, as well as the quantity of each product code filled

'''Hours & Quantities''': When a fill is completed, a message is sent with details of each asset that was filled.

====Fill With Work Order====

Fill with work order works with the above messages, plus the following message:

'''Hours & Quantities''': This message includes information about the work orders filled, including times that assets were sorted and time for filling for each asset on the fill record

====Load Truck====
====Ordered vs. Delivered====
Sent to indicate the number of items loaded on the truck by product code.

====Update Trip====
Sends a note that the trip has been touched.

====Delivery====
TrackAbout will send two different messages, depending on customer requirements:

#'''Final Amend''': Includes product codes matched to order lines at the product code level. Also includes hard goods matched to order lines.
#'''Deliveries update''': Includes details of each asset that was delivered, but not tied to order data. No hard goods currently sent.
Delivery Integration messages can be sent when the action is completed or only when the delivery is verified (Based on a configuration).

Use Empty Product Code For Returned NSAssets In Delivery Integration Messages (UseEmptyProductCodeForReturnedNSAssetsInDeliveryIntegrationMessages): controls whether a full or empty product code is sent in the Summary/Detail message for Delivery. If set to true, an empty product code will be sent for Returned NS Assets. However, this config will be overridden if another config (RecordMessagesAlwaysUseFullProductCode) is set to true. In this case, a full product code will be sent.

Split Delivery and Return lines for same product code? (SplitDeliveryAndReturnLinesForSameProductCode): When True, while building the integration message, the delivery direction (ship or return) will be included in the match of assets to line items on the order. This is only effective when the order contains separate line items for assets for the same product to be shipped and returned. Those separate line items will have the same product code and billing code but one will have a non-zero delivery quantity and zero return quantity and the other a zero delivery quantity and non-zero return quantity. This also affects adhoc deliveries, meaning that if a delivery is made where an order doesn't exist, the integration message will contain separate lines for shipped and returned assets for the same product code.
Exclude Asset Expiration Date from Delivery Integration on Empty Returns (ExcludeAssetExpirationDatefromDeliveryIntegrationOnEmptyReturns): If set to True, asset expiration dates will not be included in delivery integration detail messages for assets that are being returned as empty. This does not affect the generated data for assets that are being delivered (full or emtpy) or returned as full. This was done for Linde Panstore.
Delivery integration messages are also subject to the client config "Only Send Delivery Message During Initial Record Save". When this config is set true, a delivery integration message will only be sent the first time the record is saved (not for updates).

====Accounting Adjustments====

Integration messages for Accounting Adjustments include
#Mark Not Lost
#Discovery Period Adjustment
#Clear Customer Balance
#Set Customer Balance records
#Not-Scanned Assets Removal

For ALL accounting adjustment messages, if there are negative values for delivered or returned, we convert them to positive and flip around the "direction" - so a negative delivery becomes a positive return, and vice versa. We sum these quantities such that negative delivers will cancel out negative returns.

We explicitly send full product codes as part of accounting adjustment integration messages even if the client is tracking empty product codes.

====Unload Truck====
We send a count of cylinders by product code and empty / full status.

====Update Trip====
Sends a note that the trip has been touched.

====Resolve Truck Load====
(AWS action only)

====Bundle/Pack Actions====

====Change of Service (Reclassify)====

====Sort====
Both Sorting Assets and Sorting Containers

====Vendor Receive (3rd party fill)====

====Analysis====
You may choose to receive messages for every analysis record or only when a analysis is completed.

====Driver Trip Report====
An integration message will only send when a trip is reconciled on the TrackAbout website.

===Integration Message Reporting===

Integration Messages can be tracked on the TrackAbout website by way of the [https://www.trackabout.com/clt/production/integrationMessages.aspx Integration Messages] report

====Message Statuses ====

Message Statuses:

0 = New
1 - Sending
2 = Sent (Success) (Depends on confirmation from the recipient system)
3 = Error (Means that TA sent the message and received no confirmation of receipt from the recipient system)
4 = Failed (Means TA did not send the message for some reason)
5 = Retry

@@ Line 2: / Line 2: @@
 What is Action-Based Integration?
-These are push messages (aka callbacks, webhooks) sent from the trackabout server to a client's listening web service. The client gives us the URL and we POST data to it. The messages are triggered by actions (records) being saved to the site, or other user actions in the AWS. The whole point is to let the client keep another system in sync with changes in trackabout.
+These are push messages (aka callbacks, webhooks) sent from the TrackAbout server to a client's listening web service. The client gives us the URL and we POST data to it. The messages are triggered by actions (records) being saved to the site, or other user actions in the AWS. The whole point is to let the client keep another system in sync with changes in TrackAbout.
 == How it Works ==
@@ Line 10: / Line 10: @@
 ==Set up and Configuration ==
-You will need to work with TrackAbout Support and Implementation staff to set up this integration format.  The main setup will require a URL endpoint. This URL would be supplied to TrackAbout by the customer, and should be set up to accept a POST request with the body containing the RecordMessage XML. The client configuration for this setting is called Record Message POST URL.
+You will need to work with TrackAbout Support and Implementation staff to set up this integration format. The main setup will require a URL endpoint. This URL would be supplied to TrackAbout by the customer, and should be set up to accept a POST request with the body containing the RecordMessage XML. The client configuration for this setting is called Record Message POST URL.
-'''NOTE:'''The URL endpoint you provide to TrackAbout must support TLS (start with https). TrackAbout does not support non-TLS connections for this integration.
+'''NOTE:''' The URL endpoint you provide to TrackAbout must support TLS (in other words, the endpoint URL must begin with https). TrackAbout does not support non-TLS connections for this integration.
 You will also need to provide TrackAbout with credentials to successfully access the URL endpoint you provide.
@@ Line 21: / Line 21: @@
 ===Detail vs. Summary Message Types===
-Many, though not all, message types have both detail and summary versions. In general, the detail messages will list all the individual assets on the record, while summary messages will list asset count by product code (or whatever makes sense for that action). Clients can choose one or the other depending on what data they need.
+Many, though not all, message types have both detail and summary versions. In general, detail messages will list all the individual assets on the record, while summary messages will list asset count by product code (or whatever makes sense for that action). Clients can choose one or the other depending on what data they need.
@@ Line 34: / Line 34: @@
 '''Product / Ramp Lot Opened''': If a new lot number is needed, a message is sent indicating the lot number, the asset family and the parent lot information.
-'''Product / Ramp Lot Closed''': If a lot number is closed as a result of the fill, a message is sent indicating the lot number, the asset family, the parent lot information, as well as the quantity of each product code filled
+'''Product / Ramp Lot Closed''': If a lot number is closed as a result of the fill, a message is sent indicating the lot number, the asset family, and the parent lot information, as well as the quantity of each product code filled.
 '''Hours & Quantities''': When a fill is completed, a message is sent with details of each asset that was filled.
@@ Line 42: / Line 42: @@
 Fill with work order works with the above messages, plus the following message:
-'''Hours & Quantities''': This message includes information about the work orders filled, including times that assets were sorted and time for filling for each asset on the fill record
+'''Hours & Quantities''': This message includes information about the work orders filled, including the times that assets were sorted and the filling time for each asset on the fill record.
 ===Load Truck===
@@ Line 56: / Line 56: @@
 #'''Final Amend''': Includes product codes matched to order lines at the product code level. Also includes hard goods matched to order lines.
 #'''Deliveries update''': Includes details of each asset that was delivered, but not tied to order data. No hard goods currently sent.
-Delivery Integration messages can be sent when the action is completed or only when the delivery is verified (Based on a configuration).
+Delivery Integration messages can be sent when the action is completed or only when the delivery is verified (based on a configuration).
 Use Empty Product Code For Returned NSAssets In Delivery Integration Messages (UseEmptyProductCodeForReturnedNSAssetsInDeliveryIntegrationMessages): controls whether a full or empty product code is sent in the Summary/Detail message for Delivery. If set to true, an empty product code will be sent for Returned NS Assets. However, this config will be overridden if another config (RecordMessagesAlwaysUseFullProductCode) is set to true. In this case, a full product code will be sent.
 Split Delivery and Return lines for same product code? (SplitDeliveryAndReturnLinesForSameProductCode): When True, while building the integration message, the delivery direction (ship or return) will be included in the match of assets to line items on the order. This is only effective when the order contains separate line items for assets for the same product to be shipped and returned. Those separate line items will have the same product code and billing code but one will have a non-zero delivery quantity and zero return quantity and the other a zero delivery quantity and non-zero return quantity. This also affects adhoc deliveries, meaning that if a delivery is made where an order doesn't exist, the integration message will contain separate lines for shipped and returned assets for the same product code.
-Exclude Asset Expiration Date from Delivery Integration on Empty Returns (ExcludeAssetExpirationDatefromDeliveryIntegrationOnEmptyReturns): If set to True, asset expiration dates will not be included in delivery integration detail messages for assets that are being returned as empty. This does not affect the generated data for assets that are being delivered (full or emtpy) or returned as full. This was done for Linde Panstore.
-Delivery integration messages are also subject to the client config "Only Send Delivery Message During Initial Record Save". When this config is set true, a delivery integration message will only be sent the first time the record is saved (not for updates).
+Exclude Asset Expiration Date from Delivery Integration on Empty Returns (ExcludeAssetExpirationDatefromDeliveryIntegrationOnEmptyReturns): If set to True, asset expiration dates will not be included in delivery integration detail messages for assets that are being returned as empty. This does not affect the generated data for assets that are being delivered (full or empty) or returned as full. This was done for Linde Panstore.
 ===Accounting Adjustments===
-Integration messages for Accounting Adjustments include
+Integration messages for Accounting Adjustments include:
 #Mark Not Lost
 #Discovery Period Adjustment
@@ Line 73: / Line 75: @@
 #Not-Scanned Assets Removal
-For ALL accounting adjustment messages, if there are negative values for delivered or returned, we convert them to positive and flip around the "direction" - so a negative delivery becomes a positive return, and vice versa. We sum these quantities such that negative delivers will cancel out negative returns.
+For ALL accounting adjustment messages, if there are negative values for delivered or returned, we convert them to positive and flip around the "direction" -- so a negative delivery becomes a positive return, and vice versa. We sum these quantities such that negative delivers will cancel out negative returns.
 We explicitly send full product codes as part of accounting adjustment integration messages even if the client is tracking empty product codes.
 ===Unload Truck===
-We send a count of cylinders by product code and empty / full status.
+We send a count of cylinders by product code and empty/full status.
 ===Update Trip===

@@ Line 110: / Line 110: @@
 = New
-- Sending
+= Sending
 = Sent (Success) (Depends on confirmation from the recipient system)
 = Error (Means that TA sent the message and received no confirmation of receipt from the recipient system)
 = Failed (Means TA did not send the message for some reason)
 = Retry

@@ Line 15: / Line 15: @@
 You will also need to provide TrackAbout with credentials to successfully access the URL endpoint you provide.
 ===Detail vs. Summary Message Types===
 Many, though not all, message types have both detail and summary versions. In general, the detail messages will list all the individual assets on the record, while summary messages will list asset count by product code (or whatever makes sense for that action). Clients can choose one or the other depending on what data they need.
-=== Supported Actions ===
 The following actions can be set up to trigger Action-Based Integration messages:
-====Fill====
+===Fill===
 A fill can kick off several integration messages during and after a fill takes place:
@@ Line 33: / Line 38: @@
 '''Hours & Quantities''': When a fill is completed, a message is sent with details of each asset that was filled.
-====Fill With Work Order====
+===Fill With Work Order===
 Fill with work order works with the above messages, plus the following message:
@@ Line 39: / Line 44: @@
 '''Hours & Quantities''': This message includes information about the work orders filled, including times that assets were sorted and time for filling for each asset on the fill record
-====Load Truck====
+===Load Truck===
 ====Ordered vs. Delivered====
 Sent to indicate the number of items loaded on the truck by product code.
-====Update Trip====
+===Update Trip===
 Sends a note that the trip has been touched.
-====Delivery====
+===Delivery===
 TrackAbout will send two different messages, depending on customer requirements:
@@ Line 59: / Line 64: @@
 Delivery integration messages are also subject to the client config "Only Send Delivery Message During Initial Record Save". When this config is set true, a delivery integration message will only be sent the first time the record is saved (not for updates).
-====Accounting Adjustments====
+===Accounting Adjustments===
 Integration messages for Accounting Adjustments include
@@ Line 72: / Line 77: @@
 We explicitly send full product codes as part of accounting adjustment integration messages even if the client is tracking empty product codes.
-====Unload Truck====
+===Unload Truck===
 We send a count of cylinders by product code and empty / full status.
-====Update Trip====
+===Update Trip===
 Sends a note that the trip has been touched.
-====Resolve Truck Load====
+===Resolve Truck Load===
 (AWS action only)
-====Bundle/Pack Actions====
+===Bundle/Pack Actions===
-====Change of Service (Reclassify)====
+===Change of Service (Reclassify)===
-====Sort====
+===Sort===
 Both Sorting Assets and Sorting Containers
-====Vendor Receive (3rd party fill)====
+===Vendor Receive (3rd party fill)===
-====Analysis====
+===Analysis===
 You may choose to receive messages for every analysis record or only when a analysis is completed.
-====Driver Trip Report====
+===Driver Trip Report===
 An integration message will only send when a trip is reconciled on the TrackAbout website.
-===Integration Message Reporting===
+==Integration Message Reporting==
 Integration Messages can be tracked on the TrackAbout website by way of the [https://www.trackabout.com/clt/production/integrationMessages.aspx Integration Messages] report
-====Message Statuses ====
+===Message Statuses ===
 Message Statuses: