Fill and Assign to Orders Service

This service creates Fill Records for the assets specified in the input document and assigns these assets to the Orders specified.

Service Protocol: REST

This web service uses a REST or RESTful style protocol. This is an HTTP resource-oriented architecture that uses standard HTTP actions (e.g. GET, POST, DELETE) to manipulate resources exposed as URLs. Standard HTTP Status Codes are used for success and error codes.

More information on REST can be found at the following resources:

Service Authentication

The HTTP request must have Basic Authentication credentials included. We strongly recommend that all web service requests be made over SSL (HTTPS).

More information on HTTP Basic Authentication can be found at the following resources:

TrackAbout will provide you with a dedicated user account to use when making web service requests.

Troubleshooting Service Authentication/Authorization Issues

When calling a web service, TrackAbout will return a "403 Access Denied" error if there are any issues authenticating the request. These errors can occur under one or more of the following circumstances:

  1. The authentication header is missing or not formatted correctly. To correct this, review the links on HTTP Basic Authentication above and ensure that the application you are using to call the web service is building the authorization header correctly.

  2. The username and/or password specified in the authentication header is incorrect or the user does not have the permissions needed invoke web services. If you have both a production and test instance of TrackAbout it's important to remember that they each have a distinct set of users and login credentials; a username and password that works in the production environment will not necessarily work in the client test environment and vice-versa. To verify and/or correct this:

  • Login to the TrackAbout website for the environment against which you are trying to invoke the web service and go to the "Internal Users" page. Verify that the username you are using exists.

  • If the username does not yet exist in the environment that you are trying to use, contact TrackAbout support to have a new web service user created for that environment.

  • If the username does exist in that environment, verify that it has 'Web Service' (or something similar) listed in its Roles. The TrackAbout support team can assist in verifying whether or not the user in question has the needed web service permissions.

  • If the username exists in that environment and the it has the needed web service permissions, then it's likely that the password being provided is not correct. You can use the Internal Users page to edit the user in question and set a new password for it.

    If you change the password for a web service user, you could end up causing issues for other automated processes you're using to make web service calls using that same user. If you're storing the credentials for that user in any external applications that make automated calls into TrackAbout web services you'll need to update the password that those applications are using accordingly.

Service Metadata

TrackAbout creates Web Application Description Language (WADL) documents for all web services that make use of REST architecture. The WADL for a service is accessible via the web service's URL with the word 'meta' appended as a query string parameter. For example, to access the WADL for the simple 'Echo' web service, you would use the following URL: https://www.trackabout.com/ws/Echo.asmx?meta

You can also specify a particular version of a web service to retrieve metadata for by including the major, minor, and revision numbers of the desired version in the query string. For example, to get the WADL for version 2.0.0 of the 'Echo' service, the URL becomes: https://www.trackabout.com/ws/Echo.asmx?v2.0.0&meta

More information on WADL can be found at the following resources:

Web Application Description Language

Standard Service Parameters

The following standard web service parameters are available for this RESTful web service. These parameters are optionally provided via the querystring of the URL used to access the service.

Friendly Name Query String Name Description
Retrieve Metadata meta When this parameter is provided, the service will return its WADL document instead of doing the normal processing.
Use Encryption e The presence of this parameter enables request and response payload encryption using public/private X.509 certificates. Certificates must be exchanged and configured in advance of using this parameter. This encryption is separate from standard HTTPS/SSL encryption. Both can be used together.
Use Specific Version vX.X.X Specifies the version of the service being called. For example, the parameter value 'v2.2.5' specifies that Version 2.2.5 should be used.
Use Gzip Compression gz Indicates that gzip compression should be used for the response.
Use Zip Compression zip Indicates that zip compression should be used for the response.
Use Bz2 Compression bz2 Indicates that bz2 compression should be used for the response.

Other Service Parameters

In addition to the standard service parameters, this service also accepts the following parameters:

Friendly Name Query String Name Description
Skip Auto Verify skipAutoVerify 'True' or 'False' value indicating whether or not the service should automatically verify any accounting adjustment records that may have been created in the process of performing the cylinder validation. This is an optional parameter and will default to 'false' if not provided. This means that, by default, any request to this service will automatically verify account adjustment records that get created.

Validations and Restrictions

The following validations are applicable to the data and parameters provided to this service. If one or more of these validations fail, the web service will return a response status code and error message that indicates the source of the failure.

  • The username and password provided must be valid.

  • The XML submitted must conform to the expected schema as outlined in the service metadata.

Processing Rules

There are currently three different versions of this web service. By default, version 1 is used. Version 2 and Version 3 can be targeted by specifying the 'version' query string parameter as denoted in the 'Standard Service Parameters' above. All versions apply processing rules to locate a single asset matching the provided bar code and serial number. The rules applied differ between the versions.

Version 1 and 2 Rules

