Util · Variable · Request — Referencia de SSJS en Marketing Cloud | Cleon

Esta página cubre las superficies SSJS que no entran en otra categoría pero aparecen constantemente en producción: el namespace Variable para intercambiar valores con AMPscript adentro de bloques de script de email, el objeto Request para leer params de URL y campos de form en CloudPages, Platform.Function.RaiseError para surfacear errores de vuelta al caller, y Platform.Function.GetSetting para leer configuración del tenant. Superficie chica, alta frecuencia de uso — y el único capítulo donde SSJS deja de ser un lenguaje self-contained y empieza a ser un runtime de pegamento entre AMPscript, el ciclo de vida del request, y el entorno SFMC.

Sintaxis oficial

`Variable.*` — interop AMPscript ↔ SSJS

Usado en bloques de script de email donde AMPscript y SSJS coexisten. Las variables AMPscript se prefijan con @; SSJS lee/escribe a través de Variable.GetValue / Variable.SetValue.

%%[ /* AMPscript declara + setea */
  VAR @firstName, @loyaltyTier
  SET @firstName = AttributeValue("FirstName")
  SET @loyaltyTier = "gold"
]%%

<script runat="server" language="javascript">
Platform.Load("Core", "1.1.5");

// SSJS lee lo que AMPscript seteó
var name = Variable.GetValue("@firstName");
var tier = Variable.GetValue("@loyaltyTier");

// SSJS escribe un valor que AMPscript puede leer después de este bloque
var greeting = "Hola " + name + ", sos tier " + tier;
Variable.SetValue("@greeting", greeting);
</script>

%%[ /* AMPscript lee lo que SSJS seteó */
  Output(v(@greeting))
]%%

El interop es per-mensaje, per-bloque-script. Los valores no persisten a un Data Extension automáticamente; viven en el contexto de personalización de ese send.

`Request.*` — acceso a URL + form de CloudPage

Usado en SSJS de CloudPage donde un request de usuario llega a la página. El objeto Request expone el ciclo de vida del request.

Platform.Load("Core", "1.1.5");

// Parámetros de query string (?email=...&token=...)
var email = Request.GetQueryStringParameter("email");
var token = Request.GetQueryStringParameter("token");

// Campos de form (submissions POST a la misma página)
var formEmail = Request.GetFormField("email");

// Metadata del request
var ua = Request.GetUserAgent();
var ip = Request.GetUserHostName();
var referrer = Request.GetReferrer();
var method = Request.Method;          // "GET" o "POST"

// Body crudo del request (para webhooks / endpoints API rendereados como CloudPages)
var rawBody = Platform.Request.GetPostData();

`Platform.Function.RaiseError` — surfacear errores de vuelta al caller

La forma más limpia de fallar un paso de Script Activity (o renderear un error en una CloudPage) es raisear un error explícito. El log de corrida de la Activity captura el mensaje; la Automation puede configurarse para halt en la falla o continuar.

Platform.Load("Core", "1.1.5");

if (rows.length === 0) {
  // Halt el script con un mensaje de error explícito
  Platform.Function.RaiseError("Ningún subscriber matcheó el filtro — abortando build de send.", true);
  // El segundo argumento 'true' incluye el call stack en el error.
}

Para captura de error inline sin halt, el idiom más viejo Stack.Push todavía funciona en algunos tenants:

try {
  Platform.Function.UpsertData("master_subs", ["SubscriberKey"], [key], cols, vals);
} catch (e) {
  // Loguea a un DE
  Platform.Function.UpsertData(
    "de_log_errors",
    ["RunId"], [runId],
    ["Step","Msg","Ts"], ["upsert", e.message, Now()]
  );
  // Decidí: re-raise o tragar
  Platform.Function.RaiseError("Falló el upsert: " + e.message, true);
}

`Platform.Function.GetSetting` — leer settings del tenant

Alguna configuración instalada en momento de install se expone vía GetSetting. Útil para lógica environment-aware sin hardcodear valores.

Platform.Load("Core", "1.1.5");

var instance = Platform.Function.GetSetting("instance");           // ej. "s10.exacttarget.com"
var account = Platform.Function.GetSetting("MID");                 // MID numérico

El set exacto de nombres de setting disponibles depende del tenant. Consultá los docs de Salesforce Help para tu edición.

Resumen de referencia

| Función | Contexto | Devuelve | Usar para | |---|---|---|---| | Variable.GetValue("@name") | Bloque script email | String / valor | Leer var AMPscript en SSJS | | Variable.SetValue("@name", v) | Bloque script email | (void) | Escribir valor SSJS en var AMPscript | | Request.GetQueryStringParameter(name) | CloudPage | String / null | Leer param URL query | | Request.GetFormField(name) | CloudPage | String / null | Leer campo POST form | | Request.GetUserAgent() | CloudPage | String | UA del browser | | Request.GetUserHostName() | CloudPage | String | IP / hostname del cliente | | Request.GetReferrer() | CloudPage | String | Header HTTP Referer | | Request.Method | CloudPage | "GET" / "POST" | Método HTTP | | Platform.Request.GetPostData() | CloudPage | String | Body crudo del request | | Platform.Function.RaiseError(msg, includeStack) | Cualquier lado | (tira) | Halt con error explícito | | Platform.Function.GetSetting(name) | Cualquier lado | String / valor | Leer configuración del tenant |

Referencia:

Lo que sobrevive en producción

`Request.GetQueryStringParameter` devuelve `null` para params faltantes — no string vacío

