AddObjectArrayItem

Runtime verified Test scripts included

Syntax

AddObjectArrayItem(apiObject, propertyName, value)  →  string

3 arguments — exactly

The third link in the SOAP object-builder chain — the one that constructs the nested and array-valued parts of a SOAP object. Where SetObjectProperty sets a single value, AddObjectArrayItem appends to a collection, and can be called repeatedly to grow it.

Parameters

Name	Type	Required	Description
`apiObject`	object	Yes	A handle returned by `CreateObject`
`propertyName`	string	Yes	The array-valued property, e.g. `Fields`, `Properties`, `Value`
`value`	string \| object	Yes	The scalar to append, or another `CreateObject` handle

Example

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

Two calls append two column names to the request’s Properties array. To build nested structure, append handles instead of scalars — here two DataExtensionField objects become the Fields of a data extension:

%%[
  VAR @de, @f1, @f2
  SET @de = CreateObject("DataExtension")
  SET @f1 = CreateObject("DataExtensionField")
  SetObjectProperty(@f1, "Name", "Id")
  SetObjectProperty(@f1, "FieldType", "Text")
  AddObjectArrayItem(@de, "Fields", @f1)
  SET @f2 = CreateObject("DataExtensionField")
  SetObjectProperty(@f2, "Name", "Val")
  SetObjectProperty(@f2, "FieldType", "Text")
  AddObjectArrayItem(@de, "Fields", @f2)
]%%

Return value

string — an empty string. The call is used for its side effect on the handle.

Behaviour

Both scalar and nested-handle items work. Appending scalar strings to Properties (of a retrieve) and to the Value array of a SimpleFilterPart produced a working filtered retrieve. Appending DataExtensionField handles to the Fields array of a DataExtension produced a data extension that InvokeCreate accepted with OK / Data Extension created..

Repeated calls accumulate. Each call appends one more item; there is no replace semantics — call it once per array element.

Show test script

%%[
  VAR @b
  SET @b = RequestParameter("b")

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

  /* scalar items appended to the Properties array of a retrieve request */
  IF @b == "scalar" THEN
    VAR @rr, @st, @req, @rows
    SET @rr = CreateObject("RetrieveRequest")
    SetObjectProperty(@rr, "ObjectType", "DataExtension")
    AddObjectArrayItem(@rr, "Properties", "Name")
    AddObjectArrayItem(@rr, "Properties", "CustomerKey")
    SET @rows = InvokeRetrieve(@rr, @st, @req)
    OutputLine(Concat("scalar st=[", @st, "] rc=[", RowCount(@rows), "]"))
  ENDIF

  /* nested handle items appended to the Fields array of a DataExtension */
  IF @b == "nested" THEN
    VAR @de, @f1, @f2, @m, @e, @dm, @de3
    SET @de = CreateObject("DataExtension")
    SetObjectProperty(@de, "CustomerKey", "AMPWSPROXYSCRATCH")
    SetObjectProperty(@de, "Name", "AMPWSPROXYSCRATCH")
    SET @f1 = CreateObject("DataExtensionField")
    SetObjectProperty(@f1, "Name", "Id")
    SetObjectProperty(@f1, "FieldType", "Text")
    SetObjectProperty(@f1, "MaxLength", "50")
    SetObjectProperty(@f1, "IsPrimaryKey", "true")
    SetObjectProperty(@f1, "IsRequired", "true")
    AddObjectArrayItem(@de, "Fields", @f1)
    SET @f2 = CreateObject("DataExtensionField")
    SetObjectProperty(@f2, "Name", "Val")
    SetObjectProperty(@f2, "FieldType", "Text")
    SetObjectProperty(@f2, "MaxLength", "100")
    AddObjectArrayItem(@de, "Fields", @f2)
    OutputLine(Concat("nested create=[", InvokeCreate(@de, @m, @e), "] msg=[", @m, "]"))
    /* clean up the throwaway DE */
    SET @de3 = CreateObject("DataExtension")
    SetObjectProperty(@de3, "CustomerKey", "AMPWSPROXYSCRATCH")
    OutputLine(Concat("nested delete=[", InvokeDelete(@de3, @dm, @e), "]"))
  ENDIF
]%%

Availability

Platform	Available
Marketing Cloud Engagement	Yes
Marketing Cloud Next	No