InvokePerform

Runtime verified Test scripts included

Syntax

InvokePerform(apiObject, actionToPerform[, @statusMessage])  →  string

2–3 arguments

Runs the SOAP Perform verb — the one that triggers a definition to run (start a query, an import, an automation). The first argument is the definition object itself (e.g. a QueryDefinition) built with CreateObject; the second is the action string.

Parameters

Name	Type	Required	Description
`apiObject`	object	Yes	The definition object to act on (e.g. a `QueryDefinition`)
`actionToPerform`	string	Yes	The action, e.g. `start`
`@statusMessage`	string	No	Out-variable that receives the status message

Example

%%[
  VAR @obj, @st
  SET @obj = CreateObject("QueryDefinition")
  SetObjectProperty(@obj, "ObjectID", "00000000-0000-0000-0000-000000000000")
  OutputLine(Concat("ret=[", InvokePerform(@obj, "notarealaction", @st), "] st=[", @st, "]"))
]%%

For an invalid action this renders ret=[Error] st=[notarealaction is not an action that can be Performed on a InteractionDefinition. ErrorID = ...]. With a valid start action on a real, provisioned definition it returns OK.

Return value

string — the SOAP OverallStatus, OK or Error. The human-readable message goes to the optional @statusMessage out-variable.

Behaviour

The first argument is the definition, not a wrapper. Pass the QueryDefinition (or other definition) object directly. There is no PerformRequest wrapper type — CreateObject("PerformRequest") does not resolve and aborts the page.

Failures return Error with a message. An invalid action, or a valid action against a nonexistent ObjectID, returned Error with the reason in @statusMessage. Internally a QueryDefinition is reported as an InteractionDefinition.

Arity of two is valid. InvokePerform(apiObject, action) — without the out-variable — is a complete call.

Show test script

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

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

  /* invalid action: proves acceptance + Error return, no side effect */
  IF @b == "badaction" THEN
    VAR @obj, @st, @ret
    SET @obj = CreateObject("QueryDefinition")
    SetObjectProperty(@obj, "ObjectID", "00000000-0000-0000-0000-000000000000")
    SET @ret = InvokePerform(@obj, "notarealaction", @st)
    OutputLine(Concat("badaction ret=[", @ret, "] st=[", @st, "]"))
  ENDIF

  /* valid action but nonexistent definition: no query starts */
  IF @b == "noobj" THEN
    VAR @obj, @st, @ret
    SET @obj = CreateObject("QueryDefinition")
    SetObjectProperty(@obj, "ObjectID", "00000000-0000-0000-0000-000000000000")
    SET @ret = InvokePerform(@obj, "start", @st)
    OutputLine(Concat("noobj ret=[", @ret, "] st=[", @st, "]"))
  ENDIF
]%%

Availability

Platform	Available
Marketing Cloud Engagement	Yes
Marketing Cloud Next	No