Warning
WARNING: The TrackAbout MetaWiki has been deprecated and is no longer being updated. Please visit our new TrackAbout Knowledge Base at https://supportkb.trackabout.com for the most-up-to-date documentation on TrackAbout and TrackAbout Mobile.

Action-Based Integration

From TrackAbout MetaWiki
Jump to navigation Jump to search

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

Here are the record message xsd(s) you will use for this type of integration. File:RecordMessageResponse.zip


Detail vs. Summary Message Types

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.


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

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 the times that assets were sorted and the filling time 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:

  1. Final Amend: Includes product codes matched to order lines at the product code level. Also includes hard goods matched to order lines.
  2. 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 empty) 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" setting. 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:

  1. Mark Not Lost
  2. Discovery Period Adjustment
  3. Clear Customer Balance
  4. Set Customer Balance records
  5. 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 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