Version 1 and 2 of the web service use the standard asset resolution process when trying to locate assets for a provided bar code and serial number. These are the same rules that are applied when an asset is scanned via a hand held device or a record is created by entering bar codes and serial numbers manually through the website. It's important to note that this approach can lead to three potential outcomes:

  • A single asset is found, and that asset is attached to the 'Fill' record that is created by the web service.

  • No matching asset is found, and the creation of the 'Fill' record results in a new asset being created using the provided bar code and serial number.

  • One or more partially matching assets are found and the 'Fill' record is created with an asset collision. This collision will need to be resolved manually via the website.

Version 3 Rules

Version 3 of this web service implements a special set of processing rules for locating assets using the provided bar code and serial number. The asset database keeps a record of each time the bar code of an asset is changed. Version 3 of the web service will search through both current and previous bar codes when attempting to find the matching asset. Only an asset that matches on both the provided bar code and serial number will be considered a match, though the matching bar code does not have to be the current bar code of the asset. If a single matching asset is found, that asset is used and will be attached to the 'Fill' record. If no asset is found or multiple assets are found, the asset will not be attached to the record. Unlike versions 1 and 2 of the web service, version 3 will not attempt to create a 'Fill' record unless at least one asset can be successfully resolved using this special set of processing rules.

Request Output

The service will return a standard web service response, and include information on the status of the request. The information in the response will also include an indication of the service version and the status of the request (error codes and messages). When all provided data is processed without any errors, the service returns an HTTP status code of 200. When one or more processing errors are encountered the web service will return those error messages. The format of the error output differs between the different versions of the service. See the WADL for the target version for details.

This service uses the following error codes to denote processing issues that were encountered during the web service request. The 'Category' column in the table below refers to the four categories that errors from this web service fall under:

  • General - These are errors that are not directly attributable to any specific element of the data that was provided in the web service request. For example, an issue with validating the provided XML against the proper schema would fall under this category.

  • Order Fill - These are errors that originate due to an issue with the top-level order fill data element. Unless otherwise noted, these errors will result in the entire 'Order Fill' not being processed.

  • Asset Line - These are errors that originate due to an issue with one of the provided asset line data elements. Unless otherwise noted, these errors will result in all 'Filled Asset' elements beneath this Asset Line to not be processed.

  • Filled Asset - These are errors that originate due to an issue with one of the provided filled asset data elements. Unless otherwise noted, these errors will result in that filled asset element not being processed.

Error Code Error Category Error Description Applies to Version(s) Notes
1 General Unexpected Error All This error is used when an unexpected error caused an issue with the processing. This can be related to a technical (e.g. network or database) issue.
2 Order Fill Unknown Location All This error indicates that the 'Location Id' value in one of the provided Order Fill elements did not match any location in the database.
3 Order Fill Unknown Customer All This error indicates that the 'Customer Number' value in one of the provided Order Fill elements did not match any customers in the database.
4 Asset Line Unknown Product Code All This error indicates that one of the 'Product Code' values in one of the provided Asset Line elements was not found in the database, and that the web service was unable to create that product code on the fly. Note that while this error stems from the Asset Line element, any single instance of this error will result in the entire parent Order Fill element not being processed.
5 Order Fill Invalid Lot Number All This error indicates that one of the 'Lot Number' values provided failed the lot number validation logic that is configured for your database. Depending on the version of the web service being used, the 'lot number' field can be sent in either the 'Asset Line' or 'Filled Asset' element. Note that while this error stems from the Filled Asset or Asset Line elements, any single instance of this error will result in the entire parent Order Fill element not being processed.
6 Order Fill Missing Order All This error indicates that the provided 'Order Number' did not match any existing order in the database. Note that this error does not halt processing on the Order Fill in which it occurs. Due to timing issues it's possible that this web service request can come in prior to the actual order data, so the web service will continue processing this data even if the order does not year appear in the database.
7 Filled Asset Missing Asset All This error indicates that the web service was unable to locate a single asset in the database matching the provided bar code and serial number.
8 Filled Asset Duplicate Assets All This error indicates that multiple assets were found using the provided bar code and serial number or that the web service was unable to find a single asset that appeared to be a perfect match for the provided bar code and serial number.
9 Order Fill Fill Date Conflict All This error indicates that there is already a record in the database for one of the provided assets with the exact same date and time as the provided 'Fill Date'.
10 Order Fill Fill Date Too Far In Past All This error indicates that the provided 'Fill Date' is too far in the past.
11 Order Fill Fill Date Too Far In Future All This error indicates that the provided 'Fill Date' is too far in the future.
12 Filled Asset Asset Matched On Old Bar Code 3 This error indicates that the provided bar code and serial number were successfully matched to a single asset, but that the web service had to look at previously used bar codes in order to make that match. Note that this error does not halt processing and that the fill record will continue to be created using the found asset.
13 Filled Asset Missing Bar Code and Serial Number 3 This error indicates that the filled asset element was missing both a bar code and serial number. At least one of these values must be provided for each filled asset element.

Usage

Production Environment

Test Environment