The API for Context Variables

Cloud Application Integration (On-Premises) : Administering CloudStreams : Virtual Services : Creating a New Virtual Service (SOAP) : IS Service Constructs : Using Context Variables in IS Services : The API for Context Variables

CloudStreams 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.)

CloudStreams provides the following Java services (described below):

pub.cloudstreams.ctxvar:getContextVariable

pub.cloudstreams.ctxvar:setContextVariable

pub.cloudstreams.ctxvar:declareContextVariable

pub.cloudstreams.ctxvar:removeContextVariable

The following sample flow services are described in this section as well:

Sample Flow Service: Getting a Context Variable Value

Sample Flow Service: Setting a Context Variable Value

pub.cloudstreams.ctxvar:getContextVariable

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
MessageContext	in	Object ref	This object is inserted into the pipeline by CloudStreams.
varName	in	String	Context variable name (predefined or custom). Examples: PROTOCOL_HEADERS, SOAP_HEADERS, mx:CUSTOM_VAR
serValue	out	Object ref	java.io.Serializable value. (Usually a string).

Notes on Getting and Setting the PROTOCOL_HEADERS and SOAP_HEADERS Variables

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:

1. Set/get the entire structure.

To set the entire structure, you must:

Set the varName parameter in pub.cloudstreams.ctxvar:setContextVariable to PROTOCOL_HEADERS or SOAP_HEADERS.

Use the method RuntimeFacade.setContextVariableValue().

To get the entire structure, you must:

Set the varName parameter in pub.cloudstreams.ctxvar:getContextVariable to PROTOCOL_HEADERS or SOAP_HEADERS.

Use the method RuntimeFacade.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 (for example, 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).

2. Set/get a nested value.

Set a nested value in one of the following ways:

Set the varName parameter in pub.cloudstreams.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 RuntimeFacade.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.cloudstreams.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 RuntimeFacade.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 (for example, 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 (</wsse:Security>), then it would be addressed as SOAP_HEADERS[0]. In this case, the element will be in its string format.

pub.cloudstreams.ctxvar:setContextVariable

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
MessageContext	in	Object ref	This object is inserted into the pipeline by CloudStreams.
varName	in	String	Context variable name (predefined or custom). Examples: PROTOCOL_HEADERS, SOAP_HEADERS, mx:CUSTOM_VAR
serValue	in	Object ref	Java.io.serializable value. (Usually a string.)

pub.cloudstreams.ctxvar:declareContextVariable

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 (for example, 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
ctxVr	in	Object ref	The document type defining the context variable object. Use the ctxVar Document Type provided in the Java service pub.cloudstreams.ctxvar:ctxVar and map it to this input variable. Define the name of the context variable (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 variables provided by CloudStreams. 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 a "Context-Based" Routing Rule 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 (for example, 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.

pub.cloudstreams.ctxvar:removeContextVariable

Use this Java service to remove a custom context variable from a request/response session. All parameter names are case-sensitive.

Note:

It is not legal to use this service to remove any predefined context variables; you can only remove custom variables.

Note:

Attempting to remove a non-existent context variable will not result in an error.

Parameter	Pipeline Type	Data Type	Description
MessageContext	in	Object ref	This object is inserted into the pipeline by CloudStreams.
varName	in	String	Custom context variable name. Example: mx:CUSTOM_VAR.

Sample Flow Service: Getting a Context Variable Value

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 (that is, 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, and SERVICE_NAME is stored in customName in the "Pipeline Out".

Step 2: Calling the pub.cloudstreams.ctxvar:getContextVariable service

The call to pub.cloudstreams.ctxvar:getContextVariable looks up the context variable value for the "Pipeline In" variable varName and sets the Serializable value in the "Pipeline Out" variable serValue.

Step 3: Calling the pub.cloudstreams.ctxvar:declareContextVariable service

The call to pub.cloudstreams.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.cloudstreams.ctxvar:setContextVariable service

The call to pub.cloudstreams.ctxvar:setContextVariable sets the context variable value back into MessageContext so it will be available for the rest of the service invocation steps.

Sample Flow Service: Setting a Context Variable Value

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 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.cloudstreams.ctxvar:getContextVariable retrieves the value of the custom context variable from the context variable map.

Step 4: Calling pub.cloudstreams.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

Contact Support | Community | Feedback