Ssjs Server Side Javascript

SSJS — Server-Side JavaScript

This skill activates when a practitioner needs to author, debug, or architect Server-Side JavaScript (SSJS) code running inside Salesforce Marketing Cloud. It provides grounded guidance on execution environments, WSProxy for SOAP access, HTTP functions for REST calls, error handling, variable scoping rules, and the SSJS/AMPscript interoperability model.

Before Starting

Gather this context before working on anything in this domain:

• Execution context: is this running in a Script Activity (Automation Studio), a Cloud Page, or a Landing Page? The timeout, available functions, and subscriber context differ across contexts.
• API target: if calling SOAP APIs (retrieve/upsert Data Extensions, send Email, etc.), WSProxy is preferred over raw HTTP+XML. If calling external REST endpoints, use Script.Util.HttpRequest.
• Most common wrong assumption: SSJS is modern JavaScript. It is not. Marketing Cloud runs an ES3-compatible engine — let, const, arrow functions, template literals, destructuring, and Promises are unavailable.
• Limits: Script Activities time out at 30 minutes and have a 6 GB memory limit per execution. Cloud Pages have no documented long-execution window and should be treated as synchronous request/response.

Core Concepts

Execution Environments and the <script runat="server"> Tag

SSJS code must be wrapped in <script runat="server"> tags. Without the runat="server" attribute the block is treated as client-side JavaScript and does not execute on the Marketing Cloud server. SSJS can coexist with AMPscript in the same file — the Marketing Cloud rendering engine processes AMPscript substitutions first, then evaluates SSJS blocks. This allows AMPscript variables to be referenced inside SSJS if the AMPscript block is declared before the SSJS block.

WSProxy — Preferred SOAP API Client

WSProxy (Script.Util.WSProxy) is the built-in Marketing Cloud SOAP API client for SSJS. It is the correct and preferred way to interact with Marketing Cloud objects (Data Extensions, Subscribers, Sends, etc.) from SSJS because:

• It handles SOAP envelope construction, authentication token injection, and paging automatically.
• It has significantly lower overhead than constructing raw SOAP XML via Script.Util.HttpRequest.
• Common operations: retrieve, createItem, updateItem, upsertBatch, deleteItem.

The core pattern:

var prox = new Script.Util.WSProxy();
var cols = ["SubscriberKey", "EmailAddress", "Status"];
var filter = {
  Property: "Status",
  SimpleOperator: "equals",
  Value: "Active"
};
var result = prox.retrieve("Subscriber", cols, filter);

Retrieve results are paged. If result.HasMoreRows is true, use prox.getNextPage() to iterate.

Script.Util.HttpRequest — Outbound REST/HTTP

For calls to external REST APIs or non-Marketing Cloud SOAP endpoints, use Script.Util.HttpRequest. This is a synchronous HTTP client that supports GET, POST, PUT, PATCH, and DELETE. Set headers and body before calling request.send().

var req = new Script.Util.HttpRequest("https://api.example.com/data");
req.emptyContentHandling = 0;
req.retryCount = 2;
req.setHeader("Content-Type", "application/json");
req.setHeader("Authorization", "Bearer " + token);
req.method = "POST";
req.postData = Stringify(payload);
var resp = req.send();
var body = Platform.Function.ParseJSON(resp.content);

Error Handling and the Write() Logging Pattern

SSJS does not surface uncaught exceptions to the user in a useful way in Script Activities — an uncaught exception causes the entire Activity step to fail with a generic error, which makes diagnosis difficult. The mandatory pattern is try/catch around all significant operations with Write() logging inside the catch block.

Write() outputs text to the Script Activity log tab in Automation Studio, making it the primary debugging mechanism. Log the error message, stack if available, and any relevant variable state before re-throwing or gracefully continuing.

ES3 Dialect Constraints

The SSJS engine is ES3-compatible. This means:

• Use var for variable declarations — let and const cause syntax errors.
• No arrow functions (=>); use function keyword.
• No template literals (backtick strings); use + concatenation.
• No destructuring, spread, or Promise.
• JSON.stringify / JSON.parse are not available — use Stringify() and Platform.Function.ParseJSON() instead.
• typeof, instanceof, standard for loops, and try/catch/finally work normally.

Common Patterns

WSProxy Upsert to a Data Extension

When to use: Bulk insert or update records in a Data Extension from a Script Activity, typically after retrieving data from an external API or another system.

How it works:

