CreateObject Function

The CreateObject is used to return a Marketing Cloud webservice API object. It is most commonly used in conjunction with the AddObjectArrayItem and SetObjectProperty functions in AMPscript.

A simple use case for using the CreateObject function is to use the WebServices API on a CloudPage using AMPscript to send a triggered send email. For example, if a customer reaches a preference page, makes an update, and once they land on the “Thank You” page, it triggers a send.

Syntax:

                    

CreateObject(1)
1 = API Object receiving the new item in text form

                

Example:

                    

%%[
SET @ts = CreateObject(“TriggeredSend”)
SET @tsDef = CreateObject(“TriggeredSendDefinition”)
SET @ts_subkey = @emailaddr 

SetObjectProperty(@tsDef, “CustomerKey”, “TriggeredSendKey”)
SetObjectProperty(@ts, “TriggeredSendDefinition”, @tsDef)

SET @ts_sub = CreateObject(“Subscriber”)
SetObjectProperty(@ts_sub, “EmailAddress”, @emailaddr) 
   
SET @attribute = CreateObject(“Attribute”)
SetObjectProperty(@attribute, “Name”, “FirstName”) 
SetObjectProperty(@attribute, “Value”, @FirstName) 
AddObjectArrayItem(@ts_sub, “Attributes”, @attribute)

AddObjectArrayItem(@ts, “Subscribers”, @ts_sub)
SET @ts_statusCode = InvokeCreate(@ts, @ts_statusMsg, @errorCode)

IF @ts_statusCode != “OK” THEN
  RaiseError(@ts_statusMsg, 0, @ts_statusCode, @errorCode)
ENDIF



]%%


                

Output:

(No Output. Triggered Email Sent)

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.

Leave a Reply

Your email address will not be published. Required fields are marked *