About Properties

Properties are variables that hold values associated with the request or response phase of an operation. A property value can correspond to a message element, a fragment of an element, the combined value of several elements from the same message, or an expression that uses a message element. You can use a message element from either the message header or body to define a property.

Properties are commonly used to facilitate searches, to surface message elements without having to log message content, to define conditions, and so on.

This section explains the different ways you can define and use properties. It also describes standard properties that are defined by BTM for any operation.

Property definitions are shown in the Properties tab for any transaction that includes the service operation for which a property has been defined. Property definitions are also shown in the Properties tab for the service operation, endpoint operation, service, and endpoint. However, you can modify or delete a property only from the Properties tab for a transaction.

Using Properties

Using properties helps you do the following:

Surface aspects of a message that you would otherwise need to drill down to see. The use of properties can improve performance by making it possible for you to view values of message elements without having to log message content.
Define keys that allow you to manually correlate the operations that make up a transaction
Segment transactions by consumer
Define a condition that depends on the value of a message property

For example, imagine you have a service element containing a customer ID. If you wanted to know which customers experience exceptions on a transaction that includes the operation, you could create a property to hold the value of the customer ID element. Then, when you inspect performance results, the ID of customers experiencing exceptions on that transaction would be prominently displayed.

Standard properties, described in the next section, are defined by Business Transaction Management; user-defined properties, as the name suggests, are defined by the user as described in User-Defined Properties.

Standard Properties

The properties described in the following table are defined by BTM for any message. Standard properties are defined for each phase of a message: request, response, and fault. You can use the aggregateCount, aggregateFaultCount and the ECID-based properties in searches. You can use the ECID-based properties for manual keys.

Table 4-1 Standard Properties

Message Phase	Property Name	Description
Request	`aggregateCount`	The number of calls associated with this `execute` statement. For more information, see Effects of Enabling JDBC Summary.
	`aggregateFaultCount`	The number of faults associated with the given `execute` statement. For more information, see Effects of Enabling JDBC Summary.
	`arrivalTime`	The arrival time of the request message measured as milliseconds elapsed since January 1, 1970, 00:00:00 UT.
	`count`	The number of times the requested operation was invoked in the current transaction instance. Each request increments the count even if the operation does not execute successfully.
	`exists`	A boolean expression that is true if the request message has arrived as part of the current transaction instance.
	`interactionId`	For internal use only.
	`requestECID`	The ECID associated with the request phase of the selected operation. For more information, see ECID Basics.
	`sender`	Deprecated. Do not use. This property will be removed from future releases. A string identifying the sender of the request message. This is typically the username portion of the credentials that the sending application provides to the application server in which the receiving service is deployed. This property is set only if the application server authenticates users.
Response	`arrivalTime`	The arrival time of the response message measured as milliseconds elapsed since January 1, 1970, 00:00:00 UT.
	`exists`	A boolean expression that is true if the response message has arrived as part of the current transaction instance.
	`interactionId`	For internal use only.
	`responseECID`	The ECID associated with the response phase of the selected operation. For more information, see ECID Basics.
	`responseTime`	The time interval between the arrival of the request message and the arrival of its corresponding response message measured in milliseconds.
	`sender`	Deprecated. Do not use. This property will be removed from future releases.
Fault	`actor`	The value of the fault message's `faultactor` element, which provides information about who caused the fault to happen within the message path.
	`arrivalTime`	The arrival of the fault message measured as milliseconds elapsed since January 1, 1970, 00:00:00 UT.
	`code`	The value of the fault message's `faultcode` element, which provides an algorithmic mechanism for identifying the fault.
	`detail`	The falue of the fault's message's detailcode element, which provides application-specific error information related to the `Body` element.
	`exists`	A Boolean expression that is true ifthe fault message has arrived as part of the current transaction instance.
	responseTime	The time interval between the arrival of the request message and the arrival of its corresponding fault message measured in milliseconds.
	`sender`	Deprecated. Do not use. This property will be removed from future releases.
	`string`	The value of the fault message's faultstring element, which provides a human-readable explanation of the fault and is not intended for algorhithmic processing.

User-Defined Properties

A property can be based on any XPath expression defined on a request or response message, including message content or message headers (for example, SOAP headers, HTTP headers, or JMS message properties).

The simplest type of property holds the value of a single message element. For example, you might have the following message element:

OrcerServiceImpl.submit.request.order.orderId

You could create a property named Order_ID whose value is the value of this element.

You can also create a property that stores the result of a computation involving one or more message elements. For example, you might multiply an element that holds a price times a constant to compute tax:

OrderServiceImpl.submit.request.order.grandTotal *.0825

You could store the result in a property named Tax_Due.

In some cases, you might not be able to extract the data you need from messages directly. In these cases, you can create a property based on an XPath expression to extract data from your message and perform computations.

For example, if your message contains an indeterminate number of <item> elements, you could create a property to count the number of <item> elements in the message and store that value.

You might also use an XPath expression to extract data from an XML element that itself contains an encoded XML document.

Finally, you might have a service that is missing a WSDL. Using Business Transaction Management you can log a message from this service and then use the XML view to obtain the element you need to define the desired property.

The following subsections provide additional information about creating, modifying, duplicating, and deleting properties.