Learn About Server-Side JavaScript
Learning Objectives
After completing this unit, you'll be able to:
- Review the fundamentals and syntax for server-side JavaScript (SSJS).
- Know when to use Core and Platform SSJS libraries.
- Implement SSJS functions and operators.
- Work with SSJS examples and best practices.
While Marketing Cloud Engagement offers an integrated programmatic language with AMPscript, it’s not always convenient to learn an entirely new way of interacting with a platform. To help developers get started more quickly, Marketing Cloud Engagement put together server-side JavaScript (SSJS). The syntax and format should look familiar to web developers, but Marketing Cloud Engagement customized the language to function specifically with Marketing Cloud Engagement activities.
These functions don’t just allow access to Marketing Cloud Engagement activities—they also let you use functionality that doesn’t exist in AMPscript.
- You can use arrays in SSJS.
- You can use the EVAL function in SSJS.
- SSJS handles more advanced exception handling, including try catch blocks.
Before diving in, remember that SSJS does not work with external JavaScript libraries and you can’t work with the DOM.
SSJS Syntax and Personalization Strings
SSJS appears in Marketing Cloud Engagement as a code block, like this example.
<script runat=server language="JavaScript"> [Insert JavaScript Here] </script>
Or you can just open the block with <script runat=server> and simplify the whole matter.
SSJS also offers personalization strings to insert values from several different sources.
- ctrl:field—Subscriber and system attributes from lists and sendable data extensions
- ctrl:var—Variables
- ctrl:eval—Functions and SSJS code expressions
Here are some examples.
If you want to pull a contact’s full name into a landing page, you can use this example.
<ctrl:field name=FullName />
This example returns the contactZIP variable, along with a default value if no value exists and a format for that number.
<ctrl:var name=contactZIP default=46201 format=g />
If you want to make the variable value uppercase, you can use a function like this one.
<ctrl:eval language=javascript default=none format=G>MyVal.toUpper()</ctrl:eval>
SSJS Libraries
SSJS offers two libraries, and you may notice some overlap between them. Both allow you to use standard JSON and JavaScript functionality, but you use the libraries at different times. So how do you know which one to use? There's a simple answer to that question.
- Are you including SSJS in email or SMS messages? Use the Platform library.
- Are you building landing pages or applications? Use the Core library.
Platform functions resemble their AMPscript counterparts and always begin with the Platform prefix. Otherwise, you can accomplish the same kinds of tasks as you can with AMPscript.
- Retrieve and modify account information.
- Interact with account users.
- Interact with content areas.
- Add, retrieve, delete, and update data extension information.
- Perform date and time functions.
- Create and send email messages and triggered sends.
- Create, retrieve, update, and delete subscriber information.
- Interact with HTTP functions and information.
- Use a variety of utility and evaluation functions.
SSJS also supports these methods.
| Method Name |
Functionality |
| Add |
Invokes the SOAP API Create method on an API object |
| Remove |
Invokes the SOAP API Delete method on an API object |
| Update |
Invokes the SOAP API Update method on an API object |
| Retrieve |
Invokes the SOAP API Retrieve method on an API object |
Next, let's look at how to retrieve data with SSJS. This function pulls data from the same location as the AMPscript example in the previous unit.
<script runat="server">
var dataRows = Platform.Function.LookupRows('Purchases','MemberID',memID);
</script>
Now let's expand on that function and write those rows to an email.
<script runat="server">
var dataRows = Platform.Function.LookupRows('CustomerData','Company','exampleCompany');
if(dataRows && dataRows.length > 0) {
for(var i=0; i<dataRows.length; i++) {
Platform.Response.Write(dataRows[i]["Email"]);
}
}
</script>
If you want to add some more content to an email message, you can bring in content areas using several methods, including the key value shown in this example.
<script runat="server">
var content = Platform.Function.ContentBlockByKey("myExternalKey","impressionRegion",false,"defaultContentHere");
</script>
The additional parameters allow you to specify an impression region for the content area, choose whether the insertion call stops if it encounters an error, and insert some default content if your specific content area can’t be found.
Next, we take a closer look at Guide Template Language (GTL).
