This is the fourth 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 Core 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 Core Library.
Core Library
SFMC Core SSJS is a JavaScript library, which basically just means it is pre-written JavaScript that you can reference for easier development (similar to Client-side JS Libraries). The main difference is that Core is the only library that can be referenced with SFMC SSJS. You are unable to create your own libraries or reference any other libraries in SSJS as you can in Client-side JavaScript.
By utilizing Core, you open up quite a few different options that are basically ‘shortcuts’ for SOAP API calls inside of Email Studio. These functions allow you to accomplish many awesome things not possible natively in Platform/AMPscript, including interacting with objects like Data Extensions, Subscriber, Account, Email, Triggers and more. Core mostly is used inside of non-sendable environments – but some functions are able to be used in messaging context.
Core Versions
Core supports ECMAscript 3.0 (European Computer Manufacturer’s Association) which is a code standard set for JavaScript. You can use this info to help better define what capabilities are available for SSJS. As a note, I believe the current version for ECMAscript is 11, so keep in mind that it is a much older version, so a lot of new capabilities are not available.
In order to utilize Core, you will need to ‘call’ in the library via Platform.Load('Core', '1.1.1'). Note that there is confusion on the ‘versions’ available for Core. As declared inside the docs, ‘1.1.1’ seems to be the most recent version and what I would recommend using.
Methods
Core supports the following methods:
(some not available in certain objects)
- Add – Invokes the web service API Create method on an API object
- Remove – Invokes the web service API Delete method on an API object
- Update – Invokes the web service API Update method on an API object
- Retrieve – Invokes the web service API Retrieve method on an API object
To Use Core:
- Decent Knowledge of JavaScript and JSON
- Knowledge of SOAP Objects/Properties inside of SFMC
- Basic Knowledge of SFMC capabilities and Data Objects/Relationships
The Cons:
- Very structured, not allowing you to customize usage
- The documentation needs lots of love
- Less efficient as volume increases
- The returned information can be very vague
The Pros:
- Simpler to utilize/understand in comparison to WSProxy or an API call
- Give options and capabilities you cannot get via Platform/AMPscript
- Easy replication across Platforms/BUs – do not need to rebuild functions
To be fair, many of the capabilities afforded to you via Core can be duplicated through WSProxy – but for smaller volume uses the Core functions are usually more performant and code efficient. For instance, retrieving a single data extension object via the Core function, would be faster and less of a resource draw than utilizing a WSProxy Retrieve on the same data extension object. But if you are retrieving a batch of data extensions, WSProxy becomes the better choice exponentially as volume increases.
Now, that being said, calling in the Core library and utilizing Core functions can cause a slow down in processing when compared to Platform. This is because Core winds up being ‘translated’ a few more times behind the curtain prior to the execution compared to AMPScript and Platform. But it also offers more powerful functionality and capabilities.
Core Library Groupings/Objects:
Core opens the gate to be able to interact with SOAP objects ‘behind the scenes’ inside Marketing Cloud through a simpler and more familiar method (to those that already have background in JS). You can interact with Objects like:
Load
To load the Core Library, you need to use the following code:
Platform.Load("Core","1.1.1");Account Functions
Utilize these functions to access and modify accounts within your Marketing Cloud account. Please note that many of these functions will only work inside of the Parent level BU environment.
Initialization
To interact with the Account Functions, you will need to initialize the object (via CustomerKey). This will need to be done prior to any other Account functions.
Account.Init("myAccountCustomerKey");Function List:
Retrieve – Retrieve an account based on the specified criteria
Tracking.Retrieve – Returns array of tracking data related to the account specified
Update – Updates account and returns status
AccountUser Functions
Utilize these functions to access and modify users within your Marketing Cloud account. Please note that many of these functions will only work inside of the Parent level BU environment.
Initialization
To interact with the AccountUser Functions, you will need to initialize the object (via ExternalKey and, if in child BU, the clientId). Your current user will require the correct permissions in order to be able to utilize these functions.
var acctUser = AccountUser.Init("myUserExternalKey","myClientID");Function List:
Activate – Activates an account user
Add – Creates a new account user
Deactivate – Deactivates an account user
Retrieve – Retrieves an account user based on filter
Update – Updates account and returns status
Content Area Functions
Utilize these functions to create and edit Classic Content Areas (not Content Builder Blocks) within your Marketing Cloud account.
Initialization
To interact with a content area, you will need to initialize the object (via ExternalKey).
var contentArea = ContentAreaObj.Init("myExternalKey");Function List:
Add – Adds a new content area and returns initialized object
Remove – Removes a content area
Retrieve – Retrieves a content area
Update – Updates a content area and returns status
Data Extension Functions
Utilize these functions to access and modify the Data Extension Object as well as the rows contained inside of the Data Extension.
Initialization
To interact with a data extension, you will need to initialize the object (via ExternalKey).
var de = DataExtension.Init("myExternalKey");Function List:
Add – Creates a new Data Extension and returns initialized object
Fields – Sub-Object that allows you to add/manipulate fields in a Data Extension
Fields.Add – Add a new field to an existing data extension
Fields.Retrieve – Returns array of JSON Objects for each field in Data Extension
Fields.UpdateSendableField – updates a field to be the ‘Sendable’ field inside the Data Exension
Retrieve – Retrieves an array of Data Extension objects based on filter
Rows – Sub-Object that you can interact with rows (data) inside of a Data Extension
Rows.Add – Adds a new row to a Data Extension
Rows.Lookup – Returns columns that match specified values. Similar to Platform lookuprows function
Rows.Remove – Deletes a row from the associated Data Extension
Rows.Retrieve – Retrieves up to 2500 rows from a data extension based on filters
Rows.Update – Updates row(s) specified with a new value
DateTime Functions
Utilize these functions to access date and time data for use in content and send contexts
Function List:
LocalDateToSystemDate – Converts passed datetime string from local time (based on SFMC user setting) to system time
Now – Returns current system date and time
Retrieve – Retrieves array of time zones based on filter
SystemDateToLocalDate – Converts passed datetime string from system time to local time (based on SFMC user setting)
Delivery Profile Functions
Utilize these functions to access and control delivery profiles within your SFMC Account. Can only be used in a non-sendable environment
Initialization
To interact with the Delivery Profile Functions, you will need to initialize the object (via ExternalKey).
var deliveryProfile = DeliveryProfile.Init("myExternalKey");Function List:
Add – Adds new delivery profile and returns initilized object
Remove – Deletes existing delivery profile
Update – Updates existing delivery profile
Email Functions
Utilize these functions to access and control Classic Emails (not Content Builder Emails) within your Marketing Cloud account.
Initialization
To interact with an email, you will need to initialize the object (via ExternalKey).
var email = Email.Init("myExternalKey");Function List:
Add – Adds a new email and returns initialized object
Check Content – Runs a content check and returns JSON object with results
Remove – Deletes email and returns status
Retrieve – Retrieves array of emails based on filter
Update – Updates email and returns status
Validate – Runs validation check and returns JSON object with results
Events Functions
Utilize these functions to retrieve and use information related to specific events occuring as part of message sends.
Events:
- Click
- ForwardedEmail
- ForwardedEmailOptIn
- HardBounce
- NotSent
- Open
- OtherBounce
- Sent
- SoftBounce
- Survey
- Unsubscribe
Function List:
Retrieve – Retrieves information based on events occuring related to specific message
Filter Definition Functions
Utilize these functions to manipulate data filters in SFMC.
Initialization
To interact with a filter definition, you will need to initialize the object (via ExternalKey).
var filter = FilterDefinition.Init("myExternalKey")Function List:
Add – Adds a new filter definition and returns initialized object
Remove – Deletes filter definition and returns status
Retrieve – Retrieves array of filter definitions based on filter
Update – Updates filter definition and returns status
Folder Functions
Utilize these functions to access and control folders in your SFMC account.
Initialization
To interact with a folder, you will need to initialize the object (via ExternalKey) or assigning it to an ID number.
var folder = Folder.Init("myExternalKey");
//OR
var folderByID = Folder.Init();
folderByID.SetID(12345);Function List:
Add – Adds a new folder and returns initialized object
Remove – Deletes folder and returns status
Retrieve – Retrieves array of folders based on filter
Update – Updates folder and returns status
HTTP Functions
Utilize these functions to perform GET and POST actions
Function List:
Get – Performs HTTP GET and returns JSON object containing status and response
IsCHTMLBrowser – Recognizes if client is a CHTML browser
Post – Performs HTTP POST and returns JSON object containing status and response
List Functions
Utilize these functions to access lists contained in your SFMC account.
Initialization
To interact with a list, you will need to initialize the object (via ExternalKey). Some functions do not require the initialization
var list = List.Init("myExternalKey");Function List:
Add – Adds a new list and returns initialized object
Remove – Deletes list and returns status
Retrieve – Retrieves list based on filter
Subscribers – Sub-Object that allows you to interact with subscribers contained inside initialized list
Subscribers.Add – Add subscriber to list
Subscribers.Retrieve – Retrieves array of subscribers based on filter
Subscribers.Tracking.Retrieve – Returns array of tracking data related to subscribers in list based on filter
Subscribers.Unsubscribe – Unsubscribes specified subscriber from list
Subscribers.Update – Update specific subscriber on list
Subscribers.Upsert – Add/Update specific subscriber on list
Portfolio Functions
Utilize these functions to access and control Classic Portfolio items (not Content Builder) within your Marketing Cloud account.
Initialization
To interact with a Portfolio item, you will need to initialize the object (via ExternalKey).
var portObj = Portfolio.Init("myExternalKey");Function List:
Add – Adds a new Portfolio item and returns initialized object
Remove – Deletes Portfolio item and returns status
Retrieve – Retrieves array of Portfolio item based on filter
Update – Updates Portfolio item and returns status
Query Definition Functions
Utilize these functions to access and control query definitions in your SFMC account.
Initialization
To interact with a query definition, you will need to initialize the object (via ExternalKey).
var query = QueryDefinition.Init("myExternalKey");Function List:
Add – Adds a new query definition and returns initialized object
Perform – Runs an existing query definition
Remove – Deletes query definition and returns status
Retrieve – Retrieves array of query definition based on filter
Update – Updates query definition and returns status
Recipient Functions
Please note that the documentation incorrectly shows information about Query instead of recipient. This essentially is an Object that allows you to pull attributes or fields from the sendable data – similar to AMPScripts AttributeValue()
Function List:
Attribute.GetValue – Almost identical to the AttributeValue() function in AMPScript
Send Classification Functions
Utilize these functions to access and control send classifications within your SFMC Account. Can only be used in a non-sendable environment
Initialization
To interact with the Send Classification Functions, you will need to initialize the object (via ExternalKey).
var sendClassification = SendClassification.Init("myExternalKey");Function List:
Add – Adds new send classification and returns initilized object
Remove – Deletes existing send classification
Retrieve – Retrieves an array of send classifications based on filter
Update – Updates existing send classification
Send Functions
Utilize these functions to access and control how emails are sent within your Marketing Cloud account.
Initialization
To interact with an exist send, you will need to initialize the object (via ExternalKey).
var sendObj = Send.Init("myExternalKey");Function List:
Add – Adds a new send
CancelSend – Cancels an existing scheduled send
Send Definition – Sub-Object allowing you to interact with send definitions (user-initiated sends)
Definition.Add – Adds a new send definition using lists
Definition.AddWithDE – Adds a new send definition using Data Extensions
Definition.AddWithFilterDefinition – Adds a new send definition using Filters
Definition.Remove – Deletes an existing send definition
Definition.Retrieve – Retrieves array of send definitions based on filter
Definition.Send – Initiate an immediate send of an existing send definition
Definition.Update – Update an existing send definition
Remove – Removes an initialized send
Retrieve – Retrieves array of sends based on filter
RetrieveLists – Retrieves information on which lists used by a Send event
Tracking – Sub-Object to retrieve tracking information relating to a send
Tracking.ClicksRetrieve – returns click tracking info based on a filter
Tracking.Retrieve – returns array of tracking data related to a send by filter
Tracking.TotalByIntervalRetrieve – returns tracking data related to a send specified by type, duration and interval
Sender Profile Functions
Utilize these functions to access and control sender profiles within your SFMC Account. Can only be used in a non-sendable environment
Initialization
To interact with the Send Classification Functions, you will need to initialize the object (via ExternalKey).
var senderProfile = SenderProfile.Init("myExternalKey");Function List:
Add – Adds new sender profile and returns initilized object
Remove – Deletes existing sender profile
Update – Updates existing sender profile
Subscriber Functions
Utilize these functions to access subscribers contained in your SFMC account.
Initialization
To interact with a subscriber, you will need to initialize the object (via ExternalKey). Some functions do not require the initialization
var sub = Subscriber.Init("myExternalKey");Function List:
Add – Adds a new subscriber and returns initialized object
Attributes.Retrieve – returns array of attributes of subscriber
Lists.Retrieve – returns array of lists subscriber is on
Remove – Deletes subscriber
Retrieve – Retrieves array of subscribers based on filter
Statistics – Retrieves object containing send, click and open stats
Unsubscribe – Unsubscribe subscriber
Update – Update subscriber
Upsert – Add/Update subscriber
Template Functions
Utilize these functions to access and control Classic templates (Not Content Builder) in your SFMC account
Initialization
To interact with the Template Functions, you will need to initialize the object (via ExternalKey).
var template = Template.Init("myExternalKey");Function List:
Add – Adds new template and returns initilized object
Retrieve – Retrieves a template based on filter
Update – Updates existing template
Triggered Send Functions
Utilize these functions to access and control triggered emails within your Marketing Cloud account.
Initialization
To interact with an exist send, you will need to initialize the object (via ExternalKey).
var tsd = TriggeredSend.Init("myExternalKey");Function List:
Add – Adds a new triggered send
Pause – Pause an existing running triggered send
Publish – Publish an existing non-running triggered send
Retrieve – Retrieves array of triggered sends based on filter
Send – Sends an email message using an existing, running triggered send
Start – Starts an existing non-running triggered send
Tracking – Sub-Object to retrieve tracking information relating to a triggered send
Tracking.ClicksRetrieve – returns click tracking info based on a filter
Tracking.Retrieve – returns array of tracking data related to a triggered send by filter
Tracking.TotalByIntervalRetrieve – returns tracking data related to a triggered send specified by type, duration and interval
Update – Update an existing non-running triggered send
Utilities Functions
Utilize these functions to load and modify data in your SFMC account. I am only giving a very top level snapshot as there are a ton of these and I could not do them justice in this article. I highly recommend doing your own dive into these functions inside the documents.
Function List:
Application Utility – Use these functions to interact with a SFMC application
Base64 Utility – Encode/Decode strings as Base64
Content Area Utlility – Interact with Classic Content Areas (not Content Builder Blocks)
HTTPHeader Object Utlility – Add, Retrieve and Remove info from HTTP Header
Impression Region Utlility – Interact with Impression Regions in Content Areas (similar to AMPScript)
Request Object Utlility – Get information from parameters in URL or form post
String Utlility – Process and Transform strings
Variable Utlility – Get/Set AMPScript values
In Conclusion
Well, that is SFMC SSJS Core Library in a nutshell. As always please drop a comment or email if you saw something I missed or needs correction. Next article should be on WSProxy, hope to see you there!