Transport Layer Context Variables

The following table lists the predefined context variables related to the transport layer.
9-5
The following table lists the predefined context variables related to the transport layer.
Variable
Description
${
<
target
>
.http.version}
Returns the HTTP protocol version if the target is a valid HTTP request. Possible values are
1.0,
1.1,
or
2.0
Returns a null value if the target is not a valid HTTP request.
${
<
target
>
.http.allheadervalues}
Returns all HTTP headers and values in an array, in the format "<
name
>:<
value
>".
${
<
target
>
.http.cookies}
Returns all cookies and their attributes.
In the following example, "Cookie1" and "Cookie2" are the cookie names, while '123', '456' are the values:
Cookie1=123; Version=1; Domain=localhost; Path=/; Comment=test; Max-Age=60; Secure, Cookie2=456; Version=1; Domain=localhost; Path=/; Comment=test; Max-Age=60; Secure
Additional information:
  • For the ${request.http.cookies}, this returns the same value as
    ${request.http.headervalues.cookies}
    .
  • For ${response.http.cookies}, this returns the same value as
    ${response.http.headervalues.set-cookies}
    .
  • If the <
    target
    > is a Message variable, then:
    • If the variable was saved by a response, then
      ${MsgVar.http.cookies}
      returns the same value as
      ${MsgVar.http.headerValues.set-cookie}
      .
    • If the variable was not saved by a response, then
      ${MsgVar.http.cookies}
      returns the same value as
      ${MsgVar.http.headerValues.cookie}
      .
${
<
target
>
.http.cookienames}
Returns all cookie names (repeated names are possible). For example:
Cookie1
,
Cookie2
${
<
target
>
.http.cookies.
<
name
>
}
Returns all cookies with the given <
name
> and their attributes. Useful for finding cookies with the same name.
In the following example, "repeatedName" represents a cookie name that appears more than once and '234', '567' represent the values for each instance of the repeated cookie name:
repeatedName=234; Version=1; Domain=localhost; Path=/; Comment=test; Max-Age=60; Secure, repeatedName=567; Version=1; Domain=layer7; Path=/; Comment=test; Max-Age=60; Secure
${
<
target
>
.http.cookievalues.
<
name
>
}
Returns all values for cookies with the given name (repeated names are possible).
Using the name "repeatedName" from the example in the row above, this variable returns: 234, 567
${<
target
>
.http.header.
<
name
>
}
Retrieves the value of the HTTP header <
name
> (case insensitive) for the message. For example:
${request.http.header.soapaction}
returns the value of the SOAPAction header for that request.
${
<
target
>
.http.headerValues.
<
name
>
}
Returns a list of all the values for the specified header <
name
>, in the format:
[value1, value2, ... , valuen]
For requests, this variable may be useful while investigating audit details, email issues, etc. For example, you are communicating with a service on an IIS server that has NTLM enabled. There are two WWW-Authenticate headers, with the values NTLM and Negotiate. Using the
${request.http.header.www-authenticate}
variable will return only the NTLM value. Using
${request.http.headerValues.www-authenticate
} instead will return the literal string [
NTLM, Negotiate
].
For responses, this variable is useful for documentation purposes, to enumerate the contents of a header.
${
<
target
>.
jms.allpropertyvalues}
Returns all JMS properties and values in an array, in the format "<
name
>:<
value
>".
${
<
target
>
.tcp.localAddress}
${
<
target
>
.tcp.localIP}
Either of these variables returns the local (Gateway) side of the TCP connection's IPv4 or IPv6 address in conventional notation, or null if not applicable or unknown.
This will be the TCP connection through which the message arrived.
${
<
target
>
.tcp.localHost}
Returns the local (Gateway) side of the TCP connection's hostname, or else the IP address, or else null.
${
<
target
>
.tcp.remoteAddress}
${
<
target
>
.tcp.remoteIP}
Either of these variables returns the remote IPv4 or IPv6 address of the TCP connection through which the Message arrived, in conventional (dotted or colon) notation, or null if not known.
${
<
target
>
.tcp.remoteHost}
By default, this returns the IP address of the client (same as "*.tcp.remoteIP"). To return the hostname, enable reverse lookup by doing the following:
  1. Open the properties for the listen port whose clients should be looked up in the DNS.
  2. Select the [
    Advanced
    ] tab in the properties.
  3. Click [
    Add
    ] and then enter this new property:
    Property Name:
    enableLookups
    Value:
    true
  4. Click [
    OK
    ] to close the dialogs.
