This is the third part in an ongoing series, please visit here to read the previous article. This article is intended to give a general overview on SFMC Server-side JavaScript Platform Library and its unique capabilities.

Salesforce Marketing Cloud has two distinct libraries for Server-side JavaScript: Platform and Core Library. For this article, we will be concentrating on the Platform Library.

What is Platform?

The Platform Library is a library of functions that are available exclusively for SFMC SSJS. Unlike Core Library, Platform Library is included in the default declaration block and does not need to be called to be utilized.

Platform functions, in general, are strikingly similar to what is available in AMPscript and performs very similar tasks. Platform can be used inside of email messages, mobile messages, CloudPages, microsites and landing pages.

There are definitely differences between AMPscript and SSJS Platform though. There are some AMPscript functions that are not necessary in SSJS due to native functionality already being available. For instance, ADD() is not needed in SSJS as there are pre-existing native capabilities in JS. For example: ADD(12,2) becomes 12+2. This is also true for most of the remaining math functions.

There are also some functions in AMPscript that do not exist inside of SSJS and have no alternative option. For instance, all the Salesforce related functions are not possible inside of SSJS.

The reverse is true too, there are functions inside of SSJS that are not available or able to be reproduced inside of AMPscript. Many of these functions in Platform are actually related to webpages, API and applications and are wholly unique to SSJS. This includes the Script.Util functions, Response and Request object functions as well as WSProxy.

What Do You Need to Know to Use Platform?

In order to be able to take on the Platform Library in SFMC SSJS, I would recommend having the below prerequisites:

• Basic knowledge of scripting languages and syntax
• Good knowledge of JavaScript and JSON syntax and capabilities
• Basic Knowledge of SFMC Capabilities, Objects (Email, Data Extensions, Lists, etc.), Data Models, Relationships and Activities
• An SFMC Instance to work in as there unfortunately are no Developer Instances available.

That being said though, with all the available resources through places like HowToSFMC, SalesForce Stack Exchange, Email-Geeks, SF Success Community, and other community groups out there – you should never be afraid to take it on regardless of current skill levels. You will have the SFMC community to lean on to help you learn and grow.

The Downsides to Platform:

Let’s first discuss what are the deficiencies of using Platform compared to the alternative options out there:

• AMPscript is usually easier for less technical users to pick up
• AMPscript ‘platform interaction’ functions (Lookups, Insert, Upsert, Update, etc.) tend to be faster/more efficient then Platform.
• Usage in Messaging context should be carefully considered. AMPscript tends to be a bit more straightforward, where SSJS is usually more dynamic – making pre-compilation less viable
• Less direct interaction with the SOAP Objects than what is in Core.
• The way Platform is set up, you will need to use the full Object Properties trail on each function. For instance in Platform it is Platform.Function.Stringify() where in Core, it is Stringify().

The Upsides to Platform:

Now that we got the ‘bad’ out of the way, we can talk about all the awesome things about Platform:

• Allows for a much lower learning curve for those that already have Javascript knowledge in comparison to learning AMPscript
• Language is built for more dynamic and complex scripting capabilities
• Allows the usage of JSON Objects and Arrays – which tend to be easier to parse and utilize in comparison with AMPscripts rowsets.
• Better Looping options (For, While, Do/While, etc.)
• Better Exception Handling via native JavaScript capabilities
• Ability to create custom Functions (similar to Client-Side Javascript) allowing for more efficient repeatable actions or events.
• Performance is more efficient than Core Library
• You can use WSProxy for a more efficient API interaction
• Better web, API and application capabilities than AMPscript offers.

How are Platform and AMPscript Different?

Platform is very closely related to AMPscript, containing many of the same functions and uses. It has functions such as Lookup(), UpsertDE(), ContentBlockByID(), Now() and more.

As I stated earlier, some functions inside AMPscript are missing in SSJS, but most of these are just not necessary inside SSJS as it has native capabilities that can be used.

A good example of this is Concat():

