This chapter provides an introduction to the Common Base Event version 1.0.1 best practices guide. The purpose, scope and intended audience for this document are presented. Background information, including autonomic computing concepts, the Common Base Event and the Common Event Infrastructure is also introduced.

1.1 Purpose

The technology used for business applications continues to become more complex as businesses continue to rely more heavily on their information technology (IT) infrastructure. Autonomic computing is intended to reduce the impact of this added complexity by enabling these systems to manage themselves. One of the critical first principles required for this common management is that each component and subsystem must represent itself in a common way. Specifically, information that describes situations that arise, as well as the state of the components at any time, must be accessible in a common language, a lingua franca. This is the only way that common management components are able to reliably interpret and act on the information provided to them. The use of this common event format extends beyond management of the IT infrastructure to occurrences that are used to manage business processes (so-called business events, which are detailed later).

The Web Services Distributed Management (WSDM) standard resulted from a collaborative industry effort. WSDM was approved by the Organization for the Advancement of Structured Information Standards (OASIS). The standard provides the foundation for enabling the use of Web services to build management applications, offering one set of instrumentation to manage resources. WSDM is an important milestone in the evolution of systems management. Coupled with virtualization technology, the WSDM standard enables self-managing autonomic systems and service-oriented architecture (SOA)-based management.

As part of the WSDM standard, OASIS ratified the WSDM Event Format (WEF), which defines a common format for events that contains extension points that allow additional semantic information to be included. The Common Base Event is IBM®'s initial implementation of WEF. Because Common Base Events utilize many of the same concepts as WEF, many of the best practices outlined in this document will facilitate migration to WEF.

In addition to providing software for developers to take advantage of the standard, IBM has Tivoli® products, WebSphere® software, DB2® software and systems virtualization products available today that include implementations of WSDM, with more planned in the future. For more information about IBM’s activities with the WSDM standard, visit www.ibm.com/autonomic/wsdm.

The goal of the Common Base Event is to provide such a standard event format, and the purpose of this document is to supplement the Common Base Event specification (CBE101) by providing additional information about the usage of the Common Base Event.

The Common Base Event addresses two issues of notification diversity: the format and the content used to represent situations. This document offers practical how-to information for Common Base Events. It provides guidance about the generation and consumption of Common Base Events, including how to populate and interpret certain key elements of those events in a consistent and meaningful manner.

This document is part of the Common Base Event library and is intended to supplement the Common Base Event specification (CBE101).

1.2 Scope

This document does not supplant the Common Base Event specification [CBE101], which is considered prerequisite reading. That specification is the authoritative source for information about Common Base Events. This guide is a companion document that describes best practices, conventions, and guidelines for the generation and use of Common Base Events. This guide not only provides general information, but also provides information related to specific applications for the Common Base Event, including:

· How to use Common Base Events in general

· How to use Common Base Events specifically for problem determination applications

· How to use Common Base Events specifically for events related to business activities

· How to use certain programming environments to create and transmit Common Base Events

· How to use the Common Event Infrastructure to transport events

1.3 Who should read this guide

The primary audience for this guide includes developers who will be creating tools or infrastructure to generate or work with Common Base Events, as well as developers who need to create the events themselves. Others who want to better understand how Common Base Events can be used will also be interested.

1.4 Background

This section addresses autonomic computing concepts and introduces the autonomic computing architecture. See [ACBP] for further details about the autonomic computing architecture.

1.4.1 What is autonomic computing?

The overarching goal of autonomic computing is to shift the burden of managing IT systems from IT professionals to the systems themselves. The term comes from the autonomic nervous system of the human body, the system that regulates your body’s basic functions without your conscious awareness. For instance, when you need to run to catch a train, you don’t need to consciously decide to produce adrenaline, reallocate oxygen to the muscles in your legs, and increase your heart rate. Those important and necessary physical adjustments are handled for you automatically. In a similar way, self-managing autonomic systems handle more and more tasks on their own behalf, minimizing the need for intervention on the part of the IT staff. Autonomic computing behavior is necessary for building effective on demand operating environments that adapt and adjust quickly to the changing computing needs of organizations.

The Common Base Event is one fundamental enabler for self-managing autonomic systems. As described in this document, Common Base Events can be used to communicate situations that arise throughout the IT system.

The Autonomic Computing Architectural Blueprint (ACBP) provides this overview of the autonomic computing architecture:

The autonomic computing architecture organizes an autonomic computing system into the layers and parts shown in Figure 1 Autonomic computing reference architecture. These parts are connected using enterprise service bus patterns that allow the components to collaborate using standard mechanisms such as Web services. The enterprise service bus integrates the various blueprint building blocks, which include: touch points for managed resources, knowledge sources, and autonomic managers.

Figure 1 Autonomic computing reference architecture

The lowest layer contains the system components, or managed resources, that make up the IT infrastructure. These managed resources can be any type of resource (hardware or software) and may have embedded self-managing attributes. The next layer incorporates consistent, standard manageability interfaces for accessing and controlling the managed resources. These standard interfaces are delivered through a touch point. Layers three and four automate some portion of the IT process using an autonomic manager. A particular resource may have one or more touchpoint autonomic managers, each implementing a relevant control loop. Layer three in Figure 1 Autonomic computing reference architecture illustrates this by depicting an autonomic manager for the four broad categories [of self-management] (self-configuring, self-healing, self-optimizing and self-protecting). Layer four contains autonomic managers that orchestrate other autonomic managers. It is these orchestrating autonomic managers that deliver the system wide autonomic computing capability by incorporating control loops that have the broadest view of the overall IT infrastructure. The top layer illustrates a manual manager that provides a common system management interface for the IT professional using an integrated solutions console. The various manual and autonomic manager layers can obtain and share knowledge via knowledge sources.

Common Base Events can be used to communicate across the various layers of a self-managing autonomic system. This guide describes how Common Base Events can be used to send information (such as problem determination events) from touchpoints to touchpoint autonomic managers, how Common Base Events can be used to communicate information (such as business events) to orchestrating autonomic managers, and so on.

For a more in-depth discussion of the autonomic computing architecture, see The Common Base Event on page 13.

1.4.2 What is an event?

Fundamentally, an event is an indication of an occurrence — an indication that something of potential interest has happened. According to the Common Base Event specification (CBE101), “Events are external, visible manifestations of all systems operations — they represent the onset, evolution, and conclusion of processes both large and small”. These systems and processes are broad in scope, including everything from hardware and software in the IT infrastructure to business processes and application orchestration. In the IT infrastructure, events typically represent state changes in a resource, an autonomic manager, or another component involved in the management system. In a business process, an event can represent a business milestone or an anomalous business situation. Events can communicate situations such as:

