Trigger Automations via API
Learning Objectives
After completing this unit, you’ll be able to:
- Review available API requests for Automation Studio.
- Follow best practices for API requests.
Automation Studio allows you to chain together a bunch of activities in the Marketing Cloud Engagement app, but you can also use API requests. Each activity has an external key for reference, as well as the entire automation itself. Let’s dive into your options.
SOAP API and Automation Studio
Marketing Cloud Engagement’s SOAP API gives you options to perform several functions for Automation Studio.
- Create an automation, including all related activities.
- Immediately perform an automation.
- Retrieve the status of an automation already in progress.
- Retrieve the status of a single automation.
- Schedule an existing automation.
- Update an automation.
- Pause an automation.
- Delete an automation.
For example, Alex Driskel from Get Cloudy Consulting could use this SOAP envelope to create an automation that accesses the Sent data view.
If you use the following code, be sure that you replace these two values with your tenant-specific domain and access token values.
{{et_subdomain}}: your tenant-specific subdomain{{dne_etAccessToken}}: your access token
Sample Code: Access the Sent Data View
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<a:Action s:mustUnderstand="1">Create</a:Action>
<a:To s:mustUnderstand="1">https://{{et_subdomain}}.soap.marketingcloudapis.com/Service.asmx</a:To>
<fueloauth xmlns="http://exacttarget.com">{{dne_etAccessToken}}</fueloauth>
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
<Objects xsi:type="Automation">
<Name>System Data Views</Name>
<CustomerKey>DataViews_Automation</CustomerKey>
<AutomationTasks>
<AutomationTask>
<Name>Load Data Views</Name>
<Activities>
<Activity>
<ObjectID>64315dd7-95c6-430d-940e-09f72147f8a1</ObjectID>
<ActivityObject xsi:type="QueryDefinition">
<ObjectID>64315dd7-95c6-430d-940e-09f72147f8a1</ObjectID>
<CustomerKey>DataView_Sent</CustomerKey>
<Name>DataView_Sent</Name>
</ActivityObject>
</Activity>
</Activities>
</AutomationTask>
</AutomationTasks>
<AutomationType>scheduled</AutomationType>
</Objects>
</CreateRequest>
</s:Body>
</s:Envelope>
After Alex’s automation is set, he can schedule the automation to run at a specified time using an API request containing this information.
Sample Code: Schedule the Automation
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<a:Action s:mustUnderstand="1">Schedule</a:Action>
<a:To s:mustUnderstand="1">https://{{et_subdomain}}.soap.marketingcloudapis.com/Service.asmx</a:To>
<fueloauth xmlns="http://exacttarget.com">{{dne_etAccessToken}}</fueloauth>
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<ScheduleRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
<Action>start</Action>
<Schedule>
<Recurrence xsi:type="HourlyRecurrence">
<HourlyRecurrencePatternType>Interval</HourlyRecurrencePatternType>
<HourInterval>24</HourInterval>
</Recurrence>
<RecurrenceType>Hourly</RecurrenceType>
<RecurrenceRangeType>EndOn</RecurrenceRangeType>
<StartDateTime>2021-03-25T20:53:23.2236156-03:00</StartDateTime>
<EndDateTime>2038-03-25T20:53:23.2236156-03:00</EndDateTime>
</Schedule>
<Interactions>
<Interaction xsi:type="Automation">
<ObjectID>a41c4d53-0487-495d-b374-3427cc278fcd</ObjectID>
</Interaction>
</Interactions>
</ScheduleRequestMsg>
</s:Body>
</s:Envelope>
And if Alex needs results quickly, he can immediately perform the automation with a SOAP API request based off of this SOAP envelope.
Sample Code: Perform the Automation
<?xml version="1.0" encoding="UTF-8"?>
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xmlns:a="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:u="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<a:Action s:mustUnderstand="1">Perform</a:Action>
<a:To s:mustUnderstand="1">https://{{et_subdomain}}.soap.marketingcloudapis.com/Service.asmx</a:To>
<fueloauth xmlns="http://exacttarget.com">{{dne_etAccessToken}}</fueloauth>
</s:Header>
<s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<PerformRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI" xmlns:ns2="urn:fault.partner.exacttarget.com">
<Action>start</Action>
<Definitions>
<Definition xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Automation">
<ObjectID>a41c4d53-0487-495d-b374-3427cc278fcd</ObjectID>
</Definition>
</Definitions>
</PerformRequestMsg>
</s:Body>
</s:Envelope>
So why would Alex want to use SOAP API requests to handle this task when he could just get into Marketing Cloud Engagement and use the app to create the automation? The answer depends on the task. API calls are helpful if you’re building custom integrations or tying certain actions tightly to output from other systems. The vast majority of Automation Studio users can get what they need from the Automation Studio app and tie it to either a schedule or an automated file drop from an FTP location. For more specific cases, the SOAP API helps you work those Automation Studio requests into whatever systems you might need.
Right Request, Right Time
The standard advice for Marketing Cloud Engagement API requests apply to Automation Studio requests as well. If you know an automation is going to take a lot of time and resources to perform, try to schedule it when there is less overall activity in your account. Include only necessary information in your requests—and that applies to any queries or scripts you include in your requests. Join us in the next unit as we troubleshoot in Automation Studio.