Receive From Customer Service

This service accepts a request to return a cylinder that is currently with a customer. This is commonly used when receiving in inventory that was returned via common carrier (like UPS or FedEx) and not on your own truck.

Processing Rules

The provided input is validated to ensure that all required fields are present:

  • If the Barcode input is missing, a MISSING_BARCODE error code will be returned.

  • If the LocationCode input is missing, a MISSING_LOCATION error code will be returned.

  • If the UserCode input is missing, a MISSING_USER error code will be returned

  • If the ValidationDateTime input is missing, a MISSING_VALIDATIONDATETIME error code will be returned

The input is then validated to ensure that all provided fields reference valid entities within the database:

  • If the provided UserCode value does not match an existing user's Accounting User Code, a UNKNOWN_USER error code will be returned.

  • If the provided LocationCode value does not match an existing internal location, an UNKNOWN_LOCATION error code will be returned.

  • If the provided Barcode value does not match any existing assets, an UNKNOWN_BARCODE error code will be returned.

  • If the provided Barcode value matches more than one existing asset, a DUPLICATE_CYLINDERS error code will be returned.

If any of the above input validation rules fail, processing is stopped and the corresponding error code is returned.

If the asset is currently at a customer or if the provided input's ContinueThroughErrorsAndSave is set to True, a Receive From Customer record is created for the asset. This record will be tagged as having been entered by the user matching the provided UserCode at the date and time specified in the provided ValidationDateTime. This record will move the asset to the provided internal location if it's not already there.

If the asset is not currently at a customer and the provided input's ContinueThroughErrorsAndSave is set to False, a NOT_AT_CUSTOMER error code will be returned.

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

  1. 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:

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

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

    NOTE

    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 parameters provided to this request. 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.

Request Output

The service will return a standard web service response, and include information on the status of the request. An HTTP status code of '200' indicates that the request was successful. When successful, the service will return an XML document with information about the asset in the body of the HTTP response in the following format:

<ServiceResponse>
<Barcode>1234</Barcode>
<SerialNumber>5678</SerialNumber>
<WirelessAlert>Alert 1</Wireless_Alert>
<ErrorMessage>Not at customerErrorMessage>
</ServiceResponse>

Usage

Production Environment

Test Environment