Salesforce-style spinner for use on CloudPages

Spinners are loading indicators that can be shown when retrieving data or performing other operations.

We will use a common spinner that Salesforce Lightening users are familiar with – the full documentation can be found here. This spinner is a Lightning component, which means that it cannot be directly used on a CloudPage. My awesome colleague Anna rewrote it into HTML and CSS, so that it can be easily copied and pasted for use on a CloudPage. This way, you can emulate the look and feel of other Salesforce clouds on your CloudPages.

It doesn’t necessarily add any value for external users of your CloudPages, but it can improve the experience of Salesforce Marketing Cloud users who internally use apps created on CloudPages and are familiar with other Salesforce clouds.

Here’s a preview of the spinner we will create in a few easy steps:

Let’s start with adding the CSS for our spinner. You can paste below code anywhere in your existing style-sheet, or create a separate one and link to it in the document head:

Now let’s add our spinner to the CloudPage. We will create an HTML button and add an onclick event, so that the spinner activates once the user clicks the button:

And finally, let’s add the script with the showSpinner() function:

Above function will activate the spinner once the button is clicked and it will run indefinitely, which means that it’s appropriate for any use cases where the website gets reloaded or redirected to another one after all operations have been completed.

If you would like to control for how long the spinner is displayed, you can use the setTimeout method to deactivate the spinner after a given time. Below script will hide the spinner after 5 seconds:

You can also control the activation/deactivation of the spinner by adding a hideSpinner() function to other functions used for performing operations. Below example will post data to another website using the fetch method and hide the spinner after the operation is complete:

To see the spinner in action, visit my demo CloudPage: https://pub.s10.exacttarget.com/c5luwxbwtxa.


Questions? Comments?

Leave a comment below or email me at zuzanna@sfmarketing.cloud.

Two alternative ways of developing and testing CloudPages

As a Salesforce Marketing Cloud developer, you have certainly been caught up in this loop: Develop the CloudPage > Save and Publish > Wait 2, 3 or even 5 minutes > Check the results. Moreover, if you are not debugging correctly, you can lose a lot of time between looking for the problem and waiting for your updates to propagate on your CloudPage. I must take this opportunity to invite you to check out Zuzanna’s article about debugging AMPScript in CloudPages, it is very helpful and well explained.

In this article, we will be covering two ways of testing your code on a CloudPage without having to wait for the propagation of changes every time we save and publish our work. These two ways are probably well know by experimented Salesforce Marketing Cloud developers, or by those who were fortunate enough to stumble upon some answers regarding this problem on Salesforce Stack Exchange.

Create an external web page

If you already have a web server, that is great. You can use it to create your web pages. However, if you are on a budget, or you just do not want to spend money on a hosting service, don’t worry, I have done the heavy lifting for you.

We are going to use awardspace.com, an ad-free hosting which offers:

  • Free subdomain
  • 1GB disk space
  • Up to 4 websites (websites and not pages)

Those features are more than enough for our tests. Especially because we can use one or two pages only and overwrite their content every time we need to develop a new CloudPage.

Step 1: Create a freehosting account

Go to awardspace.com and click on FreeHosting on the homepage:

Create an account using one of the available options:

Step 2: Creating a free subdomain

Go to Hosting Tools > Domain Manager. Select “Create a free subdomain”, fill in the subdomain’s name, and click Create:

Step 3: Creating the web page

Go to Hosting Tools > File Manager. Double click on your subdomain’s folder:

Click on Create and check Create file. Give it a name like sfmc.html for example.

Step 4: add content and access the web page

Congrats, we have successfully created the web page. Double click on it to add the content. Click save when done editing The web page’s URL is as shown below without the /home/www/ part.

Call the page from within Salesforce Marketing Cloud

We are going to use two AMPScript functions to access our external page from within our CloudPage.

  • HTTPGet: Returns the content from our external web page. This function will only take our web page URL as a parameter.
  • TreatAsContent: Treats the content returned by the HTTPGet function as it came from a content area. This way, we make sure the AMPScript code in our web page gets evaluated.

For example, our CloudPage on Marketing Cloud should contain something like: [see code snippet]

Each time we need to update the code, we just have to update it on the external web page. No need to save and publish our CloudPage as its content will remain the same.  

This way, we are avoiding the wait time between the publishing and the propagation of our changes on the servers when using a traditional development method.

Content Block By Key / Name / Id

The second method is using one of the three functions above. These functions return the content stored in the specified Content Block.

First, we will start by creating our Content Block. We need to go to Content Builder > Create > Content Blocks > Code Snippet.

I highly suggest using a Code Snippet instead of an HTML Content Block in order to avoid Content Builder’s editor from truncating parts of our HTML code.

Once we have created our Content Block and added our content in it. Time for getting it’s Key, Id or Name depending on which function we are using. We can find it by clicking on the drop-down icon and select Properties.

Now, we can head in to our CloudPage and add the code below: [see code snippet]