${
<
target
>
.tcp.remotePort}
Returns the TCP port number of the remote (non-Gateway) side of the TCP connection through which the message arrived, or null if not known or not applicable.
${request.clientid}
If the user has been authenticated:
Returns "AuthUser:" followed by the identity provider entity ID, followed by a user identifier.
  • For internal users, the user identifier is the user entity ID. Example: internal user Alice has an entity ID = a5f3g62h221, with identity provider ID = -2. What is returned: AuthUser:-2:a5f3g62h221.
  • For LDAP users, the user identifier is the same as the context variable ${request.authenticateduser}. Example: AuthUser:3:cn=John Smith, o=AcmeTech LLC, where the identity provider ID = 3, and user identifier = cn=John Smith, o=AcmeTech LLC.
If the user has not been authenticated:
Returns "ClientIp:${request.tcp.remoteAddress}", assuming the client IP is known. Example: ClientIp:10.77.33.21.
If the client IP is unknown:
Returns "ProtocolID:" followed by the protocol name, followed by a client endpoint identifier from the request's transport protocol. Example:ProtocolId:XMPP:[email protected]
If the client endpoint identifier is unknown:
Returns "Protocol:" followed by the name of the transport protocol. Example: Protocol:JMS.
If the protocol is unknown:
Returns "ClientId:Unknown".
${request.command.parameter.length}
Returns the length parameter to be used in PUT and GET requests.
${request.command.parameter.offset}
Returns the offset parameter to be used in PUT and GET requests.
${request.command.parameter.newFile}
Returns the new file name parameter to be used in MOVE requests.
${request.command.parameter.newPath}
Returns the new file path parameter to be used in MOVE requests.
${request.command.type}
Returns the values GET, PUT, LIST, STAT, MOVE, DELETE, MKDIR, or RMDIR.
${request.compression
.gzip.found}
Returns a Boolean value:
  • true
    = A message compressed with the gzip algorithm has been received by the Gateway
  • false
    = No gzip-compressed message has been received
${request.ftp.command}
Returns the raw FTP command submitted; for example "MDTM".
In upload-only mode, this variable will always be set to STOR.
${request.ftp.argument}
Returns any argument submitted with the FTP command; for example, "*.log".
This variable supersedes
${request.ftp.file}
, which returns the same value as
${request.ftp.argument}
.
${request.ftp.file}
Returns the same value as ${request.ftp.argument} above.
${request.ftp.path}
Returns the current working directory for the FTP session.
${request.ftp.secure}
Used to check if a secure transport is in use; returns a Boolean value:
  • true
    = FTPS used
  • false
    = FTP used
${request.ftp.unique}
This variable supersedes
${request.ftp.file}
, which returns the same value as
${request.ftp.argument}
.
Returns a Boolean value:
  • true
    = Client has used the 'STOU' command to upload a unique file.
  • false
    = Client has used any other command (for example, LIST, SIZE, RETR. MDTM, etc.).
