Properties are variables that hold values associated with the request or response phase of an operation (message). This section explains how you use Business Transaction Management to work with properties. It includes the following sections:
The process you use to define a message property varies depending on whether the property corresponds to a single message element, a fragment of an element, a combination of elements, or an expression that includes an element.
You can access the Create Message Property tool by selecting a service, operation, or endpoint in any view; then select Create Message PropertyonName from the Create menu.
Independently of the kind of property you create, you will need to specify the following information (in addition to specifying the message element that supplies the property value):
A Name for the property
The Operation (message) whose content you will use to define the property value
An optional Description explaining the purpose of the property or anything other notes you want to retain about this property.
The Property Source: where the value of the property is to be obtained.
Whether the property should be mapped to a consumer through a particular attribute. If you want the property to be associated with a particular consumer attribute, check the Consumer Mapping check box. By default, the only user attribute defined by the system is Consumer Name. You can define other consumer attributes if you need to.
Whether the value of the property can be accessed only by Business Transaction Management users whose role allows them to view sensitive information. To restrict access, click the Treat as sensitive check box.
If you define a new property after messages have been collected, the logged messages will not include the newly defined properties.
The following procedures describe how you can create properties based on a single element, based on an element fragment, or based on more than one message element.
Defining a property based on a single element
Select a service, operation, or endpoint in any view.
Select Create Message Property on Name from the Create menu.
Specify the name of the property. If you do not provide a name, uses the message element name for the property name.
Property Source: Specify whether the element of interest is part of the message content or the message header.
If you select Header, Business Transaction Management displays a small dialog you must use to specify the Header Name, the phase (request, response, fault), and the data type. Then skip to Step 8. Steps 5-8 apply if you selected Message Content.
Click the Pick from Message link to display the message elements.
Use the Message drop down list to select Request or Response.
Double click the message element to select it.
Click the Consumer Mapping check box if you want to map this property to a consumer attribute.
Select the attribute if there is more than one.
Click the Sensitivity check box if you want to restrict access to the property value.
Click OK.
Defining a property based on an arithmetic expression
Select a service, operation, or endpoint in any view.
Select Create Message Propertyon Name from the Create menu.
Specify the name of the property. If you do not provide a name, Business Transaction Management uses the element name for the property name.
Property Source: Select Message Content.
Click the Pick from Message link to display the message elements.
Use the Message drop down list to select Request or Response.
Double click the message element to select it.
Click the Convert To XPath item. The display shows the XPath definition of the element.
In the XPath box, create the desired expression. For example, if you want to define a Tax property that computes tax, you could take the original XPath expression for the Price element
/soapenv:Envelope/soapenv:Body/*[local-name(.)='submit']/^* [1]/^tns1:OrderItems/^tns1:Price
and define it to compute a tax of 10% ; for example:
/soapenv:Envelope/soapenv:Body/*[local-name(.)='submit']/^* [1]/^tns1:OrderItems/^tns1:Price * .10
Click the Consumer Mapping check box if you want to map this property to a consumer attribute.
Select the attribute if there is more than one.
Click the Sensitivity check box if you want to restrict access to the property value.
Click OK.
Defining a property based on the partial contents of an element
This might be useful if you have nested xml documents and want the property's value to contain a nested element.
Select a service, operation, or endpoint in any view.
Select Create Message Propertyon Name from the Create menu.
Specify the name of the property. If you do not provide a name, Business Transaction Management uses the element name for the property name.
Property Source: Select Message Content.
Click the Pick from Message link to display the message elements.
Use the Message drop down list to select Request or Response.
Double click the message element to select it.
Click the Convert To XPath item. The display shows the XPath definition of the element.
Edit the XPath expression to limit the property value to the nested element.
Click the Consumer Mapping check box if you want to map this property to a consumer attribute.
Select the attribute if there is more than one.
Click the Sensitivity check box if you want to restrict access to the property value.
Click OK.
Defining a property based on the combined contents of multiple elements of the same message
This might be useful if you need to provide manual keys to correlate messages but no single message element is unique to a service. You can create a property for the unique value that results from combining two message elements; for example, Customer ID and zip code.
The following procedure assumes you are combining two elements. You can extend this case for additional elements.
Select a service, operation, or endpoint in any view.
Select Create Message Propertyon Name from the Create menu.
Property Source: Select Message Content.
Click the Pick from Message link to display the message elements.
Use the Message drop down list to select Request or Response.
Double click the message element to select it.
Click the Convert To XPath item. The display shows the XPath definition of the element.
Copy the XPath definition and push the Cancel button to dismiss the Create Message Property tool.
Select the same operation again.
From the Create menu, select Message Property on Name.
Specify the name of the property.
Property Source: Select Message Content.
Click the Pick from Message link to display the message elements.
Use the Message drop down list to select Request or Response (the phase has to be the same as for the message from which you copied the first element).
Double click the message element to select it.
Click the Convert To XPath item. The display shows the XPath definition of the element.
Paste the XPath definition you have copied from the first element. Depending on the element type, use the appropriate operator to form a valid XPath expression.
Click the Consumer Mapping checkbox if you want to map this property to a consumer attribute.
Select the attribute if there is more than one.
Click the Sensitivity checkbox if you want to restrict access to the property value.
Click OK.
Business Transaction Management uses the same model to represent interconnected components no matter what the component type: the model shows services that interact by sending request and response XML messages. The model also assumes that each of the services is described by a WSDL specifying the service's location and its interface. However, not all discovered components can be precisely rendered by this model. If the component is not an actual web service, the corresponding WSDL might be missing or incomplete. In such a case, you will need to take some additional action to create properties for the message elements of this component. Basically, you will log a message containing the element of interest, and then copy the XML into the property definition.
The process is the following:
Enable message logging for the transaction operation that contains the element for which you want to create a property.
Run traffic through your system to capture at least one transaction instance.
Select the transaction of interest in the main area of the console.
Open the Message Log tab and select the operation for which you have logged messages.
Click on the magnifying glass icon to open the Message Content inspector.
Select View XML for either the Request or the Response message, depending which of these contains the element of interest.
Copy the XML for the message.
Select a service, operation, or endpoint in any view. (The service must contain the operation of interest.)
Select Create Message Property on Name from the Create menu.
Property Source: Select Message Content.
Click the Pick from Message link to display the message elements. Ignore the element tree that is already filled in (if any).
Select the operation phase: Request or Response.
Click the Get XML button to open the Paste XML document window.
Paste the text in the window and click OK.
The element tree should now contain the message element.
Select the element of interest.
Click the Consumer Mapping check box if you want to map this property to a consumer attribute.
Select the attribute if there is more than one.
Click the Sensitivity check box if you want to restrict access to the property value.
Click OK.
You can view partial property definitions on the Properties tab of an operation, endpoint, service, or transaction. The property name, phase, type, and description are displayed. The property's sensitivity and consumer mapped attribute is also displayed.
To see the full definition, click the Edit button and select Modify.
You can view property values in the following views:
Message Log tab for a selected endpoint, operation, service, or transaction
Alerts tab for a selected endpoint, operation, service, or transaction
Transactions view, Instances tab
Transaction Instance inspector
You can change the definition of a property. Note that if you change the XPath definition of an existing property, the runtime will start calculating the new XPath definition based on incoming messages. Previously recorded messages will continue to hold the value calculated based on the old XPath definition.
To change the name of a property, you must create a duplicate, assign it a new name, and then delete the original.
Properties play an important role in transaction definitions, segmentation, conditions, and logging; for this reason, modifying a property definition might have the following consequences:
If the property is used as a key in a transaction definition, the transaction will be disabled.
If the property is used as a key in a transaction definition, the transaction will be disabled.
If the property is used by a condition, the condition will be disabled.
To modify any user-created property
Select the Properties tab of the operation, endpoint, service, or transaction of interest.
Click the Edit button and select Modify.
Modify the property definition. Refer to the instructions for creating a property.
Click OK to save the new definition.
There are a couple of reasons why you might be interested in duplicating a property definition:
You might want to use the original property as a starting point for creating another property that needs a similar complex expression or includes some of the content that is extracted by this property. In this case, you would want to duplicate the property and partly modify its definition.
You need to rename a property. In this case, you can duplicate the property, assign it the desired name, and delete the original property. Deleting properties can have significant side effects. See Troubleshooting Transactions to learn more.
To duplicate any user-created property
Select the Properties tab of the operation, endpoint, service, or transaction of interest.
Click the Edit button and select Duplicate.
Modify the property definition. Refer to the instructions for creating a property.
Change the name of the duplicate if you wish.
Click OK to save the modified copy.
Properties play a key role in transaction definitions, segmentation, condition definitions, and logging; for this reason deleting a property might have significant consequences:
If a property is used as a correlation key, it is considered fundamental to the transaction definition. If one of these properties is deleted, the entire transaction will become disabled and a system alert will be generated.
If a property used for transaction consumer segmentation is deleted, or modified so that it is no longer marked as "consumer," the transaction segmentation will no longer be captured. If the transaction is marked enabled for segmenting by consumer, a system alert will be generated and consumer segmentation will be disabled.
If a property used by a condition definition is deleted, the condition will be disabled and a system alert will be generated.
If a property is deleted which is defined on an operation in a transaction and logged (but not explicitly used for other purposes), the user will no longer be able to see that property and associated content when viewing instances of logged messages.
To delete any user-created property
Select the Properties tab of the operation, endpoint, service, or transaction of interest.
Click the Edit button and select Delete.
Click OK to save the new definition.