Variable Framework

Edit online

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

variable framework flow process
Note:
  • 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:
  • request
  • response
paramType Defines the specific parameter of the request or response. Possible values are:
  • payload
  • headers
  • query
  • path
  • httpMethod
  • statusCode
  • statusMessage
queryType Defines the query that can be applied over string elements like payload. Possible values are:
  • xpath
  • jsonPath
  • regex

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: While xpath and jsonPath are applicable only to payload, regEx can be used with both payload and path.
  • ${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: ${request.headers.Content-Type}

Gets the value of the header name in the request.
$ {request.query.NAME}

Example: ${request.query.var1}

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: ${request.path.regex[0]}

Gets the value of the path in the request.
${request.httpMethod} Gets the method in the request.
${request.payload.xpath[EXPR]}

Example:${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.

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: ${request.payload.jsonPath[$.cardDetails.number]} where $.cardDetails.number is the jsonPath to be applied on the payload if contentType is application/json.

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 ${request.payload.jsonPath[$.['first name']]}.

Gets the value after applying a JSON expression on the request path.
${request.payload.regex[EXPR]}

Example: ${request.payload.regex[[0-9]+]} where [0-9]+ is the regex to be applied on the payload if contentType is text/plain

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:${request.application.claims.sample}

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: ${request.application.hostname[0]}

Gets the value of the hostname identifier in the specified index for the application identified for this request.
${request.application.payloadIdentifier[NUMBER]}

Example:${request.application.payloadIdentifier[1]}

Gets the value of the payload identifier in the specified index for the application identified for this request.
${request.application.team[NUMBER]}

Example: ${request.application.team[0]}

Gets the value of the team identifier in the specified index for the application identified for this request.
${request.application.token[NUMBER]}

Example:${request.application.token[1]}

Gets the value of the token identifier in the specified index for the application identified for this request.
${request.application.username[NUMBER]}

Example:${request.application.username[0]}

Gets the value of the username identifier in the specified index for the application identified for this request.
${request.application.wssUsername[NUMBER]}

Example:${request.application.wssUsername[0]}

Gets the value of the wssUsername identifier in the specified index for the application identified for this request.
${request.application.headers.HEADER_NAME}

Example:${request.application.headers.Accept}

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: ${response.headers.Accept}

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:${response.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

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:${response.payload.jsonPath[$.cardDetails.number]} where $.cardDetails.number is the jsonPath to be applied on the payload if contentType is application/json

Gets the value of the payload from the specified jsonPath of the response.
${response.payload.regex[EXPR]}

Example: ${ response.payload.regex[[0-9]+]} where [0-9]+ is the regex to be applied on the payload if contentType is text/plain

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: ${customTransactionFields.sample}

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: GET

Gets the value the HTTP method used by the client to send the request.
${routingMethod}

Example: POST

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: application/json

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: 210.178.9.0

Gets the value of the client IP address used to send the request.
${gatewayHostname}

Example: uk.myhost.com

Gets the webMethods API Gateway host name.
${gatewayIP}

Example: 198.168.1.9

Gets webMethods API Gateway IP address.
${operationName}

Example: addInts

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: http://host:port/Service

Gets the value of the native endpoints from the request. It returns value only after executing the routing policy.
Note: While configuring a Condition under Custom Destination, the variable syntax should be as follows: ${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}
Note: You can use these variables when you want to use JMS/AMQP so that transformation can be applied for the JMS/AMQP values. For example, if you set the path parameter as jms.path.petidand 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.