Intelligent Management: HTTP operands

Intelligent Management: HTTP operands

Use the HTTP operands in the subexpression utility builder, an optional tool that helps you build complex rule conditions from subexpressions using AND, OR, NOT and parenthetical grouping.

Rules
HTTP request operands
HTTP response operands
Xpath expression
Operators

Rules

Each work class contains an optional ordered list of rules that are evaluated for a particular request to determine the policy for that request. Each rule consists of a Boolean expression and a policy value. If the expression evaluates to true for a particular request, the policy associated with that rule is used.

The syntax and semantics of a Boolean expression for a rule are similar to the WHERE clause of a Structured Query Language (SQL) expression. More precisely, the syntax of an expression is defined by the Java Message Service (JMS) 1.1 specification. request classification.

See: Rule-based request classification
In the JMS specification, identifiers refer to various attributes that can be associated with a request, for example, a specific query parameter, cookie, or HTTP header. A JMS identifier can be thought of as a request variable, or operand. These operands can be specific to a protocol. For example, the SOAP service name is an operand that is valid only in a SOAP work class.

Because the SOAP is over HTTP, the HTTP operands are also valid in a SOAP request. JMS specification uses literals to specify a specific value to use in a comparison to a request variable. For example, in the expression:
clienthost LIKE '%.ibm.com'

...'%.ibm.com' is a literal used to compare to the client host name for a request. This expression is true for all requests that originate from a computer in the ibm.com domain. Enclose string literals by single quotes. Do not enclose numeric literals in single quotes. Parentheses together with the AND, OR, and NOT operators can also be used to form compound Boolean expressions. See the JMS 1.1 specification for a detailed description.

HTTP request operands

Operand Syntax Description
Client host
clienthost The fully-qualified client host name. This is the value of the internet protocol (IP) command host name. This operand does not support numeric operators such as >, >=, <, <=.
Client IPV4
clientipv4 The IP address of the client using the Internet Protocol version 4 (IPv4) dotted quad address type n.n.n.n.
Client IPV6
clientipv6 The Internet Protocol version 6 (IPv6) 128-bit address type of x:x:x:x:x:x:x:x following Request for Comments 1924 (RFC 1924) of the client computer.
Cookie name
cookie$<name> A cookie name.
For example, the expression...
cookie$My_Cookie_Name='My_Cookie_Value'

...tests a request to see if it contains a cookie named My_Cookie_Name with a value of My_Cookie_Value. To test for the presence or absence of a particular cookie, use one of the following expressions:
cookie$MyCookieName IS NOT NULL
cookie$MyCookieName IS NULL

Header name
header$<name> A header name and value.
For example, the expression header$Host='localhost' tests a request to see if it contains an HTTP host header with a value of localhost. To test for presence or absence of the host header, use one of the following expressions:
header$Host IS NOT NULL
header$Host IS NULL

HTTP method
HTTPMethod The HTTP method for the request. Possible values are POST, GET, PUT, and DELETE.
MIME type
MIMEType The MIME type of the request.
Percentage
percentage$<val> The percentage operand evaluates to true, a fixed percentage of the time.
For example, percentage$50 evaluates to true on average 50% of the time.

Port
port The listening port on which the request was received.
Protocol
protocol The communications protocol that transmits the request. Currently supported protocols are HTTP, HTTPS, SOAP, and SOAPS.
Query parameter
queryparm$<name> A header name and value.
For example, the expression...
queryparm$timezone='EST'

...tests a request to see if the request contains an HTTP query parameter named timezone with a value of EST. To test for presence or absence of a query parameter, use one of the following forms:
queryparm$timezone IS NOT NULL
queryparm$timezone IS NULL

Rampup
rampup$<startTime>
$<completionTime>
The rampup operand evaluates to true a variable percentage of the time. It always evaluates to false before <startTime> and to true after <completionTime>. As time progresses from <startTime> to <completionTime>, it evaluates to true, a linearly increasing percentage.
The format of <startTime> and <completionTime> is day/month/year::hour:min:sec.
where day is the day of the month, month is one of the twelve months: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec, year is the 4 digit year, hour is the 2 digit hour of the 24 hour clock, and min and sec are 2 digit values for minute and second, respectively.
For example,

rampup$01/Jan/2007::08:00:00$01/Jan/2007::17:00:00

...begins to occasionally evaluate to true at 8 AM on Jan 1, 2007 and always evaluates to true by ramp up completion time at 5 PM of the same day.
Scheme of URI
request.uri.scheme The scheme of the URI.

