Business Service Management

Home > Integration Scenarios > Tivoli Composite Application Manager for SOA

ITCAM for SOA and TBSM integration

This scenario describes how you can use TBSM to discover and monitor service objects based on data from IBM Tivoli Composite Application Manager for Service Oriented Architecture (ITCAM for SOA). In this scenario, you set up TBSM to work with data from the ITCAM for SOA using the Discovery Library toolkit and the Tivoli Event Integration Facility Probe (EIF Probe) for IBM Tivoli Netcool.

In this scenario, TBSM monitors and discovers services as follows:

TBSM collects the application alerts from the Netcool/OMNIbus EIF Probe connected to the TEMS for the ITCAM for SOA host. You need to setup the TEMS to forward situation events to the EIF Probe and customize the EIF Probe to handle the SOA events.

The TBSM Discovery Library toolkit collects the application data from the IBM Tivoli Enterprise Monitoring Server (TEMS) and IBM Tivoli Enterprise Portal Server (TEPS) connected to ITCAM for SOA. You need to set up the ITCAM for SOA data feed and customize the Discover Library toolkit to handle the SOA data.

The following figure displays the process of integrating ITCAM for SOA with TBSM:

1 How TBSM identifies services
2 Prerequisites
3 Step 1: Forward TEMS events to the EIF probe
4 Step 2: Edit the TEMS EIF configuration files
5 Step 3: Map situation events
- 5.1 Customizing event token mapping
6 Step 4: Customizing the Discovery Library toolkit
- 6.1 Event Identifier rules file
- 6.2 Labeling rules file
- 6.3 Composite rules file
7 Step 5: Processing the ITCAM for SOA DLA
- 7.1 Process the DLA book
8 Step 6: Create the TBSM service instance
9 Step 7: Firing situation events

How TBSM identifies services

When the EIF Probe filters situation events, it converts them to Netcool/OMNIBus ObjectServer events that can be read by TBSM. TBSM identifies the service-affecting events with the value of the BSM_Identity field. You edit the EIF Probe rules file to automatically create a unique BSM_Identity value for each service you want to monitor.

Conversely, when the Discovery Library Toolkit discovers a service from TADDM or a DLA, it creates a unique BSM_Identify field value for each discovered service. You edit the eventidentifiers.xml file to automatically create BSM_identify field values that match the values created by the EIF Probe.

When the BSM_Identity field/value pairs match, TBSM discovers and monitors the services associated with your ITCAM for SOA environment.

Prerequisites

Before you begin, you need to install the ITCAM for SOA application and associated components.

Install IBM Tivoli Monitoring 6.1 FP4 (or higher) with Tivoli Enterprise Portal Server extensions.
Install ITCAM for SOA v6.1 or higher and the Discovery Library Adapter (DLA). See the ITCAM for SOA information center.
Install the Tivoli EIF Probe. See the TBSM information center.

Step 1: Forward TEMS events to the EIF probe

To monitor the status of TBSM services created from the ITCAM for SOA data, you need to configure the IBM Tivoli Monitoring to forward events to an IBM Tivoli Netcool/OMNIbus ObjectServer. The TEMS connects to the EIF Probe as another Tivoli Enterprise Console server.

Events flow from the hub Tivoli Enterprise Monitoring Server (TEMS) to the Tivoli EIF Probe. The EIF Probe filters the events and forwards the events to the Netcool/OMNIbus ObjectServer monitored by TBSM. For this scenario, you can use the events for your ITCAM for SOA monitoring services in your production or test environments.

To configure the IBM Tivoli Monitoring to forward ITCAM for SOA events to TBSM, complete the following steps:

Open the Manage Tivoli Enterprise Monitoring Services application.
Right-click on the service Tivoli Enterprise Monitoring Server and select Reconfigure from the menu.
On the TEMS configuration options window, enable the TEC Event Integration Facility check box.
Click OK twice. The TEC Server: Location and Port Number window opens.
In the TEC Server Location field, enter the host name where the EIF Probe was installed.
In the TEC port number field, enter the port number of the EIF Probe.
Click OK to close the window.

