sfmc.guide
Engagement Next
⌘K

CreateObject

Instantiates a named SOAP API object and returns a handle for SetObjectProperty, AddObjectArrayItem and the Invoke* executors. Runtime-proven on a live Marketing Cloud Engagement CloudPage.

Runtime verified Test scripts included

Syntax

CreateObject(typeName)  →  object
1 argument — exactly

CreateObject is the first link in the AMPscript SOAP object-builder chain — the AMPscript side of the shared Platform object/Invoke* API, paired 1:1 with the same-named SSJS Platform function. You build an object with CreateObject, populate it with SetObjectProperty and AddObjectArrayItem, then run it through one of the Invoke* executors.

Parameters

Name Type Required Description
typeName string Yes The SOAP API object type to instantiate, e.g. DataExtension, RetrieveRequest

Example

%%[
  VAR @de
  SET @de = CreateObject("DataExtension")
  SetObjectProperty(@de, "CustomerKey", "MY_DE")
]%%

The handle returned by CreateObject is opaque — printing it yields nothing useful; its only job is to be threaded into the property setters and an executor.

A fuller build, assembling a retrieve request:

%%[
  VAR @rr
  SET @rr = CreateObject("RetrieveRequest")
  SetObjectProperty(@rr, "ObjectType", "DataExtension")
  AddObjectArrayItem(@rr, "Properties", "Name")
]%%

Return value

object — an opaque handle to the newly created SOAP object. It is not a string or a rowset; it is only meaningful when passed to SetObjectProperty, AddObjectArrayItem, or an Invoke* function.

Behaviour

Flat type names resolve; dotted and wrapper names do not. The following types were confirmed at runtime: DataExtension, DataExtensionField, RetrieveRequest, SimpleFilterPart, ExecuteRequest, QueryDefinition. A dotted name such as DataExtension.Field and the SSJS-style PerformRequest wrapper do not resolve — calling CreateObject with them aborts the CloudPage with HTTP 422. Use the flat DataExtensionField, and pass the definition object itself (not a PerformRequest) to InvokePerform.

Show test script
%%[
  VAR @b
  SET @b = RequestParameter("b")

  IF @b == "zzz" THEN
    OutputLine(Concat("CTRL=[alive]"))
  ENDIF

  /* build a RetrieveRequest handle and prove it works via a read-only retrieve */
  IF @b == "build" THEN
    VAR @rr, @st, @req, @rows, @sfp
    SET @rr = CreateObject("RetrieveRequest")
    SetObjectProperty(@rr, "ObjectType", "DataExtension")
    AddObjectArrayItem(@rr, "Properties", "Name")
    SET @sfp = CreateObject("SimpleFilterPart")
    SetObjectProperty(@sfp, "Property", "CustomerKey")
    SetObjectProperty(@sfp, "SimpleOperator", "equals")
    AddObjectArrayItem(@sfp, "Value", "AMP_VERIFY_SCRATCH")
    SetObjectProperty(@rr, "Filter", @sfp)
    SET @rows = InvokeRetrieve(@rr, @st, @req)
    OutputLine(Concat("build st=[", @st, "] rc=[", RowCount(@rows), "]"))
  ENDIF
]%%

Availability

Platform Available
Marketing Cloud Engagement Yes
Marketing Cloud Next No

See also