${request.http.method}
Returns the HTTP verb for the request, if it arrived over HTTP; for example, GET, POST or DELETE. If the published service enables "Other" HTTP methods, then any arbitrary string may be returned as the HTTP verb. In this case, the method should be validated in policy before being passed through to a protected service.
${request.http.parameter.
<name>
}
Retrieves the value of an HTTP parameter with the name "<
name
>" for the request. Request parameters are extra information sent with the request. For HTTP servlets, parameters are contained in the query string or posted form data.
If the parameter contains multiple values and you wish to capture all the values, use the following context variable instead. Otherwise, only the first value in the parameter will be captured in this variable.
${request.http.parameters
.<
name
>
}
Same as
${request.http.parameter
.<
name
>}, except this variable allows you to retrieve all values from an HTTP parameter with multiple values. This creates a multivalued context variable.
To reference a single value within a multivalued context variable, use the indexing feature. For example, "name[0]" retrieves the first value, "name[1]" to retrieve the second value, etc. For more information on using this feature, see "Indexing Options during Interpolation" in Multivalued Context Variables.
${request.http.secure}
Returns a Boolean value:
true
= request came through an SSL port
false
= request did not come through an SSL port
${request.http.uri}
Returns the HTTP URI for the request; for example:
/ssg/soap
${request.jms.property.
<name>
}
Retrieves the value of a JMS property (case sensitive) for the request. For example:
${request.jms.property.SOAPJMS_soapAction}
returns the value of the SOAPAction property for that request.
${request.ssh.file}
Returns the name of the file being uploaded (for example, 'message.xml').
${request.ssh.path}
Returns the upload directory for the file; this is '/' on initial login.
${request.ssl.ciphersuite}
Returns the name of the cipher suite in use for the TLS connection over which this request arrived, if any. Valid only for HTTPS connections.
Example: "TLS_DHE_RSA_WITH_AES_256_CBC_SHA".
${request.ssl.keysize}
Returns the SSL/TLS key size in bits, if available. May only work with certain JSSE providers (SunJSSE or SSL-J). This is an indication of the security strength of the cipher suite (for example, it will show "128" for AES 128 and "256" for AES 256). It does not provide any indication of the size of the server (or client) private keys. Valid only for HTTPS connections.
${request.ssl.protocol}
Returns the level of the SSL/TLS negotiated in the policy. Typical values would be:
  • TLSv1.3
  • TLSv1.2
  • TLSv1.1
  • TLSv1
${request.ssl.sessionid}
Returns the SSL/TLS session identifier as a hex string, if available. May only work with certain JSSE providers (SunJSSE or SSL-J). Can be passed through to back-end services in order to detect session hijacking attacks. Valid only for HTTPS connections.
${request.tcp.localPort}
Returns the TCP port number of the local (Gateway) side of the TCP connection through which the Message arrived, or null if not applicable or not known. For example, this could be 8443, 8080 or any port configured on that server.
This variable is not meaningful for FTP, since there is a control and a data port.
${request.tcp.listenPort}
Returns the listen port number used by the
Layer7 API Gateway
.This differs from the
${request.tcp.localPort}
variable in that it returns the actual listen port on which the request was received, not the port number in the HTTP header of the received request.
This variable is not meaningful for FTP.
${request.url}
Returns the
Layer7 API Gateway
URL where the message was received. When used without a suffix, the entire URL is returned. When used with one of the following optional suffixes, only that part of the URL is returned:
.file
.fragment
.host
.path
.port
.protocol
.query
Examples:
${request.url}
returns the entire Requesting Client URL
${request.url.host}
returns only the host name portion of the URL
${request.url.query}
returns the query portion of the URL for the HTTP request
The .file and .path suffixes will usually return the same values.
${request.url.query}
Returns the query portion of the URL for the HTTP request; for example:  ?blah=foo
This variable is the same as using
${request.url}
with the ".query" suffix.
${response.ftp.replycode}
${
<
variable
>
.ftp.replycode
Returns the FTP reply code of the response received over the control connection from the remote FTP server; for example: "150".
This variable is set to "0" if the Route via FTP(S) Assertion did not receive a response or has not run yet.
${response.ftp.replytext}
${
<
variable
>
.ftp.replytext}
Returns the message portion of the response received over the control connection from the remote FTP server; for example: "/home/user".
This variable returns null if no data was returned or if the Route via FTP(S) Assertion did not receive a response or has not run yet.
${response.http.status}
${
<
variable
>
.http.status}
Returns the HTTP response status code of the message.
If the message has been the target of the Route via HTTP(S) Assertion (that is, the HTTP response was fetched to this message—not to be confused with using the message as the source for the Route via HTTP(S) assertion), then the http.status suffix variable will record the HTTP status of the last Route via HTTP(S) assertion that targeted to this message. Otherwise, the http.status suffix variable will be "0" (zero).
${response.jms.property.
<name>
}
Retrieves the value of JMS property (case sensitive) for the response.
Example:
${response.jms.property.Blah}
returns the value of the Blah property for that response.