SFMC Automation Studio API Objects

My intention for this post was to provide another avenue to access important information on some quirks of the Automation Studio API objects and their relations to each other. There are some fundamental knowledge nuggets buried deep in the official documentation, plus, some documentation is simply flat wrong.

I like to primarily work with SSJS / WS Proxy to interact with the SFMC Soap endpoints. I can recommend this great resource from Ivan:

How to use WSProxy to work with Automations in server-side JavaScript — ampscript.xyz

Firstly, I want to touch on the “undocumented” objects. The objects AutomationActivity and AutomationActivityInstance listed in the documentation cannot be referenced by these names. They must be referenced as Activity and ActivityInstance respectively. Simply, the documented object names are incorrect/misspelled.

AutomationActivity | Marketing Cloud API | Salesforce Developers

Documented Objects

• Automation /Program https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/automation.htm
• AutomationInstance / ProgramInstance
  https://developer.salesforce.com/docs/atlas.en-us.noversion.mc-apis.meta/mc-apis/automationinstance.htm

Undocumented Objects

• Task
• TaskInstance
• Activity
• ActivityInstance

Relationships between the objects :

• Tasks represent the columns in Automation Studio.
• Activities are the objects in each column

Program → Task → Activity

Program.ObjectID = Task.Program.ObjectID
Task.ObjectID = Activity.Task.ObjectID

Automation → AutomationInstance → ActivityInstance

Automation.ObjectID = AutomationInstance.AutomationID
AutomationInstance.ProgramInstanceID=ActivityInstance.ProgramInstance.ObjectID

Retrievable Fields

Not all properties of objects are “Retrievable”. The easiest way to check which properties can be retrieved is by issuing a Describe request against the API for the object. To find a solution of what fields are retrievable see:

Get the Fields Available for Retrieval with “Describe”

While working through these Automation Studio objects, particularly with the AutomationInstance object, I found the describe API results to be very incorrect and misleading. Below I have listed fields I’ve found to be available for soap api retrieve request.

Automation

“ObjectID”,
“ProgramID”,
“Name”,
“Description”,
“CustomerKey”,
“Status”,
“IsActive”,
“AutomationType”,
“Schedule.ID”,
”CategoryID”,
”LastRunTime”,
”ScheduledTime”,
”LastSaveDate”,
”ModifiedBy”,
”LastSavedBy”,
”CreatedBy”,
”RecurrenceID”,
“CreatedDate”,
“ModifiedDate”,
“Client.ID”,
“Client.CreatedBy”,
“Client.ModifiedBy”,
“Client.EnterpriseID”

AutomationInstance

“ProgramInstanceID” → This will unlock TaskInstances array, and also ensure the AutomationInstance ObjectId is returned.
“ObjectID”,
“ProgramID”, /*AutomationID will not work*/
“CustomerKey”,
“Name”,
“Description”,
“Status”,
“StatusMessage”,
“StatusLastUpdate”,
“IsActive”,
“StartTime”,
“CompletedTime”,
“ScheduledTime”,
“AutomationType”

GUID Value for ProgramInstanceID is returned from Automation "Perform" as the ObjectID — Source: Salesforce Developer doc

ProgramInstance

“ObjectID”,
“ProgramID”,
“CustomerKey”,
“Name”,
“Description”,
“StatusMessage”,
“StatusLastUpdate”,
“IsActive”,
“Schedule.ID”,
“Client.ID”,
“Client.CreatedBy”,
“Client.ModifiedBy”,
“Client.EnterpriseID”,
“CreatedDate”,
“ModifiedDate”

Task

“ObjectID”,
“Program.ObjectID”,
“Name”,
“Description”,
“Sequence”,
“Client.ID”,
“Client.UserID”,
“Client.CreatedBy”,
“Client.ModifiedBy”,
“Client.EnterpriseID”,
“CreatedDate”,
“ModifiedDate”

TaskInstance

“ObjectID”,
“TaskDefinition.ObjectID”,
“Program.ObjectID”,
“ProgramInstance.ObjectID”,
“Name”,
“Description”,
“Sequence”,
“Client.ID”,
“Client.UserID”,
“Client.CreatedBy”,
“Client.ModifiedBy”,
“Client.EnterpriseID”,
“CreatedDate”,
“ModifiedDate”

Activity

“ObjectID”,
“CustomerKey”,
“Program.ObjectID”,
“Task.ObjectID”,
“Name”,
“Description”,
“Sequence”,
“Definition.ID”,
“Definition.ObjectID”,
“PartnerAPIObjectTypeID”,
“Definition”,
“IsActive”,
“Client.ID”,
“Client.CreatedBy”,
“Client.ModifiedBy”,
“Client.EnterpriseID”,
“CreatedDate ModifiedDate”

ActivityInstance

“ProgramID”,
“ObjectID”,
“CustomerKey”,
“ProgramInstance.ObjectID”,
“TaskInstance.ObjectID”,
“ActivityDefinition.ObjectID”,
“Name”,
“Description”,
“Status”,
“StatusMessage”,
“StatusLastUpdate”,
“SequenceID”,
“IsActive”,
“Definition.ID”,
“Definition.ObjectID”,
“PartnerAPIObjectTypeID”,
“Definition”,
“CreatedDate”,
“ModifiedDate”,
“Client.ID”,
“Client.CreatedBy”,
“Client.ModifiedBy”,
“Client.EnterpriseID”

Script: ‘Activity’

<script runat="server">
    Platform.Load("Core","1");
    var api = new Script.Util.WSProxy();
try {
var AutomationName = "01 DataView_Logging";
var cols1 = ["ProgramID", "Name", "IsActive"];
        
        var filter1 = {
            Property: "Name",
            SimpleOperator: "equals",
            Value: AutomationName
        };
// Retrieve Automation object
        var request = api.retrieve("Automation", cols1, filter1);
       
        var AutomationObjectID = request.Results[0].ObjectID;
var cols2 = ["ObjectID", "CustomerKey", "Program.ObjectID", "Task.ObjectID", "Name", "Description", "Sequence", "Definition.ID", "Definition.ObjectID","PartnerAPIObjectTypeID","Definition","IsActive","Client.ID","Client.CreatedBy","Client.ModifiedBy","Client.EnterpriseID","CreatedDate ModifiedDate"];
        var filter2 = {
            Property: "Program.ObjectID",
            SimpleOperator: "equals",
            Value: AutomationObjectID
        };
// Retrieve Activity object
        var activities = api.retrieve("Activity", cols2, filter2);
Write(Stringify(activities));
} catch(err) {
        Write(Stringify(err));
    }
</script>