· A component has stopped or started

· A connection has been established or broken

· A failure has occurred

· A state transition for a task or activity in a business process has occurred

· An amount for a transaction has exceeded an automatic approval threshold

The Common Base Event enables information about situations to be captured and represented in a consistent format. The Common Base Event format facilitates effective intercommunication among disparate components for events that express information about logging, management, problem determination, business processes, and other happenings in an IT system.

For the purposes of this guide, the following definitions apply:

· Occurrence: a happening or phenomenon

· Situation: a classification of an occurrence that specifies what type of an occurrence has happened

· Event: an indication of the situation that provides information about the situation

Although the Common Base Event is generally applicable to many types of situations, it is useful to discuss certain categories of events commonly encountered in IT systems. The following sections detail two such categories: problem determination events and business events.

1.4.3 What is problem determination?

Problem determination is the detection and diagnosis of situations that affect the operational status or availability of business applications. The overarching goal of problem determination is to maximize business and IT system availability by minimizing the time it takes to recover from situations that affect system availability. This is accomplished by providing the information and tools required to quickly detect meaningful events and conditions, diagnose the underlying problem or situation, and apply available knowledge to restore normal business and IT system operations.

1.4.4 Problem determination phases

Maintaining and restoring the availability and normal operations of a business application is a multistep process that can be divided into the following phases:

Problem detection (what?)

The detection and identification of situations that adversely affect the normal operations or availability of a business application. The challenge is to detect, as quickly as possible, unanticipated changes in the status of an application and to identify events describing the situations that led to those changes. This typically involves filtering out insignificant information and events, focusing only on relevant situations and the events specifically related to those situations.

Problem isolation (who and where?)

The process of determining which component in the business application is experiencing the situation that is affecting the overall availability of the application. A typical problem can result in multiple events being reported by multiple components, as the problem propagates through the system. Problem isolation focuses on identifying the component that experienced the initial condition that caused the problem and identifying the situation that led to that problem.

Problem diagnosis (why?)

The process of determining why the problem occurred; that is, determining the root cause of the problem. Problem diagnosis focuses on identifying the situation that caused the problem. The problem could be caused by an internal failure within the component (such as a software defect or hardware error) or an adverse external condition that the component cannot recover from (for example, an inappropriate configuration setting, a network failure, or a malformed or inappropriate request).

Problem recovery

Problem recovery focuses on what to do to restore normal operation of a business application as quickly as possible. It involves using knowledge to recover from the root cause of the problem and determining the immediate actions needed to restore normal operations. Problem recovery, unlike problem diagnosis, is not concerned with the reason why a problem occurred, but rather about what can be done to work around the problem. For example, if a business application is experiencing a problem accessing data, the problem recovery action might be to recycle the database server. IT professionals typically attempt problem recovery actions first, to restore the business system’s normal operation using an effective workaround, and then concern themselves with problem resolution (described next), to address the underlying cause.

Problem resolution

Problem resolution focuses on addressing the root cause of a problem — that is, not only what to do to recover from the problem, but also what can be done to prevent the problem from occurring again. For example, problem resolution might attempt to determine not only that a database server failed, but why it failed, and how to prevent the server from failing again (perhaps by adjusting configuration settings or applying a software fix).

1.4.5 What is a problem determination event?

Problem determination events are those events that are specifically intended to be used to support the process of problem determination (described in “Problem determination phases” on page 11). Problem determination events can incorporate many types of data, including information about operational status, state changes, request processing, performance metrics, or faults.

Problem determination events are typically divided into two broad categories:

Log events

Log events are typically reported by components of a business solution during normal deployment and operations (that is, in production environments). Although log events occur and are captured during normal operation in a production environment, and hence often signify normal occurrences in system operation, they also can be used to help identify problems. The target audience for log events includes the users and administrators of the components that make up the business solution, along with the support teams and developers of the solution components. Log events typically are the primary set of events that are available when a problem is first detected and are used for problem detection and problem isolation, to support problem recovery.

Diagnostic events

Diagnostic events, also called trace events, are used to capture internal diagnostic information about a component and typically are not reported or available during normal deployment and operations (that is, in production environments). The target audience for diagnostic events is the support teams and developers of the components that make up the business solution. Diagnostic events typically are used to diagnose problems within a component, such as a software failure, especially when the information provided by the log events is not sufficient to diagnose the problem. Diagnostic events are typically used for problem diagnosis, to support problem resolution.

The preceding definitions for log events and diagnostic events are general and are used mainly to indicate how the data is captured, rather than to denote the actual data content. Most events might be used in a problem determination process, but log and diagnostic events typify problem determination events. Situations can be captured as log events or diagnostic events, or both, depending on the components that make up a solution. For example, performance data might be captured within a log event, following the general usage guidelines published in this document for log events. Detailed performance information might be captured in diagnostic events that could be used to diagnose performance problems.

The Common Base Event defines the syntax and semantics of an event in a consistent and common format to facilitate effective problem determination. For problem determination events, this guide primarily focuses on describing how to use Common Base Events to represent log events. Using Common Base Events for diagnostic information is not addressed in a detailed manner, although many of the concepts used for log events apply to diagnostic events.

1.4.6 What is a business event?

Recent developments in the software industry, such as complex event processing and business activity monitoring, have placed added attention on the notion of business events, which are distinct from those events that apply only to IT systems.

A business event is an indication of some occurrence that is significant to the operation, monitoring, or management of the business. Whereas the subject of an IT event (such as a problem determination event) might be a resource, such as network router or a database, the subject of business event is often an indication of something that is important in a business process, such as a sales order, or a business entity, such as a retail store. The primary audience for a business event typically is a line of business (LOB) role within the company.

Note: A business user, in this context, is a role player responsible for participating in, analyzing and managing business operations. The role can vary widely based on the company’s scope and area of expertise. For example, a business user could be the CEO, an insurance adjuster, or a call center representative. The term is used here to distinguish this role from an IT role player such as an IT administrator, developer, or architect who traditionally works as part of the CIO’s organization within a company and who is a primary audience for IT events, such as problem determination events.

Business events can occur in both raw and derived forms. Sometimes raw events do not directly correspond to a recognizable business event, but instead are used to derive business events. For example, to monitor a “gold customer order fulfillment” process, checking for violations of commitments to gold customers, a company might need to monitor raw events that represent order submission and order fulfillment, correlate the events, and compare the result to an established performance target. Based on these raw events, a derived business event might in turn be produced to communicate the occurrence of a violation.

