Batching of SOAP API calls
IMPORTANT The SOAP API entered a limited enhancement phase in Q4 2020. Access to version 1.6 will eventually be deactivated. At this time, there is no end-of-lifecycle date.
When an integration requires higher volumes of creates and updates, you may want to consider doing batch creates or updates to improve efficiency and reduce the number of API calls. Using batch processing has been effective in improving performance of integrations that need to pull in or update large volumes of records like an import type process.
IMPORTANT Call batching is not available for the REST API at this time.
NOTE Any batch call must be 200 or less entities per call.
For a single entity and a single action (create(), update() or delete()), you may include multiple sets of the <Entity></Entity> tags to be acted upon in a single SOAP XML request and receive a single response. This can provide performance gains over separate Web Service calls for each action, since you do not incur any overhead for a separate request, response and the authentication that need to occur with separate requests.
IMPORTANT Error handling must be thought through as a single call essentially wraps all the updates into a single transaction, so that if any single entity causes an error response, the entire set is not saved to the database.
There are some practical limitations to be aware of in your program design, and you should not include large numbers of entities in a single call. The actual number can vary, depending on the entity and the action, and best practice is to design the number of entity sets to include in a single call as something you can adjust and test with different scenarios. Too many entities in a single request may cause timeout issues and database contention with other system activity like user interface or other integrations.
Below are two examples of a batch update of Contacts and batch create of Ticket Notes.
Example 1 - Update of two contacts
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<AutotaskIntegrations xmlns="http://autotask.net/ATWS/v1_6/">
<IntegrationCode>[substitute tracking identifier here]</IntegrationCode>
</AutotaskIntegrations>
</soap:Header>
<soap:Body>
<update xmlns="http://autotask.net/ATWS/v1_6/">
<Entities>
<Entity xsi:type="Contact" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<AccountID>201</AccountID>
<Active>1</Active>
<AddressLine>7505 Commercial Dr.</AddressLine>
<BulkEmailOptOut>False</BulkEmailOptOut>
<City>New Hartford</City>
<CreateDate>2017-03-17T10:02:38.1130000</CreateDate>
<EMailAddress>jnobody@autotask.com</EMailAddress>
<FirstName>John</FirstName>
<id>30682897</id>
<LastActivityDate>2017-03-17T13:39:54.0000000</LastActivityDate>
<LastModifiedDate>2017-03-17T13:39:54.6530000</LastModifiedDate>
<LastName>Nobody</LastName>
<Notification>True</Notification>
<Phone>540-555-0191</Phone>
<PrimaryContact>True</PrimaryContact>
<SolicitationOptOut>False</SolicitationOptOut>
<State>NY</State>
<SurveyOptOut>False</SurveyOptOut>
<ZipCode>13413</ZipCode>
<UserDefinedFields>
<UserDefinedField>
<Name>Alternate Email</Name>
<Value>jnobody@datto.com</Value>
</UserDefinedField>
</UserDefinedFields>
</Entity>
<Entity xsi:type="Contact" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<AccountID>259</AccountID>
<Active>1</Active>
<AlternatePhone>5183221504</AlternatePhone>
<BulkEmailOptOut>False</BulkEmailOptOut>
<Country>United States</Country>
<CountryID>237</CountryID>
<CreateDate>2018-08-10T15:32:12.4170000</CreateDate>
<EMailAddress>jsomebody@autotask.com</EMailAddress>
<FirstName>John</FirstName>
<id>30682914</id>
<LastActivityDate>2018-08-10T15:32:12.4170000</LastActivityDate>
<LastModifiedDate>2018-08-10T15:32:12.1800000</LastModifiedDate>
<LastName>Somebody</LastName>
<Notification>True</Notification>
<Phone>5183221504</Phone>
<PrimaryContact>True</PrimaryContact>
<SolicitationOptOut>False</SolicitationOptOut>
<SurveyOptOut>False</SurveyOptOut>
<UserDefinedFields>
<UserDefinedField>
<Name>Customer Contact</Name>
<Value>Yes</Value>
</UserDefinedField>
</UserDefinedFields>
</Entity>
</Entities>
</update>
</soap:Body>
</soap:Envelope>
Example 2 - Create of four ticket notes
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<AutotaskIntegrations xmlns="http://autotask.net/ATWS/v1_5/">
<IntegrationCode>[substitute tracking identifier here]</IntegrationCode>
</AutotaskIntegrations>
</soap:Header>
<soap:Body>
<create xmlns="http://autotask.net/ATWS/v1_5/">
<Entities>
<Entity xsi:type="TicketNote" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CreatorResourceID>30686632</CreatorResourceID>
<Description>BATCH NOTE 1</Description>
<NoteType>1</NoteType>
<Publish>1</Publish>
<TicketID>34976</TicketID>
<Title>BATCH 1</Title>
</Entity>
<Entity xsi:type="TicketNote" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CreatorResourceID>30686632</CreatorResourceID>
<Description>BATCH NOTE 2</Description>
<NoteType>1</NoteType>
<Publish>1</Publish>
<TicketID>34976</TicketID>
<Title>BATCH 2</Title>
</Entity>
<Entity xsi:type="TicketNote" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CreatorResourceID>30686632</CreatorResourceID>
<Description>INTERNAL BATCH NOTE 1</Description>
<NoteType>1</NoteType>
<Publish>2</Publish>
<TicketID>34976</TicketID>
<Title>INTERNAL BATCH 1</Title>
</Entity>
<Entity xsi:type="TicketNote" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CreatorResourceID>30686632</CreatorResourceID>
<Description>INTERNAL BATCH NOTE 2</Description>
<NoteType>1</NoteType>
<Publish>2</Publish>
<TicketID>34976</TicketID>
<Title>INTERNAL BATCH 2</Title>
</Entity>
</Entities>
</create>
</soap:Body>
</soap:Envelope>
