Context Variables

Context variables relate to the request being processed by the . These variables can reveal a wealth of information about what is happening at the  and are invaluable in helping you resolve issues.
gateway83
Context variables relate to the request being processed by the
API Gateway
. These variables can reveal a wealth of information about what is happening at the
API Gateway
 and are invaluable in helping you resolve issues.
Assertions can read context variables. In this case, the value of the variable is resolved at runtime when the assertion is executed. Assertions can also write variables to the request context, making them available to other assertions.
When embedding a context variable within a string, use the following format:
${context.variable.name}
Example:
In the Send Email Alert or Return Template Response to Requestor assertions, you create this message: "This transaction is being denied because the account ${request.authenticateduser} has exceeded quota. Please contact customer support at
${gateway.supportnumber}
for assistance." The delimiter characters are required in this case.
When an assertion requires just the name of a context variable, enter the name without the delimiters:
context.variable.name
Example:
In the Restrict Access to IP Address Range assertion, you wish to resolve the IP address from this context variable: request.http.header.remoteip. In this case, the delimiter characters are not required.
 
(1) When a context variable fails, the default behavior is to log a warning and use an empty string. The assertion calling the context variable does not fail. To cause the assertion to fail when a context variable fails, set the template.strictMode cluster property to "true". Some examples of context variable failures: a) Calling "
${request.http.header.abc}
" but the request has no "abc" header. b) Requesting a context variable that doesn't exist: "
${someNonExistentVariable}
".
(2) You can access cluster property values by using the built-in context variable
${gateway.<propertyName>
}
. To learn more about using the built-in gateway prefix, see the table below.
(3) You can see the context variables set and used for any assertion by displaying the Assertion Information dialog.
 
Some context variables can target a specific message. These are indicated by the prefix <
target
> in the variable name, where <
target
> is either request, response, or a Message context variable that has been set in the policy prior to the assertion. For more information on Message context variables, see Context Variable Data Types.
Multivalued Context Variables
All the context variables described below can hold only a single value at a time. However, there is a special class of variables called multivalued context variables that can contain any number of values. These context variables are created using the Join Variable, Extract Attributes for Authenticated User, Listen Ports, or Query LDAP assertions and can be used wherever the single-value context variables are used.
Where Context Variables are Defined
The 
API Gateway
 includes a set of built-in context variables. Additionally, many assertions also define their own context variables when used in a policy. These variables are available to subsequent assertions in the policy tree. See the respective assertion topics for information about these variables.
The following topics also describe context variables used in specific scenarios:
  • XPath Context Variables
  • CA Single Sign-On Context Variables
  • Working with the Debug Trace Policy
Context Variable Naming Rules
When an assertion allows you to type in the name of a new context variable (instead of creating one using a system defined naming pattern), note the following naming rules:
  • The first character must be either a letter or the underscore (_) character.
  • After the first character, the variable name may be any combination of letters, digits, underscore (_), or period (.).
  • The dollar sign ($) is a reserved character and cannot be used anywhere within the name.
  • Context variables may not begin with "request." or "response." These characters are reserved for system use.  
  • Multi-byte characters are currently not supported within context variable names.  
Examples:
  • Valid context variable names: _counter, request.url, layer7
  • Invalid context variable names: .request, 7layer
Context Variable Data Types
Context variables can technically be of any type. They can hold anything from a number, to a string, to an entire message complete with attachments and headers. The assertions in the Policy Manager can create variables with the following data types:
  • String
    : The variable contains a string. This is the most common data type used in
    API Gateway
    . Most of the predefined variables are of this type.
  • Message
    : The variable contains a complete message, complete with attachments (if present). To access the body of the main/root MIME portion of the message as a string, add the ".mainpart" suffix to the context variable. For more information on the ".mainpart" suffix, see Message Layer Context Variables.
Message type context variables are created by the Set Context Variable assertion and by the Route via HTTP(S) assertion ("Response Destination"). They can also be accessed using any built-in variable with the prefix "${request.*}" or "${response.*}".
  • Number
    : The variable contains a number. These variables are created by an XPath assertion (Evaluate Request XPath or Evaluate Response XPath) when evaluating an XPath expression such as "0.14 * //item/@price". A context variable with type Number can be interpreted as a String in almost all cases.
  • X.509 Certificate
    : The variable contains one or more X.509 certificates. These variables are created by the (Non-SOAP) Verify XML Element and Look Up Certificates assertion. They can also be accessed by the Credential Certificates Variables.
  • Element
    : The variable contains a reference to a specific XML element from the message. These variables can be created by the following assertions:
    • (Non-SOAP) Verify XML Element 
    • (Non-SOAP) Decrypt XML Element
    • Evaluate Request XPath
    • Evaluate Response XPath
    • Require WS-Security Signature Credentials 
  • AuditDetail
    and
    AuditRecord
    : These variables are accessed using the built-in ${audit.*} variables within an audit sink policy. For more information, see Working with the Audit Sink Policy.
  • Date/Time:
    The variable contains date/time information. These variables behave similarly to the built-in variables described under Date/Time Variables.
Context variables created by a custom or a modular assertion (either from
API Gateway
or from a third party) may have data types other than those listed above.
Context Variable Validation
When you enter a context variable or a prefix for a context variable, the Policy Manager validates your entry and displays an instant feedback message in the dialog. The following table explains the various messages that may appear.
Validation
Description
OK
The name entered is valid; a new context variable will be created.
OK (Overwrite)
The name entered matches a context variable that was already defined in a previous assertion in the policy. That variable will be overwritten.
OK (Built-in, settable)
The name entered matches a built-in context variable for which you can assign a value.
Built-in, not settable
The name entered matches a built-in context variable for which you cannot assign a value. Try another name.
OK (New Prefix)
The name is valid; a new prefix will be created.
Invalid syntax
The field has been left empty or the name entered contains illegal characters. Try another name. For more information, see Context Variable Naming Rules.
No such variable
The specified variable does not exist.
This message is used in instances where you are expected to reference an existing variable from which to obtain a value, not to create a new variable.
Checking for Existence of Context Variables
Sometimes a policy may need to determine whether a context variable exists in order to branch correctly—for example, to check whether a certain header or parameter exists. There are two ways you can do this, depending on your policy logic requirements:
Method 1: Use the Look Up Context Variable assertion by itself
The following example determines whether the variable
test
exists:
  1. Add the Look Up Context Variable assertion as the first item in an "All Assertions Must Evaluate to True" folder.
  2. Configure Look Up Context Variable as follows:
    • Select the Fail if not found check box.
    • Enter test in the Expression field.
Using this logic, the branch will not execute if the variable does not exist.
Method 2: Use Look Up Context Variable in conjunction with the Compare Expression assertion
The following example determines whether the variable
 test
 exists:
  1. Add Look Up Context Variable before the Compare Expression assertion in the policy.
  2. Configure Look Up Context Variable as follows:
    Clear the Fail if not found check box.  
    Enter test in the Expression field. 
  3. Configure the Compare Expression assertion to check whether the variable
    ${lookup.found}
    = true or false
For more information, see Look Up Context Variable Assertion.