Although business events have a different focus and primary audience than IT events, the Common Base Event is suitable for communicating both types of events. This guide describes the best practices to use for both categories of events.

1.4.7 The Common Base Event

The purpose of the Common Base Event is to facilitate the effective communication among disparate enterprise components that support logging, management, problem determination, autonomic computing, and On Demand Business functions in an enterprise. The communication among these components can be either synchronous or asynchronous, with the Common Base Event serving as a primary data format for communication.

The Common Base Event is a standard XML schema that can be used to indicate several types of situations, in particular, problem determination and business events. In all of these cases, the syntax and semantics of the data elements of the event need to be consistent, because all of these event categories, occurring in multiple components in a heterogeneous environment, need to be correlated. Using log files, or events published to subscribers, most components generate data whose interpretation requires the availability of contextual information. Yet, this context is frequently maintained only in the minds of developers, administrators, and business users who are intimately familiar with the component or process that generates the event. This lack of context inhibits programmatic interpretation of events, and hence, automation of management and business processes. Consider the fundamental problem of parsing time stamps. Format and granularity (for example, is a 12- or 24-hour clock used? Or are the units milliseconds or microseconds?) both present unnecessary complexity for the consumer of the time-stamped event. This lack of consistency applies elsewhere. For example:

· What is the host name of the machine on which the event occurred?

· Which component failed?

· Is the component that failed on the same physical machine as the application that is reporting it?

· Which business process reported this event?

· Are there multiple events that should be interpreted as a single unit, in a certain order, or both?

Without standardization, automated situation handling becomes difficult. Complexity increases further when the problem occurs in a solution that is composed of multiple components and processes. Events generated by components and processes typically are product-unique, adhering to conventions limited to a particular application or vendor. Without a standard, events are of little value to autonomic management or business systems that rely on the completeness and accuracy of data to determine an appropriate course of action to take in response to the event. The Common Base Event definition alleviates this problem by providing a common format to represent event information, including:

· The identification of the component that is reporting the situation

· The identification of the component that is affected by the situation (which might or might not be the same as the component that is reporting the situation)

· The situation itself

Properties defined in the Common Base Event model supply information for these and other important elements of an event. Additional event information includes time stamps, event identifiers, component identifiers, and many other elements. This broader scope of information encapsulates enough data to allow events to be exchanged and interpreted in a deterministic and appropriate manner across multiple management and business systems that consume the events, without losing fidelity.

1.4.7.1 When should I use Common Base Events?

As a best practice, a Common Base Event should be generated to promptly inform management components (including humans) in the IT infrastructure about occurrences in the environment that are noteworthy and of interest from a management perspective. Management in this context includes management of the IT infrastructure as well as management of the performance of the business processes that rely on the IT infrastructure.

1.4.7.2 How do I choose between using Common Base Event and ARM?

Application Response Measurement (ARM) is a current popular method for collecting and representing monitoring data related to resources in an IT environment. ARM data can be encapsulated in a Common Base Event message.

This specification does not prescribe precise guidelines for using Common Base Events or ARM. Generally, however, Common Base Events should be used to indicate significant situations that could affect the availability or performance of the business system overall, whereas ARM data typically is used to provide low level and/or relatively high volume instrumentation of an application to determine the performance of that application. If ARM data indicates a potential problem, then an appropriate Common Base Event should be created based on the monitored ARM data.

1.4.7.3 How does the Common Base Event relate to other existing formats?

Not all event sources natively generate Common Base Events today, and the migration to the native production of Common Base Events will occur over time. In some domains, existing formats or standards are available and widely used (for example, SNMP traps, Systems Network Architecture [SNA] alerts, Common Information Model [CIM] indications, Java™ Management Extensions [JMX] and IBM Tivoli Event Integration Facility). The Common Base Event was designed so that other formats can be transformed to Common Base Events without data loss.

Until such time as components are modified to natively generate Common Base Events, adapters can be used. IBM provides the Generic Log Adapter technology (available from IBM developerWorks® Web site, see [DWAC]), along with adapter rules for converting numerous existing formats to Common Base Events and associated tooling to create additional adapter rules.

1.4.7.4 Who directs the Common Base Event Initiative?

The Common Base Event initiative is driven by the Autonomic Computing group of IBM. The Autonomic Computing group developed the architecture specification for Common Base Events and promotes its adoption in the industry. This guide supplements the Common Base Event specification. The current version of the Common Base Event specification supported by IBM technologies such as the Generic Log Adapter, Log and Trace Analyzer and Common Event Infrastructure is Common Base Event version 1.0.1. Many of these technologies are available from IBM developerWorks; see http://www128.ibm.com/developerworks/autonomic/overview.html.html128.ibm.com/developerworks/autonomic/overview.html [IDWAC].].

1.4.7.5 How does the Common Base Event relate to the OASIS WSDM Event Format standard?

As part of the WSDM standard, OASIS ratified the WSDM Event Format (WEF), which defines a common format for events that contains extension points that allow additional semantic information to be included. The Common Base Event is IBM's initial implementation of WEF. Because Common Base Events utilize many of the same concepts as WEF, many of the best practices outlined in this document will facilitate migration to WEF.

1.4.8 What is an event infrastructure?

Figure 2 shows the various elements that interact with the event infrastructure to produce or consume event information, along with their relationships, which influence the characteristics of the programming model.

Figure 2 Event infrastructure relationships and terminology

Figure 2 Event infrastructure relationships and terminology
1. Event Infrastructure	A set of services that allow filtering, transmission, and routing of event information between producers and consumers, as well as persistence and access to event data store.
2. Event	Unsolicited noteworthy information about a managed resource set for management purposes.
3. Event Producer	Producer of events about managed resources that it represents or controls. Events are sent asynchronously. Also known as Event Sources.
4. Customer Environment	Customer’s IT environment supporting customer’s business
5. Management Systems (also known as Event Consumers)	Consumers of event information aiming management of customer’s businesses and the IT environment supporting them.
6. Event Correlation	A set of analytics, and the components that support the analytics: rules language, engines, and tools. These allow the detection of event patterns, automation, filtering, and so forth.
7. Event Format	A well-defined, accepted, and structured way of representing event information so that events can be processed.
8. Managed Resources	IT and business resources being managed in the customer’s IT environment.

1.4.8.1 Common Event Infrastructure overview