<script runat="server">
Platform.Load("Core", "1.1.1");
try {
  var prox = new Script.Util.WSProxy();
  var rows = [
    { keys: { SubscriberKey: "abc123" }, values: { FirstName: "Ana", Score: "95" } },
    { keys: { SubscriberKey: "def456" }, values: { FirstName: "Ben", Score: "80" } }
  ];
  var result = prox.upsertBatch("DataExtensionObject", rows, { Name: "My_DE_ExternalKey" });
  Write("Upserted: " + result.Status);
} catch(e) {
  Write("ERROR: " + e.message);
}
</script>

Why not the alternative: Using AMPscript UpsertDE() works for small single-record updates inside sends, but it cannot handle batch operations, does not provide programmatic status checking, and is not appropriate for Automation Studio Script Activities.

Outbound REST Call with Error Logging

When to use: Pulling data from an external REST API (CRM, ERP, custom backend) inside a Script Activity and writing results to a Data Extension.

How it works:

<script runat="server">
Platform.Load("Core", "1.1.1");
try {
  var req = new Script.Util.HttpRequest("https://api.example.com/leads");
  req.emptyContentHandling = 0;
  req.retryCount = 1;
  req.setHeader("Authorization", "Bearer MyToken");
  req.method = "GET";
  var resp = req.send();
  if (resp.statusCode != 200) {
    throw new Error("HTTP error: " + resp.statusCode);
  }
  var data = Platform.Function.ParseJSON(resp.content);
  // process data...
  Write("Retrieved " + data.length + " leads.");
} catch(e) {
  Write("FAILED: " + e.message);
  // log to error DE if needed
}
</script>

Decision Guidance

Recommended Workflow

Step-by-step instructions for an AI agent or practitioner working on this task:

1. Confirm execution context — identify whether this is a Script Activity, Cloud Page, or Landing Page. Script Activity: check timeout risk (30-min limit). Cloud Page: check whether code needs to be synchronous and handle subscriber context.
2. Identify the API target — if interacting with Marketing Cloud objects (Data Extensions, Subscribers, Sends), plan to use WSProxy. If calling external endpoints, plan to use Script.Util.HttpRequest.
3. Author the SSJS block — wrap all code in <script runat="server"> tags. Load the Core library with Platform.Load("Core", "1.1.1"). Use only var for declarations. Use Stringify() and Platform.Function.ParseJSON() instead of JSON.stringify/JSON.parse.
4. Wrap in try/catch — every meaningful operation (API call, WSProxy call, data write) must be inside a try/catch block with Write() logging in the catch. Never allow uncaught exceptions in Script Activities.
5. Implement paging if using WSProxy retrieve — check result.HasMoreRows after every prox.retrieve() call and loop with prox.getNextPage() until false to avoid silently missing records.
6. Test incrementally — run the Script Activity manually in Automation Studio, check the Activity log tab for Write() output, verify DE row counts before and after.
7. Review for ES3 compatibility — scan for let, const, arrow functions, template literals, JSON.stringify, JSON.parse, Promise, and async/await — all are unsupported and will cause syntax or runtime errors.

Review Checklist

Run through these before marking work in this area complete:

• All code is inside <script runat="server"> tags
• Platform.Load("Core", "1.1.1") is present at the top of the block
• No let, const, arrow functions, template literals, or modern JS syntax
• All API calls and data writes are wrapped in try/catch with Write() in the catch block
• WSProxy retrieve loops check HasMoreRows and call getNextPage() if paging is possible
• Script.Util.HttpRequest calls check resp.statusCode before consuming resp.content
• Sensitive values (tokens, passwords) are stored in Data Extensions or Content Builder, not hardcoded

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Script Activity 30-minute timeout is absolute — If a Script Activity exceeds 30 minutes of execution time, it terminates without completing and the step is marked as an error. There is no graceful shutdown callback. For large-volume operations, split work across multiple Activities or use Query Activities for set-based data operations instead.

2. WSProxy retrieve does not return all rows by default — prox.retrieve() returns a paged result set. If you do not check result.HasMoreRows and call prox.getNextPage(), you silently process only the first page of results (typically 2,500 rows). This causes data processing gaps that are very hard to detect.

3. AMPscript is evaluated before SSJS — In a mixed file, AMPscript variable substitution happens before the SSJS engine runs. This means AMPscript @variables can inject values into SSJS string literals, but SSJS variables cannot be read by AMPscript in the same file. Relying on SSJS output being available to AMPscript in the same render pass will not work.

Output Artifacts

Related Skills

• data/marketing-cloud-sql-queries — Use for set-based data transformation inside Automation Studio; SQL Query Activity is more efficient than SSJS loops for bulk DE-to-DE operations
• data/marketing-cloud-data-sync — Use when the goal is syncing data between Marketing Cloud and external systems at the platform configuration level rather than via SSJS scripting
• admin/consent-management-marketing — Use when SSJS is being used to read or write subscription/preference data; consent rules affect which DE fields are writable