Glen Mazza's Weblog

Automations in Marketing Cloud consist of one or more activities placed in one or more steps, with all activities of one step activated simultaneously and with no proceeding to the next step until they have all completed. They also include scheduling and notification information. Activities are defined independently to be plugged into one or more automations, changing the activity's definition holds for all automations it is included in.

For activities, I've earlier provided examples of making SOAP requests to create both SQL query activities and the data extensions they fill, and REST calls to create data extract and file transfer activities. Finally, another entry shows creating an Import activity from a file on SFTP back to a data extension in SFMC. Both articles have seen been updated to include an Automation "shell" as described below.

Even without an API to create the automation holding and ordering these activities, the bulk of the work is done when the activities are created. One still has to figure out the steps and the activities that go into each one, however, requiring documentation for same. Unfortunately, when creating an automation via SOAP request, SFMC does not allow for specifying the needed activities via customer key, something known at the time of creating the automation, and something that remains the same across business units, allowing for reusable SOAP requests. (I've requested them to do so.) Instead, one must specify the (internal) object ID of the activity, which is known only after the objects are created and is different for each business unit.

However, SFMC thankfully meets us halfway. With a create automation SOAP request, one can still define the steps and types of activities needed in each step, and temporarily provide, as the activity name, instructions to the human for the actual activity to manually plug into the automation with Automation Studio. This saves manual documentation of same. The automation's name, customer key, and description can be provided and kept equivalent for all BUs the automation is deployed in.

A sample SOAP request creating an automation "shell" (from one of the two updated blog articles mentioned previously):

<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>User Agent Info Automation</Name>
                <CustomerKey>user_agent_atmn_key</CustomerKey>
                <Description>Obtain user agent info for opens
                </Description>
                <AutomationTasks>
                    <AutomationTask>
                        <Name>Create extract for usage agent info</Name>
                        <Activities>
                            <Activity>
                                <ActivityObject xsi:type="DataExtractActivity">
                                    <Name>Replace with s1_user_agent_info_extract</Name>
                                </ActivityObject>
                            </Activity>
                        </Activities>
                    </AutomationTask>
                    <AutomationTask>
                        <Name>File transfer of user agent info to SFTP server</Name>
                        <Activities>
                            <Activity>
                                <ActivityObject xsi:type="FileTransferActivity">
                                    <Name>Replace with s2_user_agent_info_transfer</Name>
                                </ActivityObject>
                            </Activity>
                        </Activities>
                    </AutomationTask>
                    <AutomationTask>
                        <Name>Uncompress into opens.csv on SFTP server</Name>
                        <Activities>
                            <Activity>
                                <ActivityObject xsi:type="FileTransferActivity">
                                    <Name>Replace with s3_user_agent_info_unzip</Name>
                                </ActivityObject>
                            </Activity>
                        </Activities>
                    </AutomationTask>
                    <AutomationTask>
                        <Name>Import user agent info back into data extension</Name>
                        <Activities>
                            <Activity>
                                <ActivityObject xsi:type="ImportDefinition">
                                    <Name>Replace with s4_user_agent_info_import</Name>
                                </ActivityObject>
                            </Activity>
                        </Activities>
                    </AutomationTask>
                </AutomationTasks>
                <AutomationType>scheduled</AutomationType>
            </Objects>
        </CreateRequest>
    </s:Body>
</s:Envelope>

Once the shell and the activities have been created via API, it's a rather simple matter to hit "Replace" on each of the steps making up the automation and choose the activity reported on the step, and then test and schedule the automation as usual.

The REST endpoints for automations I believe fall into the "undocumented" (i.e., unsupported) category. In attempting to create an automation via REST, I saw the same shortcomings as this 2019 Salesforce Stack Exchange posting. However, as shown in that posting, retrieving an automation feature provides some value, showing the scheduling information as well as row counts in the data extensions that the automation's SQL activities use.

Notes

• To obtain the ObjectID given an automation's customer key, one needs to request the ProgramID property, requesting the usual ObjectID does not work properly:

  <RetrieveRequestMsg xmlns="http://exacttarget.com/wsdl/partnerAPI">
      <RetrieveRequest>
          <ObjectType>Automation</ObjectType>
          <Properties>ProgramID</Properties>
          <Properties>Name</Properties>
          <Properties>Description</Properties>
          <Properties>CustomerKey</Properties>
          <Properties>IsActive</Properties>
          <Filter xsi:type="SimpleFilterPart">
              <Property>CustomerKey</Property>
              <SimpleOperator>equals</SimpleOperator>
              <Value>user_agent_atmn_key</Value>
          </Filter>
      </RetrieveRequest>
  </RetrieveRequestMsg>
  

  To run, above snippet can be put within the body of the SOAP request given for the automation above.

• Once you obtain the Object ID for an automation, you can further drill down to obtain information on the steps of an automation and activities with the steps, by querying the Task and Activity objects respectively, with this filter:

  <Filter xsi:type="SimpleFilterPart">
      <Property>Program.ObjectID</Property>
      <SimpleOperator>equals</SimpleOperator>
      <Value>...uuid of automation...</Value>
  </Filter>
  

• To find properties you can request for an object, including the Automation, Task, and Activity objects, make a DefinitionRequestMsg call and in the response check for properties with an isRetrievable value of true.