The Common Event Infrastructure (CEI) is an embeddable component, incorporated in several IBM products, that supports reporting, persistence, distribution, and interpretation of event data based on the Common Base Event format.

CEI is not a product, but rather an IBM component used in several IBM products that provides a programming model to report, persist, and consume Common Base Events, and facilitates the sharing of event information.

An application that uses CEI must install the CEI event server runtime components and configure the event repository as part of its installation process. CEI includes silent installation utilities and scripts that can be invoked by a product installation process. CEI is composed of a set of modular components that operate with IBM’s messaging (enterprise service bus [ESB]) and application integration middleware (including IBM WebSphere Application Server).

Figure 3 provides an overview of the CEI components:

Figure 3 Common Event Infrastructure overview

1.4.8.2 Common Event Infrastructure components

The CEI has the following components:

· CEI Server is a Java 2 Platform, Enterprise Edition (J2EE) application running in WebSphere Application Server. The CEI server is responsible for determining whether and how to distribute and persist events. It also handles requests from event consumers to access the event information in the event repository. The CEI Server provides event classification for publication, event persistence and access to the event information in the CEI event repository. The CEI server is the only part of CEI that requires a local WebSphere Application Server instance.

· CEI Emitter is a library that provides support for applications to report events to the CEI server. The CEI Emitter can run in a container (J2EE) or as a client of the WebSphere Application Server environment (Java 2 Platform, Standard Edition [J2SE]). In the latter case, the CEI Emitter does not require a local WebSphere Application Server instance, but does require the WebSphere J2EE application client library.

· CEI Catalog provides metadata information about events handled by CEI. This catalog typically is not accessed by the other components in CEI. As a best practice, event producers should share event metadata by populating the event catalog with event definition records. Event consumers can browse or extract from the catalog to determine the types and content of events available for subscription. Chapter 2. “Using Common Base Events” on page 33 provides additional details about how particular properties of the Common Base Event are used in catalog definitions.

· CEI Access is a client library that provides support for event consumers to perform synchronous event queries, event updates and purges of the event repository.

· CEI Helper is an optional client helper class that helps event consumers map JMS messages into Common Base Event objects when receiving events from JMS subscriptions. CEI does not define a subscription interface, but rather uses standard JMS subscription provided by any standard JMS provider, including IBM Platform Messaging Component or IBM WebSphere MQ. The consumer also can be a J2EE or a J2SE application.

Note that for the purposes of generating and consuming Common Base Events, the CEI implementation requires the use of the common programming model supplied by the Test and Performance Tools Platform (TPTP) Eclipse project. The TPTP project includes an EventFactory implementation, helper methods to populate events, and serialization methods to transform a Common Base Event object to and from XML.

1.4.9 Programming model overview

This section describes a programming model used to format and capture Common Base Events. The intent is to provide best practices for these operations, although the facilities used to format and capture events can vary by implementation. This section includes:

· An overview of the Common Base Event common programming model used to create and format Common Base Events. Note that this set of interfaces is also referred to as the TPTP common programming model, from the open source Eclipse.org TPTP project — see [TPTP]. Note that this set of interfaces should be used when creating Common Base Events for use with CEI.

· An overview of how the Common Base Event programming model relates to the JSR-47 programming model, a programming model commonly used to log events to a file or other event repository. This section describes how applications can create Common Base Events using the JSR-47 interfaces.

· Information about how application developers should use the programming model when reporting and consuming Common Base Events from the CEI Server, including CEI runtime characteristics that affect or are related to the Common Base Event and CEI programming models.

The following steps are involved when defining and capturing Common Base Events:

1. The event producer determines that it should generate a Common Base Event to inform management tools about a detected situation. Note that situation detection is outside the scope of this document. Although standard canonical situations are defined for the Common Base Event, the mechanisms used for situation detection typically are specific to the software, hardware, and other components that make up a solution.

2. After it is determined that an event should be generated, the event producer creates and formats a Common Base Event. Refer to the Common Event Infrastructure overview on page 17 for more information.

3. The event producer captures the event and processes it appropriately, which typically involves persisting the event in the appropriate event repositories (such as logging the event, perhaps using the JSR-47 interface[1]) or publishing the event to an event infrastructure (such as CEI[2]), or both. The event repository and event infrastructure perform the appropriate processing to persist the event and generate any required notifications.

These activities involved with generating an event are addressed in the following sections using this structure:

1. A component detects situations, formats the Common Base Event and invokes the event capture runtime using the event capture interfaces supplied by the runtime

2. The event capture runtime processes the request by completing the event formatting and sending the event to the appropriate event handlers, for example, persisting the event in a log repository or sending an event notification using an event infrastructure, such as CEI.

3. The event infrastructure (if present) is used to distribute the event to any number of event subscribers, including persisting the event to the event repository for future processing, when appropriate.

1.4.9.1 Formatting a Common Base Event using the TPTP Common Base Event Programming Model

Creating and formatting a Common Base Event includes these steps:

1. Creating the Common Base Event object

2. Assigning component event-specific values in the Common Base Event (that is, values unique to this specific Common Base Event reported by the component)

3. Assigning component default values in the Common Base Event (that is, values unique to a component but common to all events reported by the component)

4. Assigning runtime values in the Common Base Event (that is, setting runtime data in the Common Base Event, such as environment information or runtime-defined default settings)

For example, consider an Enterprise JavaBean (EJB) application that reports a failure when accessing a database. The application supplies event-specific information, such as the database error code or the database server name, and default information, such as the name of the application. The underlying runtime, in this case the J2EE server, provides runtime information such as the current process ID.

Consider a second example of a business process reporting a sales-order approval milestone. The process runtime supplies event-specific information, such as the process and task names, and associated business data, such as the order identifier and order amount.

The facilities used to create and format Common Base Events are specific to the application and runtime, but a best practice is to use the open source Common Base Event Programming Model supplied in the Autonomic Computing Toolkit (ACTK) and in the TPTP Eclipse project.

Figure 4 on page 20 shows the structure of this Common Base Event Programming Model.

Figure 4 Common Base Event generation Note: This illustration is for AC Toolkit and TPTP Java event generation; for the non-Java implementation, EventFactoryHome does not exist)

The structure shown in Figure 4 maps to the four steps involved in formatting an event as shown in Table 1.

