This document contains conceptual, procedural, and scenario information regarding the use of the Utilities server-side JavaScript functions.

Why Use the Utilities Server-Side JavaScript Functions

The Utilities server-side JavaScript functions allow you to load and modify data using server-side JavaScript.

How to Use the Utilities Server-Side JavaScript Functions

In your server-side JavaScript code, first load the core library using the syntax below:

Platform.Load("core","1");

Use the sample code below as models to construct your own server-side JavaScript code.

Application Functions

Use the functions below to interact with the application.

Logout

This function logs the user out of the application.

In the sample code below, the function logs the user out of the application:

Logout();

Redirect(redirectURL, movedPermanently)

This function redirects the user from a landing page to specified URL.

Arguments
  • redirectURL - Indicates the URL to which the user is redirected
  • movedPermanently - Indicates whether this redirect should be permanently enabled

In the sample code below, a landing page redirects the user to another  site.

Redirect("http://example.com/index.html",false);
Enter the full URL for the page to which you are redirecting the user. If you provide only a general directory address, make sure you place a trailing slash after the URL, such as http://example.com/.

Base64 Functions

The functions below permit you to encode and decode Base64 strings.

Base64Decode(content)

This function decodes a Base64 encoded string to a plain text string.

Arguments
  • content - The Base64 encoded string to be decoded

In the following sample code, a Base64 encoded string is passed to the function and a plain text string is returned.

var encoded = 'VGhpcyB3YXMgYSBCYXNlNjQgZW5jb2RlZCBzdHJpbmcu';
var decoded = Base64Decode(encoded); // "This was a Base64 encoded string."

Base64Encode(content)

This function Base64 encodes a plain text string.

Arguments
  • content - The plain text string to be Base64 encoded.

In the following sample code, a plain text string is Base64 encoded:

var decoded = 'Convert to Base64';
var encoded = Base64Encode(decoded); // "Q29udmVydCB0byBCYXNlNjQ="

ContentArea Functions

Use the functions below to return content from a content area.

ContentArea(id, [impressionRegion, [throwOnError, [defaultContent]]])

This function returns the content stored in the content area specified by its ID.

Arguments
  • id - The id of the specified content area
  • impressionRegion - The name of any impression region contained in the content area
  • throwOnError - The error message to deliver if no content can be returned
  • defaultContent - The content area to display if no other content area can be found

In the sample code below, the variable gets the information from the specified content area. Note that the content is not written to the email or landing page page you create. Instead, the content resides in the variable and can be used just as any other string.

var myContent = ContentArea(12345);

ContentAreaByName(name, [impressionRegion, [throwOnError, [defaultContent]]])

This function returns the content stored in the content area specified by its name.

Arguments
  • name - The name of the specified content area
  • impressionRegion - The name of any impression region contained in the content area
  • throwOnError - The error message to deliver if no content can be returned
  • defaultContent - The content area to display if no other content area can be found

In the sample code below, the variable gets the information from the specified content area. Note that the content is not written to the email or landing page page you create. Instead, the content resides in the variable and can be used just as any other string.

var myContent = ContentAreaByName("myContentArea");

HTTPHeader Object and Functions

This HTTPHeader object allows you to add, retrieve, and remove information from an HTTP header.

SetValue(key, value)

This function sets the value of an HTTP header.

Arguments

  • key - The name of the header
  • value - The value to assign to the header

The sample code below sets the From address in the HTTP header.

HTTPHeader.SetValue("From","aruiz@example.com");

GetValue(key)

This function retrieves the value of the specified HTTP header.

Arguments

  • key - The name of the header

The sample code below retrieves the From address from the HTTP header.

HTTPHeader.GetValue("From");

Remove(key)

This function removes the specified information from the HTTP header.

Arguments

  • key - The name of the header

The sample code below removes the From address from the HTTP header.

HTTPHeader.Remove("From");

Impression Region Functions

Use the functions below to create impression regions.

BeginImpressionRegion(name)