Step 2: Edit the TEMS EIF configuration files

The EIF configuration file requires the kd4.map file to work properly. Ensure the kd4.map file is copied to the directory where the EIF configuration file is located. The kd4.map file is available on the ITCAM for SOA V6.1 installation media.

To edit the TEMS EIF configuration file:

On the IBM Tivoli Monitoring host, change to the directory where the TEMS is installed. The default directory is:

Windows: \IBM\TM\cms\TECLIB\
UNIX: <itm_installdir>/tables/host name/TECLIB/om_tec.config
Make a backp copy of the original OM_TEC.CONFIG file.
In a text editor open the file: OM_TEC.CONFIG.

Add the properties and values described in the following table:

Property Name	Value	Description
FilterMode	IN	Enables event filtering.
Filter:Class	ITM_Services_Inventory_610;	Event filters that forward all ITCAM for SOA events for the Services_Inventory_610 table to the Tivoli EIF Probe.
FilterCache:Class	ITM_Services_Inventory_610;	Filter that specifies which events to cache when IBM Tivoli Monitoring is unable to forward an event to the Tivoli EIF Probe

Save and close the file.
Restart the Tivoli Enterprise Monitoring Server

Note: If the EIF configuration file already contains values for any of the parameters listed above, you should replace the current values with the values described in the table.

Step 3: Map situation events

The EIF probe maps the ITCAM for SOA situation events to Netcool/OMNIbus event tokens. The BSM_Identity strings created from these event tokens must match the BSM_Identity strings that were created from the EventIdentifiers.xml file for the Discovery Library toolkit.

By default, the situation events the EIF probe receives do not map all the required event tokens needed to identify the ITCAM for SOA services. The key event tokens excluded are:

operation_name_u
operation_namespace_u
service_name_u
port_namespace_u
service_type

These event tokens uniquely identify a specific Service Port/Operation as defined by ITCAM for SOA. To map these event tokens, modify the tivoli_eif.rules file to build a BSM_Identity event token that maps to a specific TBSM service instance (in this case, an SOA resource). You make the changes in two different places in the tivoli_eif.rules file.
On Windows systems, the rules files is in the %NCHOME%\omnibus\probes\win32 directory.
On UNIX systems, the path is $NCHOME/probes/<os_name>.

Before you begin, you need to [Forward TEMS events to the EIF probe].

Customizing event token mapping

In this example, you create a logical block to remove single quotes from custom SOA event tokens. In this block all the events tokens used by the probe are stripped of single quotes which is required to avoid problems in later processing.

You also create an SOA-specific BSM_Identity token.

To configure the EIF Probes rule file with custom event tokens:

Open the tivoli_eif.rules file in a text editor.
Find the line with the text: #End removal of embedded single quotes.

To remove the single quotes from the custom SOA event tokens, enter the following code before the #End removal of embedded single quotes comments.

if(exists($operation_name_u ))
 {
 			if(regmatch($operation_name_u , "^'.*'$"))
 			{
 				$operation_name_u = extract($operation_name_u , "^'(.*)'$")
 			}
 }
 if(exists($operation_namespace_u ))
 {
 			if(regmatch($operation_namespace_u , "^'.*'$"))
 			{
 $operation_namespace_u = extract($operation_namespace_u , "^'(.*)'$")
 			}
 }
 if(exists($port_namespace_u ))
 {
 			if(regmatch($port_namespace_u , "^'.*'$"))
 			{
 				$port_namespace_u = extract($port_namespace_u , "^'(.*)'$")
 			}
 }

 '''if(exists($service_name_u ))'''
 {
 			'''if(regmatch($service_name_u , "^'.*'$"))'''
 			{
 				'''$service_name_u = extract($service_name_u , "^'(.*)'$")'''
 			}
 }
 if(exists($service_type ))
 {
 			if(regmatch($service_type , "^'.*'$"))
 			{
 				$service_type = extract($service_type , "^'(.*)'$")
 			}
 }