1. Create the Common Base Event object	The event factory is used to create Common Base Event objects. Multiple event factories can exist, distinguished by name, managed by the event factory home (see Best Practices). This allows separate software sections (for example, components or subcomponents) to have unique event factories.
2. Assign event-specific values in the Common Base Event	The Common Base Event object provides a comprehensive set of methods (the setxxx() methods) that are used to supply and format the data associated with a Common Base Event.
3. Assign component default values in the Common Base Event	The event factory refers to an event template that contains the default values for all events created by the factory. These values are copied into the Common Base Event object when the object is completed. The template used by an event factory is determined by the name of the event factory, allowing components using different factories to use different default settings.
4. Assign runtime values in the Common Base Event	These settings are inserted into the Common Base Event object by the underlying event runtime (such as WebSphere Application Server) when the object is completed. Runtime values can be environment information (such as process IDs) or runtime-defined default settings for any required properties. The underlying runtime documentation should provide information explaining the default values and specify how to override defaults.

Table 1. Mapping the event structure of Figure 4 to the steps for formatting an event

Best practices

· Event factories are named using the standard Java dot-delimited naming convention. Factory names should resolve to a system, component, package or class name, depending on the granularity of the configuration template.

· The Common Base Event Programming Library provides a reference implementation of the Event Factory Home that configures events with default properties from a template XML file. The template XML file contains an XML Common Base Event with various properties set. The naming convention used for the template XML file is <Event Factory name>.event.xml.

More details about the Common Base Event Programming Library for the AC Toolkit and in TPTP can be found in detailed documentation such as javadoc available with [ACTK] and [TPTP].

1.4.9.2 Capturing an event using JSR-47

JSR-47 is the best practice for a logging facility; however, some environments provide their own logging infrastructures that might be appropriate to use.

Note: At this time, JSR-47 cannot be used to create Common Base Events that will be produced and consumed through the Common Event Infrastructure implementation. Rather, as described in Formatting a Common Base Event using the TPTP Common Base Event Programming Model on page 19, the Autonomic Computing Toolkit and TPTP programming library should be used in conjunction with CEI.

Two aspects of the programming model are addressed here:

· A basic event capture interface that does not explicitly expose all the details of Common Base Event objects. The event capture runtime maps the values provided by the interface to the Common Base Event properties. It then creates a Common Base Event, using these mapping rules and any other values provided by the interface implementation. The event capture runtime also augments the Common Base Event with any environment-specific values or runtime-defined default settings.

· An advanced event capture interface that exposes the details of the Common Base Event object and allows the component full control over the settings in the Common Base Event. The component formats the Common Base Events with all component data and invokes the event capture runtime, supplying the Common Base Event object. The event capture runtime is responsible for supplying any environment-specific values or runtime-defined default settings.

Note: This document does not address a third aspect of the programming model, in which the component uses a basic event capture interface and an event capture runtime that are not based on the Common Base Event model. This model uses an adapter to transform the event information captured by the runtime to Common Base Events.

1.4.9.2.1 Basic event capture using JSR-47

Basic event capture interfaces capture Common Base Events using an interface that does not expose all of the details of the Common Base Event to the application programmer. The following description of the implementation provided in WebSphere Application Server, Version 6.0 demonstrates how a basic event capture interface can be used to capture Common Base Events, using JSR-47 as the basic event-capture interface. JSR-47, or java.util.logging, defines Java 1.4 interfaces used to capture problem determination data, such as log and diagnostic events. JSR-47 provides a specific set of interfaces optimized for capturing problem determination data easily and quickly.

Note: Most basic event capture interfaces are specific to a specialized class of events. For example, JSR-47 is used to capture problem determination events, such as log and diagnostic events.

Figure 5 illustrates how applications can create Common Base Events using the JSR-47 interfaces. JSR-47 uses the concept of loggers to capture events (represented in JSR-47 by LogRecord objects), using methods supplied by the Logger class to format and capture the event information.

Figure 5 Basic event capture: Creating problem determination Common Base Events with JSR-47 interfaces

The Java logging processing for log events using named loggers proceeds as follows:

1. Application code invokes a Logger with event-specific data.

2. The Logger creates a CommonBaseEvent using the createCommonBaseEvent() method of the EventFactory associated with the Logger. The logger determines the event factory to use by using the name of the logger to locate the name of the event factory.

3. The Logger wraps the CommonBaseEvent in a CommonBaseEventLogRecord and adds event-specific data, using information supplied when the Logger was invoked.

4. The Logger calls CommonBaseEvent’s complete() method.

5. CommonBaseEvent invokes ContentHandler’s completeEvent() method.

6. The ContentHandler adds XML template data to CommonBaseEvent (including component default event settings, such as the component name). The template file to use is defined by the event factory, and typically has a default of <factory name>.event.xml.

7. The ContentHandler adds runtime data to the CommonBaseEvent (including, for example, the current thread identifier).

8. The Logger passes the completed CommonBaseEventLogRecord to the JSR-47 handlers associated with the Logger.

9. The handlers format the data and write to the output devices associated with the handlers, such as log repositories.

More details about the WebSphere Application Server support of Common Base Events and using JSR-47 to format and capture them can be found at http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/rtrb_cbejavaapi.html.

1.4.9.2.2 Advanced event capture (using JSR-47)

Advanced event capture interfaces are used to capture Common Base Events directly, allowing the application to directly control the contents of the generated Common Base Event. Advanced event capture still uses a runtime-specific interface to capture the event, but this interface can use a Common Base Event object as input. The advanced event capture illustration here uses the JSR-47 implementation provided in WebSphere Application Server 6.0, but also uses the extensions provided in WebSphere Application Server to supply a Common Base Event object as an input to the interface. This provides a good comparison with the basic event capture interface described on page 21.

Note: The JSR-47 interface is still customized to capture problem determination events and expects the Common Base Event objects supplied to the interface to contain those types of events. More general event capture interfaces are available that allow the capture of any type of event, as well as routing and formatting the event based on policies and other configurable criteria.

Figure 6 shows how an application can use the Common Base Event Programming Library to create and format an event, and then use an extended JSR-47 interface to capture the event.

Figure 6 Advanced event capture: Creating and formatting an event using JSR-47 for event capture

The steps for generating a Common Base Event are as follows:

1. The application invokes the createCommonBaseEvent() method of EventFactory to create a Common Base Event object.

2. The application wraps the CommonBaseEvent in a CommonBaseEventLogRecord and adds event-specific data using the methods provided by the CommonBaseEvent object.

Note: The need to wrap the Common Base Event in a CommonBaseEventLogRecord is specific to the JSR-47 interface, which expects a LogRecord object as input.

3. The application adds event-specific data and calls CommonBaseEvent’s complete() method to finalize the event.

