The SetObjectProperty is used to set a value created with the CreateObject function using a Marketing Cloud webservice API object. It is most commonly used in conjunction with the AddObjectArrayItem and CreateObject functions in AMPscript.
A simple use case for using the SetObjectProperty function is to use the WebServices API with SSJS and AMPscript to run an automation outside of the User Interface. This is shown in How to Run Automations More Frequently using SSJS.
Another use case would be create a custom preference page using the WebServices API with AMPscript.
Syntax:
SetObjectProperty(1,2,3)
1 = API Object receiving assigned value
2 = Name of property assigned
3 = Value of property assigned
Example:
%%[
Platform.Load(“Core”,”1.1.1″);
var automationCustomerKey = “[Customer Key Goes Here]”
var rr = Platform.Function.CreateObject(“RetrieveRequest”);
Platform.Function.SetObjectProperty(rr, “ObjectType”, “Automation”);
Platform.Function.AddObjectArrayItem(rr, “Properties”, “ProgramID”);
Platform.Function.AddObjectArrayItem(rr, “Properties”, “CustomerKey”);
Platform.Function.AddObjectArrayItem(rr, “Properties”, “Status”);
var sfp = Platform.Function.CreateObject(“SimpleFilterPart”);
Platform.Function.SetObjectProperty(sfp, “Property”, “CustomerKey”);
Platform.Function.SetObjectProperty(sfp, “SimpleOperator”, “equals”);
Platform.Function.AddObjectArrayItem(sfp, “Value”, automationCustomerKey);
Platform.Function.SetObjectProperty(rr, “Filter”, sfp);
var retrieveStatus = [0,0,0];
var automationResultSet = Platform.Function.InvokeRetrieve(rr, retrieveStatus);
var ObjectID = automationResultSet[0][“ObjectID”];
var Status = automationResultSet[0][“Status”];
if (ObjectID != “null”) {
/*
Code Status
-1 Error
0 BuildingError
1 Building
2 Ready
3 Running
4 Paused
5 Stopped
6 Scheduled
7 Awaiting Trigger
8 InactiveTrigger
*/
if (Status == 2) {
var obj = Platform.Function.CreateObject(“Automation”);
Platform.Function.SetObjectProperty(obj, “ObjectID”, ObjectID);
var po = Platform.Function.CreateObject(“PerformOptions”);
var performResult = [0,0,0];
var performStatus = Platform.Function.InvokePerform(obj, “start”, performResult, po);
} else {
// already running
}
} else {
// automation not found
}
]%%
Output:
(No Output. Automation run.)
Explanation:
First the CreateObject function is used several times in this example, for the:
- Triggered Send
- Triggered Send Definition
- Subscriber
- Attribute
The Triggered Send and Triggered Send Definition go together in Marketing Cloud as they are both needed to deploy a triggered email send. In short, one is the properties that show which email content to use and the other is a sort of envelope around the email with more properties about the actual trigger.
The Subscriber and Attribute go together to create the Attribute object with one column for “First Name” and the value equal to the AMPscript variable of @FirstName. This is used to connect with the Subscriber object to assign EmailAddress with AMPscript variables that can be defined from the CloudPage. More on the AddObjectArrayItem function that is used to connect the two objects with the array.
Lastly, I threw in a RaiseError function in case the status code for the trigger comes back with anything but “OK.”
The CreateObject function has many uses within the web services API and used with AMPscript can be a flexible and customizable tool.
Related functions are the AddObjectArrayItem function and the SetObjectProperty function.