/* AMPscript version */
%%[
SET @combined = CONCAT("This sentence"," is combined now")
]%%

/* SSJS version */
<script runat=server>
  var combined = "This sentence" + " is combined now";
</script>

You will see here that utlizing the + in SSJS will take the two strings and append the second one onto the first – exactly like the CONCAT function in AMPscript.

There are a bunch more of these differences and too many to list here without hi-jacking the article. The major difference between SSJS and AMPscript is its abilities to interact with the web, api and applications. Utilizing The Reponse and Request Objects allow SFMC SSJS to interact with the web client in ways AMPscript cannot. This includes reading HTTP Headers and Browser information from the viewer (including IP, browser version, etc.).

Last but not least there is WSProxy and the Script.Util (Content Syndication functions) capabilities that help set Platform apart from AMPscript. These both offer very powerful capabilities relating to SFMC SOAP and REST API. There is nothing that is available inside of AMPscript that can compare to these.

Now, all of the above listed items are not available in a sendable context and the Response and Request Objects are only possible inside of a webpage or application – meaning they do not come into consideration for messaging needs.

Since Platform is so similar to AMPscript, most of its use-cases are also the same as AMPscript – except for the unique functions. To be fair, for the majority of stuff you code for inside of emails, AMPscript is likely to be your language of choice – but for object/array parsing, advanced procedures/dynamic content or exception handling, SSJS is king.

Groupings of Platform Library:

Below is a quick overview of the Platform functions and groupings. I do not go into details on specific functions or uses, as this article would be then become insanely large, but I hope to be able to provide this info at some point in the future. Currently, I have the sections linked to the corresponding official SFMC docs if you need further info on each function.

API Functions

These functions provide you access to interact with the SOAP API objects inside the platform without requiring you to manually create the call and utilize XML bodies. This utilizes the current BU/Permissions of your user for authentication inside SOAP calls. This is mostly replaced by WSProxy as it is slower and more complex than utilizing WSProxy functions. The only possible exception is for Methods that are not available via WSproxy.

• AddObjectArrayItem
• CreateObject
• InvokeConfigure
• InvokeCreate
• InvokeDelete
• InvokeExecute
• InvokeExtract
• InvokePerform
• InvokeRetrieve
• InvokeSchedule
• InvokeUpdate
• SetObjectProperty

Field and Attribute Functions

This section is a single function and this function is basically a duplicatle of AMPscript AttributeValue() function. It will grab a value from a sendable data source or from All Subscribers.

• Get Attribute Value

HTTP Functions

These functions are used similar to AMPscript. It allows you to utilize RedirctTo in a similar purpose to correctly alias a url for link tracking. It also allows you to automatically encode a string for use as a valid URL.

• RedirectTo
• UrlEncode

Content Functions

This allows you to interact with both classic and Content Builder objects. You are able to call content in (via ID, Key or name) as well as impression region and treatascontent capabilities.

• BeginImpressionRegion
• ContentArea
• ContentAreaByName
• ContentBlockById
• ContentBlockByKey
• ContentBlockByName
• ContentImagebyID
• ContentImagebyKey
• EndImpressionRegion
• TreatAsContent

Data Extensions Functions

This segment allows you to do the same capabilities as you can in AMPscript in interacting with Data Extensions. This includes Deleting, Inserting, Lookups, Updates and Upserts. This also has the difference of ‘DE’ and ‘Data’ – where one is for messages and one is for non-sendable context.

• DeleteData
• DeleteDE
• InsertData
• InsertDE
• Lookup
• LookupOrderedRows
• LookupRows
• UpdateData
• UpdateDE
• UpsertData
• UpsertDE

Date and Time Functions

These functions are identical to AMPscript, but do not have all the same functions that AMPscript offers. For instance, a lot of the formatting stuff is handled natively inside JS, so there is no need for specific functions.

• LocalDateToSystemDate
• Now
• SystemDateToLocalDate

Client Browser Functions