4. The Common Base Event invokes ContentHandler’s completeEvent() method (the ContentHandler invoked is specified by the EventFactory).

5. The ContentHandler sets default data for the Common Base Event (including, for example, the component name), by using the XML template data associated with the ContentHandler.

6. The ContentHandler sets runtime data for the Common Base Event (including, for example, the current thread identifier).

7. The application passes the finalized CommonBaseEventLogRecord to the JSR-47 Logger using the Logger.log method.

8. The Logger passes the CommonBaseEventLogRecord to JSR-47 Handlers associated with the Logger.

9. The handlers format the data and write to the output devices associated with the handlers, such as log repositories.

Best practice

The application can use any EventFactory to create a Common Base Event, but it’s best to use the same EventFactory and template files employed by the underlying event capture runtime’s basic event capture interface. For example, in the JSR-47 implementation, use the EventHandler with the same name as the JSR-47 Logger, and use a template file that follows the <factory name>.event.xml convention. In this way, the same default settings and behavior are used to format Common Base Events, regardless of whether the application is using the basic or advanced event capture interfaces (or both).

More details about the WebSphere Application Server support of Common Base Events and capturing them using JSR-47 can be found at: http://publib.boulder.ibm.com/infocenter/ws60help/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/rtrb_cbeapi.html.

1.4.9.3 Using the CEI event emitter

An event producer (sometimes called an event source) is any application that reports Common Base Events. One recipient of such events is the CEI Server. To send Common Base Event events to the CEI Server, the event producer uses the CEI Emitter library. The CEI Emitter supports both J2EE and J2SE applications and requires the WebSphere Application Server client. The preceding sections described how to generate Common Base Events. This section addresses how to send events using the CEI Emitter, for those applications that use CEI, including characteristics of the CEI event emitter that can influence the way in which events are processed by the CEI server.

For details about the CEI Programming Model, see the publication [CEIDEV].

Note that the WebSphere Process Server 6.0 and WebSphere Business Integration Foundation, Version 5.1.1 products include an interface called Event Correlation Sphere that serves as an optional wrapper of the CEI Event Emitter API. See the appropriate product publications [CEIRB] and [WPSP] for additional information.

CEI emitter configuration

An emitter is obtained from an emitter factory. The emitter factory is configured through a CEI emitter factory profile, using WebSphere Application Server configuration and administration panels. The CEI emitter properties include:

· J2EE transaction mode

- SAME - Event is rolled back if the caller’s transaction is rolled back

- NEW - Event is not rolled back if the caller’s transaction is rolled back

· Synchronization mode

- Synchronous - the sendEvent() call does not return until the event is persisted and published

- Asynchronous - the sendEvent() call returns immediately

· Filter plug-in

- Default provided by CEI

- Optional user-written code that implements the isEventEnabled() interface

In addition to these properties, the emitter configuration also defines the connection used by the CEI emitter to send events to the CEI Server.

The emitterFactory is accessed through the JNDI lookup. After the event producer has an emitterFactory, it can use the getEmitter() call to obtain an emitter, the EventFactory.createCommonBaseEvent() method (or other mechanisms described in sections 1.4.9.1 and 1.4.9.2) to generate and populate Common Base Events and the Emitter.sendEvent() method to submit the Common Base Event to the CEI server.

CEI emitter SendEvent method

Example 1 shows how an event producer can send events using the CEI emitter:

Context context = new InitialContext();

EmitterFactory emitterFx = (EmitterFactory)

context.lookup("java:comp/websphere/emitter");

Emitter emitter = emitterFx.getEmitter();

EventFactory eventFactory = (EventFactory)

context.lookup("java:comp/websphere/events/factory");

CommonBaseEvent event =

eventFactory.createCommonBaseEvent("HighValueOrder");

event.addExtendedDataElement("eventSource", "TestApp");

event.addExtendedDataElement("eventDomain", "BUSINESS");

event.addExtendedDataElement("eventPurpose", "Info");

event.addExtendedDataElement("customerNo", "C03738927");

event.addExtendedDataElement("orderNo", "O56232-2003-May");

event.addExtendedDataElement("orderValue", "1394000");

emitter.sendEvent(event);

Example 1 Sending events using the CEI emitter

Common Base Events can be created and populated in various ways, as described in preceding sections; Example 1 shows just one of these ways. In any case, the CEI event emitter sendEvent() method must receive a Common Base Event based on the AC Toolkit/TPTP object.

Note:

CEI only supports a Java representation of Common Base Events. TPTP has classes to serialize and deserialize Common Base Events. CEI currently supports Common Base Event version 1.0.1. Valid Common Base Events must include these attributes:

- version=“1.0.1” (Do not use the default value of 1.0)

- creationTime

- sourceComponentId

- situation

GlobalInstanceId — the best practice is to allow the emitter to set this value. CEI requires that this be set to a globally unique value.

The event producer can override the default transaction mode and synchronization mode of the sendEvent() method when necessary.

The sendEvent() method performs the following steps:

1. event.complete() (application-supplied code)

2. event.validate()

3. Filters the plug-in (this may be application-supplied code).

4. Sends the event to the CEI server.

Completing event contents automatically with the CEI emitter complete plug-in

Events can be created for many different situations. Each situation could require unique code to populate the necessary properties of an event. A content completion handler can be associated with an event factory. You can use a completion handler to modify the events to be sent to the CEI Server. The completion handler is called by the emitter before the event is sent.

Note

Content completion handlers might be used to set attributes common to all events. They also might be used to enforce policies, such as setting the severity based on the time of day.

Filtering events in the CEI emitter

Filtering should occur close to the source to reduce network traffic and decrease the amount of log information. Filtering is a plug-in, so it can be supplied by the application. A default filter plug-in is provided with CEI. The plug-in implementation returns a Boolean value: either the event passes filtering or it does not. A filter plug-in is associated with an emitter. When an event is sent, the emitter calls the filter to determine whether or not the event should be sent. A return value of true indicates that the event should be sent. If the return value is false, the event is discarded.

CEI emitter best practices

1. If filtering is enabled in the emitter profile, ensure that the XPath expression matches some events. Otherwise, no events are sent to the CEI Server. No indication is returned to the event source when an event is filtered. Therefore, ensure that testing procedures include sending a variety of events, along with subscribing or querying to ensure that the selected events are received by the CEI Server.

2. Make sure that the Validate() and complete() methods are not be called directly, because they are automatically invoked by the CEI emitter library.

3. Check that the Common Base Event version is set to 1.0.1.