This function sets the beginning of an impression region.

Arguments
  • Name - The name of the impression region

The sample code below starts the specified impression region.

BeginImpressionRegion("myImpressionRegion");

EndImpressionRegion([ClearAll])

This function sets the end of an impression region.

Arguments
  • ClearAll - Clears all impression region information

The sample code below end the impression region. You do not have to specify the region.

BeginImpressionRegion("myImpressionRegion");
...
EndImpressionRegion(ClearAll);

Request Object and Functions

This Request object allows you to use the following functions to request data based on a specified key.

GetQueryStringParameter(key)

This function pulls back a query string parameter based on a specified key.

Arguments
  • key - The key value used to identify the applicable query string parameter.

The sample code below requests a query string parameter based on the supplied key.

Request.GetQueryStringParameter("foo");

GetFormField(key)

This function pulls back form field information POSTed to the page based on a specified key.

Arguments
  • key - The key value used to identify the applicable form field

The sample code below requests a form field based on the supplied key.

Request.GetFormField("bar");

The Request object also contains the following members:

Members
  • ApplicationID - Returns the application ID
  • PackageID - Returns the package ID
  • ApplicationBaseURL - Returns the base URL of the request
  • URL - Returns the request URL
  • PagePath - Returns the path of the requested page
  • Method -  Returns the request method

The sample code below provides examples of how to call them:

var requestURL = Request.URL();
var requestMethod = Request.Method();
You must escape any HTML form field information POSTed to the page to avoid an error. Otherwise, the application will block the information for security reasons.

String Functions

Use the functions below to work with and transform string values.

Format(str, fmt)

This function formats a string with the specified format.

Arguments
  • str - The string to format
  • fmt - The format to apply to the string. Applicable values include MM/dd/yyyyand the currency format Cn, where n equals the number of decimal places

In the sample code below, the first function takes the string and applies the MM/dd/yyyyformat to it. The second function applies two decimal places to the string.

Format(Now(),"MM/dd/yyyy");
Format(55, "C2"); // Returns "55.00"

GUID()

This function returns a new GUID as a string value.

In the sample code below, the variable gets the new GUID as its value.

var myGUID = GUID();

IsEmailAddress(str)

This function takes the string passed to it and evaluates it to see if that string is a valid email address. The function returns either a true or false value.

Arguments
  • str - The email address to be evaluated

In the sample code below, the function evaluates the email address to see if that address is valid.

IsEmailAddress("acruz@example.com");

IsPhoneNumber(str)

This function takes the string passed to it and evaluates it to see if that string is a valid phone number. The function returns either a true or false value.

Arguments
  • str - The phone number to be evaluated

In the sample code below, the function evaluates the phone number to see if that number is valid.

IsPhoneNumber("5555551212");

Stringify(obj)

This function takes an object and transforms it into a string.

Arguments
  • obj - The object to transform into a string value

In the sample code below, the function transforms the object into a string format.

Stringify(myDataObject);

Write(str)

This function writes the specified string value to the content you are creating.

Arguments
  • str - The string value to write

In the sample code below, the function writes the specified string to the screen.

Write("This is the string to be displayed");

Combined with the ContentArea function to display content might look something like the following

Write(ContentAreaByName("myContentArea"));

Variable Object and Functions

This Variable object allows you to set and retrieve information contained in AMPscript variables. If a name is passed that lacks the @ prefix, the @ will be added. This allows your JavaScript to interact with your AMPscript.

GetValue(name)

This function retrieves the value of a specified variable.

Arguments
  • name - The name of the variable

The sample code below retrieves the value of the specified variable.

Variable.GetValue("@myAmpVariable");

SetValue(name, value)

This function assigns a value to a specified variable.

Arguments

  • name - The name of the variable
  • value - The value to assign to the variable

The sample code below assigns the specified value to a variable.

Variable.SetValue("myVariable","myValue");

 

 

Was This Page Helpful?
Last updated by ryan.williams at 11:47, 9 Apr 2014