7 Working with Consumers

This chapter explains how you can present performance results to reflect consumers' use of your services. It explains how you set up consumer segmentation, how you create consumers, how you map messages to consumers, and how you view and manage consumer-based performance information. It includes the following sections:

7.1 About Consumers

In addition to presenting performance results based on the performance of individual transactions, services, and endpoints, Business Transaction Management allows you to view performance results in terms that are meaningful to your business. You can see transaction performance segmented by business criteria: your suppliers, your users, your re-sellers, or your customers. And you can see this information even in those cases when the object of interest participates in a series of different transactions. To this end, Business Transaction Management provides a consumer business object that you can define to segment performance data using criteria that is important to you. You can then monitor your business objects to make sure that your objectives are being met. For example,

  • You can view custom graphs showing performance segmented by a given consumer.

  • You can have Business Transaction Management generate alerts when the performance of your system for a given consumer does not meet the targets you define.

Consumers refer to Business Transaction Management consumer business objects; a consumer is an instance of the Consumer business object you have defined for your environment. The default name "Consumer" implies that this business object could be the initial client of a transaction; but it could also be the country or city where an order originates, a company name, and so on. Throughout this section, we will use the default name "consumer," with the understanding that this can refer to the wider range of criteria just mentioned.

To make the actual segmentation criteria more clear, the Business Transaction Management administrator can customize the consumer label that appears on fields, buttons, and links in the Management Console. For example, your administrator could change the label from "Consumer" to "Department", "Supplier", or any other descriptive term.

The following sections explain how you set up consumers:

7.1.1 Setting up Consumer Segmentation

In the simplest case, to obtain performance segmentation by consumer, you must do the following:

  1. On the start operation for a transaction, create a property whose value is the request message element that uniquely identifies the consumer. It could be an ID number, a social security number, a name, or an email address. If the consumer is not a person, it could be a company name, a code identifying the company, and so on. (The information you choose to supply for the property value can be based on a single message element, an xpath expression, or content in the message header.)

  2. Map this property to the consumer attribute on the consumer business object. This mapping process is called mapping messages to consumer.

  3. Enable consumer segmentation in your transaction definition.

The figure below shows a simple mapping between a property called email (associated with the request.submit.order.customerEmail element of the starting message of a transaction) and the default attribute of the business object, Consumer Name.

Description of simple_bus_obj.gif follows
Description of the illustration simple_bus_obj.gif

If consumer segmentation is enabled for the transaction, once traffic starts to flow, Business Transaction Management inspects the value of the email property of this transaction as part of its measurement gathering. For this example, let's assume the property value is 123hop@gmail.com:

  • If it finds an existing consumer whose name is 123hop@gmail.com, it records measurements for that consumer.

  • If it does not find a consumer of that name, it creates the consumer, assigns it the value of the property as its name, and records measurements for it.

The business object that Business Transaction Management provides by default is adequate for the simple case where you are monitoring one specific kind of consumer and you are satisfied to use the value of the property as the consumer name. In reality, you might need to handle more complicated situations. To do that, you can customize the definition of the consumer business object by adding custom attributes. Using these attributes, you can teach Business Transaction Management to recognize the same consumer though the consumer is identified by different properties.

For example, what happens if we want to monitor several transactions, and in each transaction the consumer of interest is identified in a different way? In one transaction, the consumer is identified by email address, and in the other, by a social security number.

The following figure shows two transactions, Tx1 and Tx2. Tx1 has a customerEmail element mapped to the email property; Tx2 has a custID element mapped to a SSNumber property. You want Business Transaction Management to monitor both transactions and to recognize that the same consumer is involved whether that consumer is identified by the email property or by the SSNumber property. To do this, you must add two custom attributes to the Consumer business object and map each property to its corresponding attribute.

Description of complex_bus_obj.gif follows
Description of the illustration complex_bus_obj.gif

For the sake of this example, let us assume that all consumers involved in these transactions have already been created. Once traffic starts to flow, Business Transaction Management inspects the value of each of the properties shown as it observes messages. If it encounters either an email address or social security number associated with an existing consumer, it records measurements for that consumer. This makes it possible for you to see performance information for a given consumer that is an aggregate of performance across all the transactions in which the consumer participates.

In this more complicated case, setting up consumer segmentation would involve the following:

  1. Add custom attributes to the consumer business object that will correspond to the properties you will create in Step 2.

  2. For each transaction you want to segment by consumer: Create a property whose value is the request message element that uniquely identifies the consumer.

  3. Map each property to its corresponding business object custom attribute.

  4. Enable consumer segmentation in your transaction definition.

(You can do steps 2-4 all at once when you define consumer segmentation for a transaction.)

7.1.2 Creating Consumers

Business Transaction Management creates consumers in one or more of the following ways:

  • If you have set up consumer segmentation, Business Transaction Management automatically creates a consumer whenever it encounters a message for a consumer that does not already exist.

  • According to the information you provide when you choose Create > Consumer and supply values for the consumer name and attributes.

  • According to the information you provide using the importBusinessObject command.