4. Make sure that the globalInstanceId is not set by the application, because the emitter automatically generates a globalInstanceId that is guaranteed to be globally unique.

5. Decide with synchronization mode to use — synchronous compared to asynchronous:

- SYNCHRONOUS — used when is known that an event is persisted and distributed
before the call returns to the source.

             - ASYNCHRONOUS — allows the application to continue processing immediately
                              after the sendEvent() call. If synchronous mode is not required, an event
                               producer should use the asynchronous mode to achieve better performance
                               results under the same conditions.

6. Decide which transaction mode to use — same compared with new:

            - SAME — The event is sent in the caller’s transaction. This allows multiple events
                                to be sent in a single transaction, so that if the caller’s transaction is rolled back,
                                all the events are also rolled back.

            - NEW — The event is sent in a new transaction and is processed regardless of
                               whether or not the caller’s transaction is rolled back. If there is no need for events
                               to be processed within the same transaction, the event producer should use the
                               new mode to achieve better performance results under the same conditions.

1.4.9.4 Advanced CEI topics

CEI provides additional facilities for managing and receiving events, including:

· Classifying the event using CEI event groups (which control event routing and persistence)

· Publishing the event to subscribing event consumers (as event notifications) using JMS topics and queues. The CEI notification helper is used to convert the JMS message into a Common Base Event.

· Persisting the event in the CEI event repository.

· Querying and managing events in the CEI event repository, including purging unused events.

For details on the CEI Programming Model, see [CEIDEV].

1.4.9.4.1 Event groups, persistence, and routing

Event groups are an important configuration concept for CEI. Event persistence and routing are two significant processes in the CEI Server. All of these topics relate to the event life cycle and can affect how events are consumed by applications that use CEI. Each of these topics is detailed in the following sections.

1.4.9.4.1.1 Event groups

The event group is an important concept in CEI that is part of the CEI programming model. Event groups are used for subscriptions and queries. When subscribing to events, the event consumer should specify the event groups it is interested in. The event consumer receives only those events that match the event group definitions specified in the subscription. Event groups also should be specified for event queries (although there are other ways to query events that do not require event groups). Event groups are defined through the WebSphere Application Server (WCCM) administrative console. An event group is formed by an XPath expression, using any properties of the Common Base Event, plus an associated topic name for publication. The event group contains:

· The topic name for publishing the Common Base Events that match this event group

· The XPath expression that qualifies the event group

Some additional characteristics of event groups are:

· A single event could belong to multiple event groups

· Multiple subscribers can receive the same event if they share event groups

Event groups are defined by a regular expression event selector.

Notes:

· Event groups that are too broad (selected with coarse granularity) could create unnecessary overlap among events. This can result in duplicate data being published with separate events and can have a negative impact on the overall application performance.

· Overlapping event groups can result in duplicated events being received when subscribing to multiple event groups.

· Event groups that are too narrow (selected with fine granularity) could create event groups that might not be used (that is, might never match the event group selector) and could have a negative impact on the overall application performance.

1.4.9.4.1.2 Event persistence

The CEI server receives Common Base Events and persists the events in a database known as the CEI event repository. An administrator can enable or disable persistence in the event server through a configuration parameter. By default, event persistence is enabled. The CEI Server converts the event from the internal format used by CEI to the CEI event repository schema and uses the JDBC interface to connect to the database server configured for CEI (which serves as the event repository). After being persisted, the Common Base Events are sent to the routing process (described in “Event routing (event publication)” on page 29) to be routed and published using the platform messaging publication/subscription mechanism. The CEI server also provides an event repository plug-in interface through which a product that embeds CEI can provide its own event repository implementation to replace the CEI default event repository.

The default event repository can be queried using interfaces described in [CEIDEV]. See “Event querying” on page 30 for more information on event querying.

1.4.9.4.1.3 Event routing (event publication)

The CEI server determines which event groups match each Common Base Event and then publishes the event using the platform messaging publication and subscription mechanism. Event publication in CEI is based on the classification of events according to the event groups that are specified in the CEI server.

1.4.9.4.2 Consuming events using CEI event subscription and event access

An event consumer is any application that requires access to event information. The events can be consumed asynchronously, through subscription to the publish/subscribe mechanism supported by ESB and exploited by CEI server, or synchronously, through interfaces that allow querying, updating and purging event information in the CEI event repository through CEI access interfaces.

1.4.9.4.2.1 Event subscription

CEI uses JMS publish/subscribe mechanisms to publish events to event consumers. Hence, CEI subscription is achieved using standard JMS subscriptions. Event consumers must specify topics in their subscriptions. In addition to the event group, event consumers also can specify a filter selector that further restricts the set of events that this event consumer receives.

Best practice

Event group qualification is run in the CEI server. Event selector filtering is run in the CEI client. When specifying event groups and event selectors, consider this difference that can affect performance characteristics.

Event group subscriptions can be associated with publish/subscribe topics or with queues:

· Topics are used to send the same event to multiple consumers

· Queues are used to send events to a single consumer

JMS can be configured with persistence to avoid event loss.

Use the CEI notificationHelper to convert from JMS to Common Base Event.

· Use the notificationHelperFactory to obtain a notificationHelper

· The notification helper can filter events using an XPath expression.

Example 2 shows an example of event subscription.

Context context = new InitialContext();

NotificationHelperFactory helperFactory = (NotificationHelperFactory)

context.lookup(“java:comp/env/cei/notification”);

NotificationHelper helper = helperFactory.getNotificationHelper();

helper.setEventSelector(eventSelector);

String jmsSelector =

helper.getJmsMessageSelector(“/CommonBaseEvent[@severity>50 and @extensionName=\”customer_order\”]”);

JmsPortProfile jpp = helper.getJmsTopic(“critical_events”,

context);

TopicConnectionFactory tcf = (TopicConnectionFactory)

context.lookup(jpp.getConnectionFactoryJndiName());

TopicConnection tc = tcf.createTopicConnection();

Topic t = (Topic)context.lookup(jpp.getDestinationJndiName());

TopicSession ts = tc.createTopicSession(false,

Session.CLIENT_ACKNOWLEDGE);

TopicSubscriber subscriber = ts.createSubscriber(t,

jmsSelector,

false);

subscriber.setMessageListener(this);

…

public void onMessage(Message msg) {

CommonBaseEvent event = helper.getCreatedEvent(msg);

…

}

Example 2. Event subscription

1.4.9.4.2.2 Event querying

Events can be queried in CEI using different mechanisms:

· Query by globalInstanceId

· Query event groups (optionally specifying an event selector and the maximum number of events to return)

