sfmc.guide
Engagement Next
⌘K

RetrieveSalesforceObjects

Retrieves records from a connected Salesforce Sales or Service Cloud object via Marketing Cloud Connect and returns them as a rowset. Runtime-proven on a live Marketing Cloud Engagement CloudPage — including that an unknown object name aborts the page and an empty match returns a clean empty rowset.

Next
Runtime verified Test scripts included

Syntax

RetrieveSalesforceObjects(objectName, fieldsToRetrieve, queryFieldName1, queryFieldOperator1, queryFieldValue1[, queryFieldNameN, queryFieldOperatorN, queryFieldValueN, ...])  →  rowset

Parameters

Name Type Required Description
objectName string Yes API name of the Salesforce object to query
fieldsToRetrieve string Yes Comma-separated list of field API names to return
queryFieldName1 string Yes Field to filter on
queryFieldOperator1 string Yes Comparison operator (=, !=, <, <=, >, >=)
queryFieldValue1 string | number Yes Value to filter against
queryFieldNameN string No Further filter field
queryFieldOperatorN string No Further comparison operator
queryFieldValueN string | number No Further filter value

Filters are supplied as repeating three-argument groups (field, operator, value); there is no upper bound on the number of groups, and multiple groups are joined with AND.

Example

%%[
  VAR @rows, @count
  SET @rows = RetrieveSalesforceObjects("Contact", "Id", "Id", "=", "000000000000000AAA")
  SET @count = RowCount(@rows)
]%%
Matches: %%=v(@count)=%%

Renders Matches: 0 when nothing matches the filter — an unmatched query yields an empty rowset rather than an error.

Once a rowset comes back, walk it with RowCount, Row and Field:

%%[
  VAR @rows, @i, @id
  SET @rows = RetrieveSalesforceObjects("Contact", "Id", "IsDeleted", "=", "false")
  FOR @i = 1 TO RowCount(@rows) DO
    SET @id = Field(Row(@rows, @i), "Id")
  NEXT @i
]%%

Return value

rowset — the matching records, one row per object, each field addressable by its API name through Field(Row(@rows, n), "FieldName").

There is no closed set of sentinel values: the result is a rowset whose size depends on the query. An unmatched filter returns an empty rowset (RowCount of 0, Empty of true).

Behaviour

A live query round-trips to the connected org. The function issues a SOAP request through Marketing Cloud Connect. RetrieveSalesforceObjects("Contact", "Id", "IsDeleted", "=", "false") returned a populated rowset, and the first row’s Id field was a non-empty 18-character Salesforce ID.

An empty match is a rowset, not an error. A filter that matches no record — RetrieveSalesforceObjects("Contact", "Id", "Id", "=", "000000000000000AAA") — returns a rowset whose RowCount is 0 and whose Empty is true, with the page rendering normally.

An unknown object name aborts the page

RetrieveSalesforceObjects("NotARealObject__x", "Id", "Id", "=", "000000000000000AAA") aborted the page with HTTP 422. Validate object and field API names before the call rather than relying on a graceful failure.

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

  /* a filter that matches nothing returns an empty rowset, not an error */
  IF @b == "empty" THEN
    VAR @rows, @rc
    SET @rows = RetrieveSalesforceObjects("Contact", "Id", "Id", "=", "000000000000000AAA")
    SET @rc = RowCount(@rows)
    OutputLine(Concat("empty.rowcount=[", @rc, "] empty.isEmpty=[", Empty(@rows), "]"))
  ENDIF

  /* a matching filter returns a navigable rowset */
  IF @b == "match" THEN
    VAR @rows2, @rc2, @row1
    SET @rows2 = RetrieveSalesforceObjects("Contact", "Id", "IsDeleted", "=", "false")
    SET @rc2 = RowCount(@rows2)
    OutputLine(Concat("match.rowcount=[", @rc2, "]"))
    IF @rc2 > 0 THEN
      SET @row1 = Row(@rows2, 1)
      OutputLine(Concat("match.firstIdLength=[", Length(Field(@row1, "Id")), "]"))
    ENDIF
  ENDIF

  /* an unknown object name aborts the page: the start marker never renders */
  IF @b == "badobj" THEN
    OutputLine(Concat("badobj start"))
    VAR @rows3
    SET @rows3 = RetrieveSalesforceObjects("NotARealObject__x", "Id", "Id", "=", "000000000000000AAA")
    OutputLine(Concat("badobj.rowcount=[", RowCount(@rows3), "]"))
  ENDIF
]%%

Availability

Platform Available
Marketing Cloud Engagement Yes
Marketing Cloud Next Yes, from API 67.0

Requires an active Marketing Cloud Connect integration to a Sales or Service Cloud org on the business unit.

See also