Variable Framework
This figure depicts how the variable framework is used to access the variables in various policies across stages.

- This feature does not support Set-Cookie header transformation.
- Any variables that access the request or response payloads cannot be used in the variable framework, if the payload is sent as a stream.
The following table summarizes the keywords that are used to define the variable syntaxes:
Variable keyword | Description |
---|---|
paramStage
|
Defines the stage of the system defined
policy. Possible values are:
|
paramType
|
Defines the specific parameter of the
request or response. Possible values are:
|
queryType
|
Defines the query that can be applied over
string elements like payload. Possible values are:
|
The following variable types are available in the request or response stages:
${paramStage.paramType}
You can use this syntax to access the following string variables:
path
,statusCode
,statusMessage
,httpMethod
.Examples:
${request.path}
,${response.statusCode}
${paramStage.paramType.paramName}
You can use this syntax to access map types, such as query, headers, and path.
Example:
${request.query.var1}
,${response.header.Content-Type}
,${request.path.name}
.${paramStage.paramType.queryType[queryValue]}
You can use this syntax to access the payload. Examples:
${request.payload.xpath[//ns:emp/ns:empName]}
Where "
//ns:emp/ns:empName
" is the XPath to be applied on the payload if contentType is application/xml, text/xml, or text/html.${response.payload.jsonPath[$.cardDetails.number]}
Where
$.cardDetails.number
is the jsonPath to be applied on payload if contentType is application/json or application/json/badgerfish.${request.payload.regex[[0-9]+]}
Where
[0-9]+
is the regular expression to be applied on the payload if contentType is text/plain.${request.isSoapToRest}
or${response.isSoapToRest}
This variable returns True if the current invoke is REST invoke for a SOAP API. Else it returns False.
Note: Whilexpath
andjsonPath
are applicable only to payload,regEx
can be used with bothpayload
andpath
.-
${paramStage[stepName].paramType.paramName]}
You can use this syntax to access the header or payload in the request or response stage.
Example:
Variable:
${response.headers.id}
Value:
${response[customExtension].payload.jsonPath[$.id]}
This transformation adds a header to the response with the name id, and its value is derived from the JSON payload that is sent from the external callout as per the JSON path.
The following sections summarize the variables that are available in webMethods API Gateway as part of variable framework template in addition to the existing predefined system context and custom context variables:
Request Variables
Variables that allow you to extract and reuse values in the request processing stage.
Variable Syntax | Description |
---|---|
${request.headers.NAME}
Example:
|
Gets the value of the header name in the request. |
$ {request.query.NAME}
Example:
|
Gets the value of the query name in the request. |
${request.path} | Gets the value of the path in the request. |
${request.path.regex[EXPR]}
Example:
|
Gets the value of the path in the request. |
${request.httpMethod} | Gets the method in the request. |
${request.payload.xpath[EXPR]}
Example: |
Gets the value after applying a xpath expression on the
request path.
Note: The namespace URI for the prefixes you have
configured in the xpath expression are resolved using namespaces configured in
the metadata section in the policy or using the namespaces configured through
XpathNamespaces custom variable in the
custom extension policy.
|
${request.payload.jsonPath[EXPR]}
Example:
Provide the following variable, if there is a blank space in the parameter name ${request.payload.jsonPath[$.['param name'] ]} For example, if the parameter name is
first name, then provide
the variable as
|
Gets the value after applying a JSON expression on the request path. |
${request.payload.regex[EXPR]}
Example:
|
Gets the value after applying a regular expression on the request path. |
${request.authorization.clientId} | Gets the value of the client ID identified from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.issuer} | Gets the value of the issuer identified from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.userName} | Gets the value of the username identified from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.authHeader} | Gets the value of the authorization header by the configured IAM policy. This
value is available only if the relevant IAM policy is configured. Note: If the
authorization header has bearer tokens (such as OAuth, OpenID, or JWT), then you
cannot use this variable. In such cases, it is recommended to use the
${request.authorization.incomingToken} variable.
|
${request.authorization.apiKey} | Gets the value of the API key from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.incomingToken} | Gets the value of the incoming token from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.audience} | Gets the value of the audience from the authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured. |
${request.authorization.claims.CLAIM_NAME}
Example: ${request.authorization.claims.emp.company } |
Gets the value for the claim name from the claims identified from the Authorization header by the configured IAM policy. This value is available only if the relevant IAM policy is configured |
${request.correlationID} | Gets the correlation ID for this request. |
${request.application.id} | Gets the ID of the application identified for this request. |
${request.application.name} | Gets the name of the application identified for this request. |
${request.application.version} | Gets the version ID of the application identified for this request. |
${request.application.claims.CLAIM_NAME}
Example: |
Gets the value of the claim name for the claims identifier configured in the application identified for this request. |
${request.application.partnerId} | Gets the partner ID of the application identified for this request. |
${request.application.description} | Gets the description of the application identified for this request. |
${request.application.hostname[NUMBER]}
Example:
|
Gets the value of the hostname identifier in the specified index for the application identified for this request. |
${request.application.payloadIdentifier[NUMBER]}
Example: |
Gets the value of the payload identifier in the specified index for the application identified for this request. |
${request.application.team[NUMBER]}
Example:
|
Gets the value of the team identifier in the specified index for the application identified for this request. |
${request.application.token[NUMBER]}
Example: |
Gets the value of the token identifier in the specified index for the application identified for this request. |
${request.application.username[NUMBER]}
Example: |
Gets the value of the username identifier in the specified index for the application identified for this request. |
${request.application.wssUsername[NUMBER]}
Example: |
Gets the value of the wssUsername identifier in the specified index for the application identified for this request. |
${request.application.headers.HEADER_NAME}
Example: |
Gets the value of the header name for the headers identifier configured in the application identified for this request. |
${request.payload.native.xpath [EXPR]} | In SOAP to REST context, this variable returns the SOAP request to be sent to the native API. |
Response variables
Variables that allow you to extract and reuse values in the response processing stage.
Variable Syntax | Description |
---|---|
${response.headers.NAME}
Example:
|
Gets the value of the header name in the response. |
${response.statusCode} | Gets the value for the status code for the response. |
${response.statusMessage} | Gets the value for the status message in the response |
${response.payload.xpath[EXPR]}
Example: |
Gets the value of the payload from the
specified xpath of the response.
Note: The namespace URI for the prefixes you have
configured in the xpath expression are resolved using namespaces configured in
the metadata section in the policy or using the namespaces configured through
XpathNamespaces custom variable in the
custom extension policy.
|
${response.payload.jsonPath[EXPR]}
Example: |
Gets the value of the payload from the specified jsonPath of the response. |
${response.payload.regex[EXPR]}
Example:
|
Gets the value of the payload from the specified regex of the response. |
${response.payload.native.xpath [EXPR]} | In SOAP to REST context, this variable returns the native SOAP response, returned by the native SOAP API. |
webMethods API Gateway evaluates and supports the array expressions in JSON path.
Example: Consider the following payload.
{
"firstName":"John",
"lastName":"doe",
"age":26,
"address":
{"streetAddress":"naist street","city":"Nara","postalCode":"630-0192"}
,
"phoneNumbers":[
{"type":"iPhone","number":"0123-4567-8888"}
,
{"type":"home","number":"0123-4567-8910"}
]
}
Following are the responses for the expressions after evaluating the array expressions in JSON path.
Expressions | Response |
---|---|
$.phoneNumbers[1].type | "home" |
$.phoneNumbers[0,1].type or $.phoneNumbers[:2].type | ["iPhone","home"] |
$.phoneNumbers[0,1] or $.phoneNumbers[:2] | [{"type":"iPhone","number":"0123-4567-8888"} \{"type":"home","number":"0123-4567-8910"}] |
$..firstName | ["John"] |
$.firstName | "John" |
$.address.city | "Nara" |
System Context Variables
webMethods API Gateway provides predefined system context variables and the values of these expressions are extracted from the client request.
Expression | Description |
---|---|
${apiId} | Get the value of the API ID. |
${apiName} | Get the name of the API. |
${apiVersion} | Get the version of the API. |
${packageId} | Get the value of the package ID. |
${planId} | Get the value of the plan ID. |
${customTransactionFields.FIELD_NAME}
Example: |
Provides you an option to get or set custom fields to the transactional events for this request. To set the custom fields, you can configure the customTransactionFields.FIELD_NAME custom variable in Custom Extension policy. |
${providerTime} | Gets the time taken in milliseconds between the request sent to native server and response received from native server for this transaction. |
${date} | Gets the date when the request gets invoked. |
${dynamicEndpoint} |
Gets the value of the ROUTING_ENDPOINT context variable set using pub.apigateway.ctxvar:setContextVariable |
${time} | Gets the time when the request gets invoked. |
${user} | Gets the value of the user ID who sends the request. |
${inboundHttpMethod}
Example: |
Gets the value the HTTP method used by the client to send the request. |
${routingMethod}
Example: |
Gets the value of the HTTP method used by the webMethods API Gateway in the routing policy to send the request to native API. |
${InboundContentType}
Example: |
Gets the content type of the request. |
${inboundAccept}
Example: |
Gets the accept header in the incoming request from the client. |
${inboundProtocol} | Gets the protocol of the request. |
${inboundRequestURI}
For example, if the API is invoked: http://host:port/gateway/API then the expected value of this variable would be /gateway/API. For a REST API, the URL also includes query string parameters. For example, if the following API is invoked: http://host:port/gateway/cars?vin=1234 the expected value of this variable would be /gateway/cars?vin1234. |
A partial reference to an API (for HTTP and HTTPS only). The protocol, host and port are not part of the value. |
${inboundIP}
Example: |
Gets the value of the client IP address used to send the request. |
${gatewayHostname}
Example: |
Gets the webMethods API Gateway host name. |
${gatewayIP}
Example: |
Gets webMethods API Gateway IP address. |
${operationName}
Example: |
Gets the value of API operation selected from the request. Operation names are available only for SOAP APIs. It is empty for REST API. |
${nativeEndpoint}
Example: |
Gets the value of the native endpoints from the request. It returns value only after executing the routing policy. |
${request.payload.jsonPath[$.EXPRESSION]}
.The expression can be
replaced by any field from the transactional event. For example,
${request.payload.jsonPath[$.apiName]}
, where the expression is the
name of the API as configured in the transaction event.In addition, the variable framework also supports the following variables:
- ${jms.headers.NAME}
- ${jms.query.NAME}
- ${jms.path}
- ${jms.path.regex[EXPR]}
- ${jms.httpMethod}
- ${jms.payload.xpath[EXPR]}
- ${jms.payload.jsonPath[EXPR]}
- ${jms.payload.regex[EXPR]}
- ${jms.statusCode}
jms.path.petid
and the corresponding value as
jms.header.h1
, then if the request contains the
header value h1, the value h1 is replaced by the path parameter petid.
Enhancements to Variable Framework Support
Until webMethods API Gateway version 10.5, the variable framework was supported in API Mashup, Request Transformation, Response Transformation, Conditional Error Processing, and Custom Extension policies.
In webMethods API Gateway version 10.7 the existing variable framework is enhanced to support the following use cases:
- Simple aliases can be accessed across all stages using variable framework. For example: ${simpleAlias}.
- The existing custom and
system context variables are now accessible using variable framework. As part
of variable framework, the custom context variables that were defined using
ctxVar IS service are merged into custom variables. The syntax for accessing
the system context variables or custom context variables using variable
framework is similar to the custom variables. Example : ${variableName}. For
details on how the system and custom context variables were declared in
webMethods API Gateway
version 10.5, see
Conditional Routing.
Note: As like the earlier versions of webMethods API Gateway, you can also define and access the custom-context variable or custom-variable using the ctxVar IS Service. For details, see The API for Context Variables.
- Both system context variables and custom variables (that includes custom context variables) are accessible across all policy parameters that support variables.