It pretty simple and straightforward. The code uses ContentBlockByKey to get our Content Block’s content. This is a onetime operation. Every time we need to update our code, we will only have to update it on the Content Block. This way, the updates are instantly live and we do not have to wait several minutes for the propagation on the servers.

Once we are done testing, we can copy the code on the external page or on the Content Block to our main CloudPage in Marketing Cloud and publish it.


About the author

Rachid Mamai is a SFMC geek and a Digital Marketing enthusiast living in France. To get in touch with Rachid, visit his LinkedIn.

Create a CloudPages form with an image/file upload option

The HTML <input> tag specifies an input field where the user can enter data. An input field can vary in many ways, depending on the type attribute. The <input> elements with type="file" let the user choose one or more files from their device storage. The file can then be manipulated using JavaScript in order to process it further.

In this article, we will focus on creating a CloudPages form with an image input field, and uploading that image into Marketing Cloud’s Content Builder. The high-level outline of this process, which can be found in this Stack Exchange post, is: once the file has been uploaded via the form, it needs to be Base64 encoded, and then passed in a REST API call to the /asset/v1/content/assets route in order to create the image in Content Builder.

We will need to create two separate CloudPages: the first one will run client-side JavaScript in order to encode the file into a Base64 string and it will then pass it to the second CloudPage, which will run server-side JavaScript to make an API call to create a new asset in Content Builder.

I will break it down into smaller parts to make it easier to understand the different steps along the way.

Create an input field

