Create, Retrieve & Update Records on Salesforce Objects with Ampscript

Author: Florin Valean

Use case

There could be numerous scenarios where Marketing Cloud would need to update records on Salesforce objects in other Salesforce Clouds. A common use case is the custom preference centre which has to update the status for subscribers/contacts on both sides - Marketing Cloud and other Salesforce Clouds such as Sales or Service Cloud. Ampscript provides three functions to manage records on Salesforce objects:

These functions work only for a Marketing Cloud account integrated with another Salesforce Cloud account.

Use the following syntax for these functions:

/* CreateSalesforceObject ObjectName = the name of the object where you want to create the record Number-of-Fields-to-Add = the number of field-value pairs to be set up for the new record Field-1 = the name of the first field to add Value-1 = the value for Field-1 Field-2 = the name of the second field to add Value-2 = the value for Field-2 Field-n = the name of the 'n'th field to add Value-n = the value for Field-n */ CreateSalesforceObject(ObjectName, Number-of-Fields-to-Add, Field-1, Value-1, Field-2, Value-2, Field-n, Value-n) /* RetrieveSalesforceObjects ObjectName = the name of the object where you want to retrieve the records from List-of-Fields-to-Retrieve = the name of fields to be included in the rowset separated by comma Field-1 = the name of the first field to be included in the WHERE clause Operator-1 = the operator for the first condition in the WHERE clause Value-1 = the value for Field-1 to search for in the WHERE clause Field-2 = the name of the second field to be included in the WHERE clause Operator-2 = the operator for the second condition in the WHERE clause Value-2 = the value for Field-2 to search for in the WHERE clause Field-n = the name of the 'n'th field to be included in the WHERE clause Operator-n = the operator for the 'n'th condition in the WHERE clause Value-n = the value for Field-n to search for in the WHERE clause */ RetrieveSalesforceObjects(ObjectName, List-of-Fields-to-Retrieve, Field-1, Operator-1, Value-1, Field-2, Operator-2, Value-2, Field-n, Operator-n, Value-n) /* UpdateSingleSalesforceObject ObjectName = the name of the object where you want to create the record Record-ID = the ID of the record Field-1 = the name of the first field to be updated Value-1 = the new value for Field-1 Field-2 = the name of the second field to be updated Value-2 = the new value for Field-2 Field-n = the name of the 'n'th field to be updated Value-n = the new value for Field-n */ UpdateSingleSalesforceObject(ObjectName, Record-ID, Field-1, Value-1, Field-2, Value-2, Field-n, Value-n)


Ampscript sample code

You can create a landing page in Web Studio and include this code. Publish the page and load it in a web browser to test the code. Make sure an integration with another Salesforce Cloud exists, otherwise the functions will not work.

/* replace the highlighted values with yours */ %%[ var @id, @rowset, @update, @numberOfRows, @row, @firstName, @email, @i /* creates a new record on the Lead object with FirstName = Jane, City = London, Email = contact@code4.cloud and returns the salesforce generated ID of the new record */ set @id = CreateSalesforceObject('Lead', 3, 'FirstName', 'Jane', 'City', 'London', 'Email', 'contact@code4.cloud') ]%% ID created: %%=v(@id)=%%<br /><br /> %%[ /* retrieves the values for FirstName and Email fields on records from the Contact object where HasOptedOutOfEmail is false and LastName does not equal to Trump */ set @rowset = RetrieveSalesforceObjects('Contact', 'FirstName, Email', 'HasOptedOutOfEmail', '=', 0, 'LastName', '!=', 'Trump') if not empty(@rowset) then set @numberOfRows = RowCount(@rowset) ]%% Number of rows returned: %%=v(@numberOfRows)=%%<br /><br /> %%[ for @i = 1 to @numberOfRows do set @row = Row(@rowset, @i) set @firstName = Field(@row, "FirstName") set @email = Field(@row, "Email") ]%% Row #%%=v(@i)=%%<br /> First Name: %%=v(@firstName)=%%<br /> Email address: %%=v(@email)=%%<br /><br /> %%[ next @i endif /* updates the values for Name to Best and IsWon to true for the record with ID = 0069E00000qxMq6QAE on the Opportunity object */ set @update = UpdateSingleSalesforceObject('Opportunity', '0069E00000qxMq6QAE', 'Name', 'Best', 'IsWon', 1) ]%% Updated (1 = Success / 0 = Failure): %%=v(@update)=%%

Notice the use of Row and Field functions - these are helpful when dealing with rowset objects.

The possible values for the operator in the RetrieveSalesforceObjects function are:

If the code was successfully executed the output in the browser would look like this:

ID created: 00Q5E000003yTYiXAM Number of rows returned: 2 Row #1 First Name: Alice Email address: alice@code4.cloud Row #2 First Name: Tom Email address: tom@code4.cloud Updated (1 = Success / 0 = Failure): 1
Share this page
Stay in touch

Subscribe to the newsletter

p1 p2 p3