SOAP API best practices

API User accounts are essential to all integrations. Two different types of API users are available, each with distinct access privileges. Review our Defining an API User article to understand the characteristics of API users and determine which type is right for your environment.

By default, API User (API-only) security levels only are exempted from the Password Expiration Requirement. We recommend that you do not change this setting for any copies of this security level because API users cannot log into the UI to change their password and require the assistance of an Autotask administrator.

IMPORTANT  If the password actually expires, the integration will stop working!

The API User (API-only) system security level provides full system administrator access to Autotask modules, features, and data. However, copies of the system security level can be modified to restrict access to certain modules, features, and data. As a result, the API user with a restricted license would get no response to an API call, even though the data exists in your database.

EXAMPLE  The API user is unable to retrieve an invoice even though the invoice ID exists in your database, because the API user is not assigned to the line of business the invoice is associated with.

Autotask has multiple zones. They are generally allocated geographically, but a customer can be located in any zone. The zone number appears in the customer's Autotask URL.

The Web services and WSDL URLs are specific to the customer's zone. Autotask releases do not occur simultaneously across all zones. For this reason there will be some unavoidable differences between versions of the WSDL. This difference is most noticeable between the localized and English versions.

To avoid problems when you make your code available to customers in multiple zones, do the following:

• To determine the proper zone (and accompanying URL) to use for all API interactions, set up your application so that getZoneInfo() is the first call made. Direct the getZoneInfo call to https://webservices.autotask.net/atservices/1.6/atws.asmx. This call does not require authentication or a tracking identifier.
• If you bind your code to an English language WSDL for development and testing, before you make your code available to users in any localized zone, bind your code to the WSDL for that zone. You can then detect and correct for any differences.

For a list of WSDL and Web Service URLs for important Autotask zones, refer to Autotask API zones and WSDL versions.

Do not use getZoneInfo() to validate that you have the correct username and password for API access. GetZoneInfo does not validate against username or password. It validates against the base URL only.

You can use the entity returned by create() and update() to obtain the Id field content, but do not rely on the rest of the content. Some entity fields cannot be calculated immediately during create and update. In the returned entity , those fields may not be accurate.

If you need to access the entity for information other than the Id, query for the entity after the create/update succeeds.

When constructing queries, be aware that Autotask will return only 500 records at once, sorted by id. If there are over 500 records that meet your criteria, you must create multiple queries where each query filters for id value > the maximum value received in the previous query.

Many API users regularly use API queries to update Autotask data cached in an external system. Cached data is then used by applications, for example, dashboards, that allow users to quickly access selected data. With a maximum return of 500 records at once, users with extensive databases require multiple calls. This option is time intensive and, when traffic volume is high, can tax the API resources.

An alternative to returning all records is to formulate queries to return only records that have changed since the last query. You can do this for selected entities using the LastModifiedDate or LastActivityDate fields.

• LastModifiedDate stores the most recent date and time that the entity was updated or changed.
• LastActivityDate stores both the most recent date and time that the entity was modified, as described for LastModifiedDate, and the most recent date and time that any activity related to the entity occurred. For example, this might include a note or time entry added to the entity.

You can determine if the available fields meets your needs.

Not all entities have these fields exposed. With the exception of the Contact entity, no entity has more than one of the two fields available.

The following table indicates which entities have LastModifiedDate or LastActivityDate fields exposed.

NOTE   The field names for some entities use only Date and others use DateTime. Both names return the same data and it is always a datetime data type.

StatusLastModifiedDate

Three entities include a StatusLastModifiedDate field: Contract Cost, ProjectCost, and TicketCost. The StatusLastModifiedDate field indicates changes to the cost status only , for use with the procurement workflow. These entities do not have an option to determine if/when other fields were modified.

To maintain optimum response time for all users, Autotask sets a limit on the number of external requests allowed per hour between an individual database and the API. Most users will never exceed the threshold. If you do exceed the threshold, your service is temporarily suspended.

You can avoid a service suspension by monitoring your usage. A usage-based latency is added when you reach 50% of allowed calls, and the latency increases when you reach 75% off allowed calls. In addition, you will receive a notification if you approach the threshold. For details on the latency and warning notification, refer to API call threshold.

You can use the getThresholdAndUsageInfo() API Call to learn the threshold for your database and monitor your current usage. Refer to getThresholdAndUsageInfo().

A number of Autotask entities provide an optional "External" field, for example, AllocationCode.ExternalNumber. Our users often utilize values in these fields to associate items with an external numbering system or code. That data is typically required in downstream stages of the user’s business workflow, such as mapping to items in an integrated accounting system. Whether and how these fields are used varies between databases.

As best practice, external integrations should refrain from populating these fields with data generated by the integration. If the integration is creating data in Autotask that does not map directly to an existing entity field, the integration should use a user-defined field for that purpose. Refer to UserDefinedFieldDefinition and UserDefinedFieldListItem.

The ticket entity Source field is not a required field, but it does have a default value. If no source value is provided on create, the field is populated with the default value.

If the customer does not assign a default source, Client Portal becomes the default. All Autotask systems have Client Portal and Insource as sources. The Autotask user can add as many additional sources as they wish.

As best practice, we suggest that you specify a Source to represent your integration. Have your integration users add the source name to their Autotask list of ticket sources ( > Admin > Features & Settings > Service Desk > Sources). Then, your integration can populate Ticket.Source with your source name when creating tickets. This will clearly identify tickets created by your integration. The customer can also use the source name in Autotask workflow rules to manage incoming tickets received from your integration.

To ensure correct date and time conversion via the API, be sure to submit date-time values in the correct format. Refer to SOAP API time data storage and return.

Different languages have different needs. For example, some integrations will search picklist strings for certain string matches to determine the numeric identifier needed to populate into a field. But, system provided picklist string values can change based on the language supported. As best practice, if your integration supports multiple languages, you should be testing each language in a separate sandbox.

You can use URLs to bring up pages in the Autotask UI. But, you have to study the UI and build the URLs, and the URLs can change over time. That's why Autotask provides the ExecuteCommand.

ExecuteCommand uses simple browser-level commands to programmatically access specific pages in Autotask. For example, you can use the Ticket Detail by Ticket Number ExecuteCommand to provide a link to open an Autotask ticket detail. Learn more about ExecuteCommand API.

When an Autotask user has multi-currency enabled, it will likely have an impact on integrations that include quoting, purchasing and any form of billing and financials. Review our Multi-currency articles for information about conditions that apply with the Multi-currency module enabled.

You can use your preferred language to configure your programmatic authentication to the Web Services API. For examples, refer to Sample Code.

If you're working with an entity that has one or more fields with a picklist, you really need to know what's in those picklists. You need getFieldInfo(). Not sure if you can delete an entity? Use getEntityInfo() to find out. User-defined fields are specific to a customer, so to find out anything about them, you need getUDFinfo().

These three API calls, getEntityInfo(), getFieldInfo() or getUDFInfo(), can return just about anything you need to know about an Autotask entity.

• The getEntityInfo() SOAP API call - describes entities and attribute of entities, like whether you can create, update, delete, and or query the entity.
• The getFieldInfo() SOAP API call - describes attributes of all fields on an entity. This is the how to get picklist choices for fields.
• getUDFInfo() - describes attribute of all User Defined Fields (UDF) on an entity. This is the getFieldInfo() for user-defined fields, which are specific to a customer's account.