Server host
serverhost The fully-qualified host name of the server. This operand does not support numeric operators such as >, >=, <, <=.
Server IPV4
serveripv4 The IP address of the server computer using the IPv4 dotted quad address type n.n.n.n.
Server IPV6
serveripv6 The IPv6 128-bit address type of x:x:x:x:x:x:x:x following RFC 1924 of the server computer.
Service
service The name of a Web service.
Time
time Date and time of day that a given request must be honored. Two optional fields are StartTime and EndTime. If a request is received outside of that defined window, the request will not be processed.

The Start Time and End Time fields each have the following format:
dayOfWeek/dayOfMonth/month/year::hour:minute:second

For example, Thursday, the 11th of April, year 2007 at 1:03:45 PM is specified as:

Thu/11/Apr/2007::13:03:45

The dayofWeek values are Sun, Mon, Tue, Wed, Thu, Fri, Sat, and the dayOfMonth values range from 1-31.

The month value is a non-numeric value that represents the twelve months: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec.

The year value is comprised of the year's four digits. For example, 2007.

The hour value is the hour of day in the 24-hour clock. For example, 8am is represented as ::8. The minute and second are integers ranging from 0-59.

Omissions and wild cards are not supported for the time operand.
The forward slash (/) is used to separate date parameters, the double colon (::) is used to separate the date parameters, and the colon (:) is used to separate the time of day parameters. Note that it is the Boolean result of the entire rule in which the time operand is used that determines the routing action taken.

URI
uri Uniform Resource Identifier

Virtual Host
virtualhost Virtual host target of the request, used for configuring Web applications to a particular host name.

Virtual Port
virtualport Virtual port target of the request, used for configuring Web applications to a particular port.

Virtual Portal
virtualportal Virtual portals are created within WebSphere Portal Server, and Intelligent Management supports this operand for better integration with WebSphere Portal Server. The virtual portal is the request URL minus the context root for the WebSphere Portal application's Web module. If a given request matches the virtual portal defined, then the routing action defined for that rule is taken.

HTTP response operands
When we are using a custom log file, we can use the following operands in addition to the operands in Table 1:

Operand Syntax Description
Response code
response.code Filters by HTTP response codes, such as 404, 503, and so on.

Response time
response.time The number of milliseconds between when the request in the ODR is received, and until the response from the ODR is sent.

Response write error
response.write.error
Logs errors that can occur when writing a response to a client.

Service time
service.time The number of milliseconds between when the request is sent to the application server, and when a response is received from the application server.

Target server
targetserver Shows the server where the request was sent, in a WAS format. For example, mycell/mynode/myserver.

Xpath expression

The syntax for the Xpath expression is xpathexpr and is supported by HTTP.

The XPath string expression has a required field containing the XPath expression and an optional field for defining local namespaces. If all the namespaces contained in the XPath expression are standard, the second field can be optional. If there are multiple local namespaces, separate each with a comma (,).

xpathexpr with one local namespace definition:

xpathexpr$/http:Envelope/soap:Body/m:getTimeZone/n:clientId$n\\=http://test2.classify.ws.ibm.com = \\'1000\\' or operation IS NOT NULL

In the previous expression, the XPath expression is...
/http:Envelope/soap:Body/n:getTimeZone/n:clientId

It contains the local namespace of n. So, the second field of the xpathexpr is defined as...
n\\=http://test.classify.ws.ibm.com

The dollar sign ($) is used to denote the start of a field definition. The double backslashes are the escape sequence in this example. The first equals sign (=) is escaped because it is part of the local namespace definition, whereas the second equals sign (=) is the operator in the classification expression and must not be escaped.

xpathexpr with two local namespaces:

xpathexpr$/http:Envelope/http:Body/m:getTimeZone/n:clientId$m\\=http://test.classify.ws.ibm.com,n\\=http://test2.classify.ws.ibm.com = \\'1000\\' or operation IS NOT NULL

The following table shows the standard namespaces for the xpathexpr expression:

Namespace URL
soap http://schemas.xmlsoap.org/soap/envelope/
soap-env http://schemas.xmlsoap.org/soap/envelope/
soapenc http://schemas.xmlsoap.org/soap/encoding/
soapbind http://schemas.xmlsoap.org/wsdl/soap/
xsd http://www.w3.org/2001/XMLSchema
xsi http://www.w3.org/2001/XMLSchema-instance
xsi http://ws-i.org/schemas/conformanceClaim/
wsdl http://schemas.xmlsoap.org/wsdl/

Operators

Intelligent Management supports the operators in the following table in the rules expressions. These operators are also referred to as predicates in SQL terminology because they appear inside of a WHERE or HAVING clause. Operators are case insensitive.

