SOAP Documentation: Getting Started

Overview

The TraceGains SOAP API provides access to your TraceGains Suppliers, Items, data, documents, and system configuration through several SOAP resources. Each SOAP resource targets a specific data set or configuration component in your TraceGains site.


Requesting API Access

You must make a formal request for API access to your Customer Success Manager. Once your TraceGains instance API access has been enabled, you will then have access to generate and manage your API keys and view your API logs.

Use of the TraceGains API is included with every Enterprise subscription, but may require additional license fees for Standard subscriptions. If you are running a Standard TraceGains license please contact your CSM for more information. API resources and methods are marked with an access legend that indicates which TraceGains module licenses are allowed to use that resource method.

API Access Legend: <Subscription Type> | <Supported Modules>

Enterprise Standard | SM SC SPM FM QM


Generating API Keys

Use of the TraceGains SOAP API requires a registered Application Key. You must create an Application Key using the Manage Keys view in a Supplier Management, Supplier Compliance or Quality Managment instance of TraceGains. The Manage Keys view link is accessed from the Configuration menu in a TraceGains instance.

At least 1 Application Key is required to use the TraceGains SOAP API. However, you may create a unique Application Key for each API interface you develop to access your TraceGains instance data.

Notes:

  • A registered API Key can only be used in the environment for which it was created! Developer Sandbox API Keys cannot be used in a live production instance of TraceGains.

Resource WSDL Locations

Each SOAP resource has a specific Web Services Description Language (WSDL) XML file that can be accessed via web browser. The home page of each SOAP resource contains the clickable link Service Description to the resource WSDL in the following text The following operations are supported. For a formal definition, please review the Service Description.

Additional WSDL links are also provided on the documentation page of each SOAP resource.

Notes:

  • All resource WSDL files meet SOAP 1.1 and SOAP 1.2 standards.
  • TraceGains does not provide toolset specific DTD files for any SOAP resource.

Authentication

A call to a SOAP resource method requires a registered Application Key and a valid Session ID, along with any additional parameters required by the method. A Session ID is obtained by making a call to the Login method of the Authentication resource. While a Session ID will expire automatically based on the configuration of the Application Key, TraceGains recommends that you make a call to the Logout method of the Authentication resource to expire a Session ID when it is no longer needed.

Example Authentication Workflow:

  • Call Login method using a valid Application Name and Application Key from a registered API Key.
  • Verify the response element Authenticated is equal to True.
  • Retrieve the SessionId from the Login response and retain for later use.
  • Make one or more calls to additional API methods using the value retained from SessionId.
  • Call Logout method to expire the SessionId retrieved from the original Login response.

Notes:

  • A Session ID is unique to an Application Key and cannot be used with any other Application Key!
  • TraceGains recommends that a Session ID be expired when no longer needed by calling the the Logout method of the Authentication resource.
  • You may configure the default time-to-live value of a Session ID from the Manage Keys view in the TraceGains UI if you would like your sessions to expire quickly without making an additional call to the Logout method.

HTTP Status Codes

All API method responses include a standard HTTP status code in the ResponseCode element of the response.

Notes:

Developers should treat the HTTP Status codes 200 and 202 in a response to indicate a successful SOAP request!

The HTTP Status Code 202 is used to indicate that a request was only partialy successful.

Example: A method call passes 10 attributes but only 9 attributes were updated because the 10th attribute does not exist in your TraceGains instance. The unknown attribute may have been removed or it may not yet exist in your TraceGains instance configuration. In either case, we accept the attribute data we can validate and ignore the 10th attribute. The 202 response serves to indicate that you may have an issue in your interface code, but not one that is currently causing harm to your TraceGains instance data or configuration.

Code Text Description
200 OK Request succesfully received and processed.
202 Accepted Request succesfully received. Entire request may not have been processed succesfully.
400 Bad Request One or more parameters are missing, are of the wrong type or are unknown or invalid.
401 Unauthorized The request was not authorized. May be an unknown or expired Application Key or Session ID or the method call is restricted to a specific TraceGains subscription or licensed module.
404 Not Found We could not find any matching data using the requested criteria.
500 Server Error An unexpected error was thrown. Details on these errors are generally available in the API Logs view in your TraceGains instance.

Protocol Support

All connections to the API must be made using HTTPS over TLS 1.2. The API does not support connections made using HTTP or HTTPS over SSL 2.0, SSL 3.0, TLS 1.0 and TLS 1.1.

Notes:

  • TraceGains will provide support for TLS 1.3 as it becomes available by our cloud infrastructure provider. Once TLS 1.3 is fully supported by the TraceGains API, expect TraceGains to announce end-of-life support for TLS 1.2.

Developer Sandbox

A developer sandbox with your live production data and configuration will be provisioned upon request. For more information regarding the provisioning of your site to the TraceGains sandbox environment, contact your TraceGains Customer Success Manager.

Your sandbox environment includes all resgistered User Accounts that were in your production instance of TraceGains at the time of provisioning. You may login to the environment, request password resets and create new accounts for additional developers in the sandbox instance as necessary.

The TraceGains sandbox instance environment is located here: https://test.TraceGains.net

The TraceGains sandbox API environment is located here: https://api-test.TraceGains.net/v7/soap/authentication.asmx

Notes:

  • There should be no expectation that the sandbox environment is a fully functional production instance of TraceGains!
  • TraceGains will only provision your sandbox environment once and only after a formal request for API Access has been received by your TraceGains Customer Success Manager. Requests for updates to your sandbox data or configuration must be communicated through your TraceGains Customer Success Manager.
  • TraceGains may re-provision the sandbox environment, for all Customers, without notice as product features and updates impact the sandbox environment!
  • Basic services like Email AutoStreaming, eNotifications, Midnight Business Rule processing and others are disabled in all sandbox environments.
  • The sandbox environment is provisioned only for API development and validation only. The environment should not be used to test additional configuration options for your live production instance of TraceGains.
  • TraceGains Support cannot assist you with your Developer Sandbox environment. Your TraceGains Customer Success Manager will provide contact information for TraceGains API Support upon request.
  • Sites in the TraceGains sandbox environment will be deprovisioned, at the discretion of TraceGains, if/when a site has no activity for more than 90 days.

Specification Publishing

The TraceGains API does offer support for managing the Specification Publishing module attribute conigurations. The Business Rules API resource allows for managing the 3 properties IncludeInSpecPublishing, SpecificationName and SpecificationDescription for the BusinessRuleHeader of an Item attribute.

Notes:

  • The Specification Publishing module is a purchased add-on to an enterprise subscription of the TraceGains Supplier Managament module.

Language Support

The TraceGains API only supports the en-US language tag specification. All text returned in the Message element of all SOAP responses will be in English as used in the Unites States.