This is only available in a webpage or application. It opens up the ‘Response’ object of Platform. What this means is that you are able to retrieve various types of HTTP Response object properties and application values. As a personal note, this grouping is a treasure trove of capabilities that definitely needs better documentation to show people what is possible here.

• Redirect
• RemoveCookie
• RemoveResponseHeader
• SetCookie
• SetResponseHeader
• Write

Utility Functions

These are the basic encode/decode functions as well as GUID and other miscelanious functions. This includes validation functions as well as the hugely useful ParseJSON, RaiseError and Stringify.

• Base64Decode
• Base64Encode
• GUID
• IsEmailAddress
• IsPhoneNumber
• MD5
• ParseJSON
• RaiseError
• Stringify

AMPscript Variables Functions

Through these functions, you are able to interact with AMPscript variables in the current context. You will need to make sure all variables follow the AMPscript variable-naming syntax. As a note, if you forget to add the @ to your AMPscript variable being referenced, these functions will automatically add a @ prefix to any variable that does not include that prefix.

• GetValue
• SetValue

HTTP Property Functions

This is only available in a webpage or application. Through these functions you gain access to the Request object to grab various values from the requesting server as well as requesting applications. This object contains information regarding the browser and session, allowing you to grab very personalized and specific information based on how the person is navigating to this page/application. This is another awesome feature for SFMC SSJS that is not well documented and slips between the cracks.

Example retrievable properties:

Browser – Returns the following metadata regarding the browser from the Request object as a JSON object:
– Platform
– Browser
– Version
– Major Version Number
– Minor Version Number
ClientIP – Returns the IP address of the requesting client as a string value
HasSSL – Returns a Boolean value indicating whether the current Request object could support SSL (HTTPS) usage, even if not currently using SSL
IsSSL – Returns a Boolean value indicating whether the current Request object used an SSL (HTTPS) connection
Method – Returns the method associated with the Request object in a web context (such as GET or POST) in a string value
QueryString – Returns the full query string for the Request object as a string value
ReferrerURL – Returns the URL of the referring web address in a web context in a string value
RequestURL – Returns the full URL of the Request object as a string value
UserAgent – Returns the name of the browser associated with the Request object as a string value

The following are the built-in functions in this grouping:

• GetCookieValue
• GetFormField
• GetQueryStringParameter
• GetRequestHeader
• GetUserLanguages

Content Syndication Functions

These are honestly my favorite functions that are available to SFMC SSJS. That being said, they are also the most confusing and poorly documented functions in all SFMC (at least in my opinion). The basic functions are the simple HTTPGet and HTTPPost functions, which work very similar to their AMPscript counterparts, but the real gem is the Content Syndication Objects subsection (Script.Util).

• HTTPGet
• HTTPPost

Content Syndication Objects

In basic utilization, this seems very similar to the AJAX XMLHttpRequest Object. There are differences, such as that this is not Asynchronous and it is server-side, not client-side. There also are some different capabilities that XMLHttpRequests can do, that are not possible in the given context for these functions to replicate. I make the comparison for easier understanding of basic construct and syntax.

• Script.Util.HttpResponse
• Script.Util.HttpRequest
• Script.Util.HttpGet

WSProxy

Now we get to the ‘Ace in the hole’ for SFMC SSJS – WSProxy. I will be honest, WSProxy was a major game changer for usage of SSJS in SFMC. It offered almost lightening fast SOAP API capabilities in an easier to manage, easier to create, understand and parse!

I could go on forever about WSProxy, but that will need to be another article so I can give it the attention it deserves. Currently WSProxy only supports SOAP API Objects, but fingers crossed it will eventually be introduced for REST API as well!

Well that is Platform in a nutshell! Hope you enjoyed it as much as I enjoyed writing it. Next one is going to be an overview on Core (at least that is what I am planning). Also make sure to keep your eyes peeled for updates on an upcoming SSJS Guide book that I as well as a ton of very talented individuals are working on.