Operator Description
Equals Ignore Case (EQUALSIGNORECASE) Identical to 'String = String', except that the case of the strings is ignored. So, 'ABC' EQUALSIGNORECASE 'abc' would evaluate to true. ('ABC' = 'abc') evaluates to false.
Not Equals ( <> ) The operand value is not equal to the value you enter.
In (IN) Expresses an operand with multiple values in a single expression. For example, if, for an operand called port, we want to express that the port value can be any or all of the values such as 9080, 9090, 9091, the expression fragment is port IN (9080,9090,9091). How the values inside the brackets are expressed depends on the data type of port. If port is an integer, the correct syntax is the values without quote marks. If port is a string, the correct syntax is port IN ('9080','9090','9091').
Like (LIKE) Expresses pattern matching for string operand values. The value must contain the wildcard character percent sign (%) in the position where the pattern matching starts. For example, the expression, host LIKE %blanca, matches the word blanca, or any other word that ends in blanca, while the expression host LIKE blanca% matches the word blanca or any other word that starts with blanca, and the expression, host LIKE %blanca% matches the word blanca or any word that has blanca embedded in it.
Like Ignore Case (LIKEIGNORECASE) Identical to 'string like string' except that the case of the strings is ignored.
Is Not Null (IS NOT NULL) Expresses that a validation of the query shows that the requested parameter exists.
Concatenate (+) Expresses two character strings joined together: + 'def' = 'abcdef'.
Like In (LIKEIN) Expresses string likein (string1, string2, string3, etc.) evaluates to true if the string to the left of "likein" matches one or more of the strings (stringN)
Is Null (IS NULL) Expresses that a validation of the query shows that the requested parameter does not exist.
Equals ( = ) Expresses a case-sensitive match.

Related:

Rule-based request classification
Custom log file format
Define a service policy
Set maintenance mode
Activate concurrent application editions
Validate an edition
manageODR.py script
Intelligent Management: rules for ODR routing policy administrative tasks
Intelligent Management: rules for ODR service policy administrative tasks

Operand	Syntax	Description
Client host	clienthost	The fully-qualified client host name. This is the value of the internet protocol (IP) command host name. This operand does not support numeric operators such as >, >=, <, <=.
Client IPV4	clientipv4	The IP address of the client using the Internet Protocol version 4 (IPv4) dotted quad address type n.n.n.n.
Client IPV6	clientipv6	The Internet Protocol version 6 (IPv6) 128-bit address type of x:x:x:x:x:x:x:x following Request for Comments 1924 (RFC 1924) of the client computer.
Cookie name	cookie$<name>	A cookie name. For example, the expression... cookie$My_Cookie_Name='My_Cookie_Value' ...tests a request to see if it contains a cookie named My_Cookie_Name with a value of My_Cookie_Value. To test for the presence or absence of a particular cookie, use one of the following expressions: cookie$MyCookieName IS NOT NULL cookie$MyCookieName IS NULL
Header name	header$<name>	A header name and value. For example, the expression header$Host='localhost' tests a request to see if it contains an HTTP host header with a value of localhost. To test for presence or absence of the host header, use one of the following expressions: header$Host IS NOT NULL header$Host IS NULL
HTTP method	HTTPMethod	The HTTP method for the request. Possible values are POST, GET, PUT, and DELETE.
MIME type	MIMEType	The MIME type of the request.
Percentage	percentage$<val>	The percentage operand evaluates to true, a fixed percentage of the time. For example, percentage$50 evaluates to true on average 50% of the time.
Port	port	The listening port on which the request was received.
Protocol	protocol	The communications protocol that transmits the request. Currently supported protocols are HTTP, HTTPS, SOAP, and SOAPS.
Query parameter	queryparm$<name>	A header name and value. For example, the expression... queryparm$timezone='EST' ...tests a request to see if the request contains an HTTP query parameter named timezone with a value of EST. To test for presence or absence of a query parameter, use one of the following forms: queryparm$timezone IS NOT NULL queryparm$timezone IS NULL
Rampup	rampup$<startTime> $<completionTime>	The rampup operand evaluates to true a variable percentage of the time. It always evaluates to false before <startTime> and to true after <completionTime>. As time progresses from <startTime> to <completionTime>, it evaluates to true, a linearly increasing percentage. The format of <startTime> and <completionTime> is day/month/year::hour:min:sec. where day is the day of the month, month is one of the twelve months: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec, year is the 4 digit year, hour is the 2 digit hour of the 24 hour clock, and min and sec are 2 digit values for minute and second, respectively. For example, rampup$01/Jan/2007::08:00:00$01/Jan/2007::17:00:00 ...begins to occasionally evaluate to true at 8 AM on Jan 1, 2007 and always evaluates to true by ramp up completion time at 5 PM of the same day.
Scheme of URI	request.uri.scheme	The scheme of the URI.
Server host	serverhost	The fully-qualified host name of the server. This operand does not support numeric operators such as >, >=, <, <=.
Server IPV4	serveripv4	The IP address of the server computer using the IPv4 dotted quad address type n.n.n.n.
Server IPV6	serveripv6	The IPv6 128-bit address type of x:x:x:x:x:x:x:x following RFC 1924 of the server computer.
Service	service	The name of a Web service.
Time	time	Date and time of day that a given request must be honored. Two optional fields are StartTime and EndTime. If a request is received outside of that defined window, the request will not be processed. The Start Time and End Time fields each have the following format: dayOfWeek/dayOfMonth/month/year::hour:minute:second For example, Thursday, the 11th of April, year 2007 at 1:03:45 PM is specified as: Thu/11/Apr/2007::13:03:45 The dayofWeek values are Sun, Mon, Tue, Wed, Thu, Fri, Sat, and the dayOfMonth values range from 1-31. The month value is a non-numeric value that represents the twelve months: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec. The year value is comprised of the year's four digits. For example, 2007. The hour value is the hour of day in the 24-hour clock. For example, 8am is represented as ::8. The minute and second are integers ranging from 0-59. Omissions and wild cards are not supported for the time operand. The forward slash (/) is used to separate date parameters, the double colon (::) is used to separate the date parameters, and the colon (:) is used to separate the time of day parameters. Note that it is the Boolean result of the entire rule in which the time operand is used that determines the routing action taken.
URI	uri	Uniform Resource Identifier
Virtual Host	virtualhost	Virtual host target of the request, used for configuring Web applications to a particular host name.
Virtual Port	virtualport	Virtual port target of the request, used for configuring Web applications to a particular port.
Virtual Portal	virtualportal	Virtual portals are created within WebSphere Portal Server, and Intelligent Management supports this operand for better integration with WebSphere Portal Server. The virtual portal is the request URL minus the context root for the WebSphere Portal application's Web module. If a given request matches the virtual portal defined, then the routing action defined for that rule is taken.