If you create consumers manually, as with the last two options, consumer monitoring will only start after you set up consumer segmentation.

7.1.3 Changing the Default Consumer Name

By default, discovered consumers are named according to the value of the message property to which you map them. For example, if you use a property that holds an email address, the name of the consumer displayed in the Management Console is the email address of the consumer. If the value of the property is the user's full name, that name is displayed in the Management Console. You can edit the name that will be displayed for a consumer by editing the consumer profile. If you see a combination of formats used to display user names, this might result from the fact that some were created manually (and assigned an actual name) and others were added automatically and assigned the value of the property used to map messages to consumers.

If you decide that you want to change the default consumer name, please note that you must add an attribute to the business object that corresponds to the property used for segmentation and that you must then map the property to that attribute. In the following illustration, an Email custom attribute is mapped to the email property. If you then change the default consumer name to an actual name (by editing the consumer profile), Business Transaction Management will continue to gather measurements for this consumer when it sees the message and evaluates the email property, but it will display the name you supply, in the main pane of the Consumers view and in the Name field of the Profile tab for the consumer.

Description of simple_bus_obj_attr.gif follows
Description of the illustration simple_bus_obj_attr.gif

7.2 Mapping Messages to Consumers

Consumers are the default Business Transaction Management business objects that allow you to segment transaction performance based on some desired criteria. Mapping messages to consumers is the means by which you teach the system what criteria to use to segment performance information. The mapping process involves your creating a property that identifies the consumer and then mapping that property to a consumer business object. Please read Section 7.1, "About Consumers" for a detailed discussion before you proceed.

Before you map messages to consumers, take a moment and decide the following:

  • What properties do you need to create?

    The consumer you choose must be uniquely identified by information contained in the starting message of a transaction: for example, an ID number or an email address. This information can be contained within a message element or header.

  • What message element or xpath expression will you use to define each property? (For the sake of clarity, the remainder of this procedure refers to this element or header as Consumer_ID.)

  • Do you need to customize the consumer business object by adding custom attributes? You might need to do this if you do not want Business Transaction Management to use the default name for the consumer or if you are tracking consumers across different transactions and the consumer is represented in different ways in each transaction.

The basic steps to map messages to consumers are as follows:

  1. Customize the consumer business object if needed to provide additional mapping options for your consumers.

  2. When creating the property, use one of the mapping options described below to map a property to a consumer.

After you complete this mapping, enable segmentation, and send traffic, you can then view transaction performance information segmented by consumers from the Explorer > Consumers view, or from the Analysis tab of the Transactions view.

7.2.1 Customizing the Consumer Business Object

The consumer business object is seen throughout your environment. Each consumer created manually or automatically is an instance of the consumer business object. You can see the structure of this object in the Consumer's Profile tab. Section 7.1.1, "Setting up Consumer Segmentation" explains why you might need to add attributes to the consumer business object.

To add attributes to the consumer business object:

  1. Select Admin > Edit Data Model Attributes. The Edit Data Model Attributes dialog box opens.

  2. Scroll down to the Business Object Custom Attributes section and click add attribute.

  3. Specify a Name and Type for your attribute.

  4. You can optionally specify a display name for your attribute in the Form Label field. This name will be used to identify the attribute in the Consumer's Profile tab.

    The default display name is the value of the Name field.

  5. You can optionally specify a name for querying on your attribute in the Query Label field. You can use this name in forming query expressions. The default query name is the value of the Name field.

  6. Repeat Steps 2-5 to add more attributes.

  7. Click Apply.

7.2.2 Mapping Options

You can map a message to a consumer either when you create a property or when you create a transaction.

Do the following to create a message property to hold the value of Consumer_ID and map the property to an attribute on the consumer object.

  1. Select the starting operation of the transaction to be segmented.

  2. Select Create > Message Property on operation_name.

The Message Property dialog box opens.

  1. Specify a Name for your property.

  2. Specify the Property Source: Message Content or Header, and specify Consumer_ID.If you specify Header, a dialog is opened that allows to specify the phase of the message, the header name, and the data type. If you specify Content, use the Pick from Message link to select the desired message element.

  3. In the Consumer Mapping section, select the Map to consumer through attribute checkbox and choose the consumer attribute that you want to map it to, either the default Consumer Name attribute or an attribute that you created when you customized the consumer business object.

  4. Click OK.

7.3 Monitoring Consumers

This topic lists the ways you can monitor consumers. The list orders these monitoring tasks from least to most detailed. Each listed task directs you to where you can perform the monitoring and provides a link to more detailed information.

In general, there are two views that offer transaction performance information segmented by consumer:

  • Explorer > Consumers view: Analysis, Alerts, SLA Compliance tabs

  • Transactions view: Consumer Usage pane in the Analysis tab,

If you have defined a consumer that participates in different transactions, the Analysis tab and the information presented in the main view for that consumer will display values that aggregate performance measurements for all transactions that involve the consumer.