The quotes are stripped from the new SOA event tokens the same way they are for the default event tokens. The code identifies the specific event token (such as $service_name_u), and applies functions (regmatch and extract) and regular expression to the token to remove the single quotes.

To create the BSM_Identify field value from the custom SOA event tokens, enter the following code between the last two curly brackets at the end of the rules file:
```
# add SOA specific logic here.

 		if(exists($operation_name_u ))
 		{
 	     		 </nowiki>'''if (match($service_type,"1"'''))
 	      		 {
 '''@BSM_Identity = $operation_name_u + ":" + $operation_namespace_u + "@" + $service_name_u + ":" + $port_namespace_u'''
 '''log(DEBUG,"@BSM_Identity For SOA Event = " + @BSM_Identity''')
 			  }
    }
```
In this sample, the BSM_Identity field is build from the values for the operation_name_u, operation_namespace_u, service_name_u, and port_namespace_u SOA event tokens. Note: ITCAM for SOA sends a situation event for both the requestor and provider of the service port/operation pair. For this integration purpose you only filter events/situations the provider side by adding a check in the rules file for service_type=1.
Save and close the file.
To enable the changes, stop and restart the EIF Probe. In Windows, start the Tivoli_EIF probe service. In UNIX, execute the nco_p_tivoli_eif script from the $NCHOME/omnibus/probes directory.

Step 4: Customizing the Discovery Library toolkit

The Discovery Library toolkit filters ITCAM for SOA data and TBSM creates service instances based on the SOA data. The data can come from a DLA book file or a feed from TADDM host. To correctly manage the ITCAM for SOA data, you need to modify these XML control files on the TBSM host. These files are located in the following directory:

$NCHOME/XMLToolkit/xml

Event Identifier rules file

The EventIdentifierRules.xml file in the Discovery Library toolkit creates TBSM Identification field/value pairs for services imported from TADDM or DLA books. TBSM uses these identification values to correlate events to service instances. The default event identification rules provided with the Discovery Library toolkit map the IP Address or IBM Tivoli Managed managed system name to BSM_Identity values. To use the sample the integration with ITCAM for SOA, you need to customize these files.

Before you customize the event identification rule, backup the existing EventIdentifierRules.xml file. To handle the SOA data, you create new policy in the EventIdentifierRules.xml file. This Netcool/Impact policy defines an event identifier rule to match the status events from the SOA resource that were customized in the EIF Probe rules file.

In a text editor, open the EventIdentifierRules.xml file.
Search for the line: <Mapping policy="GetAllIPAddressesAndFQDN" class="cdm:sys.OperatingSystem"/>

Above this line, add the following code for the SOA event identifier policy:

<Policy name="WSOperationPort">
<Rule name="bysoa">
<Token keyword="ATTR" value='''"cdm:ActivityName"/>'''
<Token keyword="LITERAL" value=":"/>
<Token keyword="ATTR" value='''"cdm:Namespace"/>'''
<Token keyword="LITERAL" value="@"/>
<Relationship relationship="cdm:invokedThrough" relationshipTarget='''"cdm:soa.WSPort">'''
<Token keyword="ATTR" value='''"cdm:Name"'''/>
<Token keyword="LITERAL" value=":"/>
<Token keyword="ATTR" value='''"cdm:Namespace"'''/>
</Relationship>
</Rule>
</Policy>
<Mapping policy="WSOperationPort" class="cdm:soa.WSOperation"/>

In the above policy for class type WSOperation, the event identification is built from a combination of the web services operation name, operation name space, port name and port name space.

Save and close the file.

The above policy creates a TBSM BSM_Identification field value such as:

echoWithBytes:http://eventhandlertest.ibm.com@SimpleService:http://eventhandlertest.ibm.com

As a result, each TBSM service instance created from the SOA data has a unique BSM_Identification field value. Whenever TBSM detects an event with this BSM_Identification field value, it will check the event for status information for the associated service.