Operand	Syntax	Description
Response code	response.code	Filters by HTTP response codes, such as 404, 503, and so on.
Response time	response.time	The number of milliseconds between when the request in the ODR is received, and until the response from the ODR is sent.
Response write error	response.write.error	Logs errors that can occur when writing a response to a client.
Service time	service.time	The number of milliseconds between when the request is sent to the application server, and when a response is received from the application server.
Target server	targetserver	Shows the server where the request was sent, in a WAS format. For example, mycell/mynode/myserver.

Namespace	URL
soap	http://schemas.xmlsoap.org/soap/envelope/
soap-env	http://schemas.xmlsoap.org/soap/envelope/
soapenc	http://schemas.xmlsoap.org/soap/encoding/
soapbind	http://schemas.xmlsoap.org/wsdl/soap/
xsd	http://www.w3.org/2001/XMLSchema
xsi	http://www.w3.org/2001/XMLSchema-instance
xsi	http://ws-i.org/schemas/conformanceClaim/
wsdl	http://schemas.xmlsoap.org/wsdl/

Operator	Description
Equals Ignore Case (EQUALSIGNORECASE)	Identical to 'String = String', except that the case of the strings is ignored. So, 'ABC' EQUALSIGNORECASE 'abc' would evaluate to true. ('ABC' = 'abc') evaluates to false.
Not Equals ( <> )	The operand value is not equal to the value you enter.
In (IN)	Expresses an operand with multiple values in a single expression. For example, if, for an operand called port, we want to express that the port value can be any or all of the values such as 9080, 9090, 9091, the expression fragment is port IN (9080,9090,9091). How the values inside the brackets are expressed depends on the data type of port. If port is an integer, the correct syntax is the values without quote marks. If port is a string, the correct syntax is port IN ('9080','9090','9091').
Like (LIKE)	Expresses pattern matching for string operand values. The value must contain the wildcard character percent sign (%) in the position where the pattern matching starts. For example, the expression, host LIKE %blanca, matches the word blanca, or any other word that ends in blanca, while the expression host LIKE blanca% matches the word blanca or any other word that starts with blanca, and the expression, host LIKE %blanca% matches the word blanca or any word that has blanca embedded in it.
Like Ignore Case (LIKEIGNORECASE)	Identical to 'string like string' except that the case of the strings is ignored.
Is Not Null (IS NOT NULL)	Expresses that a validation of the query shows that the requested parameter exists.
Concatenate (+)	Expresses two character strings joined together: + 'def' = 'abcdef'.
Like In (LIKEIN)	Expresses string likein (string1, string2, string3, etc.) evaluates to true if the string to the left of "likein" matches one or more of the strings (stringN)
Is Null (IS NULL)	Expresses that a validation of the query shows that the requested parameter does not exist.
Equals ( = )	Expresses a case-sensitive match.