Before you can monitor consumers, you must map messages to consumers and enable segmentation by consumer. See Section 7.2, "Mapping Messages to Consumers" for more information.

To get information about a consumer definition, select the consumer in the Explorer > Consumers view, and select the Profile tab. The tab shows the name of the consumer, its ID (useful in some CLI commands), any description you entered when you created the consumer, and any attributes you have created for the consumer business object.

To monitor consumers:

  • Total number of consumers with SLA violations

    Navigate to Dashboards > Operational Health Summary and look for Consumers information.

  • Transaction performance and usage summaries per consumer

    Navigate to the Analysis tab, Consumer Usage panel in the Transactions view, and select a transaction.

  • Detailed current transaction performance and usage for a specific consumer.

    1. Navigate to the Explorer > Consumers view.

    2. Select a consumer in the main pane.

    3. Select the Analysis tab.

    4. Look at Transaction Performance for a graphic rendition of performance over time; look at Transaction Usage for a grid view.

  • Segmentation by consumer and by ip address

    1. Navigate to the Explorer > Consumers view.

    2. Select a consumer in the main pane.

    3. Select the Analysis tab. Look at Breakdown by Client Address.

  • Violation alerts by consumer

    1. Navigate to the Explorer > Consumers view.

    2. Select a consumer in the main pane.

    3. Select the Analysis tab. Look at Violation Alerts.

  • Detailed current SLA compliance for a specific consumer.

    1. Navigate to the Explorer > Consumers view.

    2. Select a consumer in the main pane.

    3. Select the SLA Compliance tab.

  • Recent history of SLA violations for a specific consumer

    1. Navigate to the Explorer > Consumers view.

    2. Select a consumer in the main pane.

    3. Select the Alerts tab.

7.4 Adding and Deleting Consumers

Business Transaction Management creates consumers in one or more of the following ways:

  • If you have set up consumer segmentation, Business Transaction Management automatically creates a consumer whenever it encounters a message for a consumer that does not already exist.

  • According to the information you provide using the importBusinessObjects command.

  • According to the information you provide when you choose Create > Consumer and supply values for the consumer name and attributes.

This section explains this last option: how you use the management console to create consumers. It also explains how you delete consumers.

To add consumers using the management console

  1. Choose Create > Consumer.

    The Create Consumer dialog box opens. The contents shown depend on how you have defined the consumer business object. Any custom attributes you have defined are shown in the Attributes area.

  2. Enter a descriptive name and notes.

    The value of the Name field is used as the display name for the consumer in the Management Console.

    You can set up filtering on the value of the Notes field.

  3. Supply the value of any attributes defined for the consumer business object in the Attributes field.

  4. Click Apply.

To delete consumers using the management console:

  1. Select the consumer you want to delete in the Explorer > Consumers view.

  2. Choose Modify > Delete consumer_name.

    The Delete Consumer dialog box opens.

  3. Click Delete.

7.5 Editing Consumer Names

As consumers are discovered and added to the Business Transaction Management sphere, they are named according to the value of the message property to which you mapped them. For example, if you mapped them to a message property that holds an email address, the name of the consumer displayed in the Management Console is the email address of the consumer.

You can edit the name of a consumer by editing the consumer profile.

You should do this only if you created a custom attribute on the Consumer object and mapped the message property to that custom attribute. Otherwise, message traffic will no longer be segmented for that consumer. See Section 7.2, "Mapping Messages to Consumers" for more information.

For example, in the following consumer profile, you could edit the Name field to provide the name of the consumer whose email address is listed. Whatever you enter in the name field becomes the format and content used to display the consumer in the console. But make sure that the property used for segmentation is mapped to the User ID attribute, which remains the email address.

Description of consumer_profile.gif follows
Description of the illustration consumer_profile.gif

Another reason you might edit the consumer profile is to add notes. You can use the value of the Notes field to set filtering.

To edit a consumer profile:

  1. Select the consumer whose profile you want to edit from the Explorer > Consumers view.

  2. Choose Modify > Edit Profile for consumer_name.

    The Edit Profile for consumer_name dialog box opens. Make your edits.

  3. Click Apply.

7.6 Customizing the Consumer Label

RequiredBusiness Transaction Management application role: btmadmin.

You can customize the text of labels in the Management Console that by default use the terms "Consumer" or "Consumers". For example, you might want to monitor service levels and usage per department, rather than per individual. In this case, it might make sense to change the labels in the Management Console to use the term Department instead of Consumer. You should specify both the singular and plural forms of your term.

Your modified label will be used in the Navigator, in the Analysis pane names, in the Filter tool, and so on.

To modify the Consumer label:

  1. Choose Admin > Edit Data Model Attributes.

    The Edit Data Model Attributes dialog box opens.

  2. Scroll to the bottom and find the Business Object Domains section.

  3. Type the singular form of your new label into the Name field.

  4. Type the plural form of your new label into the Plural Label field.

  5. Edit the Description field as appropriate.

  6. Click Apply.

  7. Refresh your web browser to see the effect of your change by selecting Refresh from the View menu.