In this example, the event identifier policy creates BSM identifier with the operation name and port name.

<Policy name='WSOperationPort'>
<Rule name="bysoa">
<Token keyword="ATTR" value='''"cdm:ActivityName"'''/>
<Token keyword="LITERAL" value="@"/>
<Relationship relationship='cdm:invokedThrough' relationshipTarget=''''cdm:soa.WSPort'>'''
<Token keyword="ATTR" value="cdm:Name"/>
</Relationship>
</Rule>
</Policy>
<Mapping policy="WSOperationPort" class="cdm:soa.WSOperation"/>

Using the above policy the BSM_Identification value is:

echoWithBytes@SimpleService

Labeling rules file

By default, TBSM creates the display name of the service instance from cdm:Label CDM attribute of the object. You can customize the LabelingRules.xml file to create the display name from other CDM attributes of the SOA object.

When you integrate TBSM with ITCAM for SOA, the service instance that was created is the name of the web service operation on a particular web service port. In TBSM, this value is the service display name. To maintain the uniqueness, you customize the name label to be:

web service operation name @ web service port

You also include the name and namespace attributes of both the objects.

Backup the existing LabelingRules.xml file and search for: <Mapping policy="Global" class="%" />

Add the policy in this code sample:

<Policy name='WSOperationPort'>
             <Rule name="bysoa">
              	<Token keyword="ATTR" value="cdm:ActivityName"/>
              	<Token keyword="LITERAL" value=":"/>
              	<Token keyword="ATTR" value="cdm:Namespace"/>
              	<Token keyword="LITERAL" value="@"/>
 <Relationship relationship='cdm:invokedThrough'
     relationshipTarget='cdm:soa.WSPort'>
                 		<Token keyword="ATTR" value="cdm:Name"/>
                 		<Token keyword="LITERAL" value=":"/>
                 		<Token keyword="ATTR" value="cdm:Namespace"/>
              		</Relationship>
             </Rule>
       </Policy>
     <Mapping policy="WSOperationPort"
        class="cdm:soa.WSOperation" exclusive="true"/>
 <OverLayLabelsForCDMClasses>

        		<class>cdm:soa.WSOperation</class>

   	</OverLayLabelsForCDMClasses>

By performing the above customization, displayname of the service instance is generated as:

echoWithBytes:http://eventhandlertest.ibm.com@SimpleService:http://eventhandlertest.ibm.com

Composite rules file

The CDM_TO_TBSM4x_MAP.xml file groups a set of related objects into a composite representation of a single object. In some cases, the level of detail in the CCMDB is too granular. The composites create groups of objects to the level of management appropriate to the application. You can modify the default behavior of the CDM relationship types to a TBSM dependency to avoid the cyclical relationship between the various web services operations, web services ports and web services port end points.

Note: You need to have an in-depth understanding of the elements in the IBM Common Data Model before you attempt to change the composites configuration.

Composites are needed to group a set of related objects into a workable representation of a single object. If the level of detail in the CCMDB is too granular for certain applications, composites are used to create groups of objects at the level of management appropriate to the application. The default behavior of the CDM relationship types to a TBSM dependency was modified to avoid the cyclical relationship between the various web services operations, web services ports, and web services port end points. This is achieved by editing CDM_TO_TBSM4x_MAP.xml file in %NCHOME%\XMLtoolkit\xml directory.

Before you customize the file, backup the existing CDM_TO_TBSM4x_MAP.xml file. Search for following the string:

<class type="cdm:manages" isDependency="false"/>

Add the lines from the following sample:

<class type="cdm:invokedThrough" isDependency="false" priority="high" target="cdm:soa.WSPort"
  source="cdm:soa.WSOperation"/>
 <class type="cdm:federates" isDependency="false" priority="high" source="cdm:soa.WSPort"
  target="cdm:soa.WSEndpoint"/>