· Query for existence

· Retrieve associated events

These methods offer different performance characteristics. Querying by globalInstanceId typically provides the best performance results. Example 3 shows an example of an event query using an event group.

InitialContext context = new InitialContext();

Object eventAccessHomeObj = context.lookup("java:comp/env/cei/access");

EventAccessHome eventAccessHome = (EventAccessHome)

PortableRemoteObject.narrow(eventAccessHomeObj,

EventAccessHome.class);

EventAccess eventAccess = (EventAccess)eventAccessHome.create();

List events = eventAccess.queryEventsByEventGroup("critical_events",

"/CommonBaseEvent[@severity>50 and @extensionName=\"customer_order\"]",

true, // ascending order

5000); // max number of events

Iterator iter = events.iterator();

Example 3. Query using event groups

Best practice

To achieve adequate performance, event queries should be defined such that the resulting set of events should return a relatively small number of events, and events which are relatively small in size.

1.4.9.4.3 The CEI relationship to the WebSphere enterprise service bus (WESB)

This section focuses on the relationships among the Common Base Event, CEI and the WebSphere enterprise service bus product (WESB).

The Common Base Event is the standard message format for events related to business management, including events related to IT systems as well as events related to business activity. By integrating CEI, the WESB provides specialized support for these events.

Note:

The WESB provides support for mediation between software running in the same or different organizational units, irrespective of platform and programming model; because of this, it does not dictate nor constrain the message format. WESB can provide specialized support for Common Base Events through CEI integration, but Common Base Events are not the only data format used for interactions among applications that are connected using the WESB.

CEI can provide an event usage pattern for the WESB that includes persistence, querying, updating of events, filtering and topic-based distribution to event consumers. CEI is based on the platform messaging available in WebSphere. This allows the CEI configuration to be integrated with WESB configuration in the WebSphere Application Server administration console. The purpose of this is to ensure that the tasks involved in administering CEI are as simple and consistent as possible with other tasks related to WESB configuration.

The current CEI programming model includes the interfaces (the CEI emitter) for applications to report Common Base Events. The CEI emitter, which is based on the TPTP (see [TPTP]) open source project, provides a set of additional services such as complete plug-in structure, filtering support and monitoring using local log plug-ins. The programming model also includes support for consumers: the event group concept allows a consumer to subscribe to defined topics rather than subscribing to specific messages defined by the event sources.

2 Using Common Base Events

To illustrate the use of Common Base Events, this Best Practices document presents the structure of a Common Base Event and describes conventions and best practices for generating and interpreting these events. This document focuses on the general usage of a Common Base Event. It also includes information about specific uses of Common Base Events for problem determination and business processes.

2.1 Common Base Event Structure

A Common Base Event can contain several structural elements. These are:

· Common “header” information

· Component identification

· Situation information

· Extended data

· Context data

· Associated events and association engine

· Message data

Not all of these elements are required in every Common Base Event. Each of these structural elements has its own embedded elements and attributes.

The logical structure of a Common Base Event is illustrated in Figure 7; this figure is used in the sections that follow to help locate, within the Common Base event structure, the elements that are described.

Figure 7 Common Base Event structure

The remainder of this chapter describes how to generate a correct Common Base Event, providing specific information, including examples, tips and best practices, for the contents of each of the Common Base Event elements. In the following sections, we use different versions of Figure 7 Common Base Event structure to highlight the element that is being described, using an oval.

2.2 Required compared to optional elements

At the core of every Common Base Event are several elements that must always be present. The content of these elements could determine what is placed in other parts of a Common Base Event. The set of required elements for a Common Base Event is small, to allow for a wide variety of situations to be represented in a compact manner. All other elements are optional, although some optional elements are likely to be needed (required) in certain domains, such as problem determination or business events. These are detailed further in “The remainder of the Common Base Event (optional, but important, elements).

Notes:

1. This document is organized to present all of the core required properties in a Common Base Event first: The Common Base Event core (required elements) followed by the elements that describe all optional (but in many cases important) properties elements. The audience for this document is all users of Common Base Events, so the placement of properties into the required and optional chapters reflects the general usage. For those interested in specific domains, such as problem determination or business events, see the individual best practices boxes that relate to those topics, as well as the subsequent chapters that describe scenarios for problem determination and business events.

2. In the following sections, some properties of optional elements are listed as required. This means that although the element itself is optional, if that element is included, then the required properties of that element must be present.

2.2.1 Event requirements

Table 2 demonstrates and compares the required and optional elements for problem determination and business events, as compared to the base requirements for Common Base Events.

Required	A required value (either an attribute or an element) MUST be supplied.
Optional	An optional value (either an attribute or an element) MAY be supplied, but is not required.
Prohibited	A value (either an attribute or an element) MUST NOT be supplied.
Recommended	A value (either an attribute or an element) SHOULD be supplied. The value is not required but is encouraged as part of a best practice or convention.
Discouraged	A value (either an attribute or an element) SHOULD NOT be supplied. The value is not prohibited but is discouraged as part of a best practice or convention.

Property name	Detailed in section	Base specification	Problem determination log events	Problem determination diagnostic events	Business events
version	2.3.1	Required	Required	Required	Required
creationTime	2.3.2	Required	Required	Required	Required
severity	2.4.3	Optional	Required	Required	Optional
msg	2.4.8.2	Optional	Required	Required	Optional ( Note 5)
sourceComponentId*	2.3.3	Required	Required	Required	Required
sourceComponentId.location	2.3.5.2	Required	Required	Required	Required
sourceComponentId.locationType	2.3.5.3	Required	Required	Required	Required
sourceComponentId.component	2.3.5.5	Required	Required	Required	Required
sourceComponentId.subComponent	2.3.5.8	Required	Required	Required	Required
sourceComponentId.componentIdType	2.3.5.6	Required	Required	Required	Required
sourceComponentId.componentType	2.3.5.7	Required	Required	Required	Required
sourceComponentId.application	2.3.5.4	Optional	Recommended	Recommended	Recommended
sourceComponentId.instanceId	2.3.5.10	Optional	Recommended	Recommended	Recommended
sourceComponentId.processId	2.3.5.11	Optional	Recommended	Recommended	Recommended
sourceComponentId.threadId	2.3.5.12	Optional	Recommended	Recommended	Recommended
sourceComponentId.executionEnvironment	2.3.5.9	Optional	Optional	Optional	Optional
situation*	2.3.6	Required	Required	Required	Required
situation.categoryName	2.3.6.1	Required	Required	Required