Subscribe to Automation Studio notifications via SOAP API

If you have used Automation Studio to build workflows on autopilot, you are certainly aware of the importance of monitoring. Checking manually the execution status of every automation in your account is tedious and exhausting. Sometimes, you need to be notified in real time so you can fix eventual issues. That is why having email notifications enabled on your automations is necessary.

There are two types of notifications to which you can subscribe on automation settings:

  • Error or skipped run: you will receive an email if the automation’s execution fails or is skipped
  • Run Completion: you will receive an email once the automation’s run completes.

Keep in mind that at this moment, the only official way of interacting with Automation Studio via API is through SOAP. I’m saying “official” because there are actually some undocumented, but very limited, REST endpoints that can be used to play with Automation Studio. Let me know in the comments if you are interested.

Therefore, if we check the official SOAP documentation, we will see that creating an automation along with activities and email notifications in its settings is pretty easy and straightforward. However, if we look closer, we will find a comment on the notification tag saying: DOES NOT WORK. But we are not going to accept this for an answer, aren’t we?

This is the SOAP request sample from the documentation to create an automation: [see code snippet on Github]

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:wsa="http://schemas.xmlsoap.org/ws/2004/08/addressing" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<soapenv:Header>
<wsse:Security soapenv:mustUnderstand="1">
<wsse:UsernameToken>
<wsse:Username>username</wsse:Username>
<wsse:Password>password</wsse:Password>
</wsse:UsernameToken>
</wsse:Security>
</soapenv:Header>
<soapenv:Body>
<CreateRequest xmlns="http://exacttarget.com/wsdl/partnerAPI">
<Options/>
<Objects xsi:type="Automation">
<Client>
<ID>1234567</ID>
</Client>
<Name>AUT_ONEOFF</Name>
<CustomerKey>AUT_ONEOFF</CustomerKey>
<Description>AUT_ONEOFF</Description>
<!–<CategoryID>74052</CategoryID>–>
<!–<Notifications> DOES NOT WORK
<Notification>
<Address>swhitmore@salesforce.com</Address>
<NotificationType>-1</NotificationType>
</Notification>
</Notifications>–>
<AutomationTasks>
<AutomationTask>
<PartnerKey xsi:nil="true"/>
<ObjectID xsi:nil="true"/>
<Name>Task 1</Name>
<Activities>
<Activity>
<PartnerKey xsi:nil="true"/>
<ObjectID>c7ccca24-4567-4317-b8d0-3874d69c130c</ObjectID><!– ObjectID of Query –>
<Name>Query 1</Name><!– Name of Activity –>
<!–<Definition>
<PartnerKey xsi:nil="true"/>
<ObjectID xsi:nil="true"/>
</Definition>–>
<ActivityObject xsi:type="QueryDefinition">
<PartnerKey xsi:nil="true"/>
<ObjectID>c7ccca24-4567-4317-b8d0-3874d69c130c</ObjectID><!– ObjectID of Query –>
<CustomerKey>546012e7-4438-4526-9e6c-5ec73939848b</CustomerKey><!– CustomerKey of Query –>
<Name>BrowseAbandon_US_Unica_Sendable_Audience_Approved</Name><!– Name of Query –>
</ActivityObject>
</Activity>
</Activities>
</AutomationTask>
</AutomationTasks>
<AutomationType>scheduled</AutomationType>
</Objects>
</CreateRequest>
</soapenv:Body>
</soapenv:Envelope>

To find the source of the problem, we should get into the tags responsible for adding email notifications to the settings. In this example, they are using a wrong value for the NotificationType tag in addition to a missing ChannelType tag.

NotificationType should be either “Complete” OR “Error” and definitely not “-1”. And ChannelType should be equal to 1.

The correct SOAP request to create an automation along with a “Complete” notification email should look like this: [see code snippet on Github]

<?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>
<fueloauth xmlns="http://exacttarget.com">{{access_token}}</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">
<Options/>
<Objects xsi:type="Automation">
<Client>
<ID>50000xxxx</ID>
</Client>
<Name>AUT_ONEOFF4</Name>
<CustomerKey>AUT_ONEOFF4</CustomerKey>
<Description>AUT_ONEOFF4</Description>
<!–<CategoryID>74052</CategoryID>–>
<Notifications>
<Notification>
<ChannelType>1</ChannelType>
<NotificationType>Complete</NotificationType>
<Address>rachid.mamai@xxx.com</Address>
</Notification>
</Notifications>
<AutomationType>scheduled</AutomationType>
</Objects>
</CreateRequest>
</s:Body>
</s:Envelope>

For the curious ones, you may be asking how I found the working values. I invite you to go to Automation Studio, open the Chrome Developer Tools (F12) and click on the Network tab.

Open an automation, add your email to the settings and click done. Now go check out the Network tab. There is a REST call to the endpoint below.

Given the fact that we can only interact with Automation Studio using SOAP calls for now, we can understand why the endpoint is beta and not officially documented:

https://mc.s50.exacttarget.com/rest/beta/automations/notifications/AUTOMATION_ID/

Now let us look at the request payload:

We can see that the values used for NotificationType and ChannelType are as described above. That was worth a try and it worked: [see code snippet on Github]

{
"programId": "TnJZZGdzNjVjRW1zX0lhVjhrNkxPxxxxxx",
"workers": [
{
"body": "",
"channelType": "1",
"programId": "TnJZZGdzNjVjRW1zX0lhVjhrNkxPxxxxxx",
"definition": "rachid.mamai@xxxx.com",
"notificationType": "Complete"
},
{
"channelType": "1",
"programId": "TnJZZGdzNjVjRW1zX0lhVjhrNkxPxxxxxx",
"definition": "rachid.mamai@xxxx.com",
"notificationType": "Error"
}
]
}

I invite you to check the network tab every time you need to interact with Salesforce Marketing Cloud APIs. It can be very interesting and full of undocumented information.

If you know someone that can correct this on the official documentation, please get in touch through the comments or send me a message on LinkedIn.


About the author

Rachid Mamai is a SFMC geek and a Digital Marketing enthusiast living in France. To get in touch with Rachid, visit his LinkedIn.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s