Please visit our new TrackAbout Knowledge Base at https://supportkb.trackabout.com for the most-up-to-date documentation on TrackAbout and TrackAbout Mobile.
Customer Transaction History Service
Overview
This web service allows you to generate a report outlining all assets that were delivered or returned within a given date range for a given customer. Deliveries and returns are matched up on the same line representing a round trip for the asset.
Service Protocol
TrackAbout has chosen to implement and architect this web service using what is typically referred to as REST style architecture. This is a resource oriented architecture that uses standard HTTP actions (i.e. GET, POST, DELETE, etc...) to manipulate resources exposed as URLs. Standard HTTP Status Codes are used for success and error codes.
More information on REST architecture can be found at the following resources:
Template:Web Service Authentication
Report Parameters
The parameters for the report are provided via query string values. See the #Usage section below for more information on creating the query string. All parameters must have a valid value provided or the web service will return an error code.
| Friendly Name | Query String Name | Description |
|---|---|---|
| Customer ID | custId | The ID of the customer for which the report should be run. |
| Include Departments? | inclDept | True or False value indicating whether departments of the provided customer should also be included in the report. |
| Start Date | startDate | Beginning date of the date range that should be included in the report. |
| End Date | endDate | Ending date of the date range should should be included in the report. |
| Sort Column | sortCol | Numeric value indicating how the resulting data should be sorted. Valid values include:
|
Validations and Restrictions
The following validations are applicable to the parameters provided to this report. If one or more of these validations fail, the web service will return an HTTP error code with a message indicating why validation failed.
- The provided start and end date values must represent valid dates and a valid date range. For example, the end date must come after the start date.
- The provided date range can cover a maximum of three years.
- The provided customer ID must exist within the TrackAbout database.
- The provided sort column number must fall within the allowed values indicated above.
Report Output
The resulting report data will be rendered into a PDF document that will be returned to the caller. The following columns are included in the report:
- Product Code
- Product Description
- Barcode
- Serial Number
- Ship Date
- Expiration Date
- Return Date
- Invoice Number
- Purchase Order Number
- Line Number (sequentially generated line number per record to identify lines and ensure report is complete)
Usage
- Web Service URL: https://www.trackabout.com/ws/CylinderTransactionReport.asmx
- Allowed HTTP Actions: GET
- Input: All parameters are provided in the query string. When creating the query string, use the query string key values specified in the #Report Parameters section above for the corresponding parameter. Note: Be sure to properly URL Encode each parameter value. More information on URL Encoding: Wikipedia: URL Encoding
A note about date/time values: in order to accommodate customers in different locations, all date and time values stored in TrackAbout are stored as Coordinated Universal Time values (UTC). This means that we typically have to perform a time zone conversion of the provided date and time values to be consistent with how the data is stored. To make this easier, we only accept a few very specific date and time formats as outlined below:
- UTC Time - yyyy-MM-ddTHH:mm:ssZ
- Example: 2009-03-04T08:23:12Z would be evaluated as March 4, 2009 at 8:23:12 AM. The 'Z' on the end denotes a 'zero' UTC offset, meaning the provided value has already been adjusted to UTC time. When a value like this is received by this web service no time zone conversion will be performed.
- Local Time with UTC Offset - yyyy-MM-ddTHH:mm:sszzz
- Example: 2009-05-02T13:34:45-05:00 would initially be evaluated as a local time of May 2, 2009 at 1:34:45 PM. The '-05:00' at the end of the string would signal that the provided time has a negative 5 hour offset from UTC time, meaning that 5 hours would be added to the provided local time in order to convert it to UTC.
- Local Time with no Offset - yyyy-MM-ddTHH:mm:ss
- Example: 2009-11-10T09:45:00 would be evaluated as November 10, 2009 at 9:45:00 AM. Since the provided time wasn't denoted as UTC and no offset was provided, the web service will use the timezone at the location known as "headquarters" for your company to convert the provided time to UTC.
Full Example URL for Customer ID = ABC123, Include Departments = false, Start Date = 2009-01-01 12:00:00 AM UTC time, End Date = 20009-12-31 12:00:00 AM UTC time, Sort Column = 1 (Product Code):
https://www.trackabout.com/ws/CylinderTransactionReport.asmx?custId=ABC123&startDate=2009-01-01T00%3a00%3a00Z&endDate=2009-12-31T00%3a00%3a00Z&inclDept=False&sortCol=1
- Output: The resulting report data will be rendered into a PDF file and be returned as binary data in the HTTP response. A 'Content-Disposition' HTTP header will be added with the value 'attachment; filename=<generatedFileName>' where <generatedFileName> will be a unique file name with a sequence number generated from the current system time appended to it.