Contexts and sessions

GatewayScript provides access to session and context information.

Sessions come from the flow of a transaction through the DataPower services except for the API gateway. Each session is represented by a session object. Sessions contain the input and output contexts for the action and other contexts that are visible to the service.

Contexts consist of temporary data that is used by a processing action. They contain all the information that is associated with an aspect of a transaction. Some contexts are built in (such as, input and output), and users can create and use named contexts.

Contexts are properties of the session object. When a request is received, it is immediately placed in the INPUT context. The INPUT context does not change. It can be accessed at any time by any GatewayScript action in a processing rule. Each action has a configurable input and output context. The input context session.input is not necessarily passed from the previous action. Likewise, the output context session.output of the GatewayScript action is specified by users at configuration time. If a GatewayScript action does not read the input context and does not write to the output context, the payload is transferred from the input to the output.

A session object provides access to the following contexts.
INPUT
The context that is holding the body of the message as it was initially received. For example, session.INPUT.
input
The context that is specified by the Input property of the GatewayScript action. For example, session.input.
output
The context that is specified by the Output property of the GatewayScript action. For example, session.output.
name()
A named context accesses a context that is explicitly created by a GatewayScript action or other previously processed action. To access the context, specify the context by referring to the session object. To create a named context, see the createContext() API. For example, the session.name() API.
The session.createContext('context_name') function creates a context with the name context_name. The names of contexts must meet the following requirements.
  • Cannot be an empty string.
  • Cannot contain leading or trailing white spaces.
  • Cannot contain non-Latin characters.

Contexts are accessed through session objects. The content of context is accessed through context variables. Contexts are created internally or by GatewayScript, XSLT, or XQuery extension functions.

Contexts carry both content and variables. You can use the get, set, and delete variable functions to manage context variables.

There are no built-in methods for the special NULL, PIPE, and OUTPUT contexts.

You can access the contents of session contexts with the GatewayScript read and write APIs: readAsBuffer(), readAsBuffers(), readAsJSON(), and write().

You can access context variables with the following functions.
  • The setVariable() API sets the value of a variable.
  • The getVariable() API accesses the value of a variable.
  • The deleteVariable() API removes the variable from the context.
  • The name() API accesses a named context.
  • The createContext() API creates a named context.
  • The listVariables() API returns an array of variable names.

Examples

  • Use the getVariable() API to get the value of a variable from a context.
    // get variable from the input context
var myInputVar = session.input.getVariable('myInputVar');
  • Create the myContext context, if it does not exist.
    var ctx = session.name('myContext') || session.createContext('myContext');
  • Extract a context variable, and then delete it from the context.
    var oldPrice = ctx.getVariable('price') || 0;
ctx.deleteVariable('price');
  • Set and get variables in a named context.
    // set and get variables in the named context ctx
var price = oldPrice * 1.2;
ctx.setVariable('updatedPrice', price);
var quantity = ctx.getVariable('quantity') || 0;

    The oldPrice variable is zero, if the context variable price is undefined. Variable quantity is zero, if the context variable quantity is undefined.

  • Return the variable names in the mycontext context.
     let contextvars = session.name('mycontext').listVariables();
  • Write a JSON document to session output.
    session.output.write( {"price": price, 
                       "quantity": quantity, 
                       "total": quantity * total} );