Let’s start with creating an <input> field on a CloudPage. The input needs to be of the type="file" in order to allow the end-user to choose a file for upload from their local machine. We will also add an accept attribute, which specifies a filter for what file types the user can pick from the file input dialogue box. For our use case, it will be image/*: [see code snippet]

We also need to include an id attribute in order to be able to reference the input field in JavaScript.

Encode the image using Base64

Base64 is a group of binary-to-text encoding schemes which enable storing and transferring data over media that are designed to deal with ASCII (text) only. In order to encode the image, we will use the FileReader.readAsDataURL() method to securely read the contents of a file stored on the user’s computer and return a result attribute containing a data: URL representing the file’s data. We will use the addEventListener() method to attach a click event to the Upload button, which will trigger the encoding function: [see code snippet]

The format of the returned result is the following:

data:[<mediatype>][;base64],<data>

The mediatype is a MIME type string, such as ‘image/jpeg’ for a JPEG image file and <data> is the Base64 encoded string representing the uploaded file.

Fetch the data to processing page

We now need to pass the data onto our second CloudPage for further processing. The reason why we are using two pages instead of one is that client-side JavaScript is run after the server-side is complete, which makes it impossible to run them in reverse order on the same page.

In order to pass the data between our CloudPages, we will use the fetch() method. But first, let’s prepare the data that we will need for our API call: [see code snippet]

  • base64enc is the encoded string which represents the image
  • fullFileName is the full name of the file uploaded by the user (eg. “astro.png”)
  • fileName is the first part of the file name, before the filename extension (eg. “astro”)
  • assetName is the filename extension (eg. “png”)

Once we have the above, we can POST it in JSON format to the processing page that will contain the server-side script. Our request will look like this: [see code snippet]

where the method is POST, headers specify that the content-type is JSON and in the JSON body we will have three attribute-value pairs, base64enc, fileName and assetName.

The fetch() method argument is the path to the CloudPage containing our server-side script, so, for now, you can create an empty CloudPage just to obtain the link.

The fetch() method returns a promise that resolves to a response to that request, whether it is successful or not: .then(function(res) / .catch(function(err).

The full client-side script

Let’s now put all of the above elements together to create our first CloudPage. The complete code will look like this: [see code snippet]

Now we can move on and prepare the second part of the script.

Retrieve the posted data

In order to retrieve the data posted from our first CloudPage, we will use the getPostData() server-side JavaScript method, which sadly is not documented in the official Server-Side JavaScript Syntax Guide, but you can read about it in this post on Salesforce Stack Exchange. Once we access the body of our request, we can parse the data using the ParseJSON() function: [see code snippet]

Prepare the data for API call

Now we can prepare the data for our API call. Let’s take a look at an example JSON body of a create asset request: [see code snippet]

In the above, the first name represents the name of the file. The second parameter assetType, consists of a name which represents the file extension and an id of the asset type. Asset types are the file or content types supported by Content Builder and the full list can be found here: List of Asset Types.

Let’s prepare the data and match the asset type based on the name of the file extension: [see code snippet]

If you’re only going to upload images, you don’t need to include the whole list of asset types – the ones that start with “2” will be sufficient.

Create an asset using REST API

In order to make an API call using the /asset/v1/content/assets route, we first need to authenticate. If you’re not sure how to authenticate programmatically in Salesforce Marketing Cloud, refer to my article, Salesforce Marketing Cloud API Authentication using Server-Side JavaScript. Here’s the code snippet:

Once we obtain the accessToken, we will need to include it in our final API call, along with the rest_instance_url: [see code snippet]

The above call will create an image in Content Builder’s main folder and return the following response: [see code snippet]

The full server-side script

Here is the full script for our second CloudPage: [see code snippet]

You can now go back to your first CloudPage and start uploading!

To see this script in action, visit my CloudPage.


Questions? Comments?

Leave a comment below or email me at zuzanna@sfmarketing.cloud.

Exception handling in Salesforce Marketing Cloud emails

“Hope for the best and prepare for the worst” should be every marketer’s motto when it comes to creating contextual personalized content. Your company’s reputation could be easily tarnished if you send out buggy emails, that’s why exception handling should be an essential element of your email strategy.

In this article, you will learn about some of Salesforce Marketing Cloud’s build-in features and best practices that will help you maintain high quality of content that goes out to your subscribers.

Fallback values in emails

When it comes to creating personalized emails, we often hear Salesforce Marketing Cloud users assume that the data that comes through will be correct and that they are not going to include fallback values for their variables. The assumption should be exactly the opposite and you should always plan for bad or missing data!

If you’re using a Profile Attribute or a Data Extension column for personalizing an email, the best practice is to always leverage the Empty() AMPscript function to check whether there is a value available.

Here’s an example: it’s much easier to use a simple personalization string such as Dear %%FirstName%%, in your email, but if for some reason the data is missing, your subscriber would see Dear , in the email they receive. This can be easily prevented by using the Empty() function and adding a fallback value: [see code snippet]

In the above example, a Profile Attribute or a Data Extension column will be used if there’s a value available, and if not, the greeting in the email will be set to Dear Valued Customer.

Whether you’re using Lists or Data Extensions to segment the data in Salesforce Marketing Cloud, you can also leverage the “Default Value” feature to ensure that required data is always available:

Profile Attribute with a default value
Data Extension field with a default value

Using the RaiseError function in emails

The RaiseError() function, used along with a conditional statement, ensures that the email does not get sent if there is bad or missing data in the dataset used for personalizing the email. Depending on how you set the function, it can either skip the send for a current subscriber and move on to next subscriber, or it can stop the remaining send job. Here’s a summary of the function’s main features in Eliot Harper’s video:

RaiseError AMPscript Function in Salesforce Marketing Cloud

Let’s take a look at the function syntax and properties:

RaiseError(1, 2, 3, 4, 5)

OrdinalTypeRequiredDescription
1stringNError message to display
2booleanYIndicates whether function skips send for current subscriber and continues or stops. A value of true skips the send for current subscriber and moves to next subscriber. A value of false stops the send and returns an error. Function defaults to false.
3stringNAPI error code (set by the user)
4stringNAPI error number (set by the user)
5booleanNIndicates whether the function records information to data extensions before error occurs, even if the process skips the subscriber. A value of 1 retains information written to data extensions before the error occurs, even if the subscriber is skipped. A value of 0 does not retain information recorded before the error. This parameter refers to inserted, updated, upserted, or deleted information via AMPscript.

Let’s use the previous script example with the FirstName personalization, but instead of setting a fallback value in case the FirstName is missing, we will use the RaiseError() function to skip the send for that particular subscriber: [see code snippet]

You will notice, that upon previewing the email, the error message that you set will be displayed if the FirstName value is missing:

In a scenario where you would try to send this email to a subscriber with a missing FirstName value, the function would prevent from sending an email to the current subscriber and would move on to the next one.

This function should not be misused for data segmentation. Even though a subscriber is skipped or the whole job is cancelled, it still counts towards your totals as a sent message, meaning that you will pay for each suppressed email as you would for a sent one. This is a small price to pay for handling exceptions and sustaining a positive reputation with your subscribers, but it should not replace regular data cleansing and maintenance processes.

An additional thing to keep in mind is that AMPscript is interpreted top-down. This means, that if there are any other AMPscript functions before the RaiseError() function, they will all be executed, even if the send for a particular subscriber is skipped in the end.

On the other hand, if you have set the RaiseError() function to cancel the remaining send job, then any Update, Insert, and Delete AMPscript functions, which are processed in bulk during send time, will not be executed, unless you specify otherwise by setting the last of the RaiseError() properties to 1.

Bear in mind, that the second property of the RaiseError() function, which indicates whether function skips send for the current subscriber and continues or stops, will default to false if not specified. This means, that unless set to true, it will always stop the remaining send job.

Logging RaiseError results

By default, the emails and jobs suppressed by the RaiseError() function will only be visible in the NotSent tracking extract. If you’re using this function in Journey Builder emails or Triggered Sends, you will also be able to see how many emails were suppressed by checking the “Errored” column in Email Studio’s Tracking tab, under Journey Builder Sends/Triggered Sends. Unfortunately, you won’t be able to view any details of the suppressed sends in the UI.

In order to log all suppressed sends, you can create a Data Extension and add an InsertDE function to the email. Make sure to set the last property of the RaiseError() function to 1 and to include the InsertDE() function before the RaiseError() function, as everything placed after won’t get executed. This way, each email suppressed by the RaiseError() function, will also be logged in the Data Extension: [see code snippet]

Analyzing the log will help you investigate why some of the values are missing and improve your company’s data hygiene.


Questions? Comments?

Leave a comment below or email me at zuzanna@sfmarketing.cloud.

Custom profile and subscription center integrated with Sales/Service Cloud

In this tutorial, you will learn how to create a simple, yet fully customizable profile and subscription center integrated with Sales and Service Cloud. If you would like to skip the reading and jump to the final version of the script, click here. Bear in mind, that the script utilizes a couple of standard and custom Sales/Service Cloud fields – the full list can be found here.

What are Profile and Subscription Centers?

Each instance of Salesforce Marketing Cloud comes with a standard, predefined Profile Center and Subscription Center.

The profile center is a webpage where subscribers can enter and maintain the personal information that you keep about them. When you import a list, you can import attribute values for your subscribers that appear when a subscriber visits the profile center. The subscriber can update their information on this page and provide additional information.

A subscription center is a web page where a subscriber can control the messages they receive from your organization. The lists (including publication lists) you identify as public in the application are available for a subscriber to opt in to on the subscription center.

If you’re using Marketing Cloud Connect to integrate with Sales/Service Cloud, you can use the standard Profile Center based on the Marketing Cloud attributes that are mapped to fields in Sales or Service Cloud. Marketing Cloud Connect documentation states, that changes made in the Profile Center update Salesforce contact and lead data – unfortunately I haven’t been able to confirm this with my tests.

Another limitation which is very hard to overcome is the look and feel of the standard Profile and Subscription Center. If you enable Marketing Cloud BrandBuilder, you will be able to customize the color scheme of your Profile and Subscription Center based on the colors of the logo you upload – but you won’t be able to change the layout or the fonts used.

Sooner or later, most Marketing Cloud users switch to custom Profile and Subscription Centers, as the standard one is not enough when it comes to more complex use cases.

Anatomy of a Subscription Center

A Subscription Center is nothing else but an HTML form. The data passed in the form is then processed by a script – in this tutorial, we will use AMPscript. If you’ve never created a form before, you might want to check out this article first: Create a Sales Cloud-integrated lead capture form using AMPscript.

In the form, you can include any fields from any of the relevant Sales/Service Cloud objects, but to make it more simple as we go, for now, we will use three standard fields from the Contact object: FirstName, LastName and Email. Additionally, I have added three read-only checkboxes to the Contact object for subscription management: Newsletter, Offers and Events. [Why are they read-only? In this tutorial, you will learn how to allow subscribers to make changes to their preferences and sync those changes back to Salesforce. The process of managing the subscriptions by a Salesforce user and syncing the changes back to Marketing Cloud is a separate procedure and won’t be addressed in this article.] I also made sure that the Email Opt Out flag is visible on a Contact page layout in Sales Cloud:

Here is a reference of all the fields from the Contact object, which we will use in our script:

Field LabelAPI Field NameTypeLength
Contact IDIdid18
EmailEmailemail80
Email Opt OutHasOptedOutOfEmailboolean
Name FirstNamestring80
Name LastNamestring80
NewsletterNewsletter__cboolean
EventsEvents__cboolean
OffersOffers__cboolean

Let’s now create a simple HTML form which contains all of the above fields:

Since we want the form to be pre-populated with subscriber data from Sales/Service Cloud, we need to add the RetrieveSalesforceObjects function to pull the data, and display the retrieved data as field values:

You will also notice in the above script, that we have added a form action. The RequestParameter('PAGEURL') function reloads the page when the form is submitted, posting the form parameters back to the same page. You can, of course, post the form data to another page and process it there, but for the purpose of this tutorial, let’s keep everything on one page so that it’s easier to copy and paste.

After the form is submitted and posted, the data can be retrieved by using the RequestParameter AMPscript function. We will then update the data in Sales/Service Cloud using the UpdateSingleSalesforceObject function. Let’s add them now:

Congratulations – you just built the first, simple version of your profile and subscription center!

Now let’s analyze the above script. The first thing that you will notice is that all the AMPscript is placed at the beginning of the document, above the form – that’s because the form data first has to be posted before it can be processed, and upon posting the data, the page reloads and starts resolving the script from top-down. If you need more clarification on this concept, click here.

If the form has been submitted, we will update the Sales/Service Cloud contact with the new data that was posted upon form submission. The form data is retrieved using the RequestParameter function, which is used in the @updateRecord variable inside the UpdateSingleSalesforceObject function.

You will also notice, that for each of the checkboxes, I have added the following in-line IF function: Iif(RequestParameter("newsletter") == "on", "true", "false"). That is because the checkbox passed from the HTML form will have a value of either on or off, while to pass it to Sales/Service Cloud, we need to convert it to a boolean value of true or false.

Unsubscribe From All option

To make the functionality of our custom subscription and profile center similar to the standard one, we can add the Unsubscribe From All and Resubscribe options. The Unsubscribe From All option should not only set all the subscription-related flags in Sales Cloud to false, but also set the subscriber’s status to Unsubscribed in Salesforce Marketing Cloud’s All Subscribers list. To achieve this, we need to log an UnsubEvent. In order to do that, we will add an additional button to the form (Unsubscribe From All) and a hidden parameter which will be passed if someone clicks this button (name="unsub" type="hidden" value="true"). After submitting the form, if unsub value equals true, we will log the UnsubEvent in addition to updating the flags in Sales/Service Cloud. The below is a simplified version of logging an UnsubEvent and it will unsubscribe the contact from all BUs – if you would like to modify it to your use case, refer to this article: Unsubscribe and Log an UnsubEvent with a LogUnsubEvent Execute Call. Here’s what we need to add to our script to make this part work:

Since we have the option to Unsubscribe From All, we now also have to add an option to Resubscribe. The Resubscribe option will set all the subscription-related flags in Sales Cloud to true and set the subscriber’s status to Active in Salesforce Marketing Cloud’s All Subscribers list. The Resubscribe button will appear for any contact that has the HasOptedOutOfEmail flag set to true in Sales Cloud. The button also has a hidden parameter that will be passed with the form (name="sub" type="hidden" value="true"). Upon clicking the button, we will invoke the update method on a subscriber object to set their status to Active in Marketing Cloud, as well as update their subscription-related flags in Sales Cloud:

Update subscriber’s data in Marketing Cloud

If you’re using Marketing Cloud Connect, a very important thing to remember when updating subscriber’s email address is to do it in both, Sales/Service Cloud and Marketing Cloud. Here is why:

If an email address for a Lead or Contact Object is updated in Sales Cloud or Service Cloud, the corresponding email address is not updated in the All Subscribers list.

Eliot Harper, THE DATA HANDBOOK – Data Architecture for Salesforce Marketing Cloud

In order to achieve this, we will add one more piece of a script to update the subscriber object. First we will check, if the subscriber’s current email address in Marketing Cloud is different from the one provided in the form, and if it is, we will update it accordingly:

You do not need to include the above if you already have a process in place that synchronizes email address changes from Sales/Service Cloud to All Subscribers list in Salesforce Marketing Cloud. If you’d like to learn more about synching updates between the clouds, read Markus Slabina’s blog post here.

Custom subscription and profile center full script

As a final touch, to improve the experience, let’s add a confirmation message and a button that will reload the page and display the updated data in the form. Here is the final version of the script, with all of the above changes included:

Remember, that you will need to use the CloudPagesURL function to link to the subscription center CloudPage from an email.

In order to see how the above script works, feel free to play around with one of my test contacts in the test version of the subscription and profile center that I set up on a CloudPage: https://pub.s10.exacttarget.com/

Here are some resources if you would like to read further about subscription management best practices:

  • Here you will find an interesting concept of creating Campaigns for each subscription and adding the Contact as a Campaign Member
  • Here you can read how Effective Email Preference Centers Help Keep Subscribers Active and Engaged
  • Solve problems using the subscription-center and preference-center tags on Salesforce Stack Exchange

Questions? Comments?

Leave a comment below or email me at zuzanna@sfmarketing.cloud.

Trigger SMS text messages using Server-Side JavaScript

In order to be able to programmatically trigger text messages, you will need to have MobileConnect enabled in Marketing Cloud’s Mobile Studio. You will also need to be able to create an installed package in your Marketing Cloud account to interact with Salesforce Marketing Cloud APIs. If you have both in place, we can start by creating a new SMS message.

Create a new message in MobileConnect

Go to Mobile Studio > Mobile Connect and click on Create Message. Choose Outbound and click on Next. In Message Setup, choose a Name, Short/Long Code to be used, From Name and choose API Trigger as the Send Method. Click on Next, type the Outbound Message text and choose the Next Keyword if needed. To finalize, click on Activate. Before you confirm, note the API Key displayed in the pop-up:

The message will now be visible in the Overview screen – make sure it’s status is Active/Scheduled.

Trigger the message using API

In order to trigger a text message, we will have to interact with Salesforce Marketing Cloud’s REST API using the /sms/v1/messageContact/{id}/send route, but before we do that, we will need to authenticate.

Authenticate using Server-Side JavaScript

Let’s start by installing a new, or identifying an existing installed package in your Marketing Cloud account. Note the Client Id and Client Secret as we will need them to authenticate our API request. Make sure that SMS is enabled in the scope of the package you are using:

Depending on the type of the package installed (v2 – enhanced functionality or v1 – legacy functionality), use one of the following code snippets to cover the authentication part of the script.

v1: [see code snippet on Github]

v2: [see code snippet on Github]

Make a messageContact API Request

Below is an example messageContact API Request. The phone number passed in the payload must use the correct format for the designated country code. For example, a mobile number from the United States must include the numerical country code 1 and the area code, eg: 13175551212. [see code snippet on Github]

To ensure that the mobile number exists for the contact and that the contact subscribed to the specified keyword on your short code, set the Subscribe and Resubscribe values to true and specify the keyword parameter. If you’re not sure how to work with keywords, check out this help document: Keywords and Codes.

If the request is valid, the API returns a token that can be used to make a follow-up call to check the status of the request: [see code snippet on Github]

Now, let’s combine the first script snippet we used to authenticate with the messageContact payload and make a POST request. Below will work with the v1 legacy package: [see code snippet on Github]

In the above script, you will need to provide your endpoints, ClientId and ClientSecret (all three can be found in Setup > Apps > Installed Packages). You will also need to insert the message Api Key, the keyword and pass the recipient’s phone number.

Last but not least, always remember to put security measures into practice when setting up this kind of functionality on a CloudPage to prevent your ClientId and ClientSecret from being exposed.


Questions? Comments?

Leave a comment below or email me at zuzanna@sfmarketing.cloud.

Loops in AMPscript and Server-Side JavaScript

In programming languages, loops are a basic, yet a very powerful and indispensable concept. They shorten the code and reduce the need to repeat tasks. A loop is a set of instructions to be executed until a certain condition is met. In this article, we will focus on the most fundamental kind of loop, the for loop, and it’s usage in AMPscript and Server-Side JavaScript.

For loops in AMPscript

NOTE: In this article, we will focus on understanding the basic concepts of working with loops in Salesforce Marketing Cloud. For a strictly technical specification, defer to the following article: AMPscript Process Loops.

A for loop, which is actually the only loop available in AMPscript, lets you execute the same script repeatedly until an ending condition is met.

Let’s use the following example: we have a Data Extension with customer IDs and their ordered items. We want to use that dataset to send an email to each customer, listing the items each of them ordered.

Here’s our Data Extension called Orders:

CustomerIdOrderIdOrderItem
0031t000005D98UAAS4632Women’s Marine Hoodie
0031t000005D98UAAS4632Glass Love Bottle – 16.9 oz
0031t000005D98UAAS4632Eco Ballpoint Pen
0031t00000ZnTENAA33686Men’s Marine Hoodie
0031t00000YEM4ZAAX7354Leather Hampton Watch

In our example, the script contained within the loop would do the following: display a bullet point and display OrderItem name, and repeat the same action until all the OrderItems for a relevant Customer were displayed.

The most important element of any loop is the counter. The counter will define how many times the script in the loop should be executed. In order to define the counter, we must first set the criteria to find all the matching results in our Data Extension. We will use the LookupRows function to look up all rows, that match the Id of the Customer, that we want to send the email to. Then, we will use the RowCount function to determine how many results were found. The outcome of the RowCount function will be our counter and will decide how many times the script inside the loop will be repeated. Here’s the first part of our script, where we count how many records match the criteria: [click here to see the code on Github]

Now let’s think through the loop logic. This is the verbal description of the loop that we would like to build:

Start at 1 and repeat the following in a loop until you reach the number defined in the RowCount variable: display the current index and the name of the OrderItem found in the referring row from the results of the LookupRows function. Increase the index by one and repeat the process. Stop looping once the index reaches the number defined in the counter.

Here’s how this looks in AMPscript: [click here to see the code on Github]

You will notice the next keyword at the end of the loop – each time this keyword is reached, the system compares the current index to the value of the counter defined by the RowCount function. If the value is not equal to the end index, the loop will repeat until the end index is reached.

Here’s a full script that we can now use in an email, with added exception handling that will show “No items to display” in case the LookupRows function doesn’t find any matching records for a subscriber in the Orders Data Extension: [click here to see the code on Github]

For loops in Server-Side Javascript

While JavaScript offers at least five different kinds of loops, and all of those can be used in Salesforce Marketing Cloud, in this article we will focus on the most basic one, the for loop.

We will create a similar solution to the one created in the AMPscript example above. We will use the same Data Exteniosn called Orders and we will use a loop to display all the OrderItems for a Customer on a CloudPage.

The first thing we have to do in order to interact with a data extension via server-side JavaScript is to initialize the Data Extension object. Then, we will use the Server-Side JavaScript Rows.Lookup function to find all rows that match the Id of the Customer. For the purpose of this tutorial, we will hardcode the CustomerId into the script: [click here to see the code on Github]

The above script will return an ArrayList, which is a collection of elements. Arrays use numbers to access its elements and the numbering always starts at zero:

Arrays in JavaScript are zero-based. This means that JavaScript starts counting from zero when it indexes an array. In other words, the index value of the first element in the array is “0” and the index value of the second element is “1”, the third element’s index value is “2”, and so on.

https://blog.kevinchisholm.com/javascript/javascript-array-length-always-one-higher/

In AMPscript we used the RowCount function to determine the counter for our loop. In JavaScript, we will use the Array length Property. Inside the loop, we will display the current index (i) and the name of the element (OrderItem) that has this index number in the ArrayList. Remember that we will start counting at “0”, not at “1” like we did in AMPscript.

Then, we will increase the index by one and repeat the process.

In JavaScript, the ++ notation is the increment operator, which means that i++ is exactly the same thing as i = i+1. The script will stop looping once the index reaches the number defined in the counter (rows.length). Here’s the script: [click here to see the code on Github]

Here’s the full script that we can now use on a CloudPage, with added exception handling that will show “No items to display” in case there are no matching records found in the Orders Data Extension: [click here to see the code on Github]

The is how the results will be displayed on a CloudPage:

Additional resources

Here is a list of additional resources to help you understand both the general concept of loops, as well as using loops in AMPscript and Server-Side JavaScript:


Questions? Comments?

Leave a comment below or email me at zuzanna@sfmarketing.cloud.

Update multiple non-sendable Data Extensions to be sendable

In order to programmatically update the settings of an existing Data Extension, we will interact with Salesforce Marketing Cloud’s SOAP Web Services API using WSProxy. Code snippets in this article will show you how to update a Data Extension, so that a non-sendable Data Extension is turned into a sendable Data Extension, but you can modify the script to update other properties of a Data Extension, like retention settings or field properties.

DataExtension object

The DataExtension object represents a data extension within an account. In order to turn a non-sendable Data Extension into a sendable one, we will have to update three of the object’s properties:

  • IsSendable (xsd:boolean) – Indicates whether you can use a data extension as part of an audience for a message send.
  • SendableDataExtensionField (DataExtensionField) – Indicates the field within a sendable data extension to use as an address as part of a send. Possible values include SubscriberID, CustomerKey, or EmailAddress. The application uses this field to establish a data relationship between a value specified by the SendableSubscriberField property and a value within a sendable data extension.
  • SendableSubscriberField (Attribute) – Indicates field to use as sending address. The application uses this field to establish a data relationship between a subscriber field and a value specified by the SendableDataExtensionField property.

To put it in simple words, we need to set the IsSendable value to true and establish which field in the data extension relates to the Subscriber table. If you do it from the UI, you can for example set it to “ContactKey relates to Subscribers on Subscriber Key” or “EmailAddress relates to Subscribers on Subscriber Key”. Here, we will do exactly the same thing, using the following structure:

SendableDataExtensionField relates to subscribers on SendableSubscriberField

Update Data Extension properties via WSProxy

We will use the updateItem WSProxy function to interact with the DataExtension object. Below script will identify a Data Extension by it’s External Key (CustomerKey), set the IsSendable field to true and establish the following send relationship: “email relates to Subscribers on Subscriber Key”, where email is the Data Extension field of type EmailAddress.

The possible values of the SendableSubscriberField include “Subscriber Key” or “Email Address”, depending on whether the Subscriber Key business rule has been turned on. This is the tricky part of this script, as upon retrieving the properties of a sendable Data Extension, the results will return SendableSubscriberField.Name as “_SubscriberKey”, but you actually need to use “Subscriber Key” in the update call.

Here’s the script that will update a single Data Extension:

Update multiple Data Extensions in one call

We have two possible ways to go when it comes to updating multiple Data Extensions in one call.

If you’re working with a set of Data Extensions that have an identical field name and data type assigned to the field used in the send relationship, for example email field of type EmailAddress, you can use a simple loop to iterate through an array of Data Extension External Keys:

If the field names vary across the Data Extensions, it’s best to use the updateBatch WSProxy function and define properties of each Data Extension separately:

Additional resources

If you would like to learn more about using WSProxy and the DataExtension object, I highly recommend reading Gortonington’s article, WSProxy to copy a data extension.

Retrieve tracking data since account inception using WSProxy

Whether you’re building a data warehouse or are dealing with a legal compliance issue, access to historical tracking data from your Salesforce Marketing Cloud account using the out-of-the-box features is limited.

Data Views are powerful, but only allow you to query for up to six months of subscriber and tracking information.

Tracking extracts provide granular tracking data regarding several different aspects of email send jobs, such as clicks, bounces and unsubscribes. They are not time-restricted like Data Views, but if you want to get tracking data from a specific time range, the start and end dates can only be up to 30 days apart.

The third option to access historical data is to reach out to Salesforce support and ask them for a data export for a specific time range, but this service will come at a hefty price.

The method of retrieving tracking data using SOAP API and WSProxy also has some limitations, mostly related to performance when working with big data volumes, but it can be very useful in many cases where using Data Views or Tracking Extracts is not enough.

Retrieve Tracking Data with SOAP API

To retrieve tracking data using the SOAP API, we will call the SentEvent, OpenEvent, ClickEvent, BounceEvent and UnsubEvent objects, which will allow us to create a structure similar to the one we know from Data Views. Each of those objects has a persistent set of properties, which include: BatchID, ClientID, EventDate, SendID, SubscriberKey and TriggeredSendDefinitionObjectID.

Here is an example SOAP envelope that you could use in Postman to retrieve data from any of the tracking event objects:

Interact with SOAP API using WSProxy

To retrieve data from the tracking event objects using WSProxy, we will have to specify the properties to retrieve and perform the retrieve on each of the objects we are interested in. Here’s an example of retrieving data from the SentEvent object:

We can also add a filter to narrow down the results. You can filter the results by JobID, SubscriberKey or any other object property. Here, we are going to filter by EventDate, which will show us all the events that took place in the given timeframe:

If you run the above script in an account that sends large volumes of emails, you will notice that it only pulls a part of the results and displays a status message: MoreDataAvailable. That’s because the SOAP API returns up to 2500 records at a time per retrieve call. To retrieve all available data for a given timeframe, we need to include pagination of retrieves in our script. Let’s also add an HTML table, so that data is displayed in a more accessible way:

You can do the same with the remaining objects, here are the scripts:

Write retrieved data into a Data Extension

Although this will increase the processing time of the call, it will allow you to have the data ready for further processing without any additional preparations. Below script will create a new Data Extension called 01_SentEvent in your main Data Extensions folder and insert all the retrieved data.

Here are the scripts that will do the same for the remaining objects:

Performance of the retrieve calls

The official Marketing Cloud SOAP API documentation states the following:

In most production implementations, data volume in the account requires you to include specific JobIDs in the filter criteria of the request. If requests that don’t specify a JobID time out during processing, add a JobID in the filter. If specifying a JobID is not possible, or if your implementation requires a broad range of JobIDs, use a data extract-based procedure instead.

Above is true if you are sending heavy volumes of emails each month, but you are not limited to filtering by JobID. You can include any of the object properties in filter criteria. You can, for example, retrieve all send and tracking history for a specific subscriber if you use the SubscriberKey in the filter: filter = {Property: "SubscriberKey", SimpleOperator: "equals", Value: "{{SubscriberKey}}"}

If you’re experiencing time outs when working with the script, try narrowing down the amount of retrieved data by using filters.

Security

Last but not least, always remember to put security measures into practice when setting up this kind of functionality on a CloudPage to prevent your data from being exposed in a breach. For the script to run and either return results onscreen or insert them into a Data Extension, you don’t have to actually publish the CloudPage – just press “Publish”, without further saving it. Or, to be completely safe – create a Script Activity in Automation Studio and run it from there.

Retrieve client IP address and geolocation in CloudPages

There are many reasons for checking the client IP address, most common include tracking and personalization. What can you find out about the visitors of a webpage from their IP address? You can identify their ISP, figure out approximately where they’re located and see how often they (or someone else sharing their router) visit your website.

In the context of CloudPages, we most often see IP tracking for personalization purposes. By identifying the visitor’s location, you can automatically display text in their local language and control what kind of content they see.

Identify client IP using AMPscript

The X-Forwarded-For (XFF) HTTP header is a standard header for identifying the originating IP address of a client connecting to a web server. You can easily access this header by using the AMPscript HTTPRequestHeader function, which will return a specified header from an HTTP request. Here’s how to retrieve an IP address on a CloudPage using AMPscript:

Identify client IP using SSJS

There are dedicated Server-Side JavaScript HTTP Properties Functions, that allow you to retrieve various types of HTTP Request object properties and platform application values. The client browser passes this information to the server during an HTTP interaction, so this object contains information regarding the browser and session. One of the available properties to use with the HTTP Request object is ClientIP, which returns the IP address of the requesting client as a string value. Here’s how to retrieve an IP address on a CloudPage using SSJS:

This is the preferred way to retrieve the client IP, as Request.ClientIP() is a dedicated and supported function, while using the XFF HTTP header proved to be unreliable in the past.

HTTP Properties Functions allow you to retrieve other useful information, for example, browser metadata or the URL of the referring web address.

Discover the precise physical location of a given IP address

The functionality of identifying a physical location of a given IP address requires using a third party API service. There are many IP Geolocation API providers and most of them have a free plan available, as well as paid plans for bigger enterprises. My preferred one is ipify.org, which allows you to run up to 1000 queries per month for free. Once you register, you will obtain your personal apiKey, that will be used for making the calls:

The response will contain information about the country, region, city, latitude, longitude, postal code, timezone and GeoNames Id. Additionally, it will also show autonomous system (AS) info if available.

Click here to see this script in action.

As a side-note, remember that under GDPR, IP addresses are considered personal data. Tracking the IPs of your EEA based users without their consent falls under the rules of GDPR.