Mediator provides predefined context variables, and you can declare your own custom context variables. You can use both predefined and custom context variables when you configure various processing steps of a virtualized service. Specifically, you can use them:
In a webMethods IS service that you create and invoke during the Request Processing step or the Response Processing step.
In a routing rule that you create in the Context-Based Routing Protocols step.
This section discusses:
You can use the predefined context variables listed below. Any context variable state defined during the inbound request processing steps will still be available during the outbound response processing steps.
Notes:
| Context Variable Display Name | Context Variable Name | Description |
|---|---|---|
| Average Response | AVG_SUCCESS_TIME | The average amount of time it took the service
to complete all invocations in the current interval. This is measured from the
moment Mediator receives the request until the moment it returns the response
to the caller.
Note: |
| Client IP Address | INBOUND_IP | The IP address used to send the request to Mediator. |
| Consumer | CONSUMER_APPLICATION | The name of the consumer application accessing the service, if known. |
| Fault Count | INTERVAL_FAULT_COUNT | The number of service faults for the interval. |
| Inbound Content Type | MESSAGE_TYPE | A Content-Type defined in axis2.xml for a message formatter. This value must be a key in the axis2 message formatters list, since it is used to control message serialization. (The valid choices are defined as attributes of <messageFormatters/> group in the Integration Server's axis2.xml configuration.) |
| Inbound HTTP Method | INBOUND_HTTP_METHOD | The HTTP method used by the client to send the request (GET, POST, PUT, DELETE, Use Context Variable). |
| Inbound Protocol | INBOUND_PROTOCOL | The protocol (HTTP or HTTPS) of the request. |
| Maximum Response | SLOWEST_SUCCESS_INVOKE | Maximum Response Time.
Note: |
| Mediator Host Name | MEDIATOR_HOSTNAME | Mediator host name. |
| Mediator IP Address | MEDIATOR_IP | Mediator IP address. |
| Mediator Target Name | TARGET_NAME | Mediator target name. |
| Minimum Response | FASTEST_SUCCESS_INVOKE | Minimum Response Time.
Note: |
| Outbound HTTP Method | ROUTING_METHOD | The HTTP method to be sent to the native service if the inbound HTTP method is custom. Otherwise, this value will be null. For more information, see Changing the HTTP Method of a REST or XML Request. |
| Success Count | INTERVAL_SUCCESS_COUNT | The number of success counts for a given service. |
| Total Count | INTERVAL_TOTAL_COUNT | The total number of counts for a given service. |
| Virtual Service Name | SERVICE_NAME | Virtual service name. |
| N/A | BUILDER_TYPE | A Content Type defined in axis2.xml for a message builder. This value must be a key in the axis2 message builders list, since it is used to control building of native service response messages. (The valid choices are defined as attributes of <messageBuilders/> group in the Integration Server's axis2.xml configuration.) |
| N/A | INBOUND_REQUEST_URI |
A partial reference to a virtual service (for HTTP/HTTPS only). The protocol, host and port are not part of the value. For example, if the following virtual service is invoked:
then the expected value of this variable would be
For a REST or XML service, the URL might also include query string parameters. For example, if the following virtual service is invoked:
the expected value of this variable would be
This is useful to know because by the time you are able to access the request inside of Mediator, the REST request would contain a top-level element that looks like this:
So it is not obvious from an XSLT expression or a webMethods IS service callout what part of a REST request came in as a query parameter. Therefore, using this variable along with INBOUND_HTTP_METHOD and INBOUND_PROTOCOL, you can determine the exact entry point URI that was used when a virtual service was invoked. |
| N/A | NATIVE_PROVIDER_ERROR | The reason returned by the native service
provider in the case where it produced a SOAP fault. This will not contain
Mediator-hosted errors such as security policy enforcement errors. This
variable will only contain the "reason" text wrapped in a SOAP fault.
Note: |
| N/A | OPERATION | The virtual service operation selected to execute a request. |
| N/A | PROTOCOL_HEADERS | Contains a map of key-value pairs in the request, where the values are typed as strings. To get/set this variable, see pub.mediator.ctxvar:getContextVariable. |
| N/A | SOAP_HEADERS | (For use in webMethods IS services only.) Contains an array of the SOAP header elements in the request. To get/set this variable, see pub.mediator.ctxvar:getContextVariable. |
| N/A | USER | The value defined for the Integration Server session executing the request message. If the request is not authenticated, it will use a default unprivileged account. Otherwise, it will set the Integration Server session to the user credentials used for transport security. Also, if credentials were included for message based security (e.g., an X509 token was included and this certificate was mapped to an Integration Server user), then this information would override any transport security (e.g., basic authentication). |
Note:
When you use predefined context variables in a custom error message
in The Response
Processing Step, note the following:
To reference a predefined context variable in a custom fault message,
you need to prepend a $ symbol to the context variable name to indicate that
variable’s value should be referenced. Think of this usage as being similar to
the ‘&’ address operation for C variables. A predefined context variable
expression might look like this: $USER=”Administrator:”
The $ reference symbol may appear in the text as needed. (e.g., as a currency symbol). There is no escape concept used with this operator. That is, no special meaning is attached to two occurrences of this symbol: “$$”.
If no value is defined for a valid context variable reference, the string is left unmodified for that context variable.
Mediator provides an API that you can use to:
Set, get, declare and remove custom context variables.
Set and get the predefined context variables. (It is not necessary (or even legal) to declare or remove the predefined context variables.)
Mediator provides the following Java services, which are defined in the class ISMediatorRuntimeFacade.java:
The following sample flow services are described in this section as well:
Use this Java service to retrieve a context variable’s value and assign it to a pipeline variable. All parameter names are case-sensitive.
| Parameter | Pipeline Type | Data Type | Description | Examples |
|---|---|---|---|---|
| MessageContext | in | Object ref | This object is inserted into the pipeline by Mediator. | N/A |
| varName | in | String | Context variable name (predefined or custom). | PROTOCOL_HEADERSSOAP_HEADERSmx:CUSTOM_VAR |
| serValue | out | Object ref | Java.io.serializable value. (Usually a string). |
All context variable values are typed as either "string" or "int" except for the predefined context variables PROTOCOL_HEADERS and SOAP_HEADERS, which are of the type "IData". You can set/get values for PROTOCOL_HEADERS and SOAP_HEADERS in one of two ways:
To set the entire structure, you must:
Set the varName parameter in
pub.mediator.ctxvar:setContextVariable to
PROTOCOL_HEADERS or SOAP_HEADERS.
Use the method
ISMediatorRuntimeFacade.setContextVariableValue().
To get the entire structure, you must:
Set the varName parameter in
pub.mediator.ctxvar:getContextVariable to
PROTOCOL_HEADERS or SOAP_HEADERS.
Use the method
ISMediatorRuntimeFacade.getContextVariableValue().
If varName is set to PROTOCOL_HEADERS, you will get/set the entire IData structure containing all of the transport headers. The key is the transport header name (e.g., Content-Type) and the value is a String. The IData object for PROTOCOL_HEADERS will contain a set of string values where each IData string key matches the header name in the transport headers map. The set of possible keys includes the HTTP v1.1 set of headers as well as any custom key-value pairs you might have defined.
If varName is set to SOAP_HEADERS, you will get/set the entire IData structure containing all of the SOAP headers in the SOAP envelope. The key is the array position starting with '0', and the value is an Axiom OMElement containing that SOAP header block.
Alternatively, you can set the varName parameter to address a specific element in the array. For example, setting it to PROTOCOL_HEADERS[Content-Type] would apply to the Content-Type transport header. Similarly, setting it to SOAP_HEADERS[0] would return a String representation of the first SOAP header block (as opposed to an Axiom OMElement).
Set a nested value in one of the following ways:
Set the varName parameter in
pub.mediator.ctxvar:setContextVariable to
PROTOCOL_HEADERS[arrayElement], where
[arrayElement] refers to a specific
element. For example, PROTOCOL_HEADERS[Content-Type] or
SOAP_HEADERS[0] (to indicate the first array element in the
set).
Alternatively, use the method
ISMediatorRuntimeFacade.setContextVariableValue(). You would use
this method only if you are writing a Java service and you want to access it
through the Java source code.
Get a nested value in one of the following ways:
Set the varName parameter in
pub.mediator.ctxvar:getContextVariable to
PROTOCOL_HEADERS[arrayElement], where
[arrayElement] refers to a specific
element. For example, PROTOCOL_HEADERS[Content-Type] or
SOAP_HEADERS[0] (to indicate the first array element in the
set).
Alternatively, use the method
ISMediatorRuntimeFacade.getContextVariableValue(). You would use
this method only if you are writing a Java service and you want to access it
through the Java source code.
You can set/get a nested value inside PROTOCOL_HEADERS and SOAP_HEADERS via an additional keyName. In this case, the object reference will not be an IData object.
For PROTOCOL_HEADERS, the keyName must match the transport header
name in a case-sensitive manner (e.g.,
PROTOCOL_HEADERS[Content-Type] or
PROTOCOL_HEADERS[Authorization]). In this case, the Serializable
value will be a string.
For SOAP_HEADERS, the keyName must match the 0-based array element. If a request has a SOAP security header element (i.e. </wsse:Security>), then it would be addressed as SOAP_HEADERS[0]. In this case, the element will be in its string format.
Use this Java service to set a value on a context variable. The pipeline variable containing the context variable value should be an object reference that implements java.io.Serializable. All parameter names are case-sensitive.
| Parameter | Pipeline Type | Data Type | Description | Examples |
|---|---|---|---|---|
| MessageContext | in | Object ref | This object is inserted into the pipeline by Mediator. | N/A |
| varName | in | String | Context variable name (predefined or custom). | PROTOCOL_HEADERSSOAP_HEADERSmx:CUSTOM_VAR |
| serValue | in | Object ref | Java.io.serializable value. (Usually a string). |
Use this Java service to declare a custom context variable.
All custom-defined context variables must be declared in a custom namespace
that is identified by using the prefix mx (e.g.,
mx:CUSTOM_VARIABLE). All parameter names are case-sensitive.
Note:
It is not legal to use this service to declare the predefined
context variables; you can only declare custom variables.
| Parameter | Pipeline Type | Data Type | Description |
|---|---|---|---|
| ctxVar | in | Object ref | The document type defining the context variable object. Use the ctxVar Document Type provided in the Java service pub.mediator.ctxvar:ctxVar and map it to this input variable. Define the name (for example, mx:CUSTOM_VARIABLE), the schema_type (string or int), and isReadOnly (true or false). |
| ctxVar | out | Object ref | The set Context variable document type. |
| varNameQ | out | Object ref | javax.xml.namespace.QName value. The QName of the variable. |
Note the following:
After declaring the context variable, you can use the setContext variable to set a value on the context variable.
You do not need to declare the following kinds of context variables:
The predefined context variables provide by Mediator. If you attempt to declare an existing predefined context variable, an error will occur.
Any custom context variable that you define in a routing rule that you create in the Context-Based Routing step.
Any custom context variables that you explicitly declare in source code using the API will have a declaration scope of SESSION.
Any custom context variable's state that is defined during the inbound request processing steps will still be available during the outbound response processing steps.
All context variable values are typed as either "string" or "int" (excluding the SOAP_HEADERS and PROTOCOL_HEADERS variables, which are of the type "IData").
Valid names should be upper case (by convention) and must be a valid Java Identifier. In general, use alpha-numerics, $ or _ symbols to construct these context names. Names with punctuation, whitespace or other characters will be considered invalid and will fail deployment.
All custom context variables must be declared in a custom namespace
that is identified by using an mx prefix (e.g.
mx:CUSTOM_VARIABLE).
To reference a custom context variable in a flat string, you need to prepend a $ symbol to the context variable name to indicate that variable’s value should be referenced. Think of this usage as being similar to the ‘&’ address operation for C variables.
An expression that references a custom context variable might look like this:
$mx:TAXID=1234 or
$mx:ORDER_SYSTEM_NAME="Pluto"
Notice that the values of the data type “int” are not enclosed in quotation marks, while the values of the data type “string” are. The quotation marks are only needed if a context variable expression (as opposed to a reference) is defined.
Referencing an undefined context variable does not result in an error.
Once a variable has been declared it cannot be declared again.
Use this Java service to remove a custom context variable from a request/response session. All parameter names are case-sensitive.
Notes:
| Parameter | Pipeline Type | Data Type | Description | Examples |
|---|---|---|---|---|
| MessageContext | in | Object ref | This object is inserted into the pipeline by Mediator. | N/A |
| varName | in | String | Custom context variable name. | mx:CUSTOM_VAR |
This flow service gets the value of a custom context variable from a
request. The service declares a context variable using the name defined in the
pipeline variable customName ( i.e.,
mx:COMP_TEST). It is hard-coded to store the predefined context
variable SERVICE_NAME in this custom context variable name.
Step 1. Setting varName and customName
In this flow service, the following pipeline variables that are hard-coded as follows:
varName is set to the predefined context
variable SERVICE_NAME.
customName is set to
mx:COMP_TEST. SERVICE_NAME is stored in
customName in the "Pipeline Out".
Step 2. Calling the pub.mediator.ctxvar:getContextVariable service
The call to pub.mediator.ctxvar:getContextVariable looks
up the context variable value for the "Pipeline In" variable
varName and sets the Serializable value in
the output pipeline variable named serValue.
Step 3. Calling the pub.mediator.ctxvar:declareContextVariable service
The call to pub.mediator.ctxvar:declareContextVariable
takes the serialized value we looked up for varName and
assigns it to a newly declared custom context variable named
ctxVar.
Step 4. Calling the pub.mediator.ctxvar:setContextVariable service
The call to pub.mediator.ctxvar:setContextVariable sets
the context variable value back into MessageContext so
it will be available for the rest of the service invocation steps.
This flow service sets the value of a custom context variable to be used in a response.
This flow service declares a pipeline variable named
customName, which is set to the value
mx:COMP_TEST.
This flow service will retrieve the context variable for
customName and create an element for its context variable value in
the response message return to the consumer.
Step 1. Declaring customName
We define the customName variable value to be
mx:COMP_TEST so we can use this variable to lookup the custom
variable name that was seeded in the previous example.
Step 2. Setting customName to mx:COMP_TEST
Clicking on the customName pipeline variable will display
the name.
Step 3. Displaying the value of customName
The call to pub.mediator.ctxvar:getContextVariable
retrieves the value of the custom context variable from the context variable
map.
Step 4. Calling meditor.ctxvar:getContextVariable
This is just a sample Java service that takes the context variable and creates a top-level element in the response message using the same name and value.
Step 5. Sample service using the context variable