This change limits the relationship of cdm:invokedThrough has no dependency on target cdm.soa.WSPort on source cdm:soa.WSOperation. Similarly it also limits the dependency of cdm:soa.WSPort on cdm:soa.WSEndpoint.

Step 5: Processing the ITCAM for SOA DLA

The ITCAM for SOA 6.1 product shipped an ITCAM for SOA DLA that discovers SOA resources from your monitored environment. Follow the readme to discover services in your test or production environment. Run the ITCAM for SOA DLA following the documentation in the ITCAM for SOA DLA readme to generate an xml book with SOA resources in your monitored environment. A sample book (ITCAMSOA61.cvtwin02.2007-05-01T02.13.52Z.refresh.xml) discovered on our test environment is included in the TBSM_ITCAM4SOA.zip file shipped with the ITCAM for SOA Status Event Integration white paper at the TBSM Open Process Automation Library (OPAL).

There are two ways to process the IDML book:

TBSM 4.1 Discovery Library Toolkit directly processing the IDML book generated by the SOA DLA
Load the book into TADDM and TBSM 4.1 Discovery Library Toolkit integrates with TADDM and gets the information from TADDM

Process the DLA book

Copy the IDML book generated in the section above to %NCHOME%\dlbooks directory on TBSM Server which is the discovery library file system. Ensure the discovery library toolkit service is started. The discovery library toolkit service consumes the idml book from ITCAM for SOA and populates the service component registry with SOA resources.

The processing of the IDML book can be validated by checking the msgGTM_XT.log file for the message similar to the following:

GTMCL5290I: Book ITCAMSOA61.cvtwin02.2007-03-09T23.24.54Z.refresh.xml processed successfully.

The following path indicates the default location of the log file:

Windows: %NCHOME%\XMLtoolkit\log
UNIX: $NCHOME/XMLtoolkit/log

Step 6: Create the TBSM service instance

Once the book is processed and the service component registry (SCR) is populated, the objects created in the SCR can be used to construct a business service in TBSM depending upon the requirement of service model.

Complete the following steps to create a service instance:

Login to TBSM console as a user with service administration permissions.
Select Service Administration from the Pages list and click Go.
Click Templates tab and click Create New Template.The service template describes a class of services. When you create the new service instance, you assign to this new template.
Give the name of the template as ACMEServicesTemplate.
In the Rules tab, click Create a dependency rule. This launches a dependency rule editor.
Name the dependency rule as BSM_SOAOperationPortsWorst with a Child Rule/Mapping as BSM_SOAOperationPort and click OK.
Save the new template.
Next, create a business service and assign it to the new service template. To add the services from SCR, click the Dependents tab and are click the Add from Service Component Registry button.
Select the SCR services created from the SOA DLA book.
When you have finished adding services, save the service template.

Step 7: Firing situation events

ITCAM for SOA has predefined situations that can be used to monitor service performance metrics. Use the Response Time Critical situations to illustrate the integration between TBSM and ITCAM for SOA. The Response Time Critical situation has a pre-defined value of 10 seconds. This means that when response to a web service exceeds 10 seconds a Response Time Critical situation will be fired by the IBM Tivoli monitoring infrastructure.

To trigger the situation, invoke the echoWithDelay operation using the web services sample application user interface with any string and a delay of greater than 10 seconds.

By default the sampling interval is five minutes, so one request with a response of 20 seconds in a five minute period should be enough to fire the event providing you make no other shorter requests during the same interval. This situation will show up as shown below in the Tivoli Enterprise Portal console.

When the response time critical situation fires in ITCAM for SOA an EIF event is sent to the Tivoli EIF probe which forwards that event to the OMNIbus server. This event is processed by the server and the SOA resource's status changes to RED because it is a critical situation that fired.

The following is the screen shot on the TBSM Service Tree:

Once the situation from ITCAM for SOA is cleared, ITM sends a clearing situation to TBSM and the ACME Business Service that is shown as red turns back to green. There are some additional customizations that can be done for the look and feel aspect of this integration to customize the flyover text of service instances in TBSM.