Una forma de bug común: código que asume que un param faltante va a ser "" y lo concatena en una URL o escritura de DE. El resultado es el string literal "null" (por cómo + coerce — ver funciones de string).

// EN RIESGO — si 'email' no está en la URL, el mensaje de log se vuelve "User: null"
var email = Request.GetQueryStringParameter("email");
Write("User: " + email);

// SEGURO — coalesce valores faltantes explícitamente
var email = Request.GetQueryStringParameter("email") || "";
// O con guard explícito
var email = Request.GetQueryStringParameter("email");
if (email == null) {
  Platform.Function.RaiseError("Falta param de query 'email' requerido.", true);
}

La elección correcta depende de si el param es requerido (raisear error) o opcional (default a "" o algún centinela).

Siempre validá input del usuario antes de usarlo en escrituras de DE o construcción de URL

Cualquier cosa de Request.GetQueryStringParameter o Request.GetFormField es untrusted. SSJS no lo escapa por vos. Largo, character set, y formato tienen que chequearse explícitamente antes de que el valor llegue a una escritura de DE o una redirect URL.

// EN RIESGO — parámetro 'next' del usuario pegado a redirect, sin validación
var next = Request.GetQueryStringParameter("next");
Platform.Response.Redirect(next);
// Vulnerabilidad de open redirect: un atacante puede hacer ?next=https://evil.com
// y tu CloudPage redirige a su sitio

// SEGURO — whitelist de targets de redirect permitidos
var next = Request.GetQueryStringParameter("next");
var allowed = ["/preferences", "/done", "/help"];
var safeNext = "/done";
for (var i = 0; i < allowed.length; i++) {
  if (next === allowed[i]) { safeNext = next; break; }
}
Platform.Response.Redirect(safeNext);

La disciplina: nunca pases input del usuario directo a un redirect, una escritura de DE, o un input de SQL Activity sin validación. La lista de valores permitidos es corta para la mayoría de los use cases; un whitelist le gana a un blacklist.

`Variable.GetValue` devuelve lo que sea que AMPscript seteó, incluyendo `null` y string vacío

El interop es fiel — si AMPscript seteó la variable a un string vacío, SSJS lee "". Si AMPscript nunca la seteó, SSJS lee null. Si AMPscript la seteó a un número, SSJS lee un número (no un string). No asumas el tipo.

// EN RIESGO — asume que Variable.GetValue devuelve un string
var tier = Variable.GetValue("@loyaltyTier");
if (tier.toLowerCase() === "gold") {  // tira si tier es null
  // ...
}

// SEGURO — guard para null + coerce a string
var tier = Variable.GetValue("@loyaltyTier");
tier = tier == null ? "" : String(tier);
if (tier.toLowerCase() === "gold") {
  // ...
}

`Platform.Function.RaiseError` halt el script — diseñá para esto

RaiseError no solo loguea el error; tira afuera del script. Cualquier cosa después de la llamada no corre. Adentro de una Script Activity de Automation, esto falla el paso y la Automation reacciona basado en su configuración (halt vs continuar).

// El script halt en RaiseError. La escritura de DE nunca pasa.
Platform.Function.RaiseError("Parando para review.", true);
Platform.Function.UpsertData("de_log_runs", ...);  // nunca se alcanza

// Si querés loguear primero después halt, escribí el log ANTES de RaiseError
Platform.Function.UpsertData(
  "de_log_runs",
  ["RunId"], [runId],
  ["Step","Msg","Ts"], ["abort", "Parando para review", Now()]
);
Platform.Function.RaiseError("Parando para review.", true);

El orden importa — loguea antes de raisear, porque el raise es una salida one-way.

Decisión rápida

Usá Variable.GetValue / SetValue cuando:

Adentro de un bloque script de email. AMPscript declara + lee las variables, SSJS hace la lógica pesada.

Usá Request.GetQueryStringParameter cuando:

Adentro de una CloudPage. Leyendo params URL de un link clickeado por el usuario, redirect, o webhook.

Usá Request.GetFormField cuando:

Adentro de una CloudPage que acepta submissions POST (preference centers, formularios de supresión).

Usá Platform.Function.RaiseError cuando:

Querés halt una Script Activity con un mensaje de error claro que surfacea en el log de la Activity.
El script alcanzó un estado donde continuar corrompería data downstream.

Usá Platform.Function.GetSetting cuando:

Leyendo configuración a nivel tenant que varía por entorno (MID de BU, instance, etc.).

Siempre validá input del usuario de Request.* cuando:

El valor llega a una redirect URL, una escritura de DE, o una lista de recipients de Send. Sin excepciones.

Relacionado

Basics — superficie de lenguaje soportada
Platform.Function — namespace API principal, donde RaiseError + GetSetting viven
Funciones de string — coerción de + de null a "null" (relacionado con Request.GetQueryStringParameter devolviendo null)
Funciones de encoding — URL-encodeá valores Request.* antes de re-emitir en URLs
MC SSJS gotchas — ver #7 (try/catch silencioso) para el contexto de surfaceo de errores

Próximas páginas de referencia SSJS: Style Guide.

Más snippets how-to para patrones comunes de producción — DE add/update/upsert, manejo de errores, paginación de callouts, etc.

Sintaxis oficial

Variable.* — interop AMPscript ↔ SSJS

Request.* — acceso a URL + form de CloudPage

Platform.Function.RaiseError — surfacear errores de vuelta al caller

Platform.Function.GetSetting — leer settings del tenant