Business Service Manager Version Customization Guide IBM SC

Transcription

1 Business Service Manager Version Customization Guide IBM SC

2

3 Business Service Manager Version Customization Guide IBM SC

4 Note Before using this information and the product it supports, read the information in Notices on page 277. Edition notice This edition applies to IBM Tivoli Business Service Manager Version 6 Release 1.1 and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2008, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents About this publication Audience Publications TBSM library Prerequisite publications Related publications Accessing terminology online Accessing publications online Ordering publications Accessibility Tivoli technical training Support information Conventions used in this publication Typeface conventions TBSM customization overview Operating system variables and paths Custom policies Data fetchers for Tivoli Monitoring TBSM expressions Custom Settings Custom properties Advanced ESDA and auto-population rule configuration Custom maps Discovery Library Toolkit Component Registry Viewer Reformatting displayed numeric values Custom view definition layouts Custom reports Launching to and from other applications Energy Dashboard Customizing policies About the Policy editor Understanding policy language components Differences between IPL and JavaScript About special policies Service instance variables TBSMShell RemoteTBSMShell Numerical aggregation rule policy Opening the numerical aggregation rule policy 17 Customizing the Numeric Dependency Rule policy Standard deviation function Number of bad children function Recalculate after restart function Numerical formula rule policy Opening the numerical formula rule policy Creating a custom policy to calculate status of a Numerical Formula Rule Auto-population rule policies Retrieving auto-populated service attributes.. 26 Retrieving auto-populated service name Using a policy to assign service templates ESDA-rule policy Opening the ESDA rule policy Customizing the ESDA rule policy Using a policy to extract data to display in a chart 34 Configure data fetcher to run a policy Data fetchers for Tivoli Monitoring Creating the data fetcher Configuring secure connections for data fetcher.. 39 Expression language About the expression language Expression language fundamentals Basic expression syntax Expressions and literal values Expressions and field names Expressions and operators Expression parser functions Parser functions CurrentContext Eval Extract Float FormatDuration GetDate Int LocalTime Log Replace RExtract Strip Substring ToLower ToUpper Trim Custom settings Adding values to the conversions table Adding custom display icons Custom event fields for updating services Special ObjectServer fields and TBSM Settings.. 56 Netcool/OMNIbus version Including child services with no data Customizing TBSM status events Disabling status events Configuring the SLA tracker period Changing template dependencies Custom properties Advanced ESDA and auto-population configuration When to use ESDA rules Copyright IBM Corp. 2008, 2013 iii

6 Scale of ESDA models Service persistence and mapping Invalidation of ESDA services Debugging ESDA rules Custom maps Custom maps overview Map file types Converting a custom map Running MapBuilder on UNIX systems Running MapBuilder on Windows systems Converting a file in MapBuilder Adding maps to services Adding the MapName attribute to a template.. 81 Adding map location attributes to a service.. 81 Customizing the import process of the Service Component Repository Customizing the XML control files Mapping the SCR class structure to a TBSM model Customizing the Service Component Repository Import Process Using Group elements Using identifier rules to associate aliases to a resource Simplifying the TBSM service model using composite rules Initiating external action using notification rules 108 Merging custom namespace instances using reconciliation rules Altering a resource display name using labeling rules Importing resource models into the SCR with custom namespace support Custom namespace and the Discovery Library Toolkit Service Component Repository API overview Components of the SCR API Creating an Impact policy using the SCR API 142 Exporting TBSM services to an idml book Synchronizing TBSM service model data with the SCR Properties that control the TBSMToSCR function 154 Component Registry Viewer overview 157 Manual Installation of the Component Registry Viewer Starting the Component Registry Viewer Create a database connection to the Component Registry Update a database connection to the Component Registry Deleting a database connection to the Component Registry Using the Component Registry Viewer Component Registry Viewer elements Component Registry Viewer views Exporting data from the Component Registry Business Service Composer Scenarios for using the Business Service Composer 165 Features of the Business Service Composer Starting the Business Service Composer Business Service Composer Workspace Composer Project workspace Creating a Business Service Composer project Editing a Business Service Composer project 169 Deleting a Business Service Composer project 170 Opening a Business Service Composer project 170 Static resources The Static Definition panel Policy patterns Touch point static resource Policy pattern descriptions Adding a policy pattern Editing a policy pattern Deleting a policy pattern Deploying a project Removing the impact of a project on the SCR Redeploying a project Reference information Identifying the MSS names for the resource and relationship references Configuration for z/os events Tivoli Event Pump for z/os Overview Event Pump and Netcool/OMNIbus Event mappings for z/os Event Pump Resource identity data formats Resource Identity and z/os Discovery OSLC hover preview configuration 195 Overview of TBSM OSLC support Enabling / Configuring OSLC Configuring TBSM for hover preview Reformatting displayed numerical values Reformat function Reformat function example Custom view definitions View definition graph layout modes Modifying a view definition Energy Dashboard customization Energy Dashboard overview Energy Dashboard portlet details Energy Dashboard installation requirements and components TBSM configuration for Energy Dashboard Creating the Energy Management data source 223 Import the Energy Management Data Fetchers 224 Import the Energy Management Service Model 225 iv IBM Tivoli Business Service Manager: Customization Guide

7 Configuring the Energy Dashboard Tree Template Adding the scorecard column policy Creating the Energy Dashboard page Discovering energy management resources Custom reports Create reports using simple queries and formatting 231 Configuring TBSM for BIRT reports Displaying a BIRT chart for a TBSM service Importing custom BIRT reports Converting custom BIRT reports Working with the TBSM data model Launching to and from applications 237 Launching from TBSM to pre-configured applications Launching from through a WebSEAL junction Supported application launches Configure remote report launch Launching into TBSM Configuring Change and Configuration Management Database to launch into TBSM Configuring Netcool/OMNIbus Web GUI to launch into TBSM and Tivoli Enterprise Portal from Active Event List Configuring IBM Tivoli Monitoring to launch into TBSM Installing and configuring launch definitions 256 Configuring the launch URL in IBM Tivoli Monitoring Custom launch integration Custom launch steps Custom view definitions Enabling service attributes Creating launch actions Extending custom launch actions beyond view definitions Notices Trademarks Index Contents v

8 vi IBM Tivoli Business Service Manager: Customization Guide

9 About this publication Audience Publications This guide contains information how to operate, maintain, and configure the product. This publication is for administrators and system programmers who need to use, install, maintain, or configure TBSM. This section lists publications in the TBSM library and related documents. The section also describes how to access Tivoli publications online and how to order Tivoli publications. TBSM library The following documents are available in the TBSM library: v Installation Guide, GI v Provides information about installing the product. Quick Start, GI Provides overview information about TBSM. v Exploring IBM Tivoli Business Service Manager, GI Provides an overview of the product features. v Administrator's Guide, SC Provides information about managing and configuring TBSM. v Service Configuration Guide, SC Provides information on how to use the features of the product console. v Customization Guide, SC Provides information on how to customize select features of the product. v Troubleshooting Guide, GI Provides information about resolving common problems with the product. v Release Notes, Provides latest information about the product discovered late in the test cycle that cannot be incorporated into the other publications. Prerequisite publications To use the information in this publication effectively, you must have some prerequisite knowledge, which you can obtain from the publications listed here. These publications are included on the Tivoli Documentation Central pages at: v IBM Tivoli Netcool/OMNIbus Version 7 Release 3.1 User Guide Provides an overview of Netcool/OMNIbus components, as well as a description of the operator tasks related to event management using the desktop tools. TBSM uses Netcool/OMNIbus as its event manager. Copyright IBM Corp. 2008,

10 v IBM Tivoli Netcool/OMNIBUS Administration Guide Provides information about how to perform administrative tasks using the Netcool/OMNIbus Administrator GUI, command line tools, and process control. It also contains descriptions and examples of ObjectServer SQL syntax and automations. v IBM Tivoli Netcool/OMNIBUS Probe and Gateway Guide Provides information contains introductory and reference information about probes and gateways, including probe rules file syntax and gateway commands. For more information about specific probes and gateways, refer to the documentation available for each probe and gateway. v IBM Tivoli Netcool/OMNIBUS Probe for Tivoli EIF Provides reference information about the optional Probe for Tivoli EIF that is included with TBSM. Related publications The following documents also provide useful information and are included in the TBSM Information Center. These publications are included on the Tivoli Documentation Central pages at: v IBM Tivoli Netcool/Impact Administration Guide v Provides information about installing, configuring and running Netcool/Impact and its related software components. TBSM uses Netcool/Impact policies to parse events and other data. IBM Tivoli Netcool/Impact User Interface Guide Provides information about using the Netcool/Impact user interface. v IBM Tivoli Netcool/Impact Policy Reference Guide Provides reference information about the Netcool/Impact Policy Language (IPL). It contains complete information about policy language syntax, data types, operators and functions. v IBM Tivoli Netcool/Impact Solutions Guide Provides information about implementing Netcool/Impact in your environment. v IBM Tivoli Netcool/Impact DSA Reference Guide Provides reference information about Netcool/Impact data source adaptors (DSA). Accessing terminology online The IBM Terminology Web site consolidates the terminology from IBM product libraries in one convenient location. You can access the Terminology Web site at the following Web address: Accessing publications online The format of the publications is PDF, HTML, or both. IBM posts publications for this and all other Tivoli products, as they become available and whenever they are updated, to the Tivoli Documentation Central Web site at 2 IBM Tivoli Business Service Manager: Customization Guide

11 Note: If you print PDF documents on other than letter-sized paper, set the option in the File Print window that allows Adobe Reader to print letter-sized pages on your local paper. Ordering publications You can order many Tivoli publications online at You can also order by telephone by calling one of these numbers: v In the United States: v In Canada: In other countries, contact your software account representative to order Tivoli publications. To locate the telephone number of your local representative, perform the following steps: 1. Go to 2. Select your country from the list and click Go. 3. Click About this site in the main panel to see an information page that includes the telephone number of your local representative. Accessibility This guide contains information how to operate, maintain, and configure the product. Tivoli technical training Support information Accessibility features help users with a physical disability, such as restricted mobility or limited vision, to use software products successfully. In this release, the TBSM console does not meet all accessibility requirements. For Tivoli technical training information, refer to the following IBM Tivoli Education Web site at If you have a problem with your IBM software, you want to resolve it quickly. IBM provides the following ways for you to obtain the support you need: Online Access the IBM Software Support site at support/probsub.html. IBM Support Assistant The IBM Support Assistant is a free local software serviceability workbench that helps you resolve questions and problems with IBM software products. The Support Assistant provides quick access to support-related information and serviceability tools for problem determination. To install the Support Assistant software, go to support/isa. Troubleshooting Guide For more information about resolving problems, see the problem determination information for this product. About this publication 3

12 Conventions used in this publication This publication uses several conventions for special terms and actions, operating system-dependent commands and paths, and margin graphics. Typeface conventions This publication uses the following typeface conventions: Bold Italic Monospace v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text v Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) v Keywords and parameters in text v Citations (examples: titles of publications, diskettes, and CDs v Words defined in text (example: a nonswitched line is called a point-to-point line) v Emphasis of words and letters (words as words example: "Use the word that to introduce a restrictive clause."; letters as letters example: "The LUN address must start with the letter L.") v New terms in text (except in a definition list): a view is a frame in a workspace that contains data. v Variables and values you must provide:... where myname represents... v Examples and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user v Text that the user must type v Values for arguments or command options 4 IBM Tivoli Business Service Manager: Customization Guide

13 TBSM customization overview This section describes the IBM Tivoli Business Service Manager (TBSM) customization options covered in this guide. IBM Tivoli Business Service Manager (TBSM) lets you create service models, custom views, and service trees to display your service data. In addition to these features, you can create maps and Netcool/Impact policies for TBSM service models. The topics in this guide describe options that are beyond the standard options available in the TBSM console and are aimed at users who have an in-depth understanding of TBSM and the environment they want to model. You need knowledge of vendor software packages or a scripting language to implement the customization options described in this guide. In addition, Expression language on page 41 describes the Netcool/Impact policy language and includes examples of how you can use expression and parser functions in TBSM. Operating system variables and paths On both the Data server and the Dashboard server a script is provided that allows you to set environment variables for quick access to the TBSM directory structure. If you do not set the variables, you can substitute directories with full path names when you run commands. You must run the script that applies to the servers that you installed. If you installed both servers on the same system, you must run both scripts. The locations of these setup scripts on UNIX systems are as follows: v installdirectory/tbsm/bin/setuptbsmdata.sh for the Data server v installdirectory/tbsm/bin/setuptbsmdash.sh for the Dashboard server where installdirectory is the directory in which you installed the server. The default directory is /opt/ibm/tivoli. The syntax used to run the UNIX scripts is:. installdirectory/tbsm/bin/setuptbsmdata.sh The locations of these setup scripts on Windows systems are as follows: v installdirectory\tbsm\bin\setuptbsmdata.bat for the Data server v installdirectory\tbsm\bin\setuptbsmdash.bat for the Dashboard server where installdirectory is the directory in which you installed the server. The default directory is C:\Program Files\IBM\tivoli. The following environment variables are used by TBSM as system environment variables: v TBSM_HOME This variable is used on both the Data and Dashboard servers. By default, the path set for this variable on Windows is C:\Program Files\IBM\tivoli\tbsm. The default path on the UNIX operating system is /opt/ibm/tivoli/tbsm v TBSM_DATA_SERVER_HOME Copyright IBM Corp. 2008,

14 Custom policies This variable is used on the Data server. By default, the path for this variable on Windows is: C:\Program Files\IBM\tivoli\tipv2\profiles\TBSMProfile\ installedapps\tbsmcell\tbsm.ear. The default path on the UNIX operating system is /opt/ibm/tivoli/tipv2/profiles/tbsmprofile/installedapps/ TBSMCell/TBSM.ear. v TBSM_DASHBOARD_SERVER_HOME This variable is used on the Dashboard server. By default, the path set for this variable on Windows is C:\Program Files\IBM\tivoli\tipv2\profiles\ TIPProfile\installedApps\TIPCell\isc.ear\sla.war. The default path on the UNIX operating system is /opt/ibm/tivoli/tipv2/profiles/tipprofile/ installedapps/tipcell/isc.ear/sla.war v TIP_HOME This variable is used on both the Data and Dashboard servers. By default, the path set for this variable on Windows is C:\Program Files\IBM\tivoli\tipv2. The default path on the UNIX operating system is /opt/ibm/tivoli/tipv2. Variables used in TBSM Publications For many of the commands and paths specified in this publication, both the UNIX and Windows equivalents are provided. However, in instances where only the UNIX convention has been specified, follow these directions for Windows systems. When using the Windows command line, replace $variable with % variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths. The names of environment variables are not always the same in the Windows and UNIX environments. For example, %TEMP% in Windows environments is equivalent to $TMPDIR in UNIX environments. Note: If you are using the bash shell on a Windows system, you can use the UNIX conventions. A policy contains a set of statements written in either the Impact Policy Language (IPL) or JavaScript. This topic introduces how you can customize policies for Tivoli Business Service Manager (TBSM). You can customize four types of policies that control TBSM rules. You must not attempt to customize these policies unless you are familiar with Netcool/Impact policies. You can use these policies to modify the way that TBSM processes the following rule types: v Numerical aggregation rules v Numerical formula rules v Auto-population rules v ESDA rules Customizing policies on page 11 describes how to edit the policies for these rules. Examples of the ways in which TBSM can use policies are: v Create policy-based data fetchers v Create a policy that defines how metrics are displayed in the Service Tree scorecard on the Energy Dashboard. 6 IBM Tivoli Business Service Manager: Customization Guide

15 v Create a policy to obtain the data for custom charts. v You can customize the ServiceEventUpdater policy to modify the behavior of the status events that TBSM writes to Netcool/OMNIbus. Expression language on page 41 describes TBSM expressions and parser functions. Related tasks: Opening the numerical aggregation rule policy on page 17 To edit the numerical aggregation rule policy, complete the steps in this procedure. Data fetchers for Tivoli Monitoring TBSM expressions Custom Settings Custom properties Data fetcher configuration for IBM Tivoli Monitoring. You can access Tivoli Monitoring data collected by its agents with a data fetcher that uses a Netcool/Impact policy. The data fetcher calls the web service TBSM charts services for IBM Tivoli Monitoring. TBSM provides you with the Netcool/Impact policy language and Perl regular expressions to perform various actions when you configure a service in TBSM. Some of the functions you can perform with expression language are: v Create custom instance names by extracting parts of field values v Create custom filters that set thresholds for bad and marginal service status v Create secondary output status expressions by comparing the output of multiple rules v Create expressions for custom service views (canvases) For more information about how to use expressions with TBSM, see Expression language on page 41. For a complete list of all the functions available for Netcool/Impact policies, see the Netcool/Impact Policy Language Reference Guide. You can customize your TBSM system by modifying some property and configuration files. For more information about these files, see Custom settings on page 55. This section describes key properties in the TBSM_sla.props and the RAD_sla.props files. The TBSM_sla.props file in the $TBSM_HOME/etc directory and the RAD_sla.props file in the $TBSM_DASHBOARD_SERVER_HOME/etc directory include many properties. Custom properties on page 65 describes key properties that you can edit to change the behavior of your TBSM system. TBSM customization overview 7

16 Advanced ESDA and auto-population rule configuration Custom maps This section describes advanced options for ESDA and auto-population configuration. The topics in this section describe how you can manage the following aspects of ESDA and auto-population rules: v Determining which type of rule to use v The scale of service models v The service persistence and event mapping v Debugging of ESDA rules Discovery Library Toolkit v Additional attributes generated by the rules When you specify the GIS positioning for a given service, the TBSM Service Viewer can display the service location on the default world map. You can also choose and create custom maps for your service models. Custom maps on page 79 describes how to configure custom maps for your TBSM system. Note: The Java plug-in for web browsers relies on the cross platform plugin architecture NPAPI, which has been supported by all major web browsers for over a decade. However, Mozilla intends to remove support for most NPAPI plugins in Firefox by the end of Oracle has announced that it is to depreciate the Java browser plug-in technology with the next release of the Java platform (JDK9). Because of these industry moves, TBSM is announcing the end of support for the Service Viewer (and custom canvases). These features will be removed from the product in Fix Pack 5. Customers are advised to replace custom canvas usage with IBM Dashboard Application Services Hub widgets, as soon as possible. See link: com.ibm.tivoli.itbsm.doc/adminguide/bsmu_jazz_c_overview.html?lang=en. Detailed information on the TBSM Datasets available for use with DASH widgets is available in the "Advanced Topics" section of the Tivoli Business Service Manager Wiki at home?lang=en#!/wiki/tivoli+business+service+manager1/page/ Advanced+Topics. The Topology Dataset, available since in , provides simiar visualization to the legacy Concentric views. The Business Impact Dataset, introduced in , provides simiar visualizations to the legacy Business Impact All and Business Impact views and the Map Dataset, introduced in , provides simiar visualization to the legacy GIS views. You can customize the Discovery Library Toolkit to map IBM Common Data Model attributes, alternate name space objects, the SCT API, and TBSM auto-pop objects to TBSM service attributes. As Common Data Model (CDM) resources are moved into the TBSM model, the instance class structure and relationships must fit into the business model implemented by TBSM. The Service Component Repository (SCR) provides a 8 IBM Tivoli Business Service Manager: Customization Guide

17 Component Registry Viewer default implementation of the mappings and a framework through a set of XML files that enable you to customize the mapping process. The TBSM Component Registry is a collection of database tables that are used by the Discovery Library Toolkit to store the information it receives from Discovery Library Adapter books and the discovery API connection, such as the API provided by TADDM. The Component Registry Viewer presents data that you can use to validate data, in problem determination, and to build business service models. Reformatting displayed numeric values You can change how numeric values display in service image prototypes. You can reformat the display of numeric values in the TBSM service viewer. There are times when the default display of numeric values in a view definition prototype is awkward. For instance, customer KPI values are always internally stored as a double value even when they logically represent an integer value. The default display for these values includes a decimal point and tenths. At other times, you might want to have larger numbers formatted for easier readability. Custom view definition layouts Custom reports You can customize a view definition layout mode for Concentric and Grid views. You can customize the grid and concentric view definitions. There are layout modes that let you make better use for the available screen space for these view definitions. You can customize IBM Tivoli Business Service Manager reports or add new reports using reporting tools included with Tivoli Common Reporting. To take advantage of custom reports, you must install the Tivoli Common Reporting product. For information about installing and configuring TCR, see the TCR Information Center. After it is installed, you can load the TBSM historical reports to the TCR server. See the TBSM Installation guide for information about installing the TBSM historical reports. The predefined reports supplied with TBSM provide chart and tabular views of historical outage, outage duration, and service affecting event data stored in the Tivoli Data Warehouse component of IBM Tivoli Monitoring. You can customize existing TBSM reports or create new custom reports using Cognos Report Studio or Query Studio. The TBSM BIRT reports are loaded, but TCR does not provide any tools to customize them. For information about installing and configuring the TBSM agent that populates the Tivoli Data Warehouse, see the TBSM Installation guide. TBSM customization overview 9

18 Custom reports on page 231 describes how you can use Tivoli Common Reporting with TBSM and includes references to more Tivoli Common Reporting. Launching to and from other applications Energy Dashboard This topic provides an overview of how you can launch other applications in relation to services in IBM Tivoli Business Service Manager. You can also launch into TBSM from other applications. TBSM can launch other applications in context with the data for a given service. Depending on your configuration, when you right-click on a service, you have the launch options described in this topic. The service you click sets the context for the launch. That is, when you launch out to another application from the service you click, the other application that opens displays data about that service. You can also configure other applications to launch the URL for TBSM. Launching to and from applications on page 237 describes how you can configure these launch options. The Energy Dashboard for data centers customization. The Energy Dashboard is a versatile, role-based information dashboard that can collect metrics from IT, facilities, and physical assets and enables you to visualize and communicate both the environmental and economic impact of energy usage across your infrastructure. Using views from TBSM and drawing on information collected by IBM Tivoli Monitoring for Energy Management, and other potential sources, the Energy Dashboard enables you to consolidate the information you collect and present it in a highly consumable and insightful format. It can help address key questions such as: v How much energy am I using? v What services are costing the most in energy consumption? v Can I make alterations and still meet my service level agreements? v Since we made changes, how much are we saving on energy bills? 10 IBM Tivoli Business Service Manager: Customization Guide

19 Customizing policies About the Policy editor This section explains how to work with special IBM Tivoli Netcool/Impact policies for IBM Tivoli Business Service Manager (TBSM). For more information about policies, see the Netcool/Impact publications. You can use policies to customize the rules TBSM uses to monitor and create service models. The policy editing features and this section are intended for users who are familiar with Netcool/Impact policies. Policies consist of a series of function calls that manipulate events and data from your supported data sources. A policy is a script that contains a set of instructions to automate alert management tasks, for example, defining the conditions for sending an to an administrator, or sending instructions to the ObjectServer to clear an event. For more information about policies and the Policy editor, see the Netcool/Impact publications and the TBSM Service Configuration Guide. The TBSM Service Configuration Guide describes how to: v Use the Policy editor toolbar to help you create, manipulate, and save policies v Edit a policy v Delete a policy Understanding policy language components You use the Impact Policy Language (IPL), or JavaScript to write the policies that you want Netcool/Impact to run. The IPL is a scripting language similar in syntax to programming languages like C/C++ and Java. It provides a set of data types, built-in variables, control structures, and functions that you can use to perform a wide variety of event management tasks. You can create your own variables and functions, as in other programming languages. JavaScript a scripting programming language commonly used to add interactivity to web pages. It can also be used in browser environments. JavaScript uses the same programming concepts that are used in IPL to write policies. For more information about JavaScript syntax, see default.asp. Copyright IBM Corp. 2008,

20 Differences between IPL and JavaScript When writing policies using IPL or JavaScript there are a number of differences. Use the following table as a reference. Table 1. IPL and JavaScript differences IPL IPL is not case-sensitive. When creating Arrays, in IPL you must use {} curly braces to assign array values. In IPL, the escape character can be either \\s or \s. In IPL, integers return as whole numbers, for example 1. ClassOf v If you pass an integer variable to ClassOf it returns as long in IPL. v v If you pass a context variable to ClassOf, it returns as BindingsVarGetSettable in IPL. If you pass an OrgNode variable to ClassOf, it returns as OrgNode in IPL. Event Container If you are using IPL, you can optionally reference event field variables using the dot notation or notation. notation is a special shorthand that you can use to reference members of EventContainer instead of spelling out the full Exit In IPL, when you use Exit in a user-defined function it exits that function, and the policy continues. Float In IPL, the float function converts an integer, string, or Boolean expression to a floating point number. Float In IPL, the Float function returns Eval In IPL, Integer division of 10/5 is 2.0. JavaScript JavaScript is case-sensitive, keep this in mind when you are creating variables, statements, objects, and, functions. In JavaScript, you must use [] square braces to assign array values. In JavaScript, the escape character must be \\s. In JavaScript, integers are Float as a result, numbers always display with decimals for example 1 becomes 1.0. v If you pass an integer variable to ClassOf it returns as double in JavaScript. v v If you pass a context variable to ClassOf, it returns as JavaScriptScriptableWrapper in JavaScript. If you pass an OrgNode variable to ClassOf, it returns as VarGetSettable in JavaScript. If you are using JavaScript, you must use the dot notation EventContainer.Identifier. In JavaScript, when you use Exit in a user-defined function in a policy it exits the entire policy. If you want to stop a function in a JavaScript policy you must use the return command in the policy. JavaScript does not add any decimal points to the results for integers and Boolean expressions that are used with the Float function. In JavaScript, the Float function returns extra precision, for example instead of for the function Eval. In JavaScript, integer division of 10/5 is 2 for the function Eval. 12 IBM Tivoli Business Service Manager: Customization Guide

21 Table 1. IPL and JavaScript differences (continued) IPL JavaCall In IPL numbers are whole. Like In IPL supports the Like operator. For example, teststring LIKE ".*abc.*"; JavaScript JavaScript uses doubles for the numbers, when using JavaScript, for a JavaCall that needs an integer argument, you must use the Integer.parseInt JavaCall to create an actual integer. JavaScript does not use the Like operator. The equivalent example is /.*abc.*/.test(teststring); About special policies TBSM lets you customize the functions that policies use for numerical aggregation rules, numeric formula rules, and rules used to create services automatically. You can modify these policies to better meet the needs of your service environment. You must be familiar with Netcool/Impact policies before you attempt to customize these policies. For each policy, the Policy Editor window includes a comment section at the top that includes some instructions for the policy. All comments are enclosed between the /* and */ characters. Note: To edit policies in the TBSM Policy Editor, you must have either the impactadminuser or impactfullaccessuser role privileges. For more information about TBSM users, groups, and roles, see the TBSM Administration Guide. For more information about Netcool/Impact policies, see the Netcool/Impact publications included on the TBSM Quick Start DVD and Information Center. Note: If you create your own policies, never include special characters such %, or + in your policy name. If a policy name contains special characters, the policy runs improperly or not run at all. Expression language You can use Netcool/Impact expressions and parser functions in these policies. For more information, see Expression language on page 41 and the Netcool/Impact publications. Policy logger Use the log function to see the values passed to your policy in the TBSM_policylogger.log. By reading the log, you can see the values passed for each service instance. The policy logs are stored in the INSTALL_HOME/tbsm/logs directory and start with the name: TBSM_policylogger.log. To help troubleshoot your policy, you must run the UNIX tail command on the most recent TBSM_policylogger.log file when you are creating the policy. For information about enabling the log detail level, see the TBSM Troubleshooting Guide. Customizing policies 13

22 Service instance variables This section describes the service instance variables you can get and set in a policy. Whenever a policy is run against a given service instance, you can access this data from the ServiceInstance object. Service variables in a policy You can obtain these default variables from the ServiceInstance object in policies that receive a ServiceInstance object as input. Any additional variables evaluated against a ServiceInstance object return the value as an additional attribute (property) of a given service instance. These additional variables are the parameters in the Additional tab of the Edit Service tab in the TBSM console. The properties in the table below can be accessed from the ServiceInstance object using the syntax: ServiceInstance.<propertyName> All property names not in the table shown return the additional property value of that property name for the service. Table 2. Service variables in a policy Variable name DISPLAYNAME DESCRIPTION ICONNAME TIMEWINDOWNAME SLANAME SERVICEINSTANCENAME SERVICEINSTANCEID BADDURATION THRESHOLDSECS BADCUMUL THRESHOLDSECS PRIMARYTAGNAME ISINMAINTENANCE CURRENTTIME WINDOWNAME ISMEMBEROF TEMPLATE <TemplateName> CHILDINSTANCEBEANS PARENTINSTANCEBEANS NUMCHILDREN NUMCHILDREN OFTEMPLATE_<TemplateName> Service attribute description The display name field for the service. The description field for the service. The name of the icon file for the service. The name of the maintenance schedule time window for the service. The name of the service level agreement (SLA) assigned to the service. The instance name for the service. The unique instance ID for the service The amount of downtime in current outage for the service. The cumulative downtime for a service during the smallest specified monitoring interval (day, month, and so on) The name of the primary template for the service. Indicates whether the service instance is in maintenance. The name of the monitoring time window for the service and the start and end dates of time window. This variable returns whether the service is assigned to a service template. For example, ISMEMBEROFTEMPLATE Webserver returns true if the service is assigned to the Web server template. The array of child ServiceInstanceBeans for a service, if the service has child services. This variable is a READ ONLY variable. Setting this variable has no effect and will not change the relationship of the ServiceInstance being referred to. The array of parent ServiceInstanceBeans for a service if the service has parent services. This variable is a READ ONLY variable. Setting this variable has no effect and will not change the relationship of the ServiceInstance being referred to. The number of children of the service. The number of children of the service that belong to the specified template. 14 IBM Tivoli Business Service Manager: Customization Guide

23 Table 2. Service variables in a policy (continued) Variable name MEMBERTEMPLATES Service attribute description The array of ServiceTypeBeans which evaluate to the template name when operated on directly. RADSTATUS The overall status of the service, good (0), marginal (3), or bad (5). STATEMODELNODE.<AttributeName>.Value The status of the specified attribute. Note: When you edit the GetTreeColumnValue policy from the tree template editor, the ServiceInstance object only has the following fields available: SERVICEINSTANCEID, SERVICEINSTANCENAME, DISPLAYNAME, DESCRIPTION, PRIMARYTAGNAME, ICONNAME, STATEMODELNODE, MEMBERTEMPLATES, RADSTATUS. ESDA and auto-population variables The following variables can be set for service attributes from an ESDA and auto-population policy. You can also set variables for additional attributes created by an ESDA rule. Table 3. Service variables to set in a policy Variable name DISPLAYNAME DESCRIPTION TIMEWINDOWNAME SLANAME Service attribute description Sets the display name for the service. Sets the description for the service. Sets the maintenance schedule name for the service. Sets the SLA used for the service. In the ESDA policy, a membertag variable is available. This is a ServiceTemplate object. The following properties are obtainable from that object via the syntax: MemberTag.<propertyName> All property names not in the table shown return the additional property value of that property name for the template. Table 4. Template variables in an ESDA policy Variable name SERVICETYPENAME DESCRIPTION ICONNAME SERVICETYPEID NUMINSTANCES Service attribute description The template name. The description for the service. The icon of the template. The ID of the template. The number of instances of the template Customizing policies 15

24 TBSMShell This topic describes the TBSMShell function which lets you put RADshell commands in a policy. With the TBSMShell function, you can change the TBSM configuration in a policy. Only use this function if your Data server is not configured for failover. If your Data server is configured for failover, use the RemoteTBSMShell function. Syntax RemoteTBSMShell Result = TBSMShell('command'); Where command is a string that you execute in RADShell, and Result is the string output by RADShell after running the command. The command can be a sequence of RADShell commands separated by semicolons. This example creates a template called DBFarm. Result = TBSMShell ( createtemplate ("DBFarm","man_svg.gif") ); Use this function when Data server failover is configured and there is a policy that includes RADshell commands. This function checks the Name Server to see where the primary TBSM server is running and it then executes the radshell command on that primary server. Syntax Result = RemoteTBSMShell('command'); Where command is a string that you execute in RADShell, and Result is the string output by RADShell after running the command. The command can be a sequence of RADShell commands separated by semicolons. This example creates a template called DBFarm. Result = RemoteTBSMShell ( createtemplate ("DBFarm","man_svg.gif") ); Numerical aggregation rule policy The NumericAttributeFunctions policy contains a list of functions that you can use to calculate the rule-output value specified in the Numerical Aggregation Rule window. This window is shown in Figure 1 on page 17. You can edit the policy to adjust the standard deviation or the number of child services with a status of bad. You can also create new functions. This policy is triggered whenever the status of a child service changes based on the selected Child Metric Rule. This policy is shared across all numerical aggregation rules. For more information about using the Numerical Aggregation Rule window, see the TBSM Service Configuration Guide. 16 IBM Tivoli Business Service Manager: Customization Guide

25 Figure 1. Edit Numerical Aggregation Rule window You specify the Rule Name, Child Template, and Child Metric Rule you want to use to calculate the parent service status. Once you set the basic rule parameters, you select the Aggregation Function that you want to use to calculate the service status. Opening the numerical aggregation rule policy To edit the numerical aggregation rule policy, complete the steps in this procedure. Procedure 1. Open the Numerical Aggregation Rule window and select the service template and rule you want to work with. 2. Click the Policy radio button. 3. Click the Edit Policy button. The Policy Editor window opens as shown in Figure 2 on page 18. The text editor contains information about the functions used to calculate the standard deviation for child services and the total number of child services with a status of bad. Customizing policies 17

26 Figure 2. Policy editor for NumericAttributeFunctions policy For a description of the tool bar and available Netcool/Impact functions, see About the Policy editor on page 11 and Expression language on page 41. Related concepts: Custom policies on page 6 A policy contains a set of statements written in either the Impact Policy Language (IPL) or JavaScript. This topic introduces how you can customize policies for Tivoli Business Service Manager (TBSM). Customizing the Numeric Dependency Rule policy You can create new functions for this policy by following the syntax of the existing functions. When you create a function, the new function is added to the Policy drop-down list in the Edit Numerical Aggregation Rule window. About this task Note: The numerical aggregation rule functions have been created in IPL. Only IPL can be used to create and edit numerical aggregation rule functions. You select the child service template and the rule you want to use for the function in the Edit Numerical Aggregation Rule window. This policy contains a list of functions that can be used to calculate the status of the attribute. You can create new functions by following the format of the existing functions. You must pass the values from the selected rule in the following syntax: function function_name(childrenstatusarray, AllChildrenArray, ServiceInstance, Status) { functionbody } 18 IBM Tivoli Business Service Manager: Customization Guide

27 The purpose of the function is to set the Status variable to a number that TBSM can use for the selected rule output value. Table 5 describes the function input values. Note: When using a policy to calculate the status for a rule, assign the Status variable to a number. If you return a String, the server does not process it correctly and status events are not sent to the ObjectServer. If you select the Text Rule checkbox, the Status variable can be set to String. Table 5. Input values for the dependent-numeric rule policy Input value ChildrenStatusArray AllChildrenArray ServiceInstance Status Description An array of numbers for the status of the child services assigned to the child template. These are the output values from the numerical rule for each child service (the child numerical rule and child template are configured in this input value). An array of ServiceInstance objects that contains all the child services that are used for the rule calculations. Any rule for these child services is accessed by AllChildrenArray[i].StateModelNode. RuleName.Value where: RuleName is the name of the child-numerical rule you want to use for the calculation. ServiceInstance is the object of the service whose rule is being evaluated by this function. Additional properties of this service can be obtained using the syntax ServiceInstance.<propertyname>. The variable you must set in the policy. Note: If a policy or formula rule depends on an additional property (attribute) of the service instance, when the additional property is changed the rule does not reevaluate itself. The rule reevaluates itself only if other attributes that it depends on change, or if there is a configuration change to the rule. The policy can access additional properties of an instance by the syntax: ServiceInstance.propertyname. Standard deviation function The standard deviation statistic measures the dispersion or variation in a distribution of values. This function measures the range of output values for the Child Numerical rule you selected in the Numerical Aggregation Rule window. Example standard-deviation function This function calculates the standard deviation of the rule output values for all the child services of a given parent service (ServiceInstance value). You select the child service template and the rule used in this function in the Numerical Aggregation Rule window. Table 6 on page 20 describes the parts of the StandardDeviation function. [1] function StandardDeviation(ChildrenStatusArray, AllChildrenArray, ServiceInstance, Status) { [2] i = 0; [3] Sum = 0 [4] NumChildren = 0; [5] Average = 0; [6] // first find the average of the values [7] while (ChildrenStatusArray[i] <> NULL) { [8] Sum = Sum + ChildrenStatusArray[i]; Customizing policies 19

28 [9] NumChildren = NumChildren + 1; [10] i = i + 1; [11] } [12] if (NumChildren > 0) { [13] Average = Sum / NumChildren; [14] } [15] [16] // Now find the variance of the values [17] i = 0; [18] SumOfDifferenceFromMeanSquared = 0; [19] while (ChildrenStatusArray[i] <> NULL) { [20] DifferenceFromMean = ChildrenStatusArray[i] - Average; [21] DifferenceFromMeanSquared = DifferenceFromMean * DifferenceFromMean; [22] SumOfDifferenceFromMeanSquared = SumOfDifferenceFromMeanSquared + DifferenceFromMeanSquared; [23] i = i + 1; [24] } [25] Variance = 0; [26] if (NumChildren > 0) [27] { [28] Variance = SumOfDifferenceFromMeanSquared / NumChildren; [29] } [30] StandardDeviation = sqrt(variance); [31] Status = StandardDeviation;} Table 6. Standard deviation function description Line numbers Description 1 Sets the function name and passes the rule input values to the function as described in Table 5 on page Sets the default values for the variables used in the function Calculates the average rule value for the services in the ChildrenStatusArray Calculates the variance of the rule values for the services in the ChildrenStatusArray. 30 Calculates the value of the StandardDeviation as the square root of the Variance value. 31 Sets the rule Status value as the value of the StandardDeviation variable. Number of bad children function This function returns the number of children that have an overall rule value (OverallAttribute) of Bad. Use this function when the status for child services is determined by the worst overall status (OverallAttribute) for all the rules configured for the service. This policy is triggered when the overall attribute for a child service changes based on the selected aggregation rule. Example number of bad children function This function counts the number of child services where the overall status equals bad (5). The child service template and the rule used in this function are specified in the Numerical Aggregation Rule window. [1] function NumberOfBadChildren(ChildrenStatusArray, AllChildrenArray, ServiceInstance, Status) { [2] i = 0; [3] Count = 0; [4] while (ChildrenStatusArray[i] <> NULL) { [5] if (ChildrenStatusArray[i] = 5) { [6] Count = Count + 1; [7] } 20 IBM Tivoli Business Service Manager: Customization Guide

29 [8] i = i + 1; [9] } [10] Status = Count; [11] } Table 7. Number of bad children function description Line numbers Description 1 Sets the function name and passes the rule input values to the function as described in Table 5 on page Sets the default values for the variables used in the function. 4-6 Counts the number of services in the ChildrenStatusArray where the status value is bad (5) and sets the value of the Count variable. 8 Since the default value is zero, this line sets the value of the i variable to i + 1. This increments the index to the next child service in the list. 10 Sets the Status variable as the value of the Count variable. Recalculate after restart function Use this function to ensure that the numerical aggregation rule calculates the correct number of objects when the IBM Tivoli Business Service Manager is restarted. For example, you use a numerical aggregation rule that is called HowManyKidsDoIHave to calculate the number of children that a service has. The rule uses a policy function to calculate this value. For example: function NumberOfAllChildren(ChildrenStatusArray, AllChildrenArray, ServiceInstance, Status) { Status = ServiceInstance.NUMCHILDREN; log("number of children for "+ServiceInstance.SERVICEINSTANCENAME+" ("+ServiceInstance.DISPLAYNAME+") is "+Status); } The function works as expected until the IBM Tivoli Business Service Manager server is restarted. When the server restarts, the rule is not recalculated as the children exist already. The HowManyKidsDoIHave rule returns a result of 0. To avoid this issue, add a function to the policy to recalculate the nodes. You can trigger the recalculation at the leaf node level, for example: USE_SHARED_SCOPE; Type="StateModel"; Filter = "RECALCSTATENODESLEAF"; log("recalc Leaf Node Only. Policy Start." ); GetByFilter(Type, Filter, false); log("recalc Leaf Node Only. Policy Finish." ); } Alternatively, you can trigger the policy for all levels, for example: USE_SHARED_SCOPE; Type="StateModel"; Filter = "RECALCSTATENODESALL"; log("recalc All Nodes. Policy Start." ); GetByFilter(Type, Filter, false); log("recalc All Nodes. Policy Finish." ); } Customizing policies 21

30 Numerical formula rule policy Numerical formula rules calculate the service status based on the values of other rules in the service template. The rule shown in Figure 3 determines the service status by adding the output values of three rules: WebSumHigh, NetSumHigh, and DBSumHigh. For more information about numerical formula rules, see the TBSM Service Configuration Guide. Figure 3. Edit Numerical Formula Rule window You specify the Rule Name. You can also specify the rules you want to use to calculate the service status. Note: If a policy or formula rule depends on an additional property (attribute) of the service instance, when the additional property is changed, the rule does not re-evaluate itself. The rule only re-evaluates itself if other rules that it depends on change, or if there is a configuration change to the rule. To use properties of a service instance in a formula use the syntax: float(serviceinstance.propertyname) or int(serviceinstance.propertyname) This table outlines the values that can be retrieved for each rule: Table 8. Information available for each rule Input variable Rulename.value Description The value of the rule. 22 IBM Tivoli Business Service Manager: Customization Guide

31 Table 8. Information available for each rule (continued) Input variable Rulename.NumEvents Rulename.LastStateChange Rulename.LatestEventStatus Rulename.Average Rulename.Sum Description The number of ObjectServer events that affect the rule (Incoming Status Rules). The timestamp, in epoch time, for the last status change of the rule for (Incoming Status Rules) The severity of the most recent event that affected the service (Incoming Status Rules) The average value of the status field of the current matching events (Incoming Status Rules) The sum of the status field of the current matching events (Incoming Status Rules) You can also select the Use Policy checkbox to use an Impact policy, in IPL or JavaScript, to set the status thresholds for the service template. If you choose to use a policy, any expression configured in the formula is ignored. Opening the numerical formula rule policy To open the Policy Editor window, complete the steps outlined in this topic. About this task To open the Policy Editor window, complete the following steps: Procedure 1. Open the Edit Numerical Formula Rules window. 2. Select the Use Policy check box. 3. Click the Edit Policy button. The Policy Language Chooser dialog box open. 4. Click to select the IPL or JavaScript radio button to indicate the language that you want to use to edit the policy. The Policy Editor window opens as shown in Figure 4 on page 24. You are prompted to enter a name for the policy when you save the policy. Customizing policies 23

32 Figure 4. Policy editor for numerical formula rule Creating a custom policy to calculate status of a Numerical Formula Rule You can edit this policy by following the syntax in the comment at the top of the policy. To customize this policy, use the input variables described in Table 9. Table 9. Variables set from the service instance data Input variable InstanceNode.rulename.Value ServiceInstance PeerArray SiblingPeerArray Description Contains the attribute values. It is an object that contain the statuses of the rules of an Instance. The values are accessed using the Value property. The service instance object for the function. This variable passes all the attributes of the service instance to the function. A list of all instance objects that use the same template as that used by ServiceInstance. A list of all instance objects that use the same template and that share a common parent with ServiceInstance. The rule status of each of the peers are accessed using the PeerArray[i].StateModelNode.<Rulename>.Value syntax. Note: When using polices for numerical formula rules, set the Status value to a number. This is the number that corresponds to the new status of the attribute. If you return a string, the server does not process it correctly and status events are not sent to the ObjectServer. If you select the Text Rule checkbox you can set the Status variable to String. Example 1 24 IBM Tivoli Business Service Manager: Customization Guide

33 An example one-line policy to obtain the product of two attributes in a template is: Status = InstanceNode.RawAttribute1.Value * InstanceNode.RawAttribute2.Value; To update peers, add the line: UpdatePeers = "true"; or UpdateSiblingPeers = "true"; This triggers the peers, or sibling peers, to recalculate their status because of the status change of the instance. Example 2 Auto-population rule policies This policy determines the service status based on a numerical value. This sample policy determines the service status by multiplying the values for two numerical rules in the service template. Status = InstanceNode.H_Tickets.Value * InstanceNode.custRegion.Value; This line sets the service Status to the value of the H_Tickets rule multiplied by the value of the custregion rule. For example, if the value of the H_Tickets rule is 5 and the value for the custregion rule is 2, the Status value = 10. The Custom Auto-Population Rule Configuration window gives you access to two policies you can use to set a custom name and other attributes (service properties) for an auto-created service. These policies only affect the auto-population rule you are editing. They do not affect other auto-population rules. Before you begin For more information about auto-population rules, see the TBSM Scenarios and Service Configuration guides. About this task The Custom Additional Property policy retrieves custom attributes for a given service from the data source. These are the attributes you can set on the Additional tab for service templates and services. The Custom Additional Property policy retrieves the name for a given service from the data source. To access these policies, open the Custom Auto-Population Rule Configuration window as follows: Procedure 1. Open the service template you want to change in the Service Viewer and open the Edit Template tab. 2. To create an auto-population rule, click the Create auto-population rule button. To edit an existing auto-population rule, click the rule name. 3. From the Auto-Population Rule window, click the Custom Configuration link. 4. To edit one of the policies, click the check box for Use Policy and select Use Custom Policy. Figure 5 on page 26 shows the Custom Auto-Population Rule Configuration window with the Use Policy For Service Properties and the Use Custom Policy check boxes is selected. See the sections which follow for information about editing these policies. Customizing policies 25

34 Figure 5. Custom Auto-Population Rule Configuration window What to do next For more information about configuring auto-population rules, see Advanced ESDA and auto-population configuration on page 75. Retrieving auto-populated service attributes You can create custom service attributes (properties) for an auto-populated service using the policy. In the TBSM console, you set these attributes in the Additional tab for the service template and the individual service. Opening the policy To open the Policy Editor window, complete the following steps: Procedure 1. From the Custom Auto-Population Rule Configuration window, click the Use Policy For Service Properties check box. 2. Click the Edit Policy button. The Policy Language Chooser dialog box open. 3. Click to select the IPL or JavaScript radio button to indicate the language that you want to use to edit the policy. The Policy Editor window opens, as shown in Figure 6 on page IBM Tivoli Business Service Manager: Customization Guide

35 Custom policy for auto-populated instance attribute properties This policy uses the values in the EventContainer variable to set the field/value pairs in the auto-populated instances. The EventContainer includes all the values from the incoming data that triggered the auto-population rule. Table 10. Variables set by attribute creation policy Variable Attributes Taglist PrimaryTag Figure 6. Policy Editor for auto-population rule Description (Optional) The fields and associated values you want to use to create your additional attributes. (Optional) The list of service templates you want to assign to the auto-populated instances. The list is delimited by the string :::. The template you want to assign as the primary template of the auto-populated service instances. Note: You can assign templates to the service using the custom Auto-Population window as well. However, the policy allows for further customization. Retrieving auto-populated service name If you need to obtain your service names from a second data source (the names are not in the event), you can write a query to a generic policy that retrieves the service name from the specified data source. You can also write your own policy to create service names. These policies affect only the auto-population rule you are editing. They do not affect any other auto-population rules. Retrieving service names with the generic policy When you use the generic policy, you select the data source that contains the service name and enter a query that returns exactly one row for each service. The Customizing policies 27

36 Instance Name Expression and Display Name Expression you set in the main Auto-Population Rule window is evaluated against this row to obtain the service instance name. About this task To use the generic policy, complete the following steps: Procedure 1. From the Custom Auto-Population Rule Configuration window, select the Use policy radio button and then the Use Generic Policy radio button. 2. From the Data source list, choose the service instance name. 3. Type a query that retrieves a single database row that contains the service name. Results You can include values extracted from the event or other data in your query, by using the EventExpression format. Example For example, if you want to include the value of the region and serviceid incoming database fields in your query, your query must include the values region and serviceid as shown in this example: select name from customer where region= region and serviceid= serviceid In this example, the incoming event that triggered the auto-population rule contains information about the customer's geographic region and their service ID, but it does not contain the customer name. This query selects the value of the name field from the row in another table called customer where the values of the region and serviceid fields match the values from incoming event. The region variable is in quotation marks because the value is a string. Retrieving service names with a custom policy You can also create your own policy to retrieve service instance names from the incoming data which triggers the auto-population rule. About this task To open the Policy Editor window, complete the following steps: Procedure 1. From the Custom Auto-Population Rule Configuration window, select the Use Policy radio button and then the Use Custom Policy radio button. 2. Click Edit Policy. The Policy Language Chooser dialog box opens. 3. Click to select the IPL or JavaScript radio button to indicate the language that you want to use to edit the policy. The Policy Editor window opens, as shown in Figure 7 on page IBM Tivoli Business Service Manager: Customization Guide

37 Custom policy to obtain the auto-populated instance name, description, and display name When you edit this policy, you can use any Netcool/Impact expression to obtain the name, description, and display name for an auto-populated service instance. You can use the values in the EventContainer variable to help determine the service name properties. About this task The EventContainer includes all the values from the incoming data that triggered the auto-population rule. For more information on the functions and expressions you can use with TBSM, see Expression language on page 41. Table 11 describes the variables you set for this policy. Table 11. Variables set for service instance naming policy Input variable DynamicInstanceName Figure 7. Policy Editor for Custom Service Names Description Required. The name of the discovered service. This value appears in Service Name field for the discovered service instance. DynamicInstanceDescription DynamicInstanceDisplayName For example, to create the service name from the EventContainer values in the Node and Location fields, type: DynamicInstanceName = EventContainer.Node + EventContainer.Location Optional. The value for the service's Description field. Optional. The the value of the service's Display Name field. Using a policy to assign service templates This topic describes how you can use a policy to assign a service to a template. In this example, an auto-population rule is defined in a service template called: MIS_Status_Default. The policy assigns a primary template to each new service Customizing policies 29

38 ESDA-rule policy instance based on the ResourceCategory value in the source event. In addition to the primary template, the MIS_Status_Default template is assigned by this policy. In this example, the Use Policy For Service Properties policy from the Custom Auto-Population Rule Configuration window is used for the service template assignments. Create service templates and rules before you assign services to the templates with a policy. The policy code uses the Taglist, PrimaryTag, and EventContainer variables to assign service templates based on the value of the event field: ResourceCategory. In the example below, the templates are assigned based on the ResourceCategory field values described in this table. The first two lines of the policy set the default service templates if there is no mapping for a given ResourceCategory value. Table 12. Event container.resourcecategory to service template mapping ResourceCategory Value server application appserver networkdevice Service Templates (TagList) MIS_Server, MIS_Status_Default, MIS_Application, MIS_Status_Default, MIS_Appserver, MIS_Status_Default, MIS_NetworkDevice, MIS_Status_Default, TagList = "MIS_Resource:::MIS_Status_Default"; PrimaryTag = "MIS_Resource"; if (EventContainer.ResourceCategory == server ) { TagList = "MIS_Server:::MIS_Status_Default"; PrimaryTag = "MIS_Server"; } if (EventContainer.ResourceCategory == application ) { TagList = "MIS_Application:::MIS_Status_Default"; PrimaryTag = "MIS_Application"; } if (EventContainer.ResourceCategory == appserver ) { TagList = "MIS_AppServer:::MIS_Status_Default"; PrimaryTag = "MIS_AppServer"; } if (EventContainer.ResourceCategory == networkdevice ) { TagList = "MIS_NetworkDevice:::MIS_Status_Default"; PrimaryTag = "MIS_NetworkDevice"; } Primary Template (PrimaryTag) MIS_Server MIS_Application MIS_Appserver MIS_NetworkDevice You can create custom policies to obtain data which you can use to create ESDA children or parents. You can use this policy to configure the child or parent services created by the ESDA rule and to modify the additional attributes assigned to each discovered service. For more information about creating ESDA rules, see Advanced ESDA and auto-population configuration on page 75 and the TBSM Service Configuration Guide. 30 IBM Tivoli Business Service Manager: Customization Guide

39 Opening the ESDA rule policy To open the policy editor for this policy, complete the following steps: Procedure 1. Open the service template you want to edit in the Service Viewer Edit Template tab. 2. Click the Create ESDA Rule button. 3. From the ESDA Model Rule window, select the data source you want to use for the ESDA rule. 4. Configure the SQL query for the ESDA rule. 5. Under the Advanced section, click the Use Policy check box. 6. To open the Policy Editor, click the Edit Policy button. Figure 8. Policy editor with ESDA policy Customizing the ESDA rule policy An ESDA rule can be configured to run a custom policy to obtain the next level of services. In this policy, you can process the data retrieved by the query in the ESDA Model Rule window. About this task You can use variables to set service instances for the next level of your service model and to configure additional attributes for the ESDA service instances. Table 13 on page 32 describes the input variables for this policy. Customizing policies 31

40 Table 13. ESDA policy input variables Input variable SeedInstance MemberTag ExternalQueryDataType ExternalFilter Description The name of the seed service instance for the ESDA rule. For a child rule, it would be the parent service instance. For a parent rule, it would be a single child service instance. This is a ServiceInstance object. The template to which this ESDA rule belongs. This is a ServiceTemplate object. The external data source configured in the ESDA rule. The value entered for this variable is a String. The query configured in the ESDA rule. The value entered for this variable is a String. Table 14. ESDA Policy Variables Table 14 describes the variable you can set in this policy. Variable NextLevelOrgNodes Description Required. This array of OrgNodes (rows) contains the data returned from the ESDA query. The ESDA engine converts each row (OrgNode) in the array to a service instance and uses the Instance Name expression from the ESDA rule to evaluate each row and determine the service name. All the fields in the row are converted to additional attributes (properties) in the created service instances. The instance expression is configured in the ESDA user interface in the instance expression field. All of the fields of the OrgNode array are converted to additional instance properties. In addition, a number of special properties can be configured for NextLevelOrgNodes are as follows: v _TagList: A list of templates to add to the instance, separated by the ::: delimiter. v _PrimaryTag: Used to set the primary template for the discovered services. v _RemoveTagList: A list of templates that you want to remove from the instance. The list is separated by the ::: delimiter. v EventMatchingFields: An object containing any custom instance identification fields that you wish to add to the instance. v EventMatchingFieldSet: This is a similar function to EventMatchingFields, except that TBSM adds all combinations of the fields as instance identification fields. v DisplayName: Used to set the display name of the instance. It overrides the displayname expression in the ESDA user interface. v Description: Sets the description of the instance. It overrides the description expression in the ESDA user interface. v TimeWindowName: Sets the schedule name of the instance. v SlaName: Sets the SLA name of the instance. Example In this example, the templates Webserver and Host are assigned to the service instance created from the NextLevelOrgNode variable. 32 IBM Tivoli Business Service Manager: Customization Guide

41 NextLevelOrgNodes[i]._TagList = "Webserver:::Host" Example This example shows the default policy that adds a template to all discovered service instances. DataSource = ExternalQueryDataType; Query = ExternalFilter; LookupByDataSourceQuery(DataSource, Query); NextLevelOrgNodes = OrgNodes; i=0; while (NextLevelOrgNodes[i] <> NULL) { NextLevelOrgNodes[i]._TagList = "<SomeTemplateName>"; i = i + 1; } Example This example assigns 2 sets of custom instance identification fields. These fields are applied to the instance for template named Template1 and incoming status rule named Rule1. Rule1 must have AlertGroup and Node configured as its instance matching fields. i = 0; while (NextLevelOrgNodes[i] <> NULL) { NextLevelOrgNode = NextLevelOrgNodes[i]); emf = newobject(); // configure the instance to match an event where AlertGroup = "banking" and Node = "server1" OR where AlertGroup = "onlinebanking" and Node = " " emf.template1 Rule1 1 AlertGroup = "banking"; emf.template1 Rule1 1 Node = "server1"; emf.template1 Rule1 2 AlertGroup ="onlinebanking"; emf.template1 Rule1 2 Node = " "; NextLevelOrgNode.EventMatchingFields = emf; NextLevelOrgNode.SlaName = "Gold"; // set the sla of the instance to be Gold (Gold must be defined in the primary template of the instance) i = i + 1; } The example above is located below the ESDA policy code that sets the NextLevelOrgNodes variable. The following is an example of a complete ESDA policy: DataSource = ExternalQueryDataType; Query = ExternalFilter; LookupByDataSourceQuery(DataSource, Query); NextLevelOrgNodes = OrgNodes; i=0; while (NextLevelOrgNodes[i] <> NULL){ NextLevelOrgNodes[i]._TagList = "<SomeTemplateName>"; i = i + 1; } i = 0; while (NextLevelOrgNodes[i] <> NULL) { NextLevelOrgNode = NextLevelOrgNodes[i]); emf = newobject(); // configure the instance to match an event where AlertGroup = "banking" and Node = "server1" OR where AlertGroup = "onlinebanking" and Node = " " emf.template1 Rule1 1 AlertGroup = "banking"; emf.template1 Rule1 1 Node = "server1"; emf.template1 Rule1 2 AlertGroup ="onlinebanking"; emf.template1 Rule1 2 Node = " "; NextLevelOrgNode.EventMatchingFields = emf; Customizing policies 33

42 NextLevelOrgNode.SlaName = "Gold"; // set the sla of the instance to be Gold (Gold must be defined in the primary template of the instance) i = i + 1; } Using a policy to extract data to display in a chart This topic describes how you can use a policy to extract data to display in a chart. To use a Netcool/Impact policy to extract data for a chart, click to edit the chart and select the Use Policy for Data option on the Chart Policy page. The table below outlines the input variables that can be used when creating a policy to extract data to display in a chart. Table 15. Input variables Header ServiceInstance Header The ServiceInstance object corresponding to the instance clicked. This is null if the chart is displayed without you clicking a service. The table below outlines the returned variables that can be used when creating a policy to extract data to display in a chart. Table 16. Returned variables Header ChartData Header An array of objects. Each object element in the array consists of field value pairs that comprise the data used for the chart. Each object element operates similarly to a row in a database table. Example In this example, the policy creates 2 rows, each with two fields (servicename, and troubletickets). These field names can be used in the chart configuration. For example, the X axis expression might be row["servicename"] and the Y series expression might be row["troubletickets"]: ChartData = {}; Row = newobject(); Row.servicename = "CustomerA"; Row.troubletickets = 7; ChartData = ChartData + Row; Row2 = newobject(); Row2.servicename = "CustomerB"; Row2.troubletickets = 9; ChartData = ChartData + Row2; Note: ChartData can result from a LookupByDataSourceQuery call. In this case, no further processing is required. Configure data fetcher to run a policy This section describes how a data fetcher can use a policy. You must only attempt to use this feature if you know how to write IBM Tivoli Netcool/Impact policies. 34 IBM Tivoli Business Service Manager: Customization Guide

43 Note: As an alternative to using a data fetcher, you can configure a Policy Activator service in Impact to run a policy and then call the PassToTBSM function from that policy. Normally, data fetchers select data from a data source periodically (or at a particular time) using an SQL query. A policy-based data fetcher is like a normal data fetcher, except that it executes a policy to fetch data instead of an SQL query. You cannot use the TBSM console to create a policy-based data fetcher. Instead use the RAD shell command called createpolicydatafetcher(). After you create the policy-based data fetcher with RAD shell, use the TBSM console to stop, start, delete, or view the log for the data fetcher. Create the policy-based data fetcher Before you create a policy-based data fetcher, create a policy that returns data and specify the policy when you create the data fetcher. To create a policy-based data fetcher with RAD shell, run the command createpolicydatafetcher using the following syntax: /tbsm/bin/rad_radshell Under radshell env: radshell> createpolicydatafetcher("datafetchername", minpollinginterval, maxpolling Interval, pollingmultiplier, pollinghour, pollingmin, "policy name", "columnname#datatype;columnname#datatype", false, "policyscript"); radshell> exit Table 17. createpolicydatafetcher function parameters Parameter Format Description DataFetcherName String The name of the data fetcher you want to create. minpollinginterval maxpollinginterval Long Integer Long Integer The minimum interval between data fetches in milliseconds. If you want to run the fetch at a specific time each day, enter a value of -1 to disable this parameter. The maximum interval between data fetches in milliseconds. If you want to run the fetch at a specific time each day, enter a value of -1 to disable this parameter. pollingmultiplier Integer The polling multiplier for the polling interval. If you want to run the fetch at a specific time each day, enter the default value of 5. pollinghour Integer If you want to run the data fetcher once a day, enter the hour you want to run the query. The hour must be in 24 hour format. Otherwise, enter 0. pollingmin Integer If you want to run the data fetcher once a day, enter the minute you want to run the query. Otherwise, enter 0. policy name String The name of the policy to execute. Customizing policies 35

44 Table 17. createpolicydatafetcher function parameters (continued) Parameter Format Description columnnames#datatype String The names of the columns in the rows that are returned by the policy and the data type of each column. The valid values for data types are: Integer and String. Separate each columnname#datatype pair with a semi-colon (;). Disable true,false Boolean For a policy-based data fetcher, you need to enter false for this parameter. policyscript String The text of the policy that you want to import condensed as a single string. New lines are substituted with the text ENDLINE. Note: Quotes used in the policy text must be escaped with a backslash. This example creates a data fetcher named TestPolicyFetcher that uses the policy named Test_DataPolicyFetcher. The first column returned is called Column1 and is an Integer data type. The second column returned is called Column2 and is a string data type. createpolicydatafetcher(testpolicyfetcher", 30000, , 5, 0, 0, "Test_DataPolicyFetcher","Column1#Integer;Column2#String", false, " * This policy is invoked by DataFetcher as specified in the DataFetcher ENDLINE * properties files. ENDLINE ENDLINE ENDLINE The context variables that the policy must return are in the data fetcher ENDLINE are in the * corresponding DataFetcher properties file. In this example policy ENDLINE file you can see that there are two Context variables, Column1 and ENDLINE Column2. ENDLINE ENDLINE The rows (Array of xrecords) that are to be returned back by the policy ENDLINE back ENDLINE to the DataFetcher is in the variable called FetchedRecords. ENDLINE ENDLINE The policy must always return an array called FetchedRecords. Each object ENDLINE in the array must contain the variables that are defined in the ENDLINE columnnames of the data fetcher that is executing this policy. ENDLINE ENDLINE log("in the policy. Printing the last record from previous fetch"); ENDLINE Record1 = NewObject(); ENDLINE Record1.Column1 = 25; ENDLINE Record1.Column2 = "value2"; ENDLINE FetchedRecords = { Record1 }; ENDLINE log("column1 = " + Column1); ENDLINE log("column2 = " + Column2); ENDLINE "); Before you create this data fetcher, create a policy called Test_DataPolicyFetcher. This policy is called periodically by the data fetcher. You can create an incoming status rule that uses the TestDataFetcher data fetcher as its event feed. You see Column1 and Column2 as the fields available in the status rule, because these are the names of the fields specified in the RAD shell call to create the data fetcher. The policy must set the fields Column1 and Column2 in at least one record that it returns, since those are the field names that the data fetcher is expecting. 36 IBM Tivoli Business Service Manager: Customization Guide

45 Data fetchers for Tivoli Monitoring These topics describe how to configure a policy-based data fetcher that uses the IBM Tivoli Monitoring charts web service to query data. Overview Creating the data fetcher You can access Tivoli Monitoring data collected by its agents with a data fetcher that uses a Netcool/Impact policy. The data fetcher uses the Tivoli Integrated Portal Web Service available in ITM fix pack 8 and later. The policy script enables a connection to the Web Service and process the data query. You assign this policy to a policy-based data fetcher in TBSM. You can use the data retrieved by the data fetchers in TBSM incoming-status rules. In this way, you can access the agent data directly within TBSM as you would any other SQL-based data. This topic describes how to create a policy-based data fetcher that accesses data from Tivoli Monitoring. Before you begin Verify that the Tivoli Integrated Portal Web Service for Tivoli Integrated Portal charts has been deployed on your IBM Tivoli Monitoring Tivoli Enterprise Portal server. For more information, see the IBM Tivoli Monitoring Administrator's Guide. Note: The Tivoli Integrated Portal Web Service is available in ITM FP2 and later. It is strongly recommended that you use ITM FP6 or ITM for the Tivoli Integrated Portal Web Service. About this task This procedure outlines the steps you must follow to create the data fetcher. Procedure 1. From the Tivoli Integrated Portal task list, select Administration > Service Configuration. 2. From the Service Navigation drop-down list, select Data Fetcher. 3. On the Data Fetcher toolbar click the Create New Data Fetcher button. 4. Enter a data fetcher name and select ITM Policy from the Type drop-down list. 5. Specify the schedule settings you want or accept the defaults. 6. Enter values for the following which let you the test the web service connection. You are required to enter values only where the defaults are not correct for your system configuration. Service Name The name assigned to the Charting Web Service when it was installed and configured. Typically the value is TIPWebServiceHttpRouter. Copyright IBM Corp. 2008,

46 Protocol The communication protocol used to communicate with the Charting Web Service. If you need an HTTPS connection, then you need to update the truststores on both the TBSM Data server and TBSM Dashboard server. Otherwise, select HTTP. Host name The host name of the server where the Charting Service is running. Typically, this is the ITM TEPS server. This value is pre-filled with the Dashboard server short host name. Note: Do not use the value localhost as it can create an unreliable connection. Port Number The port number that the Charting Web Service is listening on. Typically this is for HTTP and for HTTPS User ID The user ID to used to connect to the IBM Tivoli Monitoring Charting Web Service. Typically this is sysadmin. Password The password for the user ID. 7. Click Test ITM Connection. If the connection was successful the Agent Id drop-down list is filled with a list of Agents and their IDs that are currently installed and running on your Tivoli Enterprise Portal Server. 8. From the Agent Id drop-down list, select the agent you want to use for your query. After a value is selected, the Query Id drop-down list is populated with queries for the selected Agent ID value. 9. Select the query you want to use from the Query ID. When the query completes the Meta Data and Query Data, grids is populated with meta information and data from the selected query. Select the appropriate tab to view the metadata or the query data. If there was no data for the selected query, the grid on the Query Data tab contains one row indicating so. 10. Click Edit Policy. This displays a popup window with a default policy already created. The variables are configured with the settings you defined for the data fetcher. CAUTION: Only change the policy if you are familiar with policies and the policy editor. 11. Save the policy by clicking Save on the policy editor toolbar. Important: You must save the policy using the policy editor in order to save the data fetcher. 12. Click Save on the Data Fetcher toolbar. The data fetcher appears in the Data Fetcher list of the Service Navigation panel. 38 IBM Tivoli Business Service Manager: Customization Guide

47 Results You can use the data fetcher wherever data fetcher data is available in TBSM. For example, you can select the data fetcher from the Data Feed drop-down list in the Edit Incoming Status Rule window. Important: Some actions for data fetchers such as clicking Preview data... in this window do not currently work for policy-based data fetchers. When you select the data fetcher, the columns from the Tivoli Monitoring query can be used in the Instance Name selection and the Filter selection lists. Configuring secure connections for data fetcher This topic describes the steps need to set up secure HTTPS connections for TBSM data fetchers. To configure HTTPS support for the TIP Web Service for Tivoli Integrated Portal charts, the trust keystores of the TBSM Data and Dashboard servers must be updated with each other's signer certificates. To configure HTTPS for the TBSM Data server use the wsadmin command To configure HTTPS for the TBSM Dashboard server the use the Tivoli Integrated Portal user interface. For more information about configuring secure connections, see the TBSM Administration Guide. Data fetchers for Tivoli Monitoring 39

48 40 IBM Tivoli Business Service Manager: Customization Guide

49 Expression language This section contains information about the expression language used in TBSM. About the expression language You use expressions in TBSM when you want to dynamically determine a value based on incoming data, or on other values that change over time. The TBSM expression language provides the means for specifying how this value is determined through the use of literal values, field names, operators, and functions. Typically, you specify expressions in TBSM when you configure a part of the system where TBSM takes a value from one source and then manipulates it according to certain terms. For example, when you create an incoming status rule, you use an expression to specify how TBSM determines the service instance affected by the outcome of the rule. You can also use an expression to specify how TBSM determines the general state of the service or the output value associated with the rule. For a more information about expressions and the policy language, see the IBM Tivoli Netcool/Impact Policy Reference Guide. You use the expression language when you perform the following tasks in TBSM: v Create incoming status rules v Create aggregation and numerical formula rules and policies v Create auto-population rules and policies v Create ESDA model rules and policies The TBSM expression language provides an abbreviated set of functionality that allows you to manipulate data in a basic way. Some features of TBSM also allow you to create custom policies that you can use to accomplish more complicated tasks. You write custom policies in TBSM using the Netcool/Impact policy language, which is a full-featured programming language with many built-in features that help you manage responses to incoming Netcool/OMNIbus events and other data. You can create custom policies when you perform the following tasks in TBSM: v Create numerical aggregation rules v Create numerical formula rules v Create auto-population rules v Create ESDA model rules For more information about the custom policies, see Customizing policies on page 11. Expression language fundamentals This section contains information about the fundamentals of the expression language used in TBSM. Copyright IBM Corp. 2008,

50 Basic expression syntax An expression is a combination of literals, variables, field names, operators, and functions that TBSM processes to determine a value. You can use expressions in TBSM in many instances where you want the application to dynamically determine a value based on incoming data from external data sources or on other values that change over time. The following expressions are examples of valid syntax: New York City True Summary + AlertKey + TBSMValue FormatDuration(LastOccurrence) Expressions and literal values The TBSM expression syntax supports the use of literal values for integers, floats, strings, and Boolean values. You must enclose string literals in double or single quotation marks. You designate Boolean values using the keywords True and False. The following expressions are examples of literal values that can be used in TBSM: "New York City" London True Expressions and field names TBSM lets you specify field names associated with incoming ObjectServer events or other data sets as part of an expression. The available fields depend on the context of where you are using the expression. For example, when you create a numerical incoming status rule, you can specify ObjectServer field names as elements of the expression that produces the rule-output value. In the following example, Severity and TBSMIncoming are fields in the alerts.status table in the ObjectServer database: Severity Severity + Int(TBSMIncoming) When you create custom policies, you must use the syntax specified by Netcool/Impact for accessing fields in incoming ObjectServer events or other data sets. Expressions and operators When you create custom policies, you can use the extended set of assignment, comparison, and Boolean operators supported by the expression language. The expression syntax supports the following types of operators: v Mathematical operators v String operators 42 IBM Tivoli Business Service Manager: Customization Guide

51 Mathematical operators The IPL supports the following mathematical operators: Table 18. Mathematical operators Operator Description + Addition - Subtraction * Multiplication / Division % Modulus Parser functions The following examples show the use of the mathematical operators. a = 1 + 2; b = 4-3; c = 6 * 4; d = 6 / 4; e = 8 % 5; String operators The expression language supports the use of the addition operator (+) for concatenating strings. The following examples show how to concatenate strings: "New York" + " City" "TBSM: " + Summary Expression parser functions The TBSM expression syntax has a set of built-in parser functions that you can use to perform many operations on numeric values, strings, and dates. When you write custom policies, you have access to the extended set of action and parser functions supported by the Netcool/Impact policy language. For information about specific parser functions, see Parser functions. The TBSM expression syntax has the number of built-in parser functions. A subset of these functions are listed here. Note: For a full list of functions, see the Netcool/Impact Policy Reference Guide. v CurrentContext v Eval v Extract v Float v FormatDuration v GetDate v Int v LocalTime v Log Expression language 43

52 v Replace v RExtract v Strip v Substring v ToLower v ToUpper v Trim CurrentContext The CurrentContext function returns the current expression language context. The context consists of all the currently defined variables in the context. Syntax CurrentContext() Example This example shows how to return the current policy context in the $TBSM_HOME/av/xmlconfig/entityTemplates.xml file. <entitytemplateattrfieldvaluetransformationexpr> eval( Color,exec( AV_GetColorForSeverity,currentcontext())) </entitytemplateattrfieldvaluetransformationexpr> In this example, the currentcontext function returns the member variables of the context of the AV_GetColorForSeverity policy. In this case, the expression retrieves the value for the Color variable from the policy. Eval The Eval function evaluates an expression using the given context. Syntax Integer Float String Boolean= Eval(Expression, Context) Parameters This function has the following parameters. Table 19. Eval function parameters Parameter Format Description Expression String Expression to evaluate. Context Context Context to use in evaluating the expression. Note: In JavaScript, the Float variable returns extra precision, for example, instead of In IPL, integer division of 10/5 is 2.0. In JavaScript, integer division of 10/5 is 2. Return Value Result of the evaluated expression. 44 IBM Tivoli Business Service Manager: Customization Guide

53 Example The following example shows how to evaluate an expression using the given context. The example shows how the Eval expression is used in the $TBSM_HOME/av/ xmlconfig/entitytemplates.xml file. <entitytemplateattrfieldvaluetransformationexpr> Eval( Color,exec( AV_GetColorForSeverity,currentcontext())) </entitytemplateattrfieldvaluetransformationexpr> In this example, the Eval function evaluates the expression that retrieves the value for the Color variable from the policy. In this case, the expression retrieves the severity-level color from the AV_GetColorForSeverity policy. Extract The Extract function extracts a word from a string. Syntax String= Extract(Expression, Index, [Delimiter]) Parameters This function has the following parameters. Table 20. Extract function parameters Parameter Format Description Expression String String expression from which to extract substrings. Index Integer Word position of the substring. Delimiter array Array of characters that separate words in the string. Default is an array with the space character as the single element. Return value The extracted substring. Example The following example shows how to extract the second word from the Summary field value. In this example, the value of the Summary field is: Node NYdata1 is not responding. Extract(Summary, 2) The example extracts the word NYdata1 from the Summary field. Float The Float function converts an integer, string, or Boolean expression to a floating point number. Expression language 45

54 Syntax The Float function has the following syntax: Float = Float(Expression) Parameters The Float function has the following parameter. Table 21. Float function parameters Parameter Format Description Expression Integer String Boolean Expression to be converted. Return value The converted floating point number. Example The following example shows how to convert integers, strings, and Boolean expressions to float point numbers using IPL. MyFloat = Float(25); Log(MyFloat); MyFloat = Float("25.12"); Log(MyFloat); MyFloat = Float(true); Log(MyFloat); This example prints the following message to the policy log: Parser Log: 25.0 Parser Log: Parser Log: 1.0 The following example shows how to convert integers, strings, and Boolean expressions to float point numbers using JavaScript. MyFloat = Float(25); Log(MyFloat); MyFloat = Float("25.12"); Log(MyFloat); MyFloat = Float(true); Log(MyFloat); JavaScript does not add any decimal points to the results for integers and Boolean expressions that are used with the Float function. This example prints the following message to the policy log: Parser Log: 25 Parser Log: Parser Log: 1 46 IBM Tivoli Business Service Manager: Customization Guide

55 FormatDuration The FormatDuration function converts a duration in seconds into a formatted date/time string. Syntax String= FormatDuration(Seconds) Parameters This function has the following parameter. Table 22. FormatDuration function parameters Parameter Format Description Seconds Integer Number of seconds. Return Value Formatted date/time string. Example The following example shows how to convert the seconds from the GetDate function into formatted date/time strings. FormatDuration(GetDate() - int(value)) GetDate The GetDate function returns the date/time as the number of seconds expired since the start of the UNIX epoch. Syntax Integer= GetDate() Return Value Number of seconds since the start of the UNIX epoch. Example The following example shows how to use the GetDate function with the formatduration function to get formatted date/time strings in a custom canvas XML file. <entitytemplateattrfieldvaluetransformationexpr> formatduration(getdate() - int(value)) </entitytemplateattrfieldvaluetransformationexpr> Int The Int function converts a float, string, or Boolean expression to an integer. This function truncates any decimal fraction value associated with the number. For example, the value of Int( ) is Expression language 47

56 Syntax The Int function has the following syntax: Integer = Int(Expression) Parameters The Int function has the following parameter. Table 23. Int function parameters Parameter Format Description Expression Float String Boolean Expression to be converted. Return value The converted integer number. Important: A float value converted to an int value is truncated not rounded. Example The following example shows how to convert float, string, and boolean expressions to an integer. MyInt = Int(123.45); Log(MyInt); MyInt = Int(123.54); Log(MyInt); MyInt = Int("456"); Log(MyInt); MyInt = Int(false); Log(MyInt); This example prints the following message to the policy log: Parser Log: 123 Parser Log: 123 Parser Log: 456 Parser Log: 0 LocalTime The LocalTime function returns the number of seconds since the beginning of the UNIX epoch as a formatted date/time string. Syntax String= LocalTime(Seconds, Pattern) Parameters This function has the following parameters. Table 24. LocalTime function parameters Parameter Format Description Seconds Integer Number of seconds. 48 IBM Tivoli Business Service Manager: Customization Guide

57 Table 24. LocalTime function parameters (continued) Parameter Format Description Pattern String Date/time pattern. Optional. If not specified, the default date/time pattern is used. Return Value A formatted date/time string. Example The following example shows how to include the local time in the title of a chart. title = "Number of Tickets from LocalTime(getdate()) " Log The Log function prints a message to the policy log. To print a message to the policy log, you call this function and pass the expression you want to print and, optionally, a log level. The log level specifies the level of severity for the message, with 1 being the lowest and 3 being highest. The policy logger service configuration specifies the level of severity that the message must meet to be printed in the log. For example, if you configure the policy logger with a severity level of 2, only messages with a log level of 2 or less are printed. Messages with a log level of 0 are always logged. Syntax The Log function has the following syntax: Log([LogLevel], Expression) Parameters The Log function has the following parameters. Table 25. Log function parameters Parameter Format Description LogLevel Integer An Integer between 0 and 3 that specifies the level of severity for the message. Default is 0. Optional. Expression Integer Float String Boolean Message to print to the log. Examples in IPL The following example shows how to print a message to the policy log in IPL. Log("This is a test."); This example prints the following message to the policy log: Parser Log: This is a test. Expression language 49

58 The following example shows how to print a message to the policy log with a severity level of 2 in IPL. Log(2, "This is another test."); This example prints the message to the policy log only if the policy logger service is configured with a log level of 2 or greater. Examples in IPL and JavaScript This is the format of a logged string in IPL: log("start with a string(ipl):"+mycontext); Start with a string(ipl): This example prints the following message to the policy log: "Created by parser"=(serial=policyadded_01, Identifier= ) This is the format of a logged string in JavaScript: Log("Start with a string:"+mycontext); Start with a string: This example prints the following message to the policy log: {Identifier: , Serial:"POLICYADDED_01"} Replace The Replace function replaces a substring of a given string. Syntax String= Replace(Expression, Pattern, Substitution, MaxNum) Parameters This function has the following parameters. Table 26. Replace function parameters Parameter Format Description Expression String String that contains the substring to be replaced. Pattern String Substring pattern to be replaced. Substitution String String to substitute for the substring. MaxNum Integer Maximum number of replacements to perform. Return Value The resulting string. Example The following example shows how to replace the value of New York in the Node field with the value US: Replace(Node, "New York","US"); Log(MyReplace); The following example replaces a blank value with 100 in a custom canvas: 50 IBM Tivoli Business Service Manager: Customization Guide

59 <fieldtopasstomodelexpr modelfield = "durationslastatusmax") Replace(BadDurationThresholdSecs, ""+NULL, "100") RExtract The RExtract function uses regular expressions to extract a substring from a string. This function supports Perl 5 regular expressions. Syntax String= RExtract(Expression, Pattern) Parameters This function has the following parameters. Table 27. RExtract function parameters Parameter Format Description Expression String String that contains the substring to extract. Pattern String Regular expression pattern that specifies the substring to extract. Return value The extracted string. Example The following example extracts the host name from the Summary field, where the summary value is: A problem on hostname has crashed the server. RExtract(Summary, A problem on (\S+) has.* Strip The Strip function strips all instances of the given substring from a string. Syntax String= Strip(Expression, Substring) Parameters This function has the following parameters. Table 28. Strip function parameters Parameter Format Description Expression String String to strip. Substring String Substring to strip from the string. Return Value The string with the substring stripped out. Expression language 51

60 Example The following example shows how to strip the & character from the value of the Node field in a service name expression: Strip (Node, & ) Substring The Substring function returns a substring from a given string using index positions. Index positions start at 0. Syntax String= Substring(Expression, Start, End) Parameters This function has the following parameters. Table 29. Substring function parameters Parameter Format Description Expression String String to search for the substring. Start Integer Starting character position of the substring. End Integer Ending character position of the substring, plus one. Return value The substring returned by index positions. Example The following example shows how to truncate the text for a display name to 20 characters. The example truncates the field value so that character positions 0 through 19 make up the display name. Substring(displayname,0,20) ToLower The ToLower function converts a string to lowercase characters. Syntax String= ToLower(Expression) Parameters This function has the following parameters. Table 30. ToLower function parameters Parameter Format Description Expression String String to convert to lowercase. 52 IBM Tivoli Business Service Manager: Customization Guide

61 Return Value The lowercase string. Example The following example shows how to convert the value of the Node field to lowercase. ToLower(Node); ToUpper The ToUpper function converts a string to uppercase characters. Syntax String= ToUpper(Expression) Parameters This function has the following parameters. Table 31. ToUpper function parameters Parameter Format Description Expression String String to convert to uppercase. Return Value The uppercase string. Example The following example shows how to convert the value of the Node field to uppercase: ToUpper(Node); Trim The Trim function trims leading and trailing white space from a string. Syntax String= Trim(Expression) Parameters This function has the following parameters. Table 32. Trim function parameters Parameter Format Description Expression String String that you want to trim. Return Value The string with white space trimmed off. Expression language 53

62 Example The following example shows how to trim trailing white space from the value of the Node field: Trim(Node) 54 IBM Tivoli Business Service Manager: Customization Guide

63 Custom settings This section describes ways you can customize your IBM Tivoli Business Service Manager (TBSM) system by modifying property and configuration files. Adding values to the conversions table If you need to add field values to the Netcool/OMNIbus ObjectServer conversions table, you must use the $OMNIHOME/bin/nco_sql command. You might want to add conversions for the Event Discriminator field and the Output Severity Threshold fields for incoming-status rules. This example shows how to add the Manager field values to the conversions table: v Pinger v TrapReceiver In the event list, conversions translate integer values into strings for readability. Conversions are associated with columns in the ObjectServer alerts.status table. For more information about the conversions, see the Netcool/OMNIbus Administration Guide. UNIX example On UNIX systems: $OMNIHOME/bin/nco_sql -server NCOMS -user root -password INSERT INTO conversions (KeyField,Colname,Value,Conversion) values ( Manager0, Manager,0, Pinger ); INSERT INTO conversions (KeyField,Colname,Value,Conversion) values ( Manager1, Manager,1, TrapReceiver ); Windows example On Windows systems: Adding custom display icons %OMNIHOME%\bin\redist\isql.exe -S NCOMS -U root -P INSERT INTO conversions (KeyField,Colname,Value,Conversion) values ( Manager0, Manager,0, Pinger ); INSERT INTO conversions (KeyField,Colname,Value,Conversion) values ( Manager1, Manager,1, TrapReceiver ); You can add custom-display icons for your TBSM service templates. You can then select one of these icons for a given service template when you click the Browse button in the Edit Template tab. To use an image as a service-display icon in a TBSM and/or the IBM Dashboard Application Services Hub (DASH), you will need multiple versions of your graphic based on where the image will be displayed: v one in standard Graphics Interchange Format (GIF) format v one in Scalable Vector Graphic (SVG) format v one in Small Web Format (SWF) format. Copyright IBM Corp. 2008,

64 Name and copy these files to your TBSM dashboard server host as described in Table 33. Table 33. Custom display icon file types File type Display target Name syntax Directory SVG TBSM myfilename.svg $TIP_HOME/profiles/TIPProfile/ installedapps/tipcell/isc.ear/ sla.war/icons/svg GIF TBSM, IBM DASH myfilename_svg.gif The myfilename value must match the myfilename value for the corresponding svg file. $TIP_HOME/profiles/TIPProfile/ installedapps/tipcell/isc.ear/ sla.war/icons SWF IBM DASH myfilename.swf $TIP_HOME/profiles/TIPProfile/ installedapps/tipcell/isc.ear/ sla.war/icons/swf Custom event fields for updating services By default, TBSM only processes an ObjectServer event when the value of the Severity field changes. In these cases, TBSM processes the de-duplicated events and updates the service status accordingly. However, you might want to base the status of a given service based on the value of a field other than Severity. In TBSM this restriction might often become problematic when dealing with numeric incoming status rules which do not depend at all on Severity. These rules do not get updated when the field they are monitoring changes if the Severity does not change. This section describes how you can customize the ObjectServer and TBSM to change the status of services based on numerical incoming status rules that use fields other than the Severity field. The solution you choose for this problem depends on your configuration. Special ObjectServer fields and TBSM Settings One solution is to use custom event fields to update your services by creating special ObjectServer fields to store values and configuring TBSM to process events when the stored value changes. About this task Complete the following steps: Procedure 1. Add special fields to the ObjectServer that store the last values of the fields you want to use to update the service status. For more information about adding fields to the ObjectServer, see the Netcool/OMNIbus Administration Guide. 2. Change the TBSM event broker restriction filter to allow events where the value of the field in the event does not equal the stored value of the special field. 3. Modify the TBSM main policy (TBSM_Main.ipl) to update the last field value when it processes the event. This configuration is the same as the setting that maps the Severity field to RAD_RawInputLastValue. 4. Stop and start the TBSM server. 56 IBM Tivoli Business Service Manager: Customization Guide

65 Results This example sets up the system to reprocess events whenever the value of the Grade field changes, even if the Severity value does not change. 1. Add an Integer field to the ObjectServer (called RAD_PrevGrade). 2. Modify the event broker filter to be the following (assuming that it has not already been modified for some reason). The event broker restriction filter is set by the property impact.eventbroker.objectserver.restriction.1 in the $TBSM_HOME/etc/TBSM_tbsmomnibuseventreader.props file. (Class <> 12000) AND (Type <> 2) AND (RAD_IsIntermediateFunction \= 0) and (RAD_ServiceName <> NONE ) and ((Severity <> RAD_RawInputLastValue) or (RAD_FunctionType = ) or Grade <> RAD_PrevGrade)) 3. And add the following line in $TBSM_HOME/policy/TBSM_Main.ipl.: Right after the line: RADEventProcessor(EventContainer), add: EventContainer.RAD_PrevGrade = EventContainer.Grade This makes TBSM update the PrevGrade field with the current value of Grade field. If the Grade changes on de-duplication, the event broker filter processes the event. The two ObjectServer fields allow TBSM to compare the changing values: Grade This field stores the changing values and is one of the default fields in Netcool/OMNIbus. RAD_PrevGrade TBSM stores the previous value in this field and compares it to the Grade value in a new event. When TBSM detects a change, the service status is updated accordingly. Netcool/OMNIbus version 7+ For installations using Netcool/OMNIbus version 7 or higher, another solution is to configure a special trigger in Netcool/OMNIbus. This trigger changes the value of RAD_RawInputLastValue when the value of the specified fields change. For more information about setting up triggers, see the Netcool/OMNIbus Administration Guide. Example This example sets up the system to reprocess events whenever the value of the Grade field changes, even if the Severity value does not change. If the incoming status rule uses the value of Grade field to change the status of services, you could configure RAD_RawInputLastValue to 6 whenever the Grade changes. Since RAD_RawInputLastValue does not equal the Severity value, TBSM processes the event. TBSM then resets RAD_RawInputLastValue to the value of the Severity of the event. Including child services with no data By default, when TBSM calculates the output value for a numerical aggregation rule, it only uses child services that have rules that have been affected by an event or data fetcher. If you want to configure TBSM to include data for services that have never received data from an incoming status rule, you must add the Custom settings 57

66 impact.sla.includeeventlessattributes=true property to the $TBSM_HOME/TBSM_sla.props file. You must restart the Data server to ensure that the change takes effect. This can affect average, maximum, and minimum functions. For example, consider taking the average of 10 children where five children have received events and five have not. It makes a difference whether the five children without an event are included in the average as 0 values or omitted from the average calculation. Customizing TBSM status events Table 34. Status event variables Variable name Severity RAD_ServiceName RAD_ServiceID RAD_ServiceTypeName RAD_ServiceTypeID RAD_SLAName RAD_UserFunctionName Summary Event ServiceInstanceBean Value Identifier It is possible to customize status events that IBM Tivoli Business Service Manager sends to the ObjectServer by editing the ServiceEventUpdater policy. Set the ObjectServer fields by setting additional variables in ObjectToCopy. The additional variables must be inserted after the line in the policy that states ObjectToCopy.FirstOccurrence = getdate();. For example, if you want to set the AlertGroup field in the ObjectServer to be "hello", you add the line: ObjectToCopy.AlertGroup = "hello"; The syntax used is Netcool/Impact syntax. This table lists the status event variables you can change. Content 0, 3, or 5 depending on service status. Name of the affected service. The service ID. Class Set to Grade RAD_FunctionName RAD_CurrentRawMetric TimeStamp Location Name of the template assigned to the affected service. The ID of the template of the service. The name of the service level agreement (SLA) for the service. The attribute being affected. The text for the Summary field. The object representing the incoming event. Fields of the event can be obtained with the syntax Event.<FieldName>. For example, CONTEXT.Event.StateChange gives the state change of the raw event. An object representation of the service affected. Properties (attributes) of the service (as they appear in the Additional tab in the Service Editor) are obtained using the syntax ServiceInstanceBean.<propertyName>. The value of the attribute being updated. The identifier for the status event. Set to different numbers depending on the type of rule being reported on. This is used for ordering in the status rules tab. The ID of the rule as stored in the TBSM database. Same as Value (the value of the attribute). The current time. The location of the resource. 58 IBM Tivoli Business Service Manager: Customization Guide

67 Table 34. Status event variables (continued) Variable name AlertGroup Content High-level category for an alert. If the affected service has the property (in the Additional tab) named City, and you want to assign the value of this property to the Location field in the ObjectServer, add the line: ObjectToCopy.Location = CONTEXT.ServiceInstanceBean.City; Sending percentage and worst case rule status events to the ObjectServer By default the ObjectServer does not include the events that TBSM generates for percentage-based threshold changes. If you have created percentage-based threshold rules, you must amend the Impact policy in the Impact interface to ensure that these events are sent to the Netcool/OMNIbus ObjectServer. To ensure that TBSM status events are sent to the ObjectServer: 1. In the navigation tree, expand System Configuration Event Automation Policies. 2. In the Policies tab, select TBSM_BASE from the Project list. 3. Click to open the ServiceEventUpdater in the policy list. 4. Remove the comment notation from the following lines of the ServiceEventUpdater policy: // Uncomment next 3 lines to send percentage and worst case rule status events // elseif (EventType = 6) { // AddDataItem(Type,ObjectToCopy); // } 5. Save the policy. Disabling status events This topic describes how to disable the status events sent by TBSM. About this task When the value of a rule or key performance indicator changes, TBSM sends a status (Class 12000) event for every service instance and rule combination. These events show up as purple status events and can be seen from the Rules tab in Service Details portlet. For the good, marginal and bad incoming status rules, the status events show up as green, red, or yellow. To suppress the status events sent by TBSM: Procedure 1. In the navigation tree, click System Configuration > Event Automation > Policies. 2. In the Policies tab, select TBSM_BASE from the Project list. 3. Click to open ServiceEventUpdater in the policy list. 4. You can disable all status events or purple events: Custom settings 59

68 Option To disable all status events: To disable only purple events: Description Comment out all lines of the policy Comment out the lines in the policy that follow the comment that reads: Comment next 3 uncommented lines to avoid sending purple numeric rule status events These lines read: if (ObjectToCopy.Severity = 1) { AddDataItem(Type, ObjectToCopy); } Note: Please also ensure that you follow the additional guidance provided in the policy comments. 5. Save and close the file. 6. If all status events are disabled, consistency checker status events checking can be disabled also for better performance. Note: Disabling the consistency checker is required to ensure that consistency checker does not send events out when it detects that the events are missing. This is only required, if you have disabled the overall instance status events. a. Edit the RAD_consistency.props file in the $TBSM_DATA_SERVER_HOME/etc/ rad/ directory. b. Add property impact.consistency.depsonly=true in the RAD_consistency.props. c. Save and close the file. Note: Consistency checker uses same RAD_ServiceEventUpdater.ipl policy to insert status events, customization of the policy will impact consistency checker behavior for status event checking. 7. Restart the TBSM Data server. Note: When you disable the status events, Rules tab in the Service Details portlet shows no events. The Events and SLA tabs in continue to function normally. Configuring the SLA tracker period This topic describes how you can change the service level agreement (SLA) trackers update period. This is how often SLA rules send updates to IBM Tivoli Netcool/OMNIbus. Editing header.xml file One of the causes for reduced scalability for SLA tracking is the over abundance of updates the SLA trackers make to the ObjectServer. When the number of active trackers grows into the hundreds, this can put a severe strain on the server. The way to adjust this period is to edit $TBSM_HOME/xml/header.xml. In the entry below, the periodic update time is configured to 15 seconds. This is the default. In a server with many SLA trackers, it is recommended to change this to 600 or 3600 (one update every 10 minutes or an hour) depending on how quickly you 60 IBM Tivoli Business Service Manager: Customization Guide

69 need the status events updated in the ObjectServer. You need to make the same change in cumultimesla.xml in that directory too, and restart the IBM Tivoli Business Service Manager Data server for the change to take effect. <startperiodicaction name = "StartUpdatingRuleStatusQuickly" periodicactionname = "FireSLAUpdateServiceEvent" periodseconds = "15"/> The subsequent entry in the header.xml file contains the update period for SLA time trackers feeding into other attributes that depend on SLA trackers. Even if you do not have attributes depending on SLAs, you must throttle down the period (from the default of 20 seconds) since it can also affect server performance. If you do not use attributes that depend on SLAs, then set it to a high number (for example, 10000). <startperiodicaction name="startupdatingstatemodelquickly" periodicactionname="fireupdatestatemodel" periodseconds="20"/> If you use the feature, you could set it for 10 minutes (600) or the maximum acceptable granularity which you can tolerate in your SLA-dependent attributes. As with the first case, you need to change this in header.xml and cumultimesla.xml and restart the TBSM Data server. Pruning the SLA tracking data tables As SLA tracking data accumulates over time, the tables in the TBSM database that store this tracking data grow. This growth can lead to dramatically reduced performance in event processing, model configuration changes, and SLA tracking. Below are some guidelines for maintaining the SLA tracking data at a reasonable size: There are essentially seven tables used to store SLA tracking data. Duration tracking has two tables: v durationcountwatchers v tasksofdurationcountwatchers Incident Tracking has two tables: v incidentcountwatchers v tasksofincidentcountwatchers Cumulative (over time) duration tracking has two tables: v cumuldurationrulestate v cumulrulearchive The radeventstore table stores event references for SLA trackers. These tables are used to resynchronize SLA status when the TBSM Data server is stopped and restarted. In addition, the tables for the cumulative trackers are used for the historical SLA charts. The best strategy for preventing these tables from getting too large is to periodically delete from them all entries older than a specified time stamp. The smaller the time-window of entries left in the database, the less likely you run into associated performance issues. However it is means that SLA charts is only able to go back that far in history. Custom settings 61

70 With Fix Pack 4, TBSM now has an automated service to delete older entries from the SLA tables. This service is disabled by default. To enable it, please follow the steps below: 1. Go to System Configuration > Event Automation > Services 2. Click on the service SLAPrunePolicyActivator. The default interval for this service is set to be 24 hours; in other words, it runs daily. Users can change the interval of this service to suit their needs. Users can also set it such that it starts with Server restarts. Save any changes made to the service. 3. Click on the green icon to start the service. The service SLAPrunePolicyActivator will execute the policy SLAPrune to delete entries in 7 tables in TBSM's database: durationcountwatchers tasksofdurationcountwatchers incidentcountwatchers tasksofincidentcountwatchers cumuldurationrulestate cumulrulearchive radeventstore By default, the time duration set in policy SLAPrune is such that it will delete all entries which are older than 30 days from the time of execution. Users can change this duration by editing the policy SLAPrune. There are three variables that the users can change to set up the time duration: Days Hours Minutes Changing template dependencies Note: These variables should never be set to 0 and should have a minimum value of 1. If a parent template depends on a child template and the child instances are members of other templates, the state of a service instance does not change if the service has the DependsOnOtherTemplates property in the Additional tab set to false. About this task To address this potential issue, you can configure the DependsOnOtherTemplates property to be true in the child template defined in the dependency rule. This causes the OverallAttribute of the child template to reflect the worst status of all member templates of the child instances. It also reflects its own template attributes. As a result, the parent instance is now updated when any of the child templates change status. Procedure 1. Open the Edit Template tab for the service template you want modify. 2. Click the Additional tab. 3. Click the New Parameter button. 4. Type DependsOnOtherTemplates in the Parameter field. 62 IBM Tivoli Business Service Manager: Customization Guide

71 5. Type true as the default value for the parameter. 6. Click the Save button on the tool bar. Custom settings 63

72 64 IBM Tivoli Business Service Manager: Customization Guide

73 Custom properties Table 35. Custom properties This section describes key properties in the TBSM_sla.props file on the Data server and the RAD_sla.props file on the Dashboard server. Purpose The TBSM_sla.props file in the $TBSM_HOME/etc and the RAD_sla.props file in the $TBSM_DASHBOARD_SERVER_HOME/etc directories contain properties that affect your system. You can also add properties to this file that affect how your system runs. This topic does not describe all properties in this file. Rather, it describes key properties you can add or edit to change the behavior of your IBM Tivoli Business Service Manager (TBSM) system. There are specific procedures in the TBSM publications for specific properties which might not be covered in this table. Note: If you edit the properties in this file you need to restart the server for the changes to take effect. If you are not sure whether a property needs to be changed for a specific server, update the property in all servers and restart the servers. Property Description Default File to Edit impact.sla. includeeventlessattributes Specifies whether child services with no service affecting events are included in average calculations. impact.sla.attributedecimalplaces The number of decimal places to round off for average calculations. impact.sla.maxnumberofchildren impact.sla.maximumtime towaitbetweeninstancegc The number of services an ESDA rule can create before it creates an intermediate child service. That is, before it creates another level in the service hierarchy. The maximum time to wait between service instance garbage collection cycles in milliseconds. impact.sla.defaultesdalifetimesecs The default lifetime for service instances in seconds. impact.sla. defaultinvalidationperiod impact.sla.staygreenifnoevent impact.sla. maxpolicyattributetimesecs impact.sla.periodic updates The default ESDA service instance invalidation period in seconds. Specifies whether a service is in a good (green) state when it is created and has not received events. If set to false, the service instance can be in a marginal (yellow) or bad (red) state when it is created (if it has a numerical rule status configured that turns red when the value is 0). The maximum allowable time to execute a policy attribute in seconds. Specifies whether SLA trackers send events at the end of time window, even if the service status is clear. false TBSM_sla.props 3 TBSM_sla.props 50 TBSM_sla.props TBSM_sla.props TBSM_sla.props 3600 TBSM_sla.props, RAD_sla.props true TBSM_sla.props 20 TBSM_sla.props false TBSM_sla.props Copyright IBM Corp. 2008,

74 Table 35. Custom properties (continued) Property Description Default File to Edit impact.sla.defaulticonname impact.sla. instancecreatedactiontree impact.sla.dieifbadxml impact.esda.listdelimiter impact.sla. defaultautopoplifetimesec impact.sla. deleteeventsonstartupfilter impact.sla. resyncstateuponstartup impact.sla. resyncdbfetchersuponstartup impact.sla.persistifyautopop The file name for the default template icon. The policy that gets invoked when a new service instance is created. Specifies whether the system starts if the cumultimesla.xml file is out of sync with the database. The default value of true prevents the TBSM server from starting when this condition occurs. If the file is out of sync, the SLA calculations are not correct. The delimiter used in auto-generated ESDA properties. The default lifetime of auto-populated instances in seconds. The filter to use to delete events on startup. Class events are TBSM status events. Specifies whether to resynch events from the ObjectServer when the TBSM server starts. Specifies whether to resynch the status from DB fetchers on startup. Specifies whether auto-populated service instances are persistent by default. cloud_svg.gif true TBSM_sla.props TBSM_sla.props TBSM_sla.props ::: TBSM_sla.props TBSM_sla.props Class = true false true TBSM_sla.props TBSM_sla.props TBSM_sla.props TBSM_sla.props 66 IBM Tivoli Business Service Manager: Customization Guide

75 Table 35. Custom properties (continued) Property Description Default File to Edit impact.sla. minimumrootcausethreshold The minimum severity value required to mark a service event as the root cause for an outage. Root cause processing within the TBSM engine is done only if a service state would change, to greater than, or equal to, impact.sla.minimumrootcausethreshold, on receipt of the event. Root cause events are the events that could cause the service's status to change to a value equal to or above impact.sla.minimumrootcausethreshold. By default, the service needs to become red for the event to be considered a root cause event, but if the property is set to 3, then if the event causes the service to turn yellow it would also be marked as a root cause. Note: Even if the service already has a status equal to (or above) minimumrootcausethreshold, the event is considered a root cause event, if it has potential to trigger a state change equal to or above minimumrootcausethreshold. For example, event 1, with severity 5 may trigger a state chnage to Bad and be considered a root cause event. If a subsequent event is received, of severity 5, then it is also considered a root cause event. 5 TBSM_sla.props Custom properties 67

76 Table 35. Custom properties (continued) Property Description Default File to Edit impact.sla. minimumrootcausethreshold By default, the Events tab of the Service Details portlet displays all Raw Events for the service. Raw Events are all events which are associated with the Service. Root cause events, are events which have potential to trigger a state change equal to, or greater than, the minimumrootcausethreshold. Root cause events are displayed in Events tab of the Service Details portlet, on right-click and select Show Root Cause event. By default, TBSM will set the RAD_WebtopTool1 field to '1' for root cause events. A different alert.status field can be used by changing the impact.sla.rootcauseeventfield in TBSM_sla.props. TBSM also stores root cause event for services in memory. This memory list is used to generate the filter for the Service Details portlet, when executing Right-Click Show Root Cause events is used, a typical filter in this case for event serial number is sql="(servername = 'NCOMS' AND ServerSerial IN(5489))" When newer events are received they are considered for root cause processing. If newer events are deemed to be root cause, then the memory root cause list is updated and RAD_WebtopTool1 field to '1' for the new event. 5 TBSM_sla.props impact.sla.servicestatuspolicies Note: If a root cause changes severity and is not longer eligible as a root cause event then RAD_WebtopTool1 is set to '0' and the Service Details portlet will no longer show the event on right-click and select Show Root Cause events. A comma-separated list of policies to invoke when an attribute or rule changes state. ServiceEvent Updater TBSM_sla.props 68 IBM Tivoli Business Service Manager: Customization Guide

77 Table 35. Custom properties (continued) Property Description Default File to Edit impact.sla.updateeventrootcause Set to true to update the root cause flag in other events. By default, after TBSM has set root cause events for a service, newer events, for a lower level of the tree, are not considered for root cause processing. However, if impact.sla.updateeventrootcause is set to true, and a root cause event is received at a lower level of the service tree, TBSM will consider the higher level event as a symptom, and set the lower level event as root cause. In this case, TBSM will update it's memory store of root cause events with the lower level events. false TBSM_sla.props impact.sla. eventtaggingrootcausepolicy Note: RAD_WebtopTool1 field is set to '1' for old and new root cause events. TBSM does not clear the field in the original root cause events. The property can be set to identify a policy to be called to re-tag other events. It passes ServerSerial, instancename, template name, and whether ServerSerial is now a root cause or not. This property is related to impact.sla.updateeventrootcause. none (no policy is triggered) TBSM_sla.props The specified policy is only fired if impact.sla.updateeventrootcause is true, and the policy exists. When this is the case, the policy is fired for each root cause event, of the affected service, with the following parameters: v v v context (full context of the original event) servername,(ncoms) serverserial (serial number of event), v rootcausevalue (String representing 1 or 0), v v. servicename primarytagname (primary template name). impact.sla.customrootcausepolicy The policy to call whenever an event is labeled as the root cause. It passes the context,servicename, templatename,rootcausevalue, serial of the event. By default this policy does not exist, so no policy is run. none TBSM_sla.props Custom properties 69

78 Table 35. Custom properties (continued) Property Description Default File to Edit impact.sla.doinstancegc impact.sla.dorootcause impact.sla.runesdasonstartup impact.sla.passwholeeventtoslas impact.sla. bubbleuprawattributes impact.sla. updatenonmatchingevents impact.sla.sendrawstatusevents impact.sla. onlymanualinvalidation impact.sla.updateeventinthread impact.sla.nevercheckforother templateupdate impact.sla.globaltagprop.1 impact.sla.globaltagprop.2 Set to false to turn off instance garbage collection. If set to false, it turns off all root cause processing. If set to false, ESDA rules does not execute on startup. If set to true, then the event is passed through the SLA engine. This could create a larger memory footprint. If set to false, when an event comes in for a raw attribute it only bubbles up to the next level if the attribute has changed status. This setting could improve performance in certain cases, but would break features such as NumEvents affecting the incoming status rules. If set to false, the server does not update RAD_RawInputLastValue in events that did not match any attributes or rules. May improve performance. If set to false, status events for incoming status rules are not sent. This could improve performance in high volume environments. If set to true, then do not invalidate any ESDA service instances unless the user does so manually. If set to true, it allows for faster deleted event response, but could slow down event processing when the ObjectServer is processing a heavy event load. If set to true, it could speed up event processing, especially when multiple service templates are configured per service instance. But one service template's overall status no longer depends on other templates of the service instance. You can configure additional properties to exist in all service instances. Assigning a default value is optional. Each new property must be assigned a consecutive number for its index. The first property is impact.sla.globaltagprop.1, the second property is impact.sla.globaltagprop.2,, and so on. true true true false true true true false false false none TBSM_sla.props TBSM_sla.props TBSM_sla.props TBSM_sla.props TBSM_sla.props TBSM_sla.props TBSM_sla.props TBSM_sla.props TBSM_sla.props TBSM_sla.props TBSM_sla.props 70 IBM Tivoli Business Service Manager: Customization Guide

79 Table 35. Custom properties (continued) Property Description Default File to Edit impact.sla. secondstillstartstandalone If set to a non-zero value, a TBSM server in failover configuration waits this many seconds on startup to connect to its backup server. If it cannot connect, then it starts up by itself. 0 TBSM_sla.props impact.sla. onlyrecomputeprimary impact.sla. scorecard.updatelistthreshold This property can also be used on the backup server, so it waits this many seconds for the primary to fully start. Otherwise the backup server starts up by itself. If a user configures the primary template of a parent service as None, all rules from all templates assigned to the parent service are run whenever child services are added or removed. This is the default behavior. If this property is added with the value set to true, some rules that are not in the primary template of the parent service might not be updated with the correct value when child services are added or removed. Specifies the maximum number of pending updates allowed to accumulate per open scorecard. When the threshold limit is reached, a clean-up of all accumulated pending updates is completed and you are notified that the page containing the tree must be refreshed or re-opened. none TBSM_sla.props RAD_sla.props impact.sla.setmaxdecimalplaces Note: If the Dashboard invalidationtimeout value is changed from the default value of 30 minutes, the impact.sla.scorecard.updatelistthreshold parameter must be set to a value of 5000 or less. Note: If the invalidationtimeout period is set to 24 hour or more, the accumulated pending updates consume memory and might result in a lack of available memory. If you do not want the maximum number of decimal places displayed on the scorecard to be determined by TBSM, add this property to the RAD_sla.props file and set the value to false. When this property is set to true, the maximum number of decimal places is set using the impact.sla.kpidecimalplaces property. Note: You must restart the Dashboard server for the changes you make to take affect. true RAD_sla.props Custom properties 71

80 Table 35. Custom properties (continued) Property Description Default File to Edit impact.sla.kpidecimalplaces impact.sla. maxesdapolicytimesecs impact.sla.servicetreedepthlimit To set the number of decimal places displayed on the scorecard, add this property to the RAD_sla.props file. This is in addition to changing the KPI values on the scorecard. Note: You must restart the Dashboard server for the changes you make to take affect. Specifies the maximum amount of time that the system waits for an ESDA to complete. Specifies the service depth limit for data that is imported from Tivoli Application Dependency Discovery Manager. 3 RAD_sla.props 120 TBSM_sla.props 20 TBSM_sla.props When data is imported from Tivoli Application Dependency Discovery Manager, the depth of the service is checked. If it exceeds the value that is specified in this property, a message is displayed warning you to review your data relationship. impact.sla. disableimportalldescendants limitcheck Specifies whether the service tree depth limit is implemented for data that is imported from Tivoli Application Dependency Discovery Manager. false TBSM_sla.props When this property is set to true, the service tree depth is disabled and is not verified during invalidation. If the property is set to false and the service tree depth limit is exceeded during invalidation, a message is displayed warning you to review your data relationship. impact.sla. sendslamevents formetricrulealways If set to true, send SLAM events even if the value of a metric rule does not change. false TBSM_sla.props impact.sla. forcecanvasautorefreshmode This parameter affects the service viewer's ability to display event count data. By default, the event counts on a parent instance will not change unless the parent instance status state changes. Child instances always get their counts updated. This parameter affects only parent instances. If enabled, the code will check to see if the displayed instance has any data that needs to be refreshed on the service viewer. false TBSM_sla.props 72 IBM Tivoli Business Service Manager: Customization Guide

81 Table 35. Custom properties (continued) Property Description Default File to Edit impact.sla.unlockservicecolumn When set to true, the Service column in the Tree Table will be unlocked and can be allowed for both vertical (via mouse wheel) and horizontal scrolling. Note that the prefs.xml found at <TIP Installation dir>/config/cells/tipcell/ applications/isc.ear/deployments/ isc/isclite.war/web-inf/isc.dir/ <username>/prefs.xml should not have any column preference pre-set in order for this property to work. Delete entries of "TreeTablePref_TreeTable_LockColumns" if there are any. false RAD_Sla.props Custom properties 73

82 74 IBM Tivoli Business Service Manager: Customization Guide

83 Advanced ESDA and auto-population configuration When to use ESDA rules This section describes advanced options for ESDA and auto-population rule configuration. When a service model exists in a database, for example, a configuration management database, there are several different techniques that you can use to import this model into TBSM. The following ways are the three most common: ESDAs, auto-population rules (typically in combination with data fetchers), and using radshell with, for example, a Perl script to retrieve the information from the database. Which solution to use in various situations is described in the following topics. Auto-population rules Auto-population rules are useful when all levels of the TBSM model can be obtained from a single query of the database. For example, you might use these rules to import a model of hosts, applications, business units, and regions when you have a table which has columns for each of these entities. In this case, the simplest way to import the model is to create a data fetcher to retrieve the rows of this table and configure auto-population rules against the data fetcher to convert the rows returned into the elements of the hierarchy. Although it is possible to use ESDAs in this situation, using auto-population with a data fetcher is easier to configure and debug. Large and dynamic service models If the size of the model to be obtained from the data fetcher/auto-population rules is large, or if the hierarchy in the database is subject to change (where relationships get removed in addition to being added), using ESDAs is the better choice. Since ESDAs only import the parts of the model that you ask to see or that are affected by incoming events, using an ESDA avoids creating large segments of the model unnecessarily. It is also a faster way to import large pieces of the model, since the full event processing system does not need to be invoked. In addition, ESDAs modifies the relationships in the model in response to changes in the database. For example, if on one day, applicationx is on host Y and the next day it moves to host Z, ESDAs re-configures the model to reflect the change. With auto-population, it is typically feasible only to add relationships, not to remove them. Multiple data sources You could also use ESDAs when the data for the model is distributed across multiple data sources, or even multiple tables within one database. At each level of the hierarchy, you can configure ESDA rules to query different data sources and perform operations in Netcool/Impact policies to obtain children and parents. RAD shell scripts If the data for the TBSM model is not in any database or accessible through a Netcool/Impact DSA, the best way to integrate the model into TBSM is to use the RAD shell. For example, if an enterprise stores its model relationships in XML Copyright IBM Corp. 2008,

84 Scale of ESDA models format, the simplest way to integrate the model into TBSM would be to write XML query scripts that obtain the model from the XML file and write out the relationships in the form of RAD shell scripts that can be imported into TBSM. The scripts that read from the data source could also dump the relationship data to a database where TBSM could use ESDA or auto-population rules. However, this method involves database upkeep, which might not be feasible. The same advantages described in the topics above for using ESDAs rather than auto-population apply to using ESDAs rather than RAD shell importing. Because by default ESDA models do not make the TBSM model persistent, they provide a quick way to create large models. However, if the model changes so that large numbers of relationships are removed and added to existing instances, then ESDA operations can take a long time. The best way to avoid these non-optimal situations is to structure the hierarchy so that service instances do not have too many children or too many parents (keeping the model to below 100 direct children or parents per instance is ideal). TBSM supports having thousands of children or parents per instance, but if the model changes significantly, some ESDA manipulations can be slow. Service persistence and mapping When using ESDAs and auto-population rules, you can configure the dynamically imported service instances to be persistent or non-persistent. ESDAs by default are non-persistent and auto-populated services by default are persistent, but you can change this behavior per template using the Standard Template Properties window. This window is displayed when you select Edit Properties from the Template Editor of the TBSM Console. Keeping services non-persistent makes it considerably faster to create, remove, and modify them. To make a non-persistent service persistent, you need to add it as a child or parent of a persistent service, or simply save the service in the TBSM console. It is not possible to change a service from a persistent state to a non-persistent state. The advantage of persistent services is that they support service-level agreement (SLA) synchronization, SLA charts, and the IBM Tivoli Service Level Advisor integration. Also, they automatically exist when the server is restarted. The identifying feature of a service in TBSM is its service name. No two services can have the same name, and a service can have only one name. If an event triggers an auto-population rule, whatever name the service name expression evaluates is the name of the service that is affected by the event. In some cases, the TBSM model is created from ESDA rules that create the service names from fields in a database. However, incoming events that affect the services that TBSM imported might have a different naming scheme for the entities they affect. (For example, a database might store hosts as IP addresses, while the events might contain a field with the host name instead of the IP). In such a case, it is necessary to configure a policy in the auto-population rule to obtain the service name based on the information in the incoming event. (In the example, the policy would have to convert the IP name to the host name). This conversion is achieved from the custom configuration page, which you can access from the Create Auto-population Rule window. 76 IBM Tivoli Business Service Manager: Customization Guide

85 Invalidation of ESDA services Debugging ESDA rules Note: Events can match non-persistent ESDA services even when no auto-population rules are configured. Internally, a service in TBSM has a Boolean property indicating whether it is valid or not. When a service is marked as invalid, the ESDA rules dynamically retrieve its child or parent services whenever a user clicks the service. If the service is marked as valid, it does not execute any ESDA rules, instead it returns the current set of children or parent services it has. By default, once an ESDA rule is run to obtain the children or parents of a service, the service is valid (for that direction) for one hour. After the hour, if the service is clicked, the ESDA rule executes and returns the updated results. It is possible to configure the invalidation period in the Standard template properties window. The smaller the invalidation period, the faster the TBSM model responds to changes in the databases. The larger the invalidation period, the less time is spent doing the database lookups and ESDA rule processing that goes along with the invocation of an ESDA rule. It is also possible to manually render a service invalid by clicking the invalidate button on the Edit Service panel. When you click the Invalidate button on the Edit Service tab, the service and all the related child and parent services become invalid. When ESDAs are being configured, it is a common debugging practice to configure the rule, invalidate the service, then test the rule by clicking the plus sign next to the service in the tree or viewing the service in the Service Viewer. To provide some further detail on how TBSM responds to model changes for ESDA services, consider the following example. You have a child rule that obtains web servers from web farms, and when webfarm1 is expanded in the service tree, the child rule retrieves the web servers. Accordingly, TBSM shows webserver1, webserver2, and webserver3 as children of webfarm1. At this point, the database changes, so that webserver4 is now a child of webfarm1 and webserver3 is no longer a child. When webfarm1 becomes invalid (either after its invalidation period is exceeded or a user manually invalidates it) and the user again clicks webfarm1, TBSM now returns webservers1, 2, and 4 as children. In this case, webserver3 is removed as a child of webfarm1. At this point, TBSM needs to decide whether to delete webserver3 all together. If webserver3 currently has no children or parents, it is deleted. If it has any children or parents, TBSM does not delete it. You can test an ESDA child rule in one of two ways: by clicking the plus sign in the tree on a service for which the child rule is configured, or by viewing the service in the Service Viewer with NumLevelsDown set to 1. This basic test is described in the TBSM Service Configuration Guide. Remember that after viewing the children and changing the ESDA configuration, invalidate the service for the changes to take effect. To test an ESDA parent rule, review the service in the canvas with NumLevelsUp set to 1. Alternatively, you can Advanced ESDA and auto-population configuration 77

86 send an event that changes the status of the service for which the parent rule is configured. This event triggers the parent rule if the service is invalid. If no children or parents are returned when the ESDA rule is invoked, there are several approaches to debugging. One is to use the query builder to get a clearer view of the data that you are using to construct the model. Another approach is to look at trace.log for exceptions while the ESDA rule is being invoked. Often, if there is an error with the database query, the nature of the error becomes clear from the exceptions in the log file. Another approach is to use a custom policy for the ESDA rule. You can also use the default policy, but add debugging log statements to the policy to find out how many rows are being returned and what the contents of those rows are. These log statements are written out to the TBSM_policylogger.log. If the hierarchy that is imported is incorrect (for example, the service instance name expression was not configured correctly or the queries were not correct) then it is often best to manually delete the incorrect imported services in the TBSM console and invoke the ESDA rule again. 78 IBM Tivoli Business Service Manager: Customization Guide

87 Custom maps Custom maps overview Map file types The section describes how to add custom maps to your IBM Tivoli Business Service Manager (TBSM) system. When you specify the geographic information system (GIS) positioning for a given service, the TBSM Service Viewer can display the service location on the default world map. You can also choose and create custom maps for your service models. This section describes how to configure custom maps for your TBSM system. To create and use a custom map: 1. Select a GIS map, and if necessary, save it as a file type listed in Map file types. 2. Insert the GIS map into the ILOG Mapbuilder utility and save it as a.ivl file on the TBSM host as described in Converting a custom map on page For each service that uses the custom map, add custom attributes for the map to TBSM services and templates as described in Adding maps to services on page 81. The maps TBSM displays in the GIS view must be in the ILOG JViews Maps file (.ivl) format. You can convert geographic information system (GIS) maps to the.ivl formats from the following file types: v TIFF file-based interchange format for georeferenced raster imagery (GeoTIFF) (.tif) v Non-georeferenced raster images (.gif,.tif,.jpg,.png) v Environmental Systems Research Institute (ESRI) Shape files (.shp) v MapInfo Interchange Format (.mif) v Topologically Integrated Geographic Encoding and Referencing system (TIGER/Line) files (.rt*) v Drawing Interchange Format (DXF) files (.dxf). v Google Earth Keyhole Markup Language (KML) and KML Zipped (KLZ) formats (.kml,.kmz) v Digital Terrain Elevation Data (DTED) 0, 1 and 2 v Global Topographic Data (GTOPO30) DEM v Web Map Server (WMS) images v Oracle Spatial The maps you use must include geographic coordinate system data used to plot the points on the map. The ILOG Mapbuilder utility lets you open files and converts them to the.ivl format. For a list of coordinate systems supported by Mapbuilder, click Help > Help Contents in the MapBuilder user interface. Copyright IBM Corp. 2008,

88 Converting a custom map The ILOG Mapbuilder utility lets you convert an existing GIS map to the ILOG JViews Maps file (.ivl) format that is compatible with TBSM. Running MapBuilder on UNIX systems To run the Mapbuilder utility, you must have a valid X Window System DISPLAY variable. You can set the DISPLAY variable from a terminal window. The DISPLAY variable must be a valid display and you must set the server display privileges with a command like xhost + on the display machine. You can also run the Mapbuilder in a virtual X-server client window. About this task To start the Mapbuilder utility on UNIX systems: Procedure 1. Open a terminal window. 2. Change to the directory. $TBSM_HOME/contrib/gistools 3. Run the command:./mapbuilder.sh. The Mapbuilder user interface opens. For general information about how to use the Mapbuilder, click Help > Help Contents. Running MapBuilder on Windows systems To run the MapBuilder utility on Windows systems complete the procedure outlined in this topic. About this task To start the MapBuilder utility on Windows systems open a command window and run the command as outlined in this procedure. Procedure 1. At the command prompt, change to the directory %TBSM_HOME%\contrib\gistools 2. Run the command: Mapbuilder.bat The MapBuilder user interface opens. For general information about how to use the MapBuilder, click Help > Help Contents. Converting a file in MapBuilder To use a map in TBSM, you need to convert a file to the ivl format and save the file to the directory: $TBSM_DASHBOARD_SERVER_HOME/av/css/maps/ For more information about saving a file to the ivl format, click Help > Help Contents to open the MapBuilder help. 80 IBM Tivoli Business Service Manager: Customization Guide

89 Adding maps to services To use the custom maps in TBSM, modify the service template assigned to the services that you want to display on the map. After you customize the service template, you can set the geographic information system (GIS) coordinates for each service that is assigned to the template. Adding the MapName attribute to a template This topic outlines the steps to add the custom MapName parameter (attribute) to a service template. Procedure 1. Open the Edit Template tab for the service template you want to modify. 2. Click the Additional tab. 3. Click the New Parameter button. Figure 9. New Parameter button The blank parameter row is added to the parameter table. 4. Type MapName in the Parameter field. 5. If you want all the services assigned to this template to use the same custom map by default, type maps/filename.ivl in the Default Value field. Figure 10. Additional Tab: example MapName parameter settings 6. Click the Save button on the toolbar. Adding map location attributes to a service If you want to change the default map for a given service instance, you must change the value of the MapName field in the Edit Service tab. About this task Before you can change the default map, add the MapName field to the template assigned to the service as described in Adding the MapName attribute to a template. Custom maps 81

90 To define the map position for a service instance, complete the following steps: Procedure 1. Open the Edit Service tab for the service instance you want to change. 2. Click the Additional tab. 3. Enter the geographic information system (GIS) coordinates for the service instance using Table 36 as your guide. Table 36. Additional tab elements: GIS positioning Tab Element Use GIS Positioning check box City Locations drop-down lists and Set button Longitude field Latitude field Description Click this check box to enable the GIS positioning option. These drop-down lists contain the country and city locations preinstalled into TBSM. Select the country and city for your service and click the Set button. The GIS coordinates for the city you selected display in the Longitude and Latitude fields. You can also type the coordinates by hand. The longitude coordinate for your service location in decimal degrees. If your service location is not in the City Locationsdrop-down lists, you can enter this coordinate by hand. The + and - signs for the longitude must be correct for the service to display at the proper map coordinates. The latitude coordinate for your service location in decimal degrees. If your service location is not in the City Locations drop-down lists, you can enter this coordinate by hand. The + and - signs for the latitude must be correct for the service to display at the proper map coordinates. Note: When you save the service, the Longitude and Latitude values are saved. However, the City Locations value reverts to the default. This list is used for setting the coordinates for well-known locations. 4. Click the Save button on the tool bar. 5. To test if the new map displays: Click the View Service tab. If you have UseGIS selected, the GIS view is the service default view in the Service Viewer. 82 IBM Tivoli Business Service Manager: Customization Guide

91 Customizing the import process of the Service Component Repository Resource, attribute, and relationship information can be imported into the Service Component Repository (SCR) through the Discovery Library Toolkit from the sources outlined in this section. idml books Identity Markup Language (idml) books are well structured XML documents that are used to store XML tags that describe a resource, its attributes and relationships. idml books also define the operations that can be performed on a document by the consuming application. The term Discovery Library Adapter (DLA) refers to any source that is capable of producing an idml book that describes resource, attribute, and relationship data in IBM's Common Data Model (CDM) format. The list of idml book providers includes: v The z/os DLA discovers z/os hardware and z/os details. This includes: Address Space details; Subsystem Details (DB2, IMS, WebSphere MQ, CICS, and WAS). v The Tivoli Monitoring Services (TMS) DLA discovers Tivoli Monitoring Services resources. This includes: All Managed Systems, including Distributed Agents and OMEGAMON XE mainframe agents, and Logical Groupings, including Logical views, Aggregate Objects, and Managed system objects. v The IBM Tivoli NetView for z/os DLA discovers System z IP Managed Element data. v IBM Tivoli Composite Application Manager for Transactions v IBM Tivoli Storage Productivity Center In addition to idml books that conform to the CDM format, an idml book containing custom namespace objects can also be consumed by the Discovery Library Toolkit. This subject is addressed in subsequent sections of this guide. TADDM TADDM automatically creates and maintains application infrastructure maps. You can use TADDM to accomplish four tasks in your data center environment: 1. Discover components 2. Discover the configuration of components 3. Discover the relationship of components 4. Discover and track the changes The SCR interacts directly with TADDM to import resource and relationship data. The SCR is configured to continually monitor TADDM for changes to ensure that its model is up to date. Class filters and attribute filters limit the information extracted from TADDM. For more information, see the Integration scenarios in: developerworks/mydeveloperworks/wikis/home?lang=en#/wiki/tivoli %20Business%20Service%20Manager1/page/Home SCR API The SCR API provides a set of Impact functions that interact with feeds Copyright IBM Corp. 2008,

92 from external sources. These Impact functions working with the SCR API expand the resource and relationship information that can be introduced into the SCR from a larger variety of sources that might not be available through TADDM or idml books. For information about the SCR API, see Service Component Repository API overview on page 133. Supported Resource Models The SCR can import two types of resource models, Common Data Model resources and an alternative resource model referred to here as Custom Namespace resource models. Custom Namespace resource models are not as rich a modeling structure as the CDM, but it does broaden the coverage of resources imported into the SCR beyond what is available in CDM format. Custom Namespace models can be imported into the SCR using a customized idml book or using the SCR API. Process overview All resource and relationship information introduced into the SCR, regardless of whether the source is added from an idml book, a Tivoli Application Dependency Discovery Manager (TADDM) interaction, or using the SCR application programming interface (API), completes the stages described in the Discovery Library data and XML control files section of this document. Using custom namespace support and the mechanics of providing this resource data to the SCR are also discussed in this section. The processes used whether these resource models are introduced to the SCR using an idml book or through the SCR API are similar. This section outlines how to apply both approaches to the same data. Location of the Discovery Library Toolkit XML control files From TBSM 6.1, a large number of TBSM artifacts are maintained in the TBSM database. This includes many customization files, including those required for customization of the Discovery Library Toolkit XML control files. The Discovery Library Toolkit XML control files can be accessed and configured using the TBSM export and import commands. Use these commands to retrieve and update the XML control files if you want to customize these files. For more information, see the Customization artifact categories and Exporting and importing customization artifacts sections of the TBSM Administrator's Guide. Customizing the XML control files The topic outlines the process that resource, attribute, and relationship data follows when it is loaded into the TBSM Service Component Repository (SCR) through the Discovery Library Toolkit. This enrichment process allows you to: v Create identifier strings to match OMNIbus or TBSM data fetcher events v Simplify the resource class model to aggregate resource class instances so they are perceived as a single resource v Identify relationships as dependency relationships to be viewed with TBSM v Create notification messages that can be used to initiate a resource enrichment process through Impact policies v Manipulate resource labels 84 IBM Tivoli Business Service Manager: Customization Guide

93 v Assign one or more TBSM templates to a class or resource, or to a particular resource instance The SCR provides a bridge between a resource and relationship class-based model and the template-based TBSM service model. Resources and relationships are represented in the SCR in a class structure that is defined by the IBM Common Data Model (CDM) or as defined by the SCR custom namespace support. For more information about custom namespace support, see Importing resource models into the SCR with custom namespace support on page 114. Robust class model structures, such as the CDM model, represent resources in a large detailed class structure. The objective of the Discovery Library toolkit is to simplify and enrich these models to allow them to smoothly fit into the TBSM service model structure. The term class is used to refer to any class model introduced into the TBSM system through the SCR. Figure 11 outlines the key stages in the transition between the CDM model and the TBSM template model. Figure 11. Import process The following list explains the key stages in the transition between the model and the TBSM template model: Naming The naming stage validates and applies a unique identifier to resources as they are imported into the system. During the naming process, the naming facility determines the uniqueness of resources and, if necessary, merges resources into a single object. Merging is required if the naming rules determine that two or more sources of information refer to the same resource. This process is called reconciliation and works within the namespace of a class of objects. In addition to the inter-class reconciliation, the SCR allows naming rules to be applied to reconcile resources from different sources that use a different class structure. This feature is called Cross Namespace reconciliation and is used to merge resources between custom namespace sources and CDM namespace sources. For more information, see Merging custom namespace instances using reconciliation rules on page 111. Customizing the import process of the Service Component Repository 85

94 Naming rules for CDM classes are contained within the NamingRules.xml file installed with TBSM. Naming Rules for custom namespace classes are defined in the OtherNamespaces.xml file. Template mapping The mapping of classes located within the SCR to one or more TBSM templates is contained within the CDM_TO_TBSM4x_MAP_Templates.xml file. If a class is not mapped to a TBSM template, TBSM service instances are not created for instances of that class. During template mapping, the SCR ensures that TBSM dependency semantics are set for the relationship classes. The relationship shown between TBSM service instances indicates the dependency between the source instance, or the parent in a tree view, and the target instance, or child in a tree view. Within the class structure, the relationship type indicates the semantics of the relationship. That semantic might identify the relationship as having a source to target dependency, or a target to source dependency, or the relationship might not have a dependency. By default, all relationship classes are identified by the SCR as source to target dependencies. To change this behavior, edit the definitions in the CDM_TO_TBSM4x.MAP.xml file. Event identification The TBSM Identification field and value pairs enable TBSM to match status and event data with a particular service instance. The status data is typically comprised of events from Tivoli Netcool/OMNIBUS, but it can also include information gathered using data fetchers. The event identification stage of the SCR provides rules for creating one or more TBSM Identification field and value pairs for resources. This is a critical step that allows a Business Service Management solution to be built. Labeling By default the cdm:label or tbsm:label attribute is assigned as the display label for the resource. However, there are occasions when instances are created without a display name attribute. The LabelingRules.xml file that is included with TBSM enables you to assign labels to resources that do not have one assigned. The LabelingRules.xml file also enables you to override labels that are insufficiently defined from a Discovery Library book or from Tivoli Application Dependency Discovery Manager (TADDM). Composites General purpose class models, such as the CDM, can provide very detailed representations of resources, attributes, and relationships. However, detailed models are not always the most effective way of communicating resource information within TBSM. The composite stage of the SCR process can be used to manipulate the resource and relationship structure stored in the SCR. This provides a tailored view of the resource and relationship structure that can be used in the TBSM service model. This stage is typically used to aggregate a set of related resources into a singe resource as viewed by TBSM. The single resource view is a combined set of attributes, event identifiers, and relationships for all resources in the set of aggregated resources. Where necessary to meet the requirements of the TBSM service model, the composite stage can also be used to add resources and relationships to the SCR. Notifications The notifications stage enables Tivoli Impact to be integrated into the resource and relationship import process in TBSM. You can create Impact 86 IBM Tivoli Business Service Manager: Customization Guide

95 policies that take actions based on the rules that you have defined. These rules detect and create notification records based on the changing SCR resource instance model. Actions that result from a notification might include using Tivoli Impact features to send , update an external database, or to read from an external source to enrich the resource model in the SCR. Mapping the SCR class structure to a TBSM model This topic describes how the Discovery Library Toolkit maps IBM common data model (CDM) classes to IBM Tivoli Business Service Manager service templates. Template Mapping Note: Resources whose class is not mapped to a TBSM template are not added to the TBSM service model. The mapping of classes to TBSM templates is defined within the CDM_TO_TBSM4x_MAP_Templates.xml file. The <template> tag and its sub-tags are contained within the <classmappings> tag, and they describe which classes map to a TBSM primary <template> and a set of <othertemplates> for the mapping. The following syntax shows the tags in the CDM_TO_TBSM4x_MAP_Templates.xml file that can be used to map classes to TBSM templates: <template primary="name"> <othertemplate name="name"/> <cdmclass name="name"/> </template> Where: <template primary="name"> Defines the primary template name to be assigned to the SCR resource when it is mapped to a TBSM service instance. Each <template> tag represents a mapping from a primary TBSM template to one or more classes. <othertemplate name="name"> Specifies the name of an additional templates to be assigned to the TBSM service instance. <cdmclass name="name"> Defines the class that maps to the set of primary and additional templates. Although the tag is named <cdmclass>, it refers to any resource class within the SCR. These tags are located in the section of the document called <classmappings>. These definitions are considered class-level default mappings, because they provide a one-to-one mapping between a class or composite class and a set of templates. TBSM allows these default mappings to be overridden through the use of additional mappings contained within the conditional <Policy> definition, which is activated by the <Mapping> elements and tags. The use of the <Policy> and <Mapping> tags to assign templates is referred to a instance-level template mapping. The <Mapping> tag associates a class with a Policy, and the Policy rules can conditionally decide to set a template for the particular instances it evaluates. This is accomplished by placing the specific template mapping definitions described above inside the Policy tag. The CDM_TO_TBSM4x_MAP_Templates.xml file has samples showing exactly how to define this behavior. Instance-level template mapping can Customizing the import process of the Service Component Repository 87

96 also force a particular object not to be mapped at all, as seen in the NotComputer policy within this file. The XML syntax for defining instance-level template mapping are similar to that described in the Customizing the Service Component Repository Import Process on page 93. <Mapping> This statement determines which policies should be activated for which classes. <Policy> The Policy contains rules that can provide conditional statements for determining if a particular instance of the mapped class should have the template overrides applied. By encapsulating the <template> element described above within the <Policy> tag element, the default template mappings are overridden by the new mappings. Omitting the template assignment tags within the policy indicates that the policy matching instances cannot have a template assigned to them. This has the effect of assigning a template to a class through the default settings, but then omitting specific instances using a policy. <Component/> The specific instance that is assigned to the new templates is marked by the <Component/> tag within the policy rule. This instance is usually the same as the mapped class, but it can be different. Alternatively, you can use of one or more <Relationship> elements to change the instance of the object assigned to the new templates. Note: v This process does not create a TBSM template. If a template is used in a mapping policy, it must be defined within TBSM. v The TBSM template named SCR_RetrieveDependentObjectsTemplate defines an Enhanced Service Dependency Adapter (ESDA) rule. This provides accessibility to resources on which an instance of this template is dependent within the SCR. For more information about ESDAs, see the IBM Tivoli Business Service Manager Service Configuration Guide. This template is required for SCR objects and must not be removed from existing template definitions or omitted from new template definitions that you define. v The TBSM template name SCR_ServiceComponentRawStatusTemplate is a simple default template that matches events that affect the status of resources. When you deploy TBSM in your environment, it is likely that you will replace the SCR_ServiceComponentRawStatusTemplate template with one or more templates containing a more appropriate set of event and propagation rules. v TBSM implementations have the option of adjusting these settings as necessary. If additional raw status rules are desired, define the template within TBSM and reference it as the <othertemplate> tag. Using this technique to provide instance template assignments is recommended for SCR resource because when it is synchronizing with TBSM, the SCR always resets instance template assignments to match the information provided in the XML definitions. v Although a large number of classes are mapped to TBSM templates in this file, some additional mappings are likely to be necessary when implementing TBSM. If a class is not mapped, it might be added to an existing template element definition or a new definition can be created. v When the SCR is accessed by TBSM, only resource instances with template mappings are loaded into TBSM. v Since the CDM_TO_TBSM4x_MAP_Templates.xml is managed by the TBSM import and export facility, you must extract the latest version of the file from the artifact 88 IBM Tivoli Business Service Manager: Customization Guide

97 store using the getartifact command, make your changes to the extracted file, and then import the new file back into the system using the putartifact command. After you have done so, the SCR reads the new configuration files from the artifact store at startup or when instructed to do so by the utils command with the -e option set to reload_cdm_definitions.xml. v When the new template settings are visible to the SCR, changes are not pushed to the TBSM service model until a parent resource within the service tree is invalidated. If an import of resource data into the SCR is not expected to cause the TBSM invalidation process to occur, you must manually validate a parent resource in the TBSM interface. It is good practice to invalidate from the root of the service tree, which should be the Imported Business Services node to ensure that template changes are propagated throughout the entire service tree for the services which have the templates applied. This also helps ensure that all services have up-to-date templates. v The example shown is as sample template mapping: <template primary="bsm_node"> <othertemplate name="scr_retrievedependentobjectstemplate"/> <othertemplate name="scr_servicecomponentrawstatustemplate"/> <cdmclass name="cdm:sys.computersystem"/> <cdmclass name="cdm:sys.genericcomputersystem"/> <cdmclass name="cdm:sys.unitarycomputersystem"/> <cdmclass name="cdm:sys.aix.aixunitarycomputersystem"/> <cdmclass name="cdm:sys.freebsd.freebsdunitarycomputersystem"/> <cdmclass name="cdm:sys.hpux.hpunitarycomputersystem"/> <cdmclass name="cdm:sys.ipso.ipsounitarycomputersystem"/> <cdmclass name="cdm:sys.linux.linuxunitarycomputersystem"/> <cdmclass name="cdm:sys.netware.netwareunitarycomputersystem"/> <cdmclass name="cdm:sys.openvms.openvmsunitarycomputersystem"/> <cdmclass name="cdm:sys.sun.sunsparcunitarycomputersystem"/> <cdmclass name="cdm:sys.sun.sunsparcvirtualcomputersystem"/> <cdmclass name="cdm:sys.vmware.vmwareunitarycomputersystem"/> <cdmclass name="cdm:sys.windows.windowscomputersystem"/> <cdmclass name="cdm:sys.zos.zvm"/> <cdmclass name="cdm:sys.zos.zlinux"/> cdmclass name="cdm:sys.zos.zos"/> </template> Class mappings Not only does TBSM ship a large number of default class mappings but new definitions are frequently added and changed. Any listing of the current state of the file is likely be out of date. It is recommended that you are familiar with the default configuration by extracting the current CDM_TO_TBSM4x_MAP_Templates.xml file from the data store. Trouble shooting tip If resources visible in TADDM or in a loaded idml book, or communicated to the SCR using the SCR API, are not visible in TBSM use the Component Registry Viewer (CRViewer) to verify that the resources were properly loaded into the SCR. If the resources are in the SCR and still not visible in TBSM, use the CRViewer to confirm that the instance has a template assigned to it. If it does not, define a template in the CDM_TO_TBSM4x_MAP_Templates.xml file. After you have defined a template, the parent of the resource within the TBSM service model must be manually validated so that its children are added into the service model. Customizing the import process of the Service Component Repository 89

98 If a instance in the CRViewer does not have a template assigned to it, it might occur because that instance is a member of a composite. An example of this is an operating system class. Operating systems are not shown individually in TBSM, but instead are a part of a composite that makes up a server. An instance of cdm:sys.aix.aix does not have a template, but looking at the Component of Composites tab shows a computer system object. Following the relationship to this object finds the BSM_Nodes template. Relationship Mapping The mapping of relationship types to a TBSM dependency is located in the CDM_TO_TBSM4x_MAP.xml file managed by the artifact store. To view or make changes to the current file, extract the file using the getarticfact command, make your changes, and then import it into the system using the putartifact command. Mapping the TBSM dependency direction for relationship classes The <class> tag and its attributes are contained within the <RelationshipInfo> tag, and can be used to change the default behavior for the TBSM interpretation of relationship classes. By default, the service component resource (SCR) interprets all relationship types as dependency relations with the source of the relationship being dependent on the target relationship. This relationship is displayed in the TBSM service tree as the source being the parent and the target being the child. When the TBSM service model is loaded from the SCR, both sides of the relationship must be mapped to a template to ensure that the dependency relationships are maintained. The following syntax shows the tags in the CDM_TO_TBSM4x_MAP.xml file that can be used to map TBSM dependency direction on relationship classes: <class type="type" reversedirection="yes no" priority="high medium low" source="source" target="target" isdependency="false" RCAOnlyreversedirection= yes no /> Where: <class> Defines the behavior for one relationship class type. The following attributes might be included in the <class> tag: type="type" Specifies the relationship class type. source="source" Specifies the source class in the CDM relationship that must match this definition. target="target" Specifies the target class in the relationship class that must match this definition. priority="high medium low" Specifies the priority associated with that class definition. This value must be set at high, medium, or low. A definition set with a high priority overrides definitions set at medium or low. isdependency="false" Specifies that the relationship is not to be used as a dependency. If not included, the relationship is used as a dependency. 90 IBM Tivoli Business Service Manager: Customization Guide

99 reversedirection="yes no" When set to yes, this indicates that the dependency is from the target resource to the source resource. RCAOnlyreversedirection= yes no Use this attribute to identify relationships whose dependency are recognized by the Impact Event, Isolation, and Correlation feature. If set to no the dependency is from the source to the target resource. If set to yes the dependency is from the target resource to the source resource. This attribute must not be specified if the isdependency or reversedirection attributes are specified. Note: The source and target attributes can use SQL wildcard syntax (for example, %) for matching classes of resources, but you must avoid using the wildcard in the beginning of the class specification. It is best to use the wildcard only at the end of the string. If the source is not specified, the definition applies to all source resource classes. If the target is not specified, the definition applies to all target resource classes. The following example displays the structure of the <class> definition within the CDM_TO_TBSM4x_MAP.xml file: <class type="cdm:memberof" reversedirection="no" priority="high" source="cdm:sys.zos.%" target="cdm:core.systemspecificcollection"/> <class type="cdm:memberof" reversedirection="yes"/> <class type="cdm:installedon" isdependency="false" target="cdm:sys.zos.zseriescomputersystem"source="cdm:sys.zos.zlinux"/> This example contains three tags: 1. The first tag indicates that a cdm:memberof relationship, where the source begins with cdm:sys.zos and the target is of class cdm:core.systemspecificcollection can be interpreted as a dependency from source to target. 2. The second tag indicates that for any relationship of type cdm:memberof, reverse the dependency direction. This indication means that the target is displayed as a dependent of the source. Since the first statement in our example is of high priority, it has a higher significance. 3. The third in the example says that any relationship of type cdm:installedon with a source class of cdm:sys.zos.zlinux and a target class of cdm:zos.zseriescomputersystem is ignored. Defining which SCR attributes are sent to the TBSM Service Model By default a limited number of resource attributes are pushed into the TBSM service model. The default set is defined in the CDM_TO_TBSM4x_MAP.xml file within the AttributeSieve tags. If you would like to extend this list, and therefore see the attributes under the Additional tab of the TBSM Service Viewer, create one of more files that contain the following structure: <?xml version="1.0" encoding="utf-8"?> <AttributeSieve> <!-... Place additional attribute definitions below here -> </AttributeSieve> Within the AttributeSieve tag can be one or more <attr> tags each of which lists the attribute name to be allowed to be sent to the TBSM Service Model. The Customizing the import process of the Service Component Repository 91

100 attribute name specified can be an exact match or can use the wildcard (%) to include a range of attribute names. The following example demonstrates specific settings and a wildcard setting. <AttributeSieve> <attr>thisnamespace:thisattr</attr> <attr>mycompany:%</attr> </AttributeSieve> After the attribute file is created, import it into the runtime environment using the putartifact command with the category specification of tbsmattributes. For the new information to be considered by the Discovery Library Toolkit, you must stop and restart the Discovery Library Toolkit or issue the utils.sh command with the -e option of reload_cdm_definitions.xml. The TBSM memory model will be updated the next time the service instances are validated which could be due to an discovery import process or by manually invalidating the Imported Business Services service instance. Note: In releases earlier than TBSM 6.1, you might have changed an SCR view named scc_componentattributeslimited to achieve the same results as the tbsmattributes category. That change cannot be used in TBSM 6.1 or later. Adding new services to the Service Component Repository Although the new services instances are pushed into the TBSM service model if they are a descendent of the a business system class, they are not visible in the Service Component Repository section of the service tree unless a service instance stub is defined to pull them in when requested. The SCR services instance stubs are service instances that are descendants of the Component Registry service instance that are assigned the SCR_TopLevelAggregateTemplate template. The SCR_TopLevelAggregateTemplate template has properties that, when defined, pull in SCR resources that match the criteria of its properties. The following Rad Shell defines an service instance for pulling in SCR resources of the class tbsm:resource. addserviceinstance( new String[] {"SCR_TopLevelAggregateTemplate" }, "SCR_TBSM_RESOURCE", "TBSM Resource objects", "", "Standard", null, null, "REGULAR" ); clearallinstanceidfieldvaluepairs( "SCR_TBSM_RESOURCE" ); adduserpreferencesforinstance( "SCR_TBSM_RESOURCE", "classnamefilter", " tbsm:resource " ); The template property named classnamefilter lists the classes that are children of the defined instance. The class list is provided with each class enclosed in single quotes and separated by a comma. This Rad Shell then creates a relationship between the SCR_TBSM_RESOURCE object and the Service Component Registry instance so that it is a child of the Service Component Registry object. If you do not create this relationship, the SCR_TBSM_RESOURCE service instance appears in the primary service instance tree. 92 IBM Tivoli Business Service Manager: Customization Guide

101 addserviceinstancedependency( "ServiceComponentRepository", "SCR_TBSM_RESOURCE", ); Running the RAD Shell script To run the example RAD Shell scripts: Procedure 1. Copy and paste this script into a text editor: addserviceinstance( new String[] { "SCR_RootTemplate" }, "SCR_Namespace", "Alternate Namespace", "SCR Alternate Namespace Resources", "Standard", null, null, "REGULAR" ); addserviceinstance( new String[] { "SCR_TopLevelAggregateTemplate","SCR_ServiceComponent RawStatusTemplate" }, "SCR_HelloWorld", "Hello World", "SCR Hello World Resources", "Standard", null, null, "REGULAR" ); addserviceinstancedependency( "SCR_Namespace", "SCR_HelloWorld" ); adduserpreferencesforinstance( "SCR_HelloWorld", "classnamefilter", " tbsm:resource " ); 2. Save the script file with a file extension of.radsh. 3. On the Data server, open a command prompt and navigate to $TBSM_HOME/bin 4. Run one of these command to run the script, replacing <filename> with the fully qualified file name of your script: On UNIX systems: cat <filename> $TBSM_HOME/bin/rad_radshell On Windows systems: type <filename> %TBSM_HOME\bin\rad_radshell Customizing the Service Component Repository Import Process Mapping, policy, and rule statements are collectively referred to as rules. They define a behavior that must apply when resource information is added to the system using the Service Component Repository (SCR). Customizing the import process of the Service Component Repository 93

102 Identifier rules Identifier rules are used to affect the creation of the strings associated with a resource. These strings are similar to the resource attributes and can be used to produce TBSM Identifiers that are used to match events, from OMNIbus or from a data fetcher, to resources. For example, to match events against the short hostname (unqualified hostname) of a resource, you might apply a rule to extract the short host name from the resource information contained in the SCR and assign it to the resource. These type of rules are called Event Identifiers and are contained in the EventIdentifierRules element of the EventIdentifierRules.xml file. Customized identifier rules are added to the SCR by creating and importing a valid identifier rule file. For more information about Identifier rules, see Using identifier rules to associate aliases to a resource on page 104. Notification rules Notification rules are used to create notification messages that are used in conjunction with Impact policies to perform resource enrichment actions when the resource and relationship model in the SCR successfully meets the condition of the rule. Using notifications, a Impact policy can be driven for any condition that can be detected by the rule including the ability to generate a notification when a resource is created in the SCR for the first time. For more information, see Initiating external action using notification rules on page 108. Composite rules Composite rules allow resource, attributes, and relationships to be grouped so that they can be viewed in the TBSM service model as a single resource or to introduce an object created in the Service Component Repository into the SCR model. The aggregation or creation of resources ensures that the discovered model represents the service model better when it is displayed in TBSM. For more information, see Simplifying the TBSM service model using composite rules on page 106. Labeling rules Labeling rules determine the display labels applied to resources when they are added to TBSM. Labeling rules can be used to overwrite existing display labels or to add labels to resources that are without a label. For more information, see Altering a resource display name using labeling rules on page 112. Reconciliation rules Reconciliation rules are used to define cross namespace naming rules that are used to generate the strings that determine if a CDM object and a non-cdm object can be merged together. For more information, see Merging custom namespace instances using reconciliation rules on page 111. Discovery Library Toolkit rule language In this section, we first describe the common rule schema definitions for all rule types and then explain the individual rule types. Mapping element This topic describes the Mapping element and its attributes. 94 IBM Tivoli Business Service Manager: Customization Guide

103 Purpose Mapping elements activate the named policy. If the resource of a specified class is referenced in an import of data into the Service Component Repository (SCR), the policy is activated with the instance as its starting point. Syntax <Mapping policy="policytorun" class="%" /> Parameters policy The policy attribute specifies the name attribute of the policy element that you want to activate. class The class attribute specifies the class of instances that activate the named policy. The class is provided as a specific class name, for example, cdm:sys.windows.windowsoperatingsystem or the wildcard value (%) which indicates that all class instances activate the policy. isbaseclass When set to true, the rule engine interprets the class setting as a base class in the CDM model. All extensions of the base class have this mapping statement applied to them. For example, if isbaseclass is set to true and class is set to cdm:sys.computersystem, the Mapping statement applies to any derived subclass of the ComputerSystem class including cdm:sys.linux.linuxunitarycomputersystem and cdm:sys.aix.aixunitarycomputersystem classes. UnMap element This topic describes the UnMap element and its attributes. Purpose Mapping statements are used to deactivate a Mapping element in one of the SCR standard configuration files. This removes the requirement to edit the standard rule files to delete one of its rules. To deactivate a Mapping element in a base rule file, create a rule file in the appropriate category and match the Mapping element that you want to deactivate. That is, create an UnMap element with the same policy and class attributes as the Mapping element that you want to deactivate. For example, if a base file has a Mapping statement as follows: <Mapping policy="tbsmcdmcreatedclass" class="cdm:sys.businesssystem" /> it can be deactivated with the following UnMap statement: <UnMap policy="tbsmcdmcreatedclass" class="cdm:sys.businesssystem" /> Syntax <UnMap policy="policytorun" class="%" /> Parameters policy The policy attribute specifies the matching policy attribute of the Mapping element that you want to deactivate. Customizing the import process of the Service Component Repository 95

104 class The class attribute specifies the matching class attribute of the Mapping element that you want to deactivate. Policy elements Policy elements are used to contain the element for one or more rule elements. The name of the policy is used to activate the policy by the Mapping element. Purpose Although, the Policy element and many of its sub-elements are common to all types of rules, there are some variances depending on the purpose of the rule as indicated by the outermost element of the XML document. This might be EventIdentifierRules, NotificationRules, CompositeDefinitions, CrossNamingRules, or LabelingRules. Syntax <Policy name="policytorun"> Parameters The Policy element has the following attributes: name The name attribute provides the reference name that is used in the Mapping element. action (optional) This attribute is used for notification processing. The action attribute is available to allow policy writers to further qualify the purpose of a notification so that the appropriate post-notification processing is easily identified. The value of the action attribute is contained in the trigger notification table for notifications created by the policy. For more information, see Initiating external action using notification rules on page 108. The Policy tag contains one or more Rule elements. Each Rule element executes independently. A Policy element might contain multiple Rule elements which execute independently. Rule element This topic describes the syntax and purpose of the Rule element. Purpose The containing node, or parent, of a Rule element must be a Policy element. The purpose of the Rule element varies depending on the purpose of the Policy element: v For composite processing the Rule element identifies and selects subcomponents of the root element. The root element is the instance that was mapped to the policy. This is also the instance that activated the policy. Within the rule, the Component element selects the resource to be collected and used for the remaining parts of the composite processing. v For identifier processing, the Rule element outputs a string that is then available as an alias that can be applied to the mapped instance of the policy as a TBSM identifier. These aliases can be used to align the discovery flow of resource 96 IBM Tivoli Business Service Manager: Customization Guide

105 awareness to events. Each Token element within the rule outputs a string segment that is concatenated together to create the alias string. v For notifications processing, the Rule element outputs a string that is provided by the SCR as the notification string. The string can then be used by Impact, acting as a notification string processor. Each Token element within the rule outputs a string segment that is concatenated to create the notification string. v For labeling processing, the Rule element outputs a string that can used as a display label for the resource mapped to the policy. v For instance-based template mapping, the Rule element selects the resource whose templates settings are provided by the policy. The Component element within the rule selects the resource. v For cross namespace reconciliation processing, the Rule element outputs a string that is used to determine whether to merge two or more objects in different namespaces. Each Token element within the rule outputs a string segment that is concatenated to create the identification string used for cross namespace reconciliation. Rule elements act against a resource in the relationship node graph. When started the node that is the current node, and therefore the node that is tested, is the instance of the class that was mapped to the policy containing the rule. The Relationship element within the rule can move the current node along a relationship so that related objects can be considered during processing. Syntax <Rule name="somerulename"> Parameters The Rule element includes the following attributes: name A string used to identify the rule uniquely within the Policy element. field (optional) For identifier rules, this attribute identifies the keyword associated with the output string of the rule. By default it is set to BSM_Identity which is the common type identifier used to associate OMNIbus events to TBSM service model resources that enter the system through the Service Component Repository (SCR). Relationship elements Relationship elements can alter the current node within the Service Component Repository (SCR) model that a rule is testing. This allows the rule to review objects that are related to the root instance by traversing the relationship node graph. A Relationship element can contain another Relationship element. When this occurs, the rule engine continues to traverse the relationship node graph from that point forward. As a Relationship element is ended, the current node returns to the point prior to the Relationship element. Purpose The purpose of the Relationship element is to allow the node graph to be traversed to meet the requirements of the Rule. Customizing the import process of the Service Component Repository 97

106 Syntax <Relationship relationship= cdm:reltype1 relationshiptarget= hop1class > <Relationship relationship= cdm:reltype2 relationshipsource= hop2class > Parameters The Relationship element includes the following attributes: relationship The type of relationship that must be tested. The exact relationship name must be provided. For example, cdm:runson, cdm:contains. relationshiptarget relationshipsource (one of these parameters is required) Used in conjunction with the relationship attribute, the relationshiptarget instructs which relationship from the current node is tested. This review requires that the node is traversed until the node on the other side of the relationship is reached. If relationshiptarget is defined, the rule engine traverses any relationship that has a type defined in the relationship attribute and where the target resource class matches the relationshiptarget and the source of the relationship is the current node. If relationshipsource is defined, the rule engine traverses relationships where the source resource class matches the value provided. The relationshipsource or relationshiptarget is required and is specified as an exact resource class name, a list of resource class names separated by a semicolon, or by a wildcard such as % required (optional) When the required attribute is not defined, or is set to true, and where the described relationship does not exist, the rule engine ends the evaluation of the rule. If the required attribute is set to false, and the relationship exists, the rule engine traverses the relationship. However, if the relationship does not exist the rule engine continues to evaluate the rule. exist (optional) When a described relationship exists, setting the exist attribute to false causes the rule engine to stop processing a rule. Use this attribute to test that a relationship must not exist for the rule conditions to be met. Condition elements Condition elements place conditions on their parent elements that must be met before the rule engine proceeds. Purpose Note: A lower case letter c must be used for the condition element. Condition elements impose the following restrictions: v When the containing element is a Relationship element, the rule engine cannot proceed to the next resource element in a relationship unless the next resource element meets the condition specified. v When the containing element is a Rule element, the class instance mapped to the Policy element is tested. v When the containing element is a Token element, the current node instance and attribute is tested. 98 IBM Tivoli Business Service Manager: Customization Guide

107 Syntax <condition attrkeyword= cdm:attrname1 operator="=" value= attrvalue1 > <condition booleanoperator= OR value= attrvalue2 /> </condition> Parameters The condition element can contain the following attributes: attrkeyword The attrkeyword parameter defines the resource attribute name of a resource instance that is to be tested. The exact attribute name must be provided. For example, cdm:name,cdm:fqdn. This parameter is required if the condition element is an immediate child of a Rule element or Relationship element. This parameter is ignored if the immediate parent element of the condition element specifies an attribute name to test. This is the case with a Token element. operator The operator parameter defines the comparison operation between the attribute and the value it is tested against. All comparisons are string compares. The comparison operation can include SQL string operations such as =,!=, LIKE, or NOT LIKE. req_attr (optional) This parameter is only used when the attrkeyword parameter is defined on the same element. The req_attr parameter indicates to the rule engine whether or not the attribution condition must be met for the Rule conditions to be met. When req_attr is set to false, the rule engine continues to process the rule even if the condition being tested does not exist. If this parameter is set to true, the rule engine stops processing the rule if the condition cannot be met. value The value parameter defines the string against which the attribute is tested. Optionally, it can be specified using the standard SQL string expressions for LIKE testing of % or _ (underscore). The underscore indicates that the rule engine must match any one character in its position. For example, matchallendings%, matchonecharacter_, and _startanymatchallendings%. A condition can contain another condition element specifying an additional condition on the parameter. This allows a rule to test an parameter against 2 or more values. booleanoperator In order to direct the rule engine to test an attribute value against two or more conditions, a condition element can contain another condition element. When defined this way, the contained condition element must contain the booleanoperator parameter. Valid values are AND and OR A condition element can be defined to use the string value referenced by the attrkeyword parameter to match and return information in an ActionInfo Group definition. ActionInfo Group definitions allow information outside the discovered resource, attribute, and relationship information in the SCR to be used in a Rule definition. Using an ActionInfo Group in a condition rule simplifies checks for or conditions in a particular attribute. By placing all the possible options in a Group definition, the condition can be conditionally met given any number of possible values. For information about ActionInfo elements, see ActionInfo elements on page 102. Customizing the import process of the Service Component Repository 99

108 groupname The groupname parameter specifies the specific ActionInfo Group to be referenced. groupoperator The groupoperator parameter provides the comparison operator to find the row, the r element, in the Group definition. If not specified, the default value is =. The only other valid operator is LIKE. groupfield The groupfield parameter specifies the row element on which match from the following list: v v v v v field value arg1 arg2 arg2 If not specified, the default value of field is applied. Token elements The Token element outputs a string segment. All output string segments for a given rule are concatenated in the order that they are specified. This creates the string rule output for the event, notification, labeling, and cross namespace naming rules. Many of the Token element parameters work together to control the behavior of the rule engine. These related parameters are described below. Purpose The rule engine is directed to the current node by the nested Relationship elements. The actions performed by thetoken element are performed on the current node. If the Token element exists outside any Relationship element, it acts against the parameters of the root instance, the instance that was mapped to the policy. Parameters The following are the parameters for the Token element. For purposes of these descriptions, the term string refers to the value of the attribute identified by the Token keyword attribute which the parsing function acts on: keyword and value parameters These parameters define the string value that is output as a string segment. v v v v When the keyword is set to ATTR, the value is set to the attribute name that is to be output. When the keyword is set to LITERAL, the value is the literal that is output as the string segment When the keyword is set to FUNC, the value can be set to class, shortclass, or label which results in, respectively, the class name of the current resource, the rightmost part of the class name, and the display label of the current resource. When the keyword is set to SOURCETOKEN and the value is set to a particular product name that provides the source token value along with their resource, attribute, and relationship data, the rule engine outputs the source token value for the resource. 100 IBM Tivoli Business Service Manager: Customization Guide

109 case (optional) The case parameter instructs the rule engine to apply the specified case to the output string. The possible values are UPPER and LOWER. The token, delimiters, and string_delimiter optional parameters allow the string outputted by the Token element to be manipulated before it is output. token (optional) The token parameter instructs the rule engine how to manipulate a string before it is it outputted. Optional values for this parameter are contained in the ScrConfig.xml file include first, last, allbutfirst, allbutfirsttwo, allbutfirsttwo, allbutfirsttwo, firsttwo, lasttwo, findmatchoccurrence, format, excludestring, getexecutable, and javaregexreplace. The token attribute works in conjunction with the delimiters and string_delimiter attributes. delimiters (optional) The delimiters parameter specifies the delimiter used by the rule engine to break up the string. If more that one character is provided anyone of them causes the string to be broken up into segments. The default is a (.). Examples of other values and :. string _delimiter (optional) The string_delimiter parameter tells the rule engine to treat its value as a single delimiter. For example, you can use the string atto break up the string abbyatthispace into two tokens abby and this place. A Token element can also use regular expression behaviors to extract data from a resource attribute value: javaregex and occurrence parameters The javaregex and the occurence parameters cause the nth matching region or occurrence of a regular expression within the input attribute value string javaregex = "a.b" occurrence=1 input string = "aababbacbadb" This returns aab. javaregex and format parameters The form of the substitute pattern in the format string is ${n} where n represents the nth matching occurrence of the regular expression in the incoming string. You will always get an output so you must test the string if necessary to first detect if it should be acted upon. An example of this is: <Token keyword= ATTR value= cdm:name javaregex="a.b" format="this ${1} and that ${2}" /> If the input attribute value string, the value of the cdm:name attribute for the current resource, is aabcccccabbacbadb then the output string segment would be This aab adn that abb. javaregexreplace This regular expression replaces regular expressions in the format string with the matched regions in the incoming string. An example of this is: javaregexreplace="this ${a.b, 2} and that ${a.d, 2}" input string = "aababbaadabd" Customizing the import process of the Service Component Repository 101

110 Optionally, a condition element can be contained by, or is a sub-element of, the Token element. In this case the parameter that the condition is acting upon is defined by the string being outputted by the attributes of the Token element. ActionInfo elements ActionInfo and Group elements provide a mechanism to link data from another source, as captured in the group definition, into the rule processing. Group elements create tables of data that are available to rule processing to augment the information found within the resource, relationship, and attribute data being loaded into the component registry. Group elements can be referenced in condition and Token elements. Purpose The ActionInfo and Group elements contains a set of rows of data similar to a table. One or more Group elements are allowed within an ActionInfo element and one or more r elements can be defined within a Group element. Each r element or row element can contain one each of the field, value, arg1, arg2, and arg3 elements. The attribute named type that can be provided on the field, value, arg1, arg2, and arg3 elements instructs the rule engine to prepare the value of the element as it specifies. The arg1 element is used to display its syntax. <arg1 type= asis sqllike regexpr > elementvalue</arg> If set to asis, or not specified, the value of the element is left as is for comparison purposes. If type is set to sqllike, the element value is interpreted as an expression similar to an SQL expression. If type is set to regexpr, the element value is interpreted as a regular expression. Syntax The syntax for ActionInfo and Group elements is as follows: <ActionInfo> <Group name= groupname > <r> <field>raleigh</field> <value>nc/raleigh.ibm.com</value> <arg1></arg1> <arg2></arg2> <arg3></arg3> </r> <r>... </r> <r>... </r> </Group> <Group name= groupname2 >... </Group> </ActionInfo> 102 IBM Tivoli Business Service Manager: Customization Guide

111 Using Group elements Group elements can be used with condition elements or in Token element statements as an output string segment. The attribute names used to reference the ActionInfo and Group element are: Parameters groupname The name attribute of the Group element groupoperator Specifies the operator to be used to test against the Group elements. Valid group operator values are LIKE, NOT LIKE, or =. IN and NOT IN can also be used in condition elements groupfield Specifies the element in the Group row to test. Can be set to field, value, arg1, arg2, or arg3. If not specified, the field argument is tested. groupreturn Specifies the element in the ActionInfo/Group/r element to be returned on the Token expression When used with a Token element, the ActionInfo and Group elements can use in this way: <Token /> keyword= as described above value= as described above groupname= buildmsnname groupoperator= LIKE groupreturn= value In this case, the ActionInfo group is referenced to determine the string that must be output as the string segment for this Token element. The groupname instructs the rule engine to consult the ActionInfo or Group element to identify the element that has a name attribute equal to the value of the groupname attribute. In this case buildmsnname. It compares the field element value in the ActionInfo, Group or r element with the Token value as defined by the token keyword and token value attributes using the groupoperator value, in this case LIKEand outputs the ActionInfo, Group, or r value element value as a string segment. When used with a rule condition element, the ActionInfo and Group elements can be used to test the value of an attribute: <Token keyword="attr" value="cdm:fqdn" token="first" delimiters="."> <condition groupname= testfqqdnwithaction operator= IN value= field > </condition> </Token> <Rule name="functionclasscomp" > <condition attrkeyword = cdm:notation value= field groupname= localipaddresses operator= NOT LIKE /> <Relationship relationship= tbsm:identifies relationshipsource= tbsm:identity > <condition attrkeyword = cdm:attrname groupname= testfqqdnwithaction groupoperator= = value= field > </condition> Customizing the import process of the Service Component Repository 103

112 Using identifier rules to associate aliases to a resource This topic describes how Service Component Repository (SCR) resources can be assigned additional identifying names, also called aliases, that are used outside the scope of the SCR naming and reconciliation process. The most common use of the output of identifier rules is to assign TBSM service identification fields to SCR instances for the purpose of assigning values to TBSM template status and numeric rules. TBSM service instances are aligned with status information, such as events, by their identification fields. Identification fields specify a pair of values that include a field name and value. If an event is received that has a matching field name and value as the instance, the event is applied to the resource. Unlike the SCR Naming and Reconciliation process, different resources can share the same identifiers without them being merged into a single resource. A TBSM service instance can be assigned multiple identification fields and multiple values for the same field name. Defining Identifier Rules Using the SCR rule language, identifier field/value pairs are generated by defining rules within the EventIdentifierRules.xml file and in custom identifier XML files. The EventIdentifierRules.xml file contains the default SCR identifier rules. Extend the list of rules by creating one or more XML files that contain the following structure: <?xml version="1.0" encoding="utf-8"?> <EventIdentifierRules version="1.0.0"> <!--... Place custom Mapping and Policy Elements below this comment - > </EventIdentifierRules> Note: The file must start with the first two lines and end with the last line of the structure shown. Use a an Internet browser to confirm the validity of the syntax. An example is shown in the XMLtoolkit/samples/xml/ SampleEventIdentifierRules.xml file. After the file is created, it is imported into the Discovery Library toolkit using the putartifact command using the category specification of eventidentifiers. Only imported files are recognized by the Discovery Library toolkit. If you would like to change a currently imported file, you should extract the current version of the file by using the getartifact command, make the desired changes to the file, and then using the putartifact make it available to the SCR rule engine. After using the putartifact command, the SCR rule engine does not load the new definitions until the Service Component Repository is restarted or the utils command is run with the -e parameter and reload_cdm_definitions.xml as the utility value. To push new identifiers to the TBSM service model, you must validate the top level service instance of the SCR instances. For more information, see the Discovery Library Toolkit commands section of this document. The list of currently imported custom identifier rule files can be acquired by using the listartifacts command with the category option specification of eventidentifiers. Identifier rules follow the same standard schema structure as other SCR rules. As the objective of an identifier rule is to output a identifier name/value pair one or more Token elements are required to output string segments that are concatenated 104 IBM Tivoli Business Service Manager: Customization Guide

113 together to form the identifier value of the rule. The name of the identifier field by default is set to BSM_Identity. However, the name can be altered by specifying the field attribute on the Rule element. Example <Policy name= fqdn > <Rule name="allipfqdn" field= hostname > <Token keyword= FUNC value= class /> <Token keyword= LITERAL /> <Relationship relationship= cdm:runson relationshiptarget= % > <Relationship relationship= cdm:contains relationshiptarget= cdm:net.ipinterface > <Relationship relationship= cdm:bindsto relationshiptarget= cdm:net.ipv4address;cdm:net.ipv6address;cdm:net.ipaddress > <Relationship relationship= cdm:assignedto relationshipsource= cdm:net.fqdn > <Token keyword="attr" value="cdm:fqdn"> <condition operator=!= value= localhost /> </Token> </Relationship> </Relationship> </Relationship> </Relationship> </Rule> </Policy> <Mapping policy="fqdn" class="cdm:app.db.db2.db2instance"> The fqdn policy in this example is activated when the SCR discovers a CDM class instance of cdm:app.db2.db2instance. The purpose of this policy is to use the service instance's relationships to find all of the hostnames of the system it is running on. It generates a string of cdm:app.db2.db2instance@hostname where the hostname value is the hostname of the system the Db2 instance is running on. If the system has multiple hostnames, and the information is provided on the load into the SCR, a string is generated for each hostname of the system. This behavior can be applied to any class whose instances run on an instance of a computer system that has similar relationships to the Db2 instance. The field name for these values is hostname. The Rule processor follows the following steps to generate this string: 1. Place the class instance cursor on the class instance mapped to this policy. 2. Return the class name of the cursor class. 3. Return the 4. Move the cursor to the target instance of any class type over a CDM relationship of type cdm:runson, where the source is the class instance pointed to by the current cursor. 5. Move the cursor to the target cdm:net.ipinterface instance over a CDM relationship of type cdm:contains, where the source is the class instance pointed to by the current cursor. 6. Move the cursor to the target instance either the cdm:net.ipv4address, cdm:net.ipv6address, or cdm:net.ipaddress class over a CDM relationship of type cdm:bindsto, where the source is the class instance pointed to by the current cursor. 7. Move the cursor to the source cdm:net.fqdn instance over a CDM relationship of type cdm:assignedto, where the target is the class instance pointed to by the current cursor. 8. Now that the cursor is on a cdm:net.fqdn class instance, return the value of the cdm:net.fqdn attribute of the cdm:net.fqdn class if the value is not equal to localhost. Customizing the import process of the Service Component Repository 105

114 When a resource from the SCR is loaded as a TBSM service instance, the TBSM identifiers as created by this process are also loaded. As the identifiers are loaded, the SCR process searches all templates that are assigned to the service instance for the TBSM template rules using the field name that matches the field name specified in the Policy/Rule. If matched, the SCR adds the values generated by this process. Default BSM_Identity Every resource imported from the SCR into the TBSM service model has at least one value assigned to all template rules. If a particular instance does not have an SCR Identifier that generates a string for a particular template rule field, TBSM assigns it the service instance name to the identifier which is comprised of the resource's name, GUID, and the CDM class. An example of this is: smith.ibm.com(cf74c1450a33333ca2b14148a8871dca)-aixunitarycomputersystem If you have an imported resource that only has a BSM_Identity with the above format, this means that none of the policies imported into the SCR with the eventidentifiers category has successfully been matched to this resource. Simplifying the TBSM service model using composite rules Simplifying the instance class structure within the Service Component Repository (SCR) for complex class models such as the CDM is an essential step for building a usable service instance model within TBSM. Composite rules allow you to simplify the model by providing a language that manipulates the way the SCR resource instances and the relationships between these resource instances are viewed in the TBSM service model. You can define composite rules that: v Aggregate a set of instances consisting of a root instance and its related subcomponent instances. This aggregated instance is viewed in the TBSM service instance model as one instance with the sum of all attributes and relationships v Create an instance that results from the existence of a particular imported instance structure v Create relationships between two relationships that would otherwise not have one Defining composite rules Using the SCR rule language, composite rules are defined in the CDM_TO_TBSM4x_MAP.xml file and in custom composite XML files. The CDM_TO_TBSM4x_MAP.xml file contains the default TBSM composite rules. You can extend the list of rules by creating one or more XMLfiles that contain the following structure: <?xml version="1.0" encoding="utf-8"?> <CompositeDefinitions version="1.0.0"> <!--... Place custom Mapping and Policy Elements below this comment - > </CompositeDefinitions> Note: The file must start with the first two lines and end with the last line of the structure shown. Use an Internet browser to confirm the validity of the syntax. An example is shown in the XMLtoolkit/samples/xml/SampleCompositeRules.xml file. 106 IBM Tivoli Business Service Manager: Customization Guide

115 After the file is created, it is imported into the Discovery Library Toolkit using the putartifact command with the category specification of composites. Only imported files are recognized by the Discovery Library Toolkit. If you would like to change a currently imported file, you should extract the current version of the file by using the getartifact command, make the desired changes to the file, and then using the putartifact to make it available to the SCR rule engine. After using the putartifact command, the SCR rule engine does not load the new definitions until the Service Component Repository is restarted or the or the utils command is run with the -e parameter and reload_cdm_definitions.xml as the utility value. The list of currently imported custom composite rule files can be acquired by using the listartifacts with the category option specification of composites. Composite rules follow the same standard schema structure as other SCR rules. However, unlike the other rules that output a string, the objective of composite rules is to identify candidate subcomponents of the root component that have been mapped to the policy. The Component element within a Rule element is used by composite rule engine to mark the instance pointed to by the instance cursor as a candidate subcomponent. Only one Component tag is allowed in a Rule tag. The following example from the CDM_TO_TBSM4x_MAP.xml file shows a composite rule: <Policy name="nodes"> <Rule name="os"> <Relationship relationship= cdm:runson relationshipsource= cdm:sys.aix.aix > <Component/> </Relationship> </Rule> <Rule name="interfaces"> <Relationship relationship= cdm:contains relationshiptarget= cdm:net.ipinterface > <Component/> </Relationship> </Rule> <Rule name="fqdn"> <Relationship relationship= cdm:contains relationshiptarget= cdm:net.ipinterface > <Relationship relationship= cdm:bindsto relationshiptarget= cdm:net.ipv4address > <Relationship relationship= cdm:assignedto relationshipsource= cdm:net.fqdn > <Component/> </Relationship> </Relationship> </Relationship> </Rule> <Rule name="osipaddress"> <Relationship relationship= cdm:contains relationshiptarget= cdm:net.ipinterface > <Relationship relationship= cdm:bindsto relationshiptarget= cdm:net.ipv4address > <Component/> </Relationship> </Relationship> </Rule> </Policy> <Mapping policy= Nodes class= cdm:sys.aix.aixunitarycomputersystem /> The composite rule processor is activated by the Mapping element. In the previous example, the existence of an AIX computer system starts the process of creating Customizing the import process of the Service Component Repository 107

116 the composite for the AIX host by driving the Nodes policy. The Nodes policy defines a set of rules. The following list displays the result of each rule: v The OS rule adds in the related AIX operating system instance. v The Interfaces rule adds in all related interface instances. v The fqdn rule adds in all related cdm:fqdn class instances (the hostnames of the system are captured in the cdm:fqdn instances) v The OSIPAddress rule adds in the related IP address instances (the IP addresses of the system) As a result, the original AIX computer system class instance is now the root of a composite that contains information on all of the other objects. When TBSM uses the SCR to access the AIX computer system object, its view of that object includes all of the attributes, relationships, and TBSM identifiers for all class instances in the composite. Since these instances are seen as a composite with the root as the access point for the composite, the only object that needs to be mapped to a TBSM template is the AIX computer system. To simplify working with the composite, all relationships, attributes, and TBSM identifiers are viewed as belonging to the root instance. If the operating system object of the composite has a relationship to another CDM object outside of the composite, it is also presented as a relationship of the root object. Initiating external action using notification rules At times it might be desirable to drive external actions as a result of the creating, deleting, or updating of resource and relationship information in the Service Component Repository (SCR). Notification rules enable initiation of Tivoli Impact IPL or JavaScript policies when the Notification rules are met to support resource enrichment. Notification rules in conjunction with Tivoli Impact policies and the SCR API, can be used to perform such actions as: v sending an when the SCR is aware of a new resource instance of a particular class; v accessing an external source about SCR objects whose data could then be used to add additional resource attribute about the resource within the SCR; and v applying a naming convention policy about the object to place the object within a container object based on the value of a resource attribute such as its fully qualified domain name. Defining notification rules Using the Service Component Repository (SCR) rule language, notification rules are defined in the NotificationRules file and in custom XML files. The NotificationRules.xml file contains the default TBSM notification rules. You can extend the list of rules by creating one or more XML files that contain the following structure: <?xml version="1.0" encoding="utf-8"?> <NotificationRules version="1.0.0" <!--... Place custom Mapping and Policy Elements below this comment - </NotificationRules> 108 IBM Tivoli Business Service Manager: Customization Guide

117 Note: The file must start with the first two lines and end with the last line of the structure shown. Use a an Internet browser to confirm the validity of the syntax. An example is shown in the XMLtoolkit/samples/xml/ SampleNotificationRules.xml file. To simplify the processing of notifications, the Policy element for notification rules can contain an attribute name action whose value is provided with the notifications that policy produces. If used, this field can simplify the process of associating a particular a Impact policy with a particular notification. After the file is created, it is imported into the Discovery Library toolkit using the putartifact command with the category specification. The category specification is included as the -c parameter to the putartifact command of notifications. Only imported files are recognized by the Discovery Library toolkit. If you would like to change a currently imported file, you should extract the current version of the file by using the getartifact command, make the desired changes to the file, and then using the putartifact to make it available to the SCR rule engine. After using the putartifact command, the SCR rule engine does not load the new definitions until the SCR is restarted or the or the utils command is run with the -e parameter and reload_cdm_definitions.xml as the utility value. After the new rules are loaded they are applied to resources as they are imported into the SCR. If you would like to generate event identifiers for the resources currently in the SCR without waiting for a future import process to include the resources, issue the utils.sh command using the -e option of reload_notifications.xml. In this case, the SCR send notifications with the scc_productname field of the trigger to REBUILD_NOTIFICATIONS allowing the enrichment policy to act accordingly. The list of currently imported custom notification rule files can be acquired by using the listartifacts command with the category option specification of notifications. Since notification rules produce strings, their definition is almost identical to the definition of identifier rules. However, rather than the output of the rule being paired with a field name such as the BSM_Identity, notification rules output a string and supporting data that is then made available to an Tivoli Impact Event Reader to allow it to react to the situation detected by the notification rule. Notifications are written, with the TBSM SCR schema, to two tables in the TBSM database. Since a policy or rule element might produce multiple notification strings, the two tables work together to capture that notification details. One entry to the TRIGGER_ENRICHMENT table is created each time a policy or rule executes for a given root node and produces at least one notification string. The details of all notification strings for that policy or rule execution is captured in the TRIGGER_ENRICHMENT_DETAILS table. Table 37. TRIGGER_ENRICHMENT table Notification field ID create_time delete_time Description The unique identification of the row The time that the row was created The time that the row was available to be cleaned up Customizing the import process of the Service Component Repository 109

118 Table 37. TRIGGER_ENRICHMENT table (continued) Notification field notify_state policy_name policy_rule action_name src_productcode stage_time Description 0 indicates that the notification is be written, 1 indicates that the notification is ready to be processed, and 2 indicates that the notification has been processed. The policy name that created the notification The policy rule name that created the notification The action attribute from the policy that created the notification A string that is set to REBUILD_NOTIFICATIONS to indicate that notifications are being refreshed. Table 38. TRIGGER_ENRICHMENT_DETAILS table Notification string enrichment_id guid comp_id class_name notification Description This is a reference to the TRIGGER_ENRICHMENT table ID column If it exists, this is the guide to the object that was mapped to the notification policy that generated the notification. The SCR identifier of the root object that created the notification The class name of the root object The notification string produced by the policy or rule Using a Impact Event Reader, an Impact policy can process new entries in the TRIGGER_ENRICHMENT table. Using the ID column of the TRIGGER_ENRICHMENT table to reference the details of the notification in the TRIGGER_ENRICHMENT_DETAILS table, the Impact policy can then act on the notification. When the Impact policy is completed, set the TRIGGER_ENRICHMENT notify_state column to the value of 2 which indicates that the notification has been processed. The Discovery Library Toolkit cleans up entries in the notification tables when the entries exceed the TRIGGER_ENRICHMENT delete_time value or the notify_state value has a value of 2. The TBSM installation process creates a Impact event reader named ResEnrichReader within the Impact project named TBSM_BASE. Disabled by default, this reader is configured to periodically read new entries in the Trigger enrichment table and drive the ResEnrichMain Impact policy to process the notification. The ResEnrichMain policy is structured to key off the action_name column value and drive a different Impact policy to take the desired action. It is recommended that you extend the ResEnrichMain policy to add additional policies to process notifications or create your own event reader for your notifications. If the latter is done, you must configure any Impact Event Reader that is watching the trigger table so that their processing does not conflict with one another. 110 IBM Tivoli Business Service Manager: Customization Guide

119 Merging custom namespace instances using reconciliation rules Custom namespace definitions allow the Service Component Repository (SCR) to be aware of class structures beyond the common data model (CDM). However, reconciliation facilities in the SCR only reconcile resource instances within a namespace. The SCR merges information about a resource from different sources based on naming rules. This means that the base supports only reconciliation of data when both sources of resource information communicate using the same namespace. The Cross Namespace Reconciliation feature allows you to build rules that reconcile data that is captured from sources that use a different namespace. This is an extension of the Custom Namespace support that allows you to integrate resource information outside the IBM CDM namespace. However, when a CDM discovery source is introduced into the environment and it is capable of discovering a resource that is also represented by a Custom Namespace discovery source, you can create a reconciliation rule to merge the resource instances into one rather than the two that exist without the reconciliation rule. For example, if the source of resource and relationship data communicates its information using a custom namespace of mynamespace and one of the classes it supports is myserver. In addition to providing special identifying information to the myserver instance, the source also provides an attribute named mynamespace:hostname containing the fully qualified hostname of the server. Another source of resource data captures information about a server and knows it in CDM terms. It reports an instance of the CDM class type cdm:sys.linux.linux and includes the CDM attributes that provide naming and an additional attribute named cdm:fqdn with the fully qualified hostname of the resource. Without any further customization, the SCR does not recognize these resources as being the same and maintains awareness of both instances. However, the Cross Namespace Reconciliation features allows a reconciliation rule to be defined, that instructs the SCR to merge a resource within the CDM namespace and a resource in the mynamespace namespace when the cdm:fqdn attribute is the same as the mynamespace:hostname attribute. Defining CrossNamespace rules Using the SCR rule language, CrossNamespace rules are defined within the CrossNamespaceNamingRules.xml file. You can add reconciliation rules by adding them within the CrossNamespaceNamingRules element. The file is then imported into the Discovery Library toolkit when you run the putartifact command specifying the scrconfig category. Only one imported file is recognized by the Discovery Library Toolkit. If you want to change the currently loaded rules, you can retrieve the current version of the CrossNamespaceNamingRules.xml file using the getartifacts command specifying the category of scrconfig. You can then edit this file and reimport it. After you have done so, the SCR reads the new configuration files from the artifact store at startup or when instructed to do so by the utils command with the -e option set to reload_cdm_definitions.xml. Customizing the import process of the Service Component Repository 111

120 Cross namespace rules As cross namespace rules produce strings that are used to match resources to be reconciled, the definition of these rules is almost identical to the definition of identifier rules. However, rather than the output of the rule being paired with a field name such as the BSM_Identity, cross namespace rules output a string that is used to find a matching resource in another namespace that produces the same string. Therefore, to be effective, cross namespace rules must be written in pairs, one for each namespace class instance that could potentially be reconciled. The following is an example of a cross namespace rule file that can be imported into the Discovery Library toolkit: <CrossNamespaceNamingRules version="1.0.0"> <Mapping policy = 'mynamespace_host_id class= mynamespace:myserver /> <Policy name='mynamespace_host_id > <Rule name='mynamespace_host_id_rule1 > <Token keyword= ATTR value= mynamespace:hostname case= lower /> </Rule> </Policy> Mapping policy = 'cdm_host_id class= cdm:sys.linux.linux /> <Policy name='cdm_host_id > <Rule name='cdm_host_id_rule1 > <Token keyword= ATTR value= cdm:fqdn case= lower /> </Rule> </Policy> </CrossNamespaceNamingRules> These rules are activated by the Discovery Library toolkit whenever a instance of either the mynamespace:myserver or cdm:sys.linux.linux is imported into the SCR. Each rule captures the proper value of the particular instance that represents the hostname of the system. The value is converted to lower case to make sure that it is captured in a consistent case. When the Discovery Library toolkit reconciliation process executes, it attempts to match resulting strings from the rules from different resources in different namespaces. If a one or more matches is found, the process to merge the information of the two instances is initiated. When cross namespace naming rule determines that a CDM and a non-cdm resource must be merged, the CDM class designation is maintained as the class of the resulting resource. Altering a resource display name using labeling rules By default, the source of the discovery information controls the display name of the resource it describes. There are cases when the discovery source might not provide a display name and there are cases when a different label than the source-chosen display name is desired. Labeling rules enable you to customize the attributes used to provide a label when one is not provided by the source. They also allow you to override the source-provided label. Defining Labeling Rules Classes within a Discovery Library book or Tivoli Application Dependency Discovery Manager (TADDM) might be instantiated without a cdm:label attribute. This attribute is used to display the name for the instance when it is loaded as a service instance into TBSM. Labeling rules enable you to assign labels to resources that do not have one assigned. The LabelingRules.xml file also enables you to override labels from a discovery library book or TADDM that are insufficient. Since labeling rules produce strings, their definition is almost identical to the definition of identifier rules. 112 IBM Tivoli Business Service Manager: Customization Guide

121 Using the Service Component Repository (SCR) rule language, labeling rules are defined in the LabelingRules.xml file and in custom XML files. The LabelingRules.xml file contains the default TBSM labeling rules. You can extend the list of rules by creating one or more XML files that contain the structure described in the Labeling Rules section. After the labeling rules file is created, it is imported into the Discovery Library Toolkit using the putartifact command with the category specification. The category specification is included as the -c parameter to the putartifact command of labeling. Only imported files are recognized by the Discovery Library Toolkit. If you want to change a currently imported file, extract the current version of the file by using the getartifact command, make the desired changes to the file, and using the putartifact command make it available to the SCR rule engine. After the new rules are loaded they are applied to resources as they are imported into the SCR. If you want to generate new labels for the resources currently in the SCR without waiting for a future import process to include the resources, issue the utils.sh command using the -e option of reload_label_definitions.xml. For the new labels to be pushed to the TBSM service model, you must invalidate the top level service instance of the SCR instances. Labeling Rules The following syntax shows tags in the LabelingRules.xml file that can be used to override labels from a discovery library book: <LabelingRules> <!--... Place custom Mapping and Policy Elements that output a string below this comment --> <OverLayLabelsForCDMClasses> <class>classname</class> <class>classname</class> </OverLayLabelsForCDMClasses> </LabelingRules> <Policy name="name"> <Rule name="name" field="name"> <Token keyword="attr LITERAL SOURCETOKEN FUNC" value="class"/> <Relationship relationship="type" relationshiptarget="target" relationshipsource="source"> <Token keyword="attr LITERAL SOURCETOKEN FUNC" value="class"/> </Relationship> </Rule> </Policy> <Mapping policy="name" class="class" exclusive= true false > <OverLayLabelsForCDMClasses> <class>class</class>... <class>class</class> </OverLayLabelsForCDMClasses> The Mapping statement for labeling rules may have a additional attribute named exclusive that is not pertinent to other rules. If the exclusive attribute is set to true then the he policy it names is the only policy that is used to generate a label for the instance of the specified class. Otherwise, all mapped policies for a class are executed in order and the first policy rule that generates a new label is applied to the instance. Customizing the import process of the Service Component Repository 113

122 The default behavior for labeling is to use the CDM attribute named cdm:label or tbsm:label as the TBSM display name for the resource. To instruct the labeling rule processor to override an existing label, include a class element within the OverLayLabelsForCDMClasses tag. One class element must be used for each class whose label is overridden if a policy or rule can generate a new label. The following example from the LabelingRules.xml file shows the default labeling policy for all classes that do not have a label: In the following example, the mapping policy specifies % for the class, so the global policy applies to all classes. The global policy contains the following two rules: 1. NameAttr1, looks for the cdm:name attribute. If it is found and its value is not localhost, the value of cdm:name is used for the label. 2. NameAttr2 functions is NameAttr1 fails. It looks for the attribute cdm:managedsystemname. If found, the value of this attribute is used for the label. <Policy name="global"> <Rule name="nameattr1"> <Token keyword="attr" value="cdm:name"> <condition operator="!=" value="localhost"/> </Token> </Rule> <Rule name="nameattr2"> <Token keyword="attr" value="cdm:managedsystemname"> </Token> </Rule> </Policy> <Mapping policy="global" class="%"/> Importing resource models into the SCR with custom namespace support This section contains information, instructions, and examples of how to perform a Discovery Library Toolkit import containing custom namespace resource models using either an idml book or the SCR API. Custom namespace and the Discovery Library Toolkit The Discovery Library Toolkit has been enhanced to support resource models of a custom namespace. A custom namespace consists of two parts; a namespace designation and a class designation. The namespace designation is a container or a domain classification for its class definitions. The class designation provides a specific description of the entity it describes within the namespace. Service Component Repository (SCR) namespaces are of the form namespace:class. Within the SCR, identifying data with a different namespace than the CDM namespace, simplifies the resource identification process by making it the responsibility of the source of the resource information only. When working with custom namespaces, the Discovery Library Toolkit plays a less significant role in the naming (identification) and reconciliation (resource correlation) process that it provides for CDM sources. Beyond these differences, resources and relationships imported through custom namespace support are imported through the same process, as their CDM counterparts, including template mapping and event identification. 114 IBM Tivoli Business Service Manager: Customization Guide

123 Custom namespace overview The Service Component Repository (SCR) is a class-based repository of resource, attribute, and relationship information that supports the building of TBSM service model instances. However, the SCR validation of the resource instance information against the model it represents is limited to assuring that the instance data contains identifying information about the resource. This allows the SCR to uniquely identify the resource and to reconcile, or merge, resources from different sources with the same identifying information. The Common Data Model (CDM) is a specific namespace resource model that defines a set of identification rules that the SCR supports. These rules ensure proper identification and merging, or reconciliation, of resource instances across many sources of information. With the SCR cross namespace support, resource identification is simplified to a single attribute and is the responsibility of the provider of the data. For this reason, proper use of the namespace and class designation is an important ingredient for a successful import of data into the SCR. Custom namespaces allow you to distinguish class categorizations of items that have the same name, but that are not the same entity. As an example, an item with the class designation of mynamespace:car is different from an item with a class designation of yournamespace:car. In this case, even though both items have the same root name car, the names can be handled differently because they belong to different namespaces. The Discovery Library Toolkit takes advantage of custom namespaces so that it can process discovered information from multiple sources without accidentally overlapping the identification of items contained within the information. A custom namespace is implemented by including a namespace prefix on all item names. The tbsm namespace, along with the naming attribute tbsm:identity, is the default custom namespace. For the TBSM namespace, the namespace prefix is tbsm. An example item name is tbsm:windowsserver. The tbsm namespace is an implementation of a custom namespace that is recognized by the Discovery Library Toolkit without any customization. Despite the out of box support for the tbsm namespace and the tbsm:identity naming attribute, it is strongly recommended that you use a namespace designation other than tbsm. Benefits of using a custom namespace Using a custom namespace, you can import non-common data model (CDM)-compliant sources of resource and relationship data while at the same time taking advantage of the built-in efficiencies that the Discovery Library Toolkit provides when you are working with the TBSM memory-based service model. Using custom namespace support provides these benefits: v A solution for creating resources from data sources that do not comply with the CDM standard. This can be particularly useful when the effort involved in converting a data source to CDM is prohibative. v The Discovery Library Toolkit interacts with the TBSM memory-based model to make sure that it stays current in an efficient and robust way. v A more efficient solution for resource creation when compared to External Service Dependency Adapters (ESDA) resource creation. Book processing can be completely automated whereas ESDA processing can be manual. v Non-CDM resources are staged through the same process as CDM resources when they are processed by the Discovery Library Toolkit. Therefore, techniques used for template mapping, composite definitions, and generating event identification strings can be applied to non-cdm information. Customizing the import process of the Service Component Repository 115

124 v The unique identity for a resource is provided by the source of the data. Unlike the more involved naming (identification) process for CDM resources, the Discovery Library Toolkit follows the unique identifier provided in one attribute of the resource. The source of the data has complete control and responsibility for the naming process. Limitation of using a custom namespace There are some limitations when using a custom namespace. idml books with content that includes custom namespace definitions cannot be consumed by other products such as Tivoli Application Dependency Discovery Manager (TADDM). Choosing a custom namespace It is important not to make the choice of a namespace and class definition overly complex or trivial. Follow these guidelines when choosing a custom namespace. v Choose a custom namespace to represent the domain or source of the resource information. The chosen namespace can be as broad as a value that represents your company or as specific as a reference to the source of the information within your organization. v Choose a class name to represent a general category description of the resource. For example, if you are modeling typical IT components, you might want to use class names such as server, application, appserver, cluster, webserver, transaction, and router. If you are modeling a building consider building, floor, office, and conference room. v Choose an appropriate naming attribute for each class. Service Component Repository (SCR) reconciliation for custom namespace objects is based on the attribute name that is used for identification. Therefore choosing the naming attribute is just as important as choosing the class name. v If you are modeling a business system, use the common data model (CDM) class named cdm:sys.businesssystem since the CDM naming rules for it can be satisfied by including an identifying value for a single attribute named cdm:name. Defining a custom namespace It is best practice to use a custom namespace rather than the default tbsm namespace. Using a custom namespace allows you to create a namespace that better reflects your environment. It is also a best practice to define a different identity attribute, also called the naming attribute, other than the default tbsm:identity attribute. To define a custom namespace and its identity attribute, you must amend the OtherNamespaces.xml file in the scrconfig category. Extract the current version of this file using the getartifact command, make the changes described below, and use the putartifact command to add the file back into the system. The Discovery Library Toolkit must be restarted for the change to take effect. For information about the getartifact and putartifact commands, see the Exporting and importing customization artifacts section of the TBSM Administrator's Guide. This example outlines the contents of the OtherNamespaces.xml file. It shows custom namespace definitions for three classes: my:server, my:application, and my:default. Both the my:server and my:application class names also define the attribute value within the idml book that is used as the identifier for each of their respective classes. The my:default class does not specify an identifier attribute so its identifier value defaults to tbsm:identity. <document> <NameSpaceDefinition classname= my:server identityattribute= serveridentity /> 116 IBM Tivoli Business Service Manager: Customization Guide

125 <NameSpaceDefinition classname= my:application identityattribute= applicationidentity /> <NameSpaceDefinition classname= my:default /> </document> After this file is properly customized, reinserted into the system using the putartifact command, an import containing custom namespace resources can be successfully loaded into the SCR. Importing resource information into the SCR The process for importing resource, attribute, and relationship data into the Service Component Repository (SCR) is the same whether you use an idml book or SCR application programming interface (API). The process can be broken into four segments: v Header v Payload operation v Payload v Tail or footnote. Note: You can create multiple operation and payload sections within a single header and tail. Using the Service Component Repository (SCR) Application Programming Interface (API) is similar to building an idml book. The same components of an idml book are represented in an SCR API implementation. When you use the SCR API, each of these segments is implemented by an Impact function call. When you use idml books, the different segments are contained in the different sections of the idml book as XML elements. Defining the header: The header begins the import process by providing a beginning marker to the process and by identifying the source of the resource information contained in the payload component. The term management software system (MSS) is the term used to refer to this source entity. The header defines the source that is associated with the payload containing resource, attribute, and relationship information. All resource and relationship information imported through the Discovery Library Toolkit is associated with a source, and import operations are performed within the context of that source. As resource information is imported by the Discovery Library Toolkit, a reference counter is maintained for each resource. The reference counter counts the number of different sources that have referred to that resource. If two sources indicate that a particular resource exists, but only one of them indicates that it must be removed, the reference counter is decremented but the resource is not deleted until the reference counter moves to 0. The key pieces of information that identify the MSS of the resource data are included in the following table: Table 39. Components of the MSSName Name Description Customizing the import process of the Service Component Repository 117

126 Table 39. Components of the MSSName (continued) ManufacturerName ProductName Hostname MSS Identity The name of the entity that produced the book, for example, ABC Corp. The name of the product for which this book was created, for example, CustomCCMDDatabase. Used to distinguish between two different instances of the same producer. A unique string that clearly identifies a particular MSS. Typically this string consists of the other components within this table and takes the format: ibm-cdm:///cdmmss/manufacturername= CustomerNameHere+ProductName= SomethingtoDenoteThisBookNa mehere+productname=hostname Within an idml book, the management software system is defined in the cdm:process.managementsoftwaresystem XML element and its unique identity is provided within the cdm:mssname tag. When you use the SCR API, the header is provided by the SCRRegister function. Defining the operation: The payload operation section of an Service Component Repository (SCR) import provides context to the payload contents. There are two major payload operations and three sub operations. v refresh: indicates to the Discovery Library Toolkit that the content of the payload section is the totality of what the source knows about all its resources, relationships, and attributes. The SCR synchronizes with this information, in other words, resources and relationships that are not in the payload that were in previous imports are removed, and new resources and relationships that are added. All components and relations in a refresh operation are enclosed in a create sub operation. v delta: is an implied operation when the refresh operation is not specified. Delta operation indicate to the SCR to perform the action identified by the sub operation create, modify, or delete. idml book operation The idml book provides the Discovery Library Toolkit with the operation to be applied using XML tags. The appropriate operation element must be a parent element of the resource and relationships to which it applies. The idml standard defines the following three operations that the book can describe: v create: adds the following objects, relationships, and attributes v delete: deletes the following objects and relationships v refresh: indicates to the Discovery Library Toolkit that the content of the book is the totality of what the source knows about all its resources, relationships, and attributes. The reader of the book synchronizes with this information, in other words, resources and relationships that are not in the book that were in previous books are removed, and new resources and relationships that are added. 118 IBM Tivoli Business Service Manager: Customization Guide

127 The appropriate operation element must be a parent element of the resource and relationships. Creating, deleting, and synchronizing a payload Use the following operation tags to create a payload: <idml:operationset opid="1"> <cdm:create> <!--Payload --> </cdm:create> </idml:operationset> Use the following operation tags to delete a payload: <idml:operationset opid="1"> <cdm:delete> <!--Payload --> </cdm:delete> </idml:operationset> Use the following operation tags to synchronize the payload. The refresh and create tags are required. The delete tag is not relevant within a refresh operation. <idml:operationset opid="1"> <cdm:refresh> <cdm:create> <!--Payload --> </cdm:create> </cdm:refresh> </idml:operationset> Using the SCR API to define the operation The SCRRegister function initiates the SCR API process and data acquisition. It also identifies the major payload operation. The sub operation are implicitly defined by the function that is used to define the payload SCRCreateComponentInfo, SCRCreateRelationship, SCRDeleteComponentInfo, and SCRDeleteRelationship. Defining the payload: The payload component of an Service Component Repository (SCR) import is the most important section as it defines the resources, attributes, and relationship information that is imported and persisted within the SCR. The requirements for building a proper payload are: v All payload information must conform to SCR standards. This means that if a common data model (CDM) class is added to the payload, its class name, identity attribute names, and relationship types, that participate in the identification process, must exactly match, including case, the class model information as defined in the NamingRules.xml file. v It must be possible to resolve all component payload information to at least one valid identity string, also known as its name or naming string. This is so that the resource is uniquely identified to the SCR. For CDM resources, correct naming is defined by the NamingRules.xml file provided by IBM. The Custom Namespace function supports a simple naming strategy based on the source of the data taking sole responsibility for this process by providing a unique value for a single attribute of the resource. By default, the attribute named tbsm:identity contains the unique identity for custom namespace resources. If you use multiple custom namespaces within an SCR instance, you must define the Customizing the import process of the Service Component Repository 119

128 namespace-based identity attributes in the OtherNamespaces.xml document. This reduces the likelihood that two or more sources provide the same identify string for different resources. v Resource component information includes the resource's namespace and class, attributes of the resource, and an optional source token for this resource. One of the attributes must be the naming attribute that is used for the particular class. This information if properly provided is persisted in the SCR. It is recommended that attributes are provided with a namespace designation (namespace:attributename). The source token for a resource allows the source of the payload to pass along a value whose context is only understood by the source itself. In many cases, this value is set to a unique identifier on the source system that can be easily used to look up the resource on the external source system. This value is typically used to enable launch in-context scenarios and can be used to match status events against the resource. The SCR persists the source token and makes it available to the TBSM service model as an attribute. It is also available to be used in event identification rules. v Resource information must also include a string whose value is scoped to a single import operation. Its value is used to uniquely identify the resource within the import process therefore the provider of the payload is responsible for its uniqueness. Its value is commonly used to provide the source and target resource identifiers for relationship information. This value is referred to as the bookid when building an idml book and the transientid when using the SCR API. Though very important to the import process, the identifier has nothing to do with the eventual SCR naming process that must be satisfied in order for the resource to be successfully persisted in the SCR. v To define a relationship between resources, a relationship type, source resource identifier and target resource identifier must be specified. The resource identifiers are the scoped resource identifiers previously referred to as the bookid or transientid. A namespace identifier is also recommended for the relationship type of the form namespace:reltype such as tbsm:depends or myns:uses. v As is the case with resource, attribute, and relationship information from a CDM source, a successful import of data into the SCR does not necessarily guarantee that the loaded data will be pushed into the TBSM service model. Resource class mapping, relationship dependency definition and the class attributes may need to be configured to be available to the TBSM service model. v Relationships are defined by providing a relationship type, source identifier of a resource, and the target identifier of a resource. By default, if both resources are represented in the TBSM service model, the source resource is the parent of the target relationship. For information about on how to change this default behavior, see Relationship Mapping on page 90. v It is good practice to provide the ability to generate a refresh transaction for all sources of resource data whether or not the source supports a delta transaction. v There are additional requirements for abstract resources. These requirements are discussed in subsequent topics. When you use SCR API, the SCRCreateComponentInfo and SCRCreateRelationship functions are used to create the resource, attribute, and relationship information that is persisted in the Service Component Repository (SCR). The purpose of these functions is to add resource and relationship information into the SCR Application Programming Interface (API) transaction payload. When building a custom namespace idml book, the payload takes the form of a set of XML elements that describe the resources, attributes, and relationships and is contained within the book operation. 120 IBM Tivoli Business Service Manager: Customization Guide

129 Abstract resources Abstract references can be used when you want to add an attribute or relationship to a resource, but do not want to associate the source or MSS of the data. In SCR terms, each source that requests that a resource be created updates a reference counter for the component. If a single source instructs the SCR to delete a resource, all attributes that are only provided by that managed software system (MSS) are removed, and the reference counter for the resource is decremented. When the counter goes to zero, in other words, when there are no source references to the object left, the resource is removed from the SCR. Programming an abstract resource reference does not update the reference counter. This technique is advantageous when using Impact to enrich the attributes of a discovered resource. Consider the situation where an Impact policy is used to add the latitude and longitude values for a resource so that a mapping service could be used to locate the object on a map. In that case, Impact is a source of the attributes and must not be considered when the existence of the resource is being evaluated. Using abstract resources The following is a list of implementations for abstract resources which allow the SCR to locate the referenced object that must already exist within the SCR. They are listed from most efficient to least efficient. In all cases the class is set to cdm:abstractresource v Abstract resource attribute named cdm:resourceguid whose value must be set to the GUID of the object. v Abstract resource attribute named cdm:externalidentity must be set to the sourcetoken of the object and an attribute named ExternalSystemName must be set to the MSS cdmidentity related to the sourcetoken v Abstract resource attribute named tbsm:identity whose value is a string pattern where the first token is the name of an event identifier field and the second token is the value of that particular identifier. The tokens are separated by and equal (=) sign. For example, the value of the attribute might be BSM_Identity=some value v Abstract resource attribute named tbsm:attr: whose value is a string pattern where the first token is the name of an attribute and the second token is the value of that particular attribute for the resource to be referenced. The tokens are separated by and equal (=) sign.. For example, cdm:name=some_value_for_cdmname. Defining the tail: The tail component of an Service Component Repository (SCR) import simply marks the end of the import process and communicates that the contained information is ready to be processed by the SCR. For an idml book, the tail is the required XML to properly close the XML elements of the book. The resulting idml book is processed by the Discovery Library Toolkit when it is placed in the defined directory that it monitors for new books. For SCR API imports, the tail is communicated via the SCRComplete Impact function which also makes the data available to the SCR for processing. Customizing the import process of the Service Component Repository 121

130 Building a custom namespace idml book As described in the previous section, successfully building a custom namespace idml book requires the successful definition of the header, payload operation, payload, and tail sections. When combined together, these sections form a correct idml book. This section describes how to correctly construct the structure and content of an idml book. idml header overview: The header section of an idml book begins the XML document, defines the appropriate namespaces, and identifies the MSS to be associated with the payload. Defining the beginning of the XML document and the XML namespace prefixes: All XML documents must have a single enveloping starting tag and an end tag. In the case of idml books the first tag must be <idml:idml>. Within this tag, the namespaces contained within the book must be defined. The idml:idml tag that defines the idml, cdm, tbsm, and xsi namespaces is shown in the following example: <idml:idml xmlns:idml=" xmlns:cdm=" xmlns:tbsm=" xmlns:xsi=" xsi:schemalocation=" idml.xsd"> To define a custom namespace prefix, so that it can be used properly as a part of the element name in an XML document, a similar xmlns attribute must be added to the idml:idml tag. The syntax of the xmlns is: xmlns:prefix="uri" You must provide values for both the prefix and the URI for your custom namespace. The prefix value must be kept under six characters in length. The URI portion of the attribute is a Universal Recourse Identifier (URI) that is a string used to identify an Internet resource. Typically this string is your company URL that identifies your Internet domain address such as xmlns/swg/tbsm. Note: The idml tag must be the top most containing tag in the file. Optionally, the XML encoding declaration can be included as the first line. It takes the following form: <xml version="1.0" encoding="utf-8"/> Defining the MSS: The header includes identifying information about the source of the resource information contained in the payload section. The term management software system (MSS) is the term used to refer to this source entity. The management software system is defined in the cdm:process.managementsoftwaresystem XML element and its unique identity is provided within the cdm:mssname tag. 122 IBM Tivoli Business Service Manager: Customization Guide

131 The cdm:mssname tag has the following format: <idml:source IdMLSchemaVersion="0.8"> <cdm:process.managementsoftwaresystem CDMSchemaVersion="2.7"> <cdm:mssname>ibm-cdm:///cdmmss/manufacturername= CustomerNameHere+ProductName=SomethingtoDenoteThisBookNameHere +ProductName=Hostname</cdm:MSSName> </cdm:process.managementsoftwaresystem> </idml:source> Example header section: The following example shows a valid header section: <?xml version="1.0" encoding="utf-8"?> <idml:idml xmlns:idml=" xmlns:cdm=" xmlns:tbsm= xmlns:my=" xmlns:xsi=" xsi:schemalocation=" idml.xsd"> <!--Header... =================================================== --> <!-- Source and Software... --> <idml:source IdMLSchemaVersion="0.8"> <cdm:process.managementsoftwaresystem CDMSchemaVersion="2.7"> <cdm:mssname>ibm-cdm:///cdmmss/manufacturername= mycompany+productname=mycompanysourceproduct +hostname=host1</cdm:mssname> </cdm:process.managementsoftwaresystem> </idml:source> <!-- book operation to follow --> Payload operation: The payload operation section of the idml book provides context to the payload contents the operation tags contain. Use the following operation tags to create a payload: <idml:operationset opid="1"> <cdm:create> <!--Payload --> </cdm:create> </idml:operationset> Use the following operation tags to delete a payload: <idml:operationset opid="1"> <cdm:delete> <!--Payload --> </cdm:delete> </idml:operationset> Use the following operation tags to synchronize the payload. The refresh and create tags are required. The delete tag is not relevant within a refresh operation. <idml:operationset opid="1"> <cdm:refresh> <cdm:create> <!--Payload --> </cdm:create> </cdm:refresh> </idml:operationset> Customizing the import process of the Service Component Repository 123

132 Payload: This section describes the syntax to be used for creating valid XML to communicate resource, attribute, and relationship information. Creating a business service object: The Discovery Library Toolkit maintains a repository of resources and relationships that can be used to build service models within TBSM. However, the Discovery Library Toolkit automatically pushes certain resource class types into the TBSM service model. This service model then imports all of its dependent objects. Although the list of classes that support this behavior is customizable, a common data model (CDM) BusinessSystem object is a defined object that is easy to build within any idml book. Therefore, you might want to use that namespace class to define the high-level resource in the service model. The cdm:name attribute is the only required attribute when you are providing the unique naming of thebusinesssystem resource instance. Mixing namespaces in a book is acceptable and best practice when building resources that are intended to be business systems. To create a business service object, the CDM class name for a business service must be used. This is an example of a business service definition: <cdm:sys.businesssystem id= mybusinessservice sourcetoken= My Business Service > <cdm:name>my Business Service</cdm:Name> <cdm:label>my Business Service </cdm:label> </cdm:sys.businesssystem> To create a Business Service object using the SCR API: // resource myuniverse SCRCreateComponentInfo(DataSource,transactionId,"myuniverse", "cdm:sys.businesssystem", "My Universe", "My Universe",{"cdm:Name", "cdm:displayname"}, {"My Universe", "My Universe"}); //----Create Components----{end}// Defining resources in XML format: This basic syntax is used to capture resource and attribute information: <namespace:classname id= bookreferenceid sourcetoken= source(book writer) local id for object > <namespace:attributename>attribute_value</namespace:attributename> <namespace:attributename>attribute_value</namespace:attributename> <namespace:attributename>attribute_value</namespace:attributename> </namespace:classname> The structure of this XML element is the same for common data model (CDM) objects as well as custom namespace objects. The following example shows two CDM object instances and non-cdm object instances: <cdm:sys.computersystem id="cvtwin05.ibm.com-computersystem" > <cdm:name>cvtwin05.ibm.com</cdm:name> <cdm:label>cvtwin05.ibm.com</cdm:label> <cdm:signature> </cdm:signature> <cdm:type>computersystem</cdm:type> 124 IBM Tivoli Business Service Manager: Customization Guide

133 <cdm:fqdn>cvtwin05.ibm.com</cdm:fqdn> </cdm:sys.computersystem> <cdm:sys.windows.windowsoperatingsystem id="cvtwin05.ibm.com-windowsoperatingsystem" sourcetoken="primary:cvtwin05:nt"> <cdm:managedsystemname>primary:cvtwin05:nt</cdm:managedsystemname> <cdm:name>cvtwin05.ibm.com</cdm:name> <cdm:label>cvtwin05.ibm.com</cdm:label> </cdm:sys.windows.windowsoperatingsystem> <tbsm:resource id= bookid_websphere > <tbsm:restype>j2eeserver</tbsm:restype> </tbsm:resource> <my:server id= myserver1 > <my:serveridentiy>server_1</ my:serveridenty > <tbsm:label>my Server 1</tbsm:Label> </my:server > <my:server id= myserver2 > <my:serveridentiy>server_2</ my:serveridenty > <tbsm:label>my Server 2</tbsm:Label> </my:server > A class resource instance is defined with a containing element that first identifies the class of the resource. In the previous examples, the instances being defined are for the following classes: cdm:sys.computersystem, cdm:sys.windows.windowsoperatingsystem, tbsm:resource, and my:server. These classes are in three different namespaces. This starting element tag must contain the remainder of the elements used for the resource definition. v The set of common data model (CDM) classes that might be instantiated are limited to those defined in the NamingRules.xml document that is included with TBSM. v The tbsm namespace is limited to a class named resource, which mainly serves as an example of how to create custom namespaces. v The mynamespace is a custom namespace that is defined in the OtherNamespaces.xml file. v The attributes of the class tag are id and sourcetoken: The id attribute tag must be unique within the book. The scope of this tag is only within the book and is used by relationship elements to reference the class instance. The id tag is required. This attribute is referred to as the bookid. The sourcetoken attribute tag allows the source of the class instance definition to pass along a value that has context only to the source. A sourcetoken is optional. v Contained within the class tags are a set of sibling elements, each of which provides an attribute of the resource instance and its value. Attribute definitions for an attribute instance include cdm:name, cdm:label,tbsm:identity, and my:serveridentity. For CDM classes, a set of rules that work with attributes and relationships is used to build the unique identity for the class instance. For the tbsm namespace, the tbsm:identity attribute provides the unique identity value for the instance. Customizing the import process of the Service Component Repository 125

134 For custom namespace definitions, one of the attribute elements must be designated to provide the unique identity for the instance of this class or the attribute tbsm:identity can be provided. Defining relationships in XML format: The syntax that is used to capture relationship information is described in this topic. A relationship consists of the following three parts: <[relationship type] [source=book_id] [target=book_id]/> This example defines the two relationships between resources defined in the previous section: <cdm:runson source="cvtwin05.ibm.com-windowsoperatingsystem" target="cvtwin05.ibm.com-computersystem" /> <my:dependent source="myserver1" target="myserver2" /> v A relationship definition is not contained within a class resource instance definition. v A relationship is started with a class designation for the relationship, which is also called the relationship type. Relationship types do not have to be defined in the Discovery Library Toolkit to be created. v The source and target attribute reference the unique book identifier. The id attribute tag on the class instance definition is used to reference the resources within the book that participate in this relationship. v Avoid circular relationships. Payload example: In this example, you define a UserTransaction that is dependent on both an IBM WebSphere Application Server and a DB2 database running on a particular DB2 instance. This example uses the default tbsm namespace. Note: Comments are included to help explain the purpose of the XML content. <!-- this is a comment begin tag The following tags end the comment -> <!-- -this id is only used as reference within the file-book --> <tbsm:resource id= bookid_trans1 > <!-- the toolkit does not enforce values here but it would be wise for you to break your resources up into types which will allow you to map them to templates later on --> <tbsm:restype>usertransaction</tbsm:restype> <!-- the displayname you will see in tbsm --> <tbsm:label>importanttransaction</tbsm:label> <!-- the unique identity string for this object - it must be namespace unique --> <tbsm:identity>usertransaction_uniqueidentify</tbsm:identity> <!-- you can add any number of additional attributes on the object that may be used for your solution... just make sure you follow standard xml formatting --> <tbsm:attr1> attrvalue1</tbsm:attr1> 126 IBM Tivoli Business Service Manager: Customization Guide

135 <!-- the closing tag for the resource definition. </tbsm:resource> <!-- the definition of the websphere resource --> <tbsm:resource id= bookid_websphere > <tbsm:restype>j2eeserver</tbsm:restype> </tbsm:resource> <!-- the db table --> <tbsm:resource id= bookid_dbtable > <tbsm:restype>dbtable</tbsm:restype> <tbsm:label>table1</tbsm:label> </tbsm:resource> <!-- the db instance --> <tbsm:resource id= bookid_db2inst > <tbsm:restype>db2</tbsm:restype> <tbsm:label>db2instance1</tbsm:label> </tbsm:resource> <!-- and now the relationships between them --> <tbsm:uses source= bookid_trans1 target= bookid_websphere /> <tbsm:uses source= bookid_trans1 target= bookid_dbtable /> <tbsm:uses source= bookid_dbtable target= bookid_db2inst /> After being wrapped in a correct header, tail, and footnote section, the XML code can be processed by the TBSM Discovery Library Toolkit and the resources created in TBSM Service Component Repository (SCR). When the resource is in the SCR, the resource is then available to use to build service models. You can also define your resources with custom namespace definitions.for example: <my:server id= server_1 > <my:serveridentiy>server_1</ my:serveridentiy > <tbsm:label>my Server 1</tbsm:Label> </my:server > <my:application id= appl_1 > <my:applicationidentity>appl_1</ my: applicationidentity > <tbsm:label>my Application 1</tbsm:Label> </my: application > <my:default id= rsc_1 > <tbsm:identity>resourcedef 1</ tbsm:identity > <tbsm:label>resource 1</tbsm:Label> </my:default > <my:uses source= appl_1 target= 'server_1 /> <my:dependson source= server_1 target= 'rsc_1 /> Creating the tail and footer of the idml book: The tail and footer of the idml book end the XML elements of the header and operation sections of the document. For example, a refresh operation book is ended with this block of static text: Customizing the import process of the Service Component Repository 127

136 <!-- END OF PAYLOAD --> </cdm:cdm-er-specification> </idml:create> </idml:refresh> </idml:operationset> </idml:idml> A create operation book is ended with this block of static text: <!-- END OF PAYLOAD --> </cdm:cdm-er-specification> </idml:create> </idml:operationset> </idml:idml> A delete operation book is ended with this block of static text: <!-- END OF PAYLOAD --> </cdm:cdm-er-specification> </idml:delete> </idml:operationset> </idml:idml> Note: The XML book cannot be processed by the Discovery Library Toolkit if it is not a valid XML document. A simple test to determine if your book is a valid XML document is to attempt to open it up with a web browser or an XML editor. Reviewing the complete idml book: Combining the header, operation, payload, and tail sections together result in an idml book that can be imported with the Discovery Library Toolkit. The following example can be copied into a separate file and imported into the Discovery Library Toolkit: <?xml version="1.0" encoding="utf-8"?> <idml:idml xmlns:idml=" xmlns:cdm=" xmlns:tbsm=" xmlns:xsi=" xsi:schemalocation=" idml.xsd"> <!-- NOTE THIS IDML BOOK DOES NOT FOLLOW STANDARD IDML CONVENTION ITS CONTENTS ARE SUPPORTED ONLY WITH TBSM 4.2 PLUS ENHANCEMENTS --> <!--Header... =================================================== --> <!-- Source and Software... --> <idml:source IdMLSchemaVersion="0.8"> <cdm:process.managementsoftwaresystem CDMSchemaVersion="2.7"> <cdm:mssname>ibm-cdm:///cdmmss/ ManufacturerName=mycompany+ProductName=myproduct+Hostname= host1</ cdm:mssname> </cdm:process.managementsoftwaresystem> </idml:source> <!-- Operation... --> <idml:operationset opid="1"> <idml:refresh> <idml:create> <cdm:cdm-er-specification> <!-- BEGINNING OF CONTENT --> 128 IBM Tivoli Business Service Manager: Customization Guide

137 <tbsm:resource id= bookid_trans1 > <!-- -this id is only used as reference within the file-book --> <tbsm:restype>usertransaction</tbsm:restype> <!-- the toolkit does not enforce values here but it would be wise for you to break your resources up into types which will allow you to map them to templates later on --> <tbsm:label>importanttransaction</tbsm:label> <!-- the displayname you will see in tbsm --> <tbsm:identity>usertransaction_uniqueidentify</tbsm:identity> <!-- the unique identity string for this object - it must be globally unique this value is used to build the serviceinstancename in tbsm thought it will not be exact --> <tbsm:attr1> attrvalue1</tbsm:attr1> <!-- you can add any number of additional attributes on the object that may be used to your solution... just make sure you follow standard xml formatting --> </tbsm:resource> <tbsm:resource id= bookid_websphere > <tbsm:restype>j2eeserver</tbsm:restype> <tbsm:label>websphere@host1.com</tbsm:label> <tbsm:identity>websphere@host1.com_identity</tbsm:identity> </tbsm:resource> <tbsm:resource id= bookid_dbtable > <tbsm:restype>dbtable</tbsm:restype> <tbsm:label>table1</tbsm:label> <tbsm:identity>table1@db2instance1</tbsm:identity> </tbsm:resource> <tbsm:resource id= bookid_db2inst > <tbsm:restype>db2</tbsm:restype> <tbsm:label>db2instance1</tbsm:label> <tbsm:identity>db2instance1@host1</tbsm:identity> </tbsm:resource> <tbsm:uses source= bookid_trans1 target= bookid_websphere /> <tbsm:uses source= bookid_trans1 target= bookid_dbtable /> <tbsm:uses source= bookid_dbtable target= bookid_db2inst /> <cdm:sys.businesssystem id= mybusinessservice > <cdm:name>my Business Service</cdm:Name> <cdm:label>my Business Service </cdm:label> </cdm:sys.businesssystem> <tbsm:contains source= mybusinessservice' target= bookid_trans1 /> <!-- END OF CONTENT --> </cdm:cdm-er-specification> </idml:create> </idml:refresh> </idml:operationset> </idml:idml> Using the idml book in the TBSM service model After the custom namespace idml book is created, you must complete a additional steps to successfully use the resource, attribute, and relationship information within the TBSM service model. Naming the idml book: The name of the XML file for a book is important. The name not only helps identify the author or source of the book, but this file name also contains a date and time that enables the Discovery Library Toolkit to process multiple books from the same author in the correct sequence. Customizing the import process of the Service Component Repository 129

138 Use the following format to name the XML file: <author_name>.<host_name>.yyyy-mm-ddthh.mm.ssz.xml where: v <author_name> is the unique name classifying the source of the book. v <host_name> is the fully qualified host name of the host the file was generated from. v YYYY-MM-DD: the date format. v T: used to separate the date and time. v HH: the zero-padded two-digit hour in 24-hour time. v MM: the zero-padded two-digit minute. v SS: the zero-padded two-digit second. v Z: used to represent the time zone offset. The Z sets this value so that no offset is used. This attribute is required. Note: A period (.) is used to separate the host name from the date. The.xml extension is used by all files. By convention, any book that contains the cdm:refresh operation should include the word refresh in the file name following the timestamp of the book. Examples of file names: ABCCorp.myserver.mylocation.abc.com T Z.xml ABCCorp.myserver.mylocation.abc.com T Z.refresh.xml Loading the book into TBSM: The book is loaded into TBSM using the Discovery Library Toolkit. About this task Ensure that the Discovery Library Toolkit is configured to read books and copy the book into the import book folder/directory provided when Discovery Library Toolkit was installed. By default, this important directory is named in the following way: Procedure 1. By default, the directory is named in the following way: For Windows systems: %TBSM_HOME%\discovery\dlbooks For Non-Windows systems: $TBSM_HOME/discovery/dlbooks 2. Verify that the Discovery Library Toolkit is configured to process books in the xmltoolkitsvc.properties properties file. This file is located in the %TBSM_HOME%\XMLtoolkit\bin directory. To import books, set the DL_ImportSource property to all or books. 130 IBM Tivoli Business Service Manager: Customization Guide

139 Mapping class instances to templates For the information in an idml book to be used in TBSM, the custom namespace classes must be mapped to the TBSM templates. Templates are used by TBSM to provide a definition and default behavior to all TBSM resource instances. Resource instances can have more than one template assigned to them. For more information, see Mapping the SCR class structure to a TBSM model on page 87. Mapping to TBSM templates: To map a tbsm:resource class to the BSM_BusinessService template, use the following business service template mapping: <template primary= BSM_BusinessService > <othertemplate name= SCR_RetrieveDependentObjectsTemplate /> <othertemplate name= SCR_ServiceComponentRawStatusTemplate /> <cdmclass name= cdm:sys.businesssystem /> <cdmclass name= cdm:process.businessservice /> </template> <cdmclass name= tbsm:resource /> The <cdmclass name= tbsm:resource /> line as been added to the mapping. A template mapping can also assign templates that you create. The process of mapping a user-defined template to the custom namespace classes in the idml book is no different that mapping the value to a template supplied by TBSM. The template must be defined before it can be used in a template mapping definition. Code and sample RAD Shell script The following are a sample Hello World code and RAD Shell script. Hello World sample book: This example outlines the contents of a sample book. <?xml version="1.0" encoding="utf-8"?> <idml:idml xmlns:idml=" xmlns:cdm=" xmlns:tbsm=" xmlns:xsi=" xsi:schemalocation=" idml.xsd"> <!-- NOTE THIS IDML BOOK DOES NOT FOLLOW STANDARD IDML CONVENTION ITS CONTENTS ARE SUPPORTED ONLY WITH TBSM 4.2 PLUS ENHANCEMENTS --> <!--Header... =================================================== --> <!-- Source and Software... --> <idml:source IdMLSchemaVersion="0.8"> <cdm:process.managementsoftwaresystem CDMSchemaVersion="2.7"> <cdm:mssname>ibm-cdm:///cdmmss/manufacturername=anycustomer+productname= AnyProductName</cdm:MSSName> </cdm:process.managementsoftwaresystem> </idml:source> <!-- Operation... --> <idml:operationset opid="1"> <idml:refresh> Customizing the import process of the Service Component Repository 131

140 <idml:create> <cdm:cdm-er-specification> <!-- BEGINNING OF CONTENT --> <cdm:sys.businesssystem id= myuniverse sourcetoken= My Universe > <cdm:name>my Universe</cdm:Name> <cdm:displayname>my Universe</cdm:DisplayName> </cdm:sys.businesssystem> <tbsm:resource id= earth > <tbsm:restype>planet</tbsm:restype> <tbsm:label>earth</tbsm:label> <tbsm:identity>planet_earth_uniqueidentify</tbsm:identity> <tbsm:attr1>billions</tbsm:attr1> </tbsm:resource> <tbsm:resource id= mars > <tbsm:restype>planet</tbsm:restype> <tbsm:label>mars</tbsm:label> <tbsm:identity>planet_mars_uniqueidentify</tbsm:identity> </tbsm:resource> <tbsm:resource id= continent1 > <tbsm:restype>continent</tbsm:restype> <tbsm:label>north America</tbsm:Label> </tbsm:resource> <tbsm:resource id= country1 > <tbsm:restype>country</tbsm:restype> <tbsm:label>united States</tbsm:Label> </tbsm:resource> <tbsm:resource id= country2 > <tbsm:restype>country</tbsm:restype> <tbsm:label>canada</tbsm:label> </tbsm:resource> <!-- relationships that link continents to planets, countries to continents and planets to the universe --> <tbsm:uses source= earth target= continent1 /> <tbsm:uses source= continent1 target= country1 /> <tbsm:uses source= continent1 target= country2 /> <tbsm:uses source= myuniverse target= earth /> <tbsm:uses source= myuniverse target= mars /> <!-- END OF CONTENT --> </cdm:cdm-er-specification> </idml:create> </idml:refresh> </idml:operationset> </idml:idml> Hello World sample Service Component Repository Rad Shell script: addserviceinstance( new String[] { "SCR_RootTemplate" }, "SCR_Namespace", "Customized Namespace", "SCR Customized Namespace Resources", "Standard", null, null, "REGULAR" 132 IBM Tivoli Business Service Manager: Customization Guide

141 ); addserviceinstance( new String[] { "SCR_TopLevelAggregateTemplate","SCR_ServiceComponent RawStatusTemplate" }, "SCR_HelloWorld", "Hello World", "SCR Hello World Resources", "Standard", null, null, "REGULAR" ); addserviceinstancedependency( "SCR_Namespace", "SCR_HelloWorld" ); adduserpreferencesforinstance( "SCR_HelloWorld", "classnamefilter", " tbsm:resource " ); Adding a description field to the services created by idml books Use the Edit Services tab of the Administration page to provide a description of the service. To add text in this field when creating custom namespace resources, add the <description> </description> attribute to the idml book: <tbsm:resource id= earth > <tbsm:restype>planet</tbsm:restype> <tbsm:label>earth</tbsm:label> <description>the planet Earth</description> <tbsm:identity>planet_earth_uniqueidentity</tbsm:identity> <tbsm:attr1>billions</tbsm:attr1> </tbsm:resource> Changing the service name that appears in TBSM While the label can be specified using the tbsm:label attribute, the actual service name is generated and cannot be changed. Service Component Repository API overview The Service Component Repository (SCR) Application Programming Interface (API) allows you to load resource, attribute, and relationship information into the SCR using a programmatic interface. The SCR API is an alternative to using idml books or loading the information using TADDM. The types of resource information that can be added to the SCR using the SCR API can also be added using other SCR import methods. However, SCR API allows you to take advantage of the integration of TBSM and Impact by allowing you to access data from a variety of sources that can then be used to introduce resource, attribute, and relationship data models into the SCR. The SCR API interface is a set of Impact function calls that execute within an Impact Policy Language (IPL) or JavaScript policy. Using the advanced data access capabilities of Impact with this API and the support of both Common Data Model Customizing the import process of the Service Component Repository 133

142 (CDM) and custom namespace models provides a powerful platform for integrating a broad set of resource and relationship instance dependency models into SCR and TBSM. Using the SCR API as an alternative to ESDA When used in conjunction with the custom namespace support, the SCR API also provides an alternative to the TBSM ESDA feature. When using the SCR API as an alternative to ESDA, there are a number of considerations: v In cases where the source of the external resource information is a SQL database, the SCR API and TBSM ESDA processes can be used interchangeably. However, as it is an extension of the Impact function library, the SCR API supports data access mechanisms, such as web services, that the TBSM ESDA does not support. v While the ESDA process interacts directly with the TBSM service memory model, the SCR API writes data to the SCR which then writes it into the service memory model. The SCR is an adapted ESDA mechanism that works with an interface to the TBSM Data server to write this data into the TBSM memory-based service model in an efficient way. This limits the resources required to maintain service models. This structure is useful for large service models where the dependency model changes. v The ESDA process interacts with an external source of resource and relationship data so that a node can be updated. This process retrieves the children of a resource. For each of those child resources, it retrieves any child resources and so on. This technique is identical to the process that occurs when you click and open the nodes of a service tree. Updates to previously created service models are imported into the system using the same process. This involves a validation process that is initiated on a timed basis or when you open a service model using the TBSM interface and a ESDA resource has become invalid. If the source of the data is structured for this type of interaction, the ESDA method is less complex than the SCR API process. v The SCR API does not require a model for the interaction between it and any external source of resource and relationship data. If the source of the data allows all resource information to be acquired using one or more queries, with a separate query to acquire relationships between the resources, the overall performance of acquiring the data is likely to be more efficient. If the source of data can be queried or can broadcast an awareness of changing model changes, Impact can be used to listen for those changes rather than using a timer mechanism for querying model changes that might or might not exist. v The TBSM ESDA interface is directly integrated with the TBSM Data server. The SCR API inserts resource data into the SCR process. This process then interacts with the TBSM Data server as directed by a set of XML configuration files. This additional step might be a lot of effort for simple service models, however if you use idml books or TADDM, this brings a level of consistency to the process of building and maintaining service models. Components of the SCR API The Service Component Repository (SCR) Application Programming Interface (API) allows you to add new components, attributes, and relationships to the SCR. The API also allows you to delete components and relationships from the SCR. 134 IBM Tivoli Business Service Manager: Customization Guide

143 Impact policy functions have been developed that use the functions provided by the SCR API. For each transaction, where information is entered into the SCR using this API, the functions outlined must be executed in the sequence in which they are outlined: SCRRegister( ) This function creates the unique transaction ID (UUID) and also ensures that the transaction information is persisted to the registration table. The unique transaction ID returned from this function, is required for all other functions so that the components and relationships created can be identified. SCRCreateComponentInfo( ) This function creates and adds component information values to the appropriate database table. It returns the unique transaction ID, or where an exception occurs, it returns a null value. SCRCreateRelationship( ) This function creates a relationship between two components. It returns the unique transaction ID, or where an exception occurs, it returns a null value. SCRDeleteComponentInfo( ) Where required, this function deletes a component from the SCR. It returns the unique transaction ID, or where an exception occurs, it returns a null value. SCRDeleteRelationship( ) Where required, this function deletes the relationship between two components. It returns the unique transaction ID, or where an exception occurs, it returns a null value. SCRComplete( ) This function commits all the component information and relationship values for the transaction ID to the database. This function returns 0 when successful and returns an exception when it fails. Working with the SCR API Using the Service Component Repository (SCR) Application Programming Interface (API) is similar to building an idml book. The same components of an idml book are used when you use the SCR API implementation. They are the header, operation, payload, and the tail. Note: Familiarize yourself with the information in the Importing resource information into the SCR section of this document, before attempting any of the operations in this section. Header and operation The SCRRegister function initiates the SCR API process and data acquisition. It creates the unique transaction ID that is required for all other functions so that the components and relationships created can be correctly associated with the single transaction. Using the SCRRegister function, two critical pieces of information are collected: v The management software system name v The transaction operation (refresh or delta) The management software system name provides a connection between the source and the content that is being provided so that the SCR can integrate the Customizing the import process of the Service Component Repository 135

144 information with data provided by other sources. The operation indicates to the SCR what operation is to be performed on the payload. Valid operations are refresh or delta. These operations are discussed in detail in the Custom namespace section of this guide. Payload: The SCRCreateComponentInfo and SCRCreateRelationship functions are used to create the resource, attribute, and relationship information that is persisted in the Service Component Repository (SCR). The purpose of these functions is to add resource and relationship information into the SCR Application Programming Interface (API) transaction payload. The requirements for the payload are: v When using the ScrCreateComponentInfo function, an identifier must be supplied with a value for the transientid parameter. This is a unique identifier for the component whose scope is limited to the current transaction, in other words, the transaction started by the SCRRegister function call. The transientid provides a reference that identifies the object in a consistent way for the SCRCreateComponentInfo function and as a reference identifier in the SCRCreateRelationship function as either a source or target. Though very important to this process, this value has little to do with the eventual SCR naming process that must be satisfied in order for the resource to be successfully persisted in the SCR. v For a relationship, the proper relationship type, source transientid, and target transientid must be specified. For the SCRDeleteComponentInfo function call, the keywords parameter must include the proper naming attributes required to properly identify the resource in the SCR. v Deleting a particular relationship, and not the components on either side of the relationship, is difficult. The identifying attributes of the component must be provided to properly identify the relationship source component and target component. Therefore to delete a relationship while not touching the components, issue a SCRCreateComponentInfo command providing all the proper attributes for the source component. Perform the same operation for the target components. After completing these steps, issue the SCRDeleteRelationship command, including the source and target transientids. v When the SCRRegister function is called to start a transaction of type refresh, only SCRCreateComponentInfo and SCRCreateRelationship function calls are included in that transaction. As a refresh operation indicates to the SCR that this transaction contains all of the information available to the management software system about its resources, attributes and relationships, the SCR synchronizes with the payload in this transaction. This adds the new data in this transaction to the SCR and deletes any resources that are not in this transaction, but that were included in the SCR with this source previously. Therefore, it is not necessary to specifically delete resources. v When the SCRRegister function is called to start a transaction of type delta, any combination of SCRCreateComponentInfo, SCRCreateRelationship, SCRDeleteComponentInfo, and SCRDeleteRelationship can be included within the transaction. Delta transactions are very useful if the source of the information can provide ongoing changes to the resource and relationship model. Tail: The SCRComplete function indicates to the Service Component Repository (SCR) that this payload is complete and ready for processing. It also must include the 136 IBM Tivoli Business Service Manager: Customization Guide

145 transaction identifier acquired through the SCRRegister function. If a transaction with the SCR Application Programming Interface (API) is started with the SCRRegister function and payload is added to the transaction with any number of SCRCreateComponentInfo and SCRCreateRelationship function calls but the transaction is not closed with a proper SCRComplete function call, the transaction is discarded without being processed. SCR API functions This section describes each of the Service Component Registry (SCR) Application Programming Interface (API) functions. Note: The examples provided to illustrate Service Component Registry (SCR) Application Programming Interface (API) functions are provided in Impact Policy Language (IPL). For information about the differences between IPL and JavaScript, see the Customizing policies section of this document. SCRRegister The SCRRegister function creates the unique transaction ID (UUID) and also ensures that the transaction information is persisted to the registration table. The unique transaction ID returned from this function, is required for all other functions so that the components and relationships referenced can be correctly associated with this source. Syntax SCRRegister (datasource,transientid, cdmidentity, productname, sourcecontrolinfo, transtype,); Parameters This function has the following parameters. Table 40. SCRRegister function parameters Parameter Format Description datasource String This is the name for the data source created in the data model transientid String ID that locally identifies what is being registered cdmidentity String MSS name for the source productname String Product name being used sourcecontrolinfo String Source control information transtype String This parameter can be set to Refresh if you are synchronizing all components and relationships as known by the source, otherwise set this to Delta which allows components and relationships to be deleted as well as created individually. Example The following example returns the transaction ID and allows for components and relationships to be deleted as well as created. Customizing the import process of the Service Component Repository 137

146 DataSource= TBSM_DS ; TransientID= Service_0001 ; CDMIdentity= Service ; ProductName= ServiceApp ; SourceControlInfo=NULL; Transtype= Delta ; transactionid=scrregister(datasource, TransientID, CDMIdentity, ProductName, SourceControlInfo, Transtype); SCRCreateComponentInfo The SCRCreateComponentInfo function creates and adds component information values to the appropriate database table. It returns the unique transaction ID, or where an exception occurs, it returns a null value. Syntax transactionid =SCRCreateComponentInfo (datasource, transactionid, transientid, classtype, label, sourcetoken, keywords, values, modifyonly); Parameters This function has the following parameters. Table 41. SCRCreateComponentInfo function parameters Parameter Format Description datasource String This is the name for the data source created in the data model transactionid String This is the unique transaction ID returned from SCRRegister (); transientid String Unique ID of the component within the context of the transaction started with the SCRRegister function call classtype String Class type of the component being created label String Label of the component being created sourcetoken String Source token for the component being created. This value cannot be Null. keywords String The keywords array allows keyword attributes to be added for each component being created values String The values array allows value attributes to be added for each component being created modifyonly Boolean (Optional) When true an existing component is updated if it exists. If false, the component is created if it does not exist or updated if it does exist. Example The following example utilizes the transactionid created by the SCRRegister function. ComponentTransientID= Comp0001 ; ClassType= ServiceComponent ; Label= NO_LABEL ; 138 IBM Tivoli Business Service Manager: Customization Guide

147 SourceToken=NULL ; Keywords={}; Values={}; transactionid=scrcreatecomponentinfo(datasource, transactionid, ComponentTransientID, ClassType, Label, SourceToken, Keywords, Values); SCRCreateRelationship The SCRCreateRelationship function creates a relationship between two components. It returns the unique transaction ID, or where an exception occurs, it returns a null value. Syntax transactionid =SCRCreateRelationship (datasource, transactionid, relationshiptype, sourceid, targetid); Parameters This function has the following parameters. Table 42. SCRCreateRelationship function parameters Parameter Format Description datasource String The name for the data source created in the data model transactionid String The unique transaction ID returned from SCRRegister (); relationshiptype String The relationship type, for example, tbsm:contains sourceid String Transient ID of the relationship source targetid String Transient ID of the relationship target Example The following example utilizes the transactionid created by the SCRRegister function. It creates a relationship between the two components created using the SCRCreateComponentInfo function: RelationshipType= tbsm:contains ; SourceID= Comp0001 ; TargetID= Comp0002 ; transactionid=scrcreatecomponentinfo(datasource, transactionid, RelationshipType, SourceID, TargetID); SCRDeleteComponentInfo Where required, the SCRDeleteComponentInfo function deletes a component from the SCR. It returns the unique transaction ID, or where an exception occurs, it returns a null value. Syntax transactionid =SCRDeleteComponentInfo (datasource, transactionid, transientid, classtype, label, sourcetoken, keywords, values); Customizing the import process of the Service Component Repository 139

148 Parameters This function has the following parameters. Table 43. SCRDeleteComponentInfo function parameters Parameter Format Description datasource String This is the name for the data source created in the data model transactionid String This is the unique transaction ID returned from SCRRegister (); transientid String Unique ID for the component being created classtype String Class type of the component being created label String Label of the component being created sourcetoken String Source token for the component being created. This value cannot be Null. keywords String The keywords array allows keyword attributes to be added for each component being created values String The values array allows value attributes to be added for each component being created Example The following example utilizes the transactionid created by the SCRRegister function. // DataSource declared // transactionid created by the SCRRegister function ComponentTransientID= Comp0001 ; ClassType= ServiceComponent ; Label= NO_LABEL ; SourceToken=NULL ; Keywords={}; Values={}; // delete the component transactionid=scrdeletecomponentinfo(datasource, transactionid, ComponentTransientID, ClassType, Label, SourceToken, Keywords, Values); SCRDeleteRelationship Where required, the SCRCreateRelationship function deletes the relationship between two components. It returns the unique transaction ID, or where an exception occurs, it returns a null value. Syntax transactionid =SCRDeleteRelationship (datasource, transactionid, relationshiptype, sourceid, targetid); 140 IBM Tivoli Business Service Manager: Customization Guide

149 Parameters This function has the following parameters. Table 44. SCRDeleteRelationship function parameters Parameter Format Description datasource String The name for the data source created in the data model transactionid String The unique transaction ID returned from SCRRegister (); relationshiptype String The relationship type, for example, tbsm:contains sourceid String Transient ID of the relationship source targetid String Transient ID of the relationship target Example The following example utilizes the transactionid created by the SCRRegister function. It deletes the relationship between the two components deleted by the SCRDeleteComponentInfo function: RelationshipType= tbsm:contains ; SourceID= Comp0001 ; TargetID= Comp0002 ; transactionid=scrdeleterelationship(datasource, transactionid, RelationshipType, SourceID, TargetID); SCRComplete The SCRComplete function commits all the component info and relationship values for the transaction ID to the database. This function returns 0 when successful and returns an exception when it fails. Syntax SCRComplete (datasource, transactionid); Parameters This function has the following parameters. Table 45. SCRComplete function parameters Parameter Format Description datasource String The name for the data source created in the data model transactionid String The unique transaction ID returned from SCRRegister (); Example The following example utilizes the transactionid created by the SCRRegister function. It returns 0 if it completes correctly, otherwise an exception is thrown. ReturnValue = SCRComplete(DataSource, transactionid); Customizing the import process of the Service Component Repository 141

150 Creating an Impact policy using the SCR API This Impact Policy language (IPL) policy retrieves resources from a database and created components and relationships for the resources in the Service Component Repository (SCR). To allow this policy to run successfully, the database must be populated with sample data. The sample policy in this topic provides the SCR API functions to populate the database. Instructions to allow you to use this sample policy are embedded in the code text shown. This policy uses the following SCR functions: v SCRRegister(): to register the transaction taking place v SCRCreateComponentInfo(): to create each component from each resource retrieved from the database v SCRRelationship(): to create a relationship between the components v SCRComplete(): to persist all the components and relationships created. Note: The components and relationships can be viewed in the CRViewer after the Discovery Library Toolkit has run. Sample Impact policy The following is a sample Impact JavaScript policy showing the application of the API functions outlined: /********************************************************* {COPYRIGHT-TOP-RM} *** * Licensed Materials - Property of IBM * * "Restricted Materials of IBM" * * 5724-C51 * * (C) Copyright IBM Corp All Rights Reserved. * * US Government Users Restricted Rights - Use, duplication, or * disclosure restricted by GSA ADP Schedule Contract with IBM Corp. ********************************************************* {COPYRIGHT-END-RM} **/ /* * This policy demonstrates a simple use of the TBSM Service Component Repository API to access * a database containing a high level business system structure for a fictitious * company. * Although the database schema is greatly simplified, this policy can be used as * a starting point for connected the SCR API to a more elaborate schema, and * service model. * * The following changes to the environment in order to successfully execute this policy: * * - On the system that has the XMLtoolkit installed, the following directions assume a starting working directory of the XMLtoolkit/bin directory * * - Copy the following files from their current directory --> to the target directory *../tools/crviewer/deprecatedbuscomp/sql/scrapisample ABSTableLoad.sql -->../sql *../tools/crviewer/deprecatedbuscomp/sql/abs_schema_crea te_indexes.sql -->../sql *../tools/crviewer/deprecatedbuscomp/sql/abs_schema_dro p_indexes.sql -->../sql *../tools/crviewer/deprecatedbuscomp/sql/abs_schema_del etes.sql -->../sql *../tools/crviewer/deprecatedbuscomp/sql/abs_schema_set 142 IBM Tivoli Business Service Manager: Customization Guide

151 up.sql -->../sql *../tools/crviewer/deprecatedbuscomp/sql/abs_schema_tru ncates.sql -->../sql *../tools/crviewer/deprecatedbuscomp/scripts/loadsampl eapiabsdata.xml -->../scripts *../tools/crviewer/deprecatedbuscomp/scripts/abscreatet ables.xml -->../scripts *../tools/crviewer/deprecatedbuscomp/scripts/absdroptab les.xml -->../scripts * * - Execute the following commands *./utils.sh (or utils.bat) -U dbuserid -P dbpassword -e../scripts/abscreatetables.xml *./utils.sh (or utils.bat) -U dbuserid -P dbpassword -e../scripts/loadsample apiabsdata.xml * * At this point the tables that the sample will read are created and * populated. * * Execute this sample and then use the XMLToolkit crviewer to view the * data in the component registry * that was created by the sample. * The structure created will be similar to this: * * Zowie * Applications * Inventory * Media * Distribution * Warehouse * Trucking * Tracking * Sales and Marketing * Internet * Print * TV * Infrastructure * Failed System Transactions * * As you can see in the sample data that is created, all the resources * that are loaded into the SCR through this sample are defined as a the * Common Data Model * class cdm:sys.businesssystem * except for the Warehouse, Trucking, * and Tracking resource instances. These are defined as zowie:division * instances where zowie is the namespace and division is the class * of the resource. * As is the case with all resources loaded through the SCR, the class of * the resource must be mapped to a tbsm template in order for the * instance to be visible in the TBSM TIP UI. * See XMLtoolkit customization documentation for details on how to * accomplish this task. * * */ /* #################################################################{start}*/ /* ########################### Global Variables ####################{start} /* #################################################################{start}*/ // Using the default datasource name var DATA_SOURCE = "TBSMComponentRegistry"; var TRANSIENT_ID = "transientid_001"; var COUNT_ONLY = "False"; var DEBUG = false; /* #################################################################{end}*/ /* ########################### Global Variables ####################{end} /* #################################################################{end}*/ Customizing the import process of the Service Component Repository 143

152 /* Output a <code>string</code> to the log console * / function log(string){ if(string!= null) Log(string); } /* Register a transaction */ function register( transientid, cdmidentity, productname, sourcecontrolinfo, transtype) { if(debug) { log("register() "); log("- transientid: " + transientid); log("- cdmidentity: " + cdmidentity); log("- productname: " + productname); log("- sourcecontrolinfo: " + sourcecontrolinfo); log("- transtype: " + transtype); log(" "); } transactionid = SCRRegister( DATA_SOURCE, transientid, cdmidentity, productname, sourcecontrolinfo, transtype); return transactionid; } /* Create a component info with various key / pair values */ function createcomponentinfowithkeywordvaluepairs( transactionid, transientid, classtype, label, sourcetoken, keywords, values ) { if(debug) { log("createcomponentinfowithkeywordvaluepairs() "); log("- transactionid: " + transactionid); log("- transientid: " + transientid); log("- classtype: " + classtype); log("- label: " + label); log("- sourcetoken: " + sourcetoken); log("- keywords: " + keywords); log("- values: " + values); log(" "); } transactionid = SCRCreateComponentInfo( DATA_SOURCE, transactionid, transientid, classtype, label, sourcetoken, keywords, values ); return transactionid; } /* Create a relationship */ function createrelationship( transactionid, relationshiptype, sourceid, targetid ) { if(debug) { log("createrelationship() "); log("- transactionid: " + transactionid); log("- relationshiptype: " + relationshiptype); log("- sourceid: " + sourceid); log("- targetid: " + targetid); log(" "); } transactionid = SCRCreateRelationship( DATA_SOURCE, transactionid, relationshiptype, sourceid, targetid ); return transactionid; } /* Commit the entire transaction */ function commit( transactionid ) { if(debug) { log("commit() "); log("- transactionid: " + transactionid); 144 IBM Tivoli Business Service Manager: Customization Guide

153 log(" "); } returncode = SCRComplete( DATA_SOURCE, transactionid); return returncode; } /* Check if a value is undefined, blank or null */ function isundefinedornullorblank(value) { if(undefined == value) return true; else if(null == value) return true; else if("" == value) return true; else return false; } /* ################################################################ */ /* START: POLICY BODY */ /* ##################################################################*/ log("starting policy..."); if(debug) { log(" "); log("information "); log("data_source: " + DATA_SOURCE); log("transient_id: " + TRANSIENT_ID); log(" "); } // register the transaction var transactionid = register(transient_id, "ABS_SOURCE", "TBSM", "ABS_SOURCE_001", "REFRESH"); if(debug) log("register() returned transactionid = " + transactionid); // Go get resource info from db absobjects = DirectSQL (DATA_SOURCE, "select * from tbsmscr.abs_objectinfo", COUNT_ONLY); var index = 0; if(debug) log("len = " + Length(absobjects)); while( index < Length(absobjects) ) { if(!isundefinedornullorblank(absobjects[index])) { transientid = absobjects[index].objectkey; reltype = "tbsm:contains"; sourceid = absobjects[index].objectkey; targetid = absobjects[index].placementkey; var keywords = []; var values = []; var arrayindex = 0; var classtype; var label; // Class name if(!isundefinedornullorblank(absobjects[index].classname)){ classtype = absobjects[index].classname; } // Display name if(!isundefinedornullorblank(absobjects[index].displayname)){ label = absobjects[index].displayname; } // 1st keyword/value pair if(!isundefinedornullorblank(absobjects[index].attributename1)){ keywords[arrayindex] = absobjects[index].attributename1; if(!isundefinedornullorblank(absobjects[index].attributevalue1)){ values[arrayindex] = absobjects[index].attributevalue1; } else { values[arrayindex] = ""; Customizing the import process of the Service Component Repository 145

154 } arrayindex = arrayindex + 1; } // 2nd keyword/value pair if(!isundefinedornullorblank(absobjects[index].attributename2)){ keywords[arrayindex] = absobjects[index].attributename2; if(!isundefinedornullorblank(absobjects[index].attributevalue2)){ values[arrayindex] = absobjects[index].attributevalue2; } else { values[arrayindex] = ""; } arrayindex = arrayindex + 1; } // 3rd keyword/value pair if(!isundefinedornullorblank(absobjects[index].attributename3)){ keywords[arrayindex] = absobjects[index].attributename3; if(!isundefinedornullorblank(absobjects[index].attributevalue3)){ values[arrayindex] = absobjects[index].attributevalue3; } else { values[arrayindex] = ""; } arrayindex = arrayindex + 1; } // 4th keyword/value pair if(!isundefinedornullorblank(absobjects[index].attributename4)){ keywords[arrayindex] = absobjects[index].attributename4; if(!isundefinedornullorblank(absobjects[index].attributevalue4)){ values[arrayindex] = absobjects[index].attributevalue4; } else { values[arrayindex] = ""; } arrayindex = arrayindex + 1; } // 5th keyword/value pair if(!isundefinedornullorblank(absobjects[index].attributename5)){ keywords[arrayindex] = absobjects[index].attributename5; if(!isundefinedornullorblank(absobjects[index].attributevalue5)){ values[arrayindex] = absobjects[index].attributevalue5; } else { values[arrayindex] = ""; } arrayindex = arrayindex + 1; } // 6th keyword/value pair if(!isundefinedornullorblank(absobjects[index].attributename6)){ keywords[arrayindex] = absobjects[index].attributename6; if(!isundefinedornullorblank(absobjects[index].attributevalue6)){ values[arrayindex] = absobjects[index].attributevalue6; } else { values[arrayindex] = ""; } arrayindex = arrayindex + 1; } // create component if keyword/value pairs exist if(keywords.length == 0 values.length == 0) log("cannot create component for resource number " + index + " as one or both of the keyword/value arrays has a length of 0. Note: resources start from number " + index + " "); else createcomponentinfowithkeywordvaluepairs(transactionid, transientid, classtype, label, null, keywords, values); // create relationship if targetid is available 146 IBM Tivoli Business Service Manager: Customization Guide

155 if(isundefinedornullorblank(targetid)) log("cannot create relationship for resource number " + index + " as the target ID ["+targetid+"] is undefined, blank or null. Note: resources start from number " + index + " "); else createrelationship(transactionid, reltype, targetid, sourceid); } index = index + 1; } commit(transactionid); log("...policy finished"); #######################################################################* / /* END: POLICY BODY */ /* ########################################################################*/ Customizing the import process of the Service Component Repository 147

156 148 IBM Tivoli Business Service Manager: Customization Guide

157 Exporting TBSM services to an idml book This topic describes how to export TBSM service model data to a Discovery Library Adaptor (DLA) idml book and how to add custom services to the exported file. These files can be imported into Tivoli Application Dependency Discovery Manager The recommended approach is to build the service tree in TADDM. TBSM can be used to update the structure with Business Services and Business Applications. Before you begin To export TBSM services to a DLA book in idml format, run the command: UNIX $TBSM_HOME/XMLtoolkit/bin/genidml.sh -U userid -P password -o directory Windows %TBSM_HOME%\XMLtoolkit\bin\genidml.bat -U userid -P password -o directory where: -U The user ID for the database. -P The password for the database user ID. -o The directory path to which the DLA book is exported. By default, this command exports: v All services created by TBSM that are assigned the BSM_BusinessService template are exported as an instance of the cdm:sys.businesssystem class v All services created by TBSM that are assigned the BSM_BusinessApplication template are exported as an instance of the cdm:app.application class v References to all services either from an idml book or from Tivoli Application Dependency Discovery Manager (TADDM) that are within the TBSM service instance tree. genidml will not export services which were previously imported from an idml book, or from TADDM. It will only export a relationship to these services. Relationships to TBSM created services, are only exported, if these TBSM created services are exported. To summarize, TBSM exports: 1. TBSM created services with the ServiceExport attribute, as Business Systems or Business Applications (depending on the ServiceExport attribute setting) 2. TBSM export relationships (only) from the services above, to services created via a TADDM import. v When services created by TBSM are exported into the book, the following data is included: the class name of the TBSM service within the Common Data Model (CDM) the TBSM service's display name is recorded as the label of the CDM object the TBSM service's service instance name is recorded as the identity attribute for the object. It is written to the cdm:name attribute a sourcetoken value that enables launching from readers of the TBSM book back into TBSM, in context of a particular service instance Copyright IBM Corp. 2008,

158 all relationships to other TBSM service instances that are included in the book all relationships to TBSM resources that originated from a CDM feed (TADDM, DLAs) v When TBSM exports references to service instances that originated in TADDM or idml book, the data is includes: a sourcetoken value that enables launching from readers of the TBSM book back into TBSM in context of a particular service instance v Note, services can only be successfully imported into TADDM if they follow standard CMDB rules, for example a Functional Group is a child of an Application Server. v Services created in TBSM, exported to TADDM, will not be re-imported back into the same TBSM by a bulk import. v TBSM exports only Business Services and Business Applications. Non Business Application or Business Service TBSM Services, exported from TBSM, to TADDM, will not be imported into TADDM. This fails because the services were TBSM services, not TADDM created ones, and thus are missing vital information required by TADDM. v The Service Component Registry tree is not automatically invalided after a toolkit import. This tree must be manually invalidated. If you want to export services assigned to other templates, add an additional parameter to the service template that you want to export. See the following section for additional detail. About this task To export services assigned to a custom service template: Procedure 1. Select Administration -> Service Administration from the console task list. 2. Select the service template you want to edit from the Templates list in the Service Navigation portlet. The service template opens in the Service Editor. 3. In the Service Editor, click Edit Template. 4. Click the Additional tab. 5. Click the Add New Parameter button. 6. In the Parameter column, type: ServiceExport 7. In the Default Value column: type: cdm:sys.businesssystem 8. Save the service template. Results The next time you run the genidml command, the exported file will include services assigned to the templates where you added the ServiceExport parameter. If the services exported by the DLA contain resources that were imported from either TADDM or an idml book, these resources is included in the DLA as abstract resources. The book generated by TBSM contains a managed software system (MSS) clause that references a TBSM Dashboard server. A product that reads the TBSM idml 150 IBM Tivoli Business Service Manager: Customization Guide

159 book can launch-in-context back to TBSM by using this information. The TBSM toolkit installer sets the Dashboard server. To change the Dashboard server information after the installation: 1. Open the file: $TBSH_HOME/XMLtoolkit/sql/createidmlbookstatic.sql in a text editor. 2. Change the HOSTNAME and PORT insert statements to reference the new Dashboard server. In this example, replace mydashboard_server_host and mydashboard_server_port with the values for your Dashboard server. INSERT INTO TBSMCONFIG.TBSMConfig_SystemConfig (category, keyword, value) VALUES ( TBSM_DLA, HOSTNAME, mydashboard_server_host ); INSERT INTO TBSMCONFIG.TBSMConfig_SystemConfig (category, keyword, value) VALUES ( TBSM_DLA, PORT, mydashboard_server_port ); 3. To load the change into the database run the command: setdbschema.sh -U -P -f i The MSS change will be picked up the next time you run the genidml command. Note: If you have configured several Dashboard servers and are using a load balancer, then you need to specify the load balancer Dashboard server in the createidmlbookstatic.sql file. Exporting TBSM services to an idml book 151

160 152 IBM Tivoli Business Service Manager: Customization Guide

161 Synchronizing TBSM service model data with the SCR The TBSMToSCR function, located on the Data server, is used to send TBSM service model data to the Service Component Registry (SCR). Service model data that can be sent to the SCR includes TBSM services, service attributes, and relationships. Only services created manually, either using the TBSM interface or Rad shell, and auto-populated services and related data can be added to the SCR. Note: TBSM ESDA-generated service instances and related data are not sent to the SCR. Note: This function is not enabled on the Data server by default. To enable it, a property must be set in the Data server configuration. The Data server must be restarted after you set this property. Purpose of the synchronization function This function: v reconciles TBSM data model objects with SCR objects discovered using other sources. This ensures that object duplication is prevented. v automatically places TBSM data models in a defined location within an existing SCR hierarchy of resources. Note: The refresh and delta processing of TBSM data into the SCR works asynchronously by writing data to a set of tables in the database which is later consumed and processed by the Discovery Library Toolkit. As such, the Discovery Library Toolkit component must be running so that the flow of data from TBSM to the SCR is successful. Refreshing service model data stored in the SCR After TBSMToSCR is enabled, the TBSM model data in the SCR is refreshed. This is done when the Data server is started and also at configurable intervals. As part of this process, TBSM services, attributes, and relationships are loaded into the SCR. The default interval between each refresh is 168 hours or 7 days. You can configure the default interval by updating the impact.sla.tbsmtoscrrefreshinterval property in the TBSM_sla.props file on the Data server. Note: You can also initiate an immediate refresh of the TBSM model data in the SCR using the initiatescrrefresh() Rad shell command. For more information, see the Rad shell commands section in the TBSM Administrator's Guide. Processing changes to service model data stored in the SCR After the function is enabled, the server sends a baseline or refresh of the TBSM model data to the SCR and continues to refresh the model data at certain configurable intervals. Between refresh intervals, the server records changes to the service model using SCR Events which are processed asynchronously at periodic intervals. The time between intervals is configurable. Delta SCR events are generated by changes to the TBSM model data such as creating new services, deleting services that were previously sent, adding/deleting/modifying service instance attribute data, or by creating/deleting relationships between services that Copyright IBM Corp. 2008,

162 were sent to the SCR. While TBSM template definitions are not sent to the SCR, manipulating them can have an impact on the data that is sent to the SCR. For example, as services inherit attributes from the templates they are tagged with, adding or removing a template to or from a service affects the attributes for that service and subsequently generates an SCR update event for that service to synchronize the attribute data for that service in the SCR. TBSMToSCR attributes This is a list of attributes that you can use with TBSMToSCR: Table 46. TBSMToSCR attributes Attribute SendInstanceToSCR tbsm:class tbsm:identity SCRIdentityAttribute Description Excludes unwanted services from the SCR. The valid values are true and false. If there is a set of services that you do not want to be sent to the SCR, you can tag them with a template that has this attribute set to false to prevent them from being sent to the SCR. The value of this attribute is determined by the class type of the service instance. If not set otherwise, it is set to the tbsm:primary template name Used to provide the identity of the service. The value of this attribute is the same as the service instance name. This attribute is only used if tbsm:identity is not used as the identity attribute name. If set, the value of SCRIdentityAttribute is used as the identity attribute name associated with the service instance. However, the value of the new identity attribute is the service instance name of the service. Properties that control the TBSMToSCR function To set any of the following properties, add the property to the $TBSM_HOME/etc/TBSM_sla.props file on the Data server. A number of these properties exist in the TBSM_sla.props file, but might require modification to meet your requirements. If a property is not present, you can add it to the TBSM_sla.props file and configure it to match your requirements. Note: Backup the TBSM_sla.props file before making any changes. After adding the properties and updating them to match your requirements, you must restart the Data server. Table 47. TBSMToSCR function properties Property impact.sla.tbsmtoscrrefreshinterval impact.sla.sendtbsmtoscr Description Number of hours between refresh operations. The default value is 168 hours. Enable or disable this function to load TBSM data model data to the SCR. Valid values are true and false. The default value is false. 154 IBM Tivoli Business Service Manager: Customization Guide

163 Table 47. TBSMToSCR function properties (continued) Property impact.sla.tbsmtoscrsleeptime impact.sla.tbsmtoscrmaxtransactionsize impact.sla.tbsmtoscrattrexcludelist.ma tches impact.sla.tbsmtoscrattrexcludelist.star tswith impact.sla.tbsmtoscrattrexcludel ist.endswith impact.sla.tbsmtoscrmaxqueuesize Description Interval, in seconds, for which the Data server sleeps between iterations of processing data into the SCR. Maximum number of delta SCR events that can be processed within a single transaction. The default value is A comma-separated list of service attributes that are excluded from the set of attributes sent to the SCR for a given service. The default values for this property are provided in the TBSM_sla.props file located $TBSM_HOME/etc. A comma-separated list of partial service attribute names for which TBSM searches when determining the set of attributes to be excluded from the attributes that are sent to the SCR for a given service. The default values for this property are provided in the TBSM_sla.props file located $TBSM_HOME/etc. Each partial attribute name on this list is checked against the attribute names for each service sent to the SCR. Any attributes that starts with any of the partial names on this list is excluded. A comma-separated list of partial service attribute names for which TBSM searches when determining the set of attributes to be excluded from the attributes that are sent to the SCR for a given service The default values for this property are provided in the TBSM_sla.props file located $TBSM_HOME/etc. Each partial attribute name on this list is checked against the attribute names for each service sent to the SCR. Any attribute that ends with any of the partial names on this list is excluded. Maximum number of SCR events, or changes to the TBSM data model that are imported into the SCR, that can exist on the delta queue at one time. If the maximum queue size is exceeded, a refresh operation is initiated and the queue is cleared. The default value is The Discovery Library Toolkit and TBSMToSCR The Discovery Library Toolkit contains an SCR API data processing thread which reads SCR API transaction data from the database and imports it into the SCR. The SCR API transaction data is written to the database by the TBSM Data server when the TBSMToSCR function is enabled. The SCR API data processing thread can be controlled by the properties defined in the xmltoolkitsvc.properties file located: $TBSM_HOME/XMLtoolkit/bin. Synchronizing TBSM service model data with the SCR 155

164 Table 48. Discovery Library Toolkit properties Property DL_PollApiIntervalSeconds DL_Enable_API_Thread DL_API_Record_Read_Limit DL_API_Transaction_Age DL_API_Cleanup_Process_Max_Wait Description Determines how often the toolkit SCR API data processing thread checks for updates or new data. The default value is 13 seconds. Determines whether or not the SCR API data processing thread is enabled. Valid values are true and false. The default value is true. The number of records to be processed by the SCR API thread at one time. The default value is Specifies how long, in hours, processed transaction data is kept in the database. The default value is 24 hours with a minimum value of 1 hour. Specifies how long, in minutes, that the SCR API processing thread continues to process new data before pausing for cleanup processing. Cleanup processing deletes aged SCR API transaction records from the database. The default and minimum value for this parameter is 60 minutes. Note: Before making any changes to the properties in the xmltoolkitsvc.properties file, create a backup copy of the file. The Discovery Library Toolkit must be restarted, for any modified property values to take effect. 156 IBM Tivoli Business Service Manager: Customization Guide

165 Component Registry Viewer overview The Component Registry Viewer is an application that you can use to view discovery data stored in the TBSM Component Registry. The TBSM Component Registry is a collection of database tables that are used by the Discovery Library Toolkit to store the information it receives from Discovery Library Adapter books and the discovery API connection, such as the API provided by TADDM. The Component Registry Viewer presents data that you can use to validate data, in problem determination, and to build business service models. Business Service Composer The Business Service Composer is a component of the Component Registry Viewer. It allows you to create and maintain project files that you can use to create business service models. For more information about the Business Service Composer, see the Business Service Composer section of this guide. Manual Installation of the Component Registry Viewer The Component Registry Viewer is automatically installed when the Discovery Library Toolkit is installed for TBSM 6.1 or higher. However, it can also be installed on any computer that meets the minimum installation requirements. This topic describes how to manually install the Component Registry Viewer. Before you begin The prerequisite requirements to run the application are: v IBM Java Runtime Environment version for TBSM can be obtained from fix central. Download the TBSM interim fix: TIV-BSM-IF0001 from the IBM Fix Central site. ibm~tivoli&query.product=ibm~tivoli~tivoli Business Service Manager &query.release=all&query.platform=all To install the IBM Java plug-in on a client host, follow the instructions included with TBSM interim fix TIV-BSM-IF Note: Verify the version of Java runtime that is installed by running the java -version command. About this task The crviewer.zip file is provided to install the applications. If you have installed the Discovery Library Toolkit the crviewer.zip can be found in the $TBSM_HOME/XMLtoolkit/tools/crviewer directory. Procedure 1. Create an installation directory for the Component Registry Viewer. Copyright IBM Corp. 2008,

166 2. From the TBSM 6.1 Data server, copy the Component Registry Viewer file archive from the $TBSM_HOME/XMLtoolkit/tools/crviewer directory to the installation directory that you created. The file archive is named crviewer.zip for a Windows installation or crvierwer.tar file for a UNIX installation. 3. Extract the files from crviewer.zip or crvierwer.tar into the installation directory. Note: If you have made configuration changes, such as adding a database connection, to the Component Registry Viewer application, you can copy the CRC_config.xml from the $TBSM_HOME/XMLtoolkit/tools/crviewer directory to the installation directory you created. Note: If you are going to use the CRViewer to access a TBSM database, you must copy the Postgres driver from your TBSM Discovery Library toolkit directory located XMLtoolkit/jars/postgresql-8.1dev-400.jdbc3.jar to your expanded CRViewer. Starting the Component Registry Viewer The script that starts the Component Registry Viewer application is configured to reuse the Java runtime installed with the Discovery Library Toolkit. The Component Registry Viewer can be started using the CRC-Start convenience scripts located in the $TBSM_HOME/XMLtoolkit/tools/crviewer directory. For Windows systems use the CRC-Start.bat file and for UNIX, use CRC-Start.sh. Create a database connection to the Component Registry You must create a database connection to the Component Registry. To create a database connection follow these steps: Procedure 1. Select the Tools > Connection Manager from the menu options. 2. Click New. 3. Type the database connection information that you want to use for this connection. The connection name must be unique. 4. Click Apply to save your changes or Cancel to abandon the creation of the new connection. 5. Click Test to ensure that the database connection is operating correctly. Update a database connection to the Component Registry To update a database connection, follow these steps. Procedure 1. Select the Tools > Connection Manager from the menu options. 2. From the Connections list, select the database connection that you want to update. 3. Update the connection values as required and click Apply. 4. Click OK to exit the Connection Manager dialog box. 158 IBM Tivoli Business Service Manager: Customization Guide

167 Deleting a database connection to the Component Registry To delete a database connection, follow these steps. Procedure 1. Select the Tools > Connection Manager from the menu options. 2. From the Connections list, select the database connection that you want to delete. 3. Click Delete and the Yes. 4. Click OK to exit the Connection Manager dialog box. Using the Component Registry Viewer After you have created a database connection, you can then connect to the database to view data in the Component Registry Viewer. Procedure 1. Connect to your data source by selecting the connection from the Connect To: on the toolbar. 2. In the Live Database View, select a resource class from the Class List view to populate the Instance List view panel. 3. From the Instance List view, click to select the resource instance whose attribute you want to review. Clicking the instance populates the Attributes List view panel. 4. Review the attributes listed in the Attributes List view panel to determine if the resource instance selected is the one you want to review. 5. Click the Get Details button on the toolbar to retrieve the details for the instance. 6. In the Details List view panel, right-click any row in the Relationships table to follow the relationship line path to the related resource instance. Following the relationship path updates the Attributes List view panel with the attribute values for the resource instance that is the target of the relationship you have followed. 7. Repeat steps 5 to 6 for each service instance relationship that you want to review. Note: For information about each of the Component Registry Viewer views, see Component Registry Viewer views on page 160. Component Registry Viewer elements This topic describes the elements of the Component Registry Viewer user interface. Menu Options The menu options in the Component Registry Viewer are: File Tools You can close and exit the application from this menu. The Edit menu contains the options as described in the table below. Component Registry Viewer overview 159

168 Table 49. Edit menu options Menu option Export Connection Manager Business Service Composer Description Choose this option to export the Component Registry contents to a set of XML files. Select this option to display the Connection Manager dialog box. This dialog box allows you to add, delete, update, and test database connections used by the Component Registry Viewer. For more information about managing database connections, see the topics that address these tasks in this document. Select this option to open the Business Service Composer. This allows you to create, edit, and delete project files. These project files can you can use to create TBSM service models. Help Select this option to display the online help for the Component Registry Viewer. This menu also allows you to open the Component Registry Viewer Getting Started guide and to view the Component Registry Viewer splash screen which provides licensing and copyright information. Toolbar options These options available from the Component Registry Viewer toolbar are outlined in this topic. Connect To list Select the database that you want to connect to from the Connect To list. When a connection is selected, you are be prompted for the password. Type the password for the database connection and click OK to connect. Component Registry Viewer views The Component Registry Viewer has five views: Live Database View, Class View, Instance View, Attribute View, and Details View. Live Database View The Live Database View is the default display for the Component Registry Viewer. It is divided into four data views: Class View, Instance View, Attribute View, and Details View. Each view can be sized individually by dragging the bars that divide each view. You can also hide and reveal each of the views using the arrows on each of the dividing bars. On the Live Database View toolbar, the Recent drop-down list allows you to choose from a list of recently visited resources. The Get Details button is also available on this toolbar. This button refreshes the Details View. Note: This operation might take some time, depending on the amount of data in the Component Registry. This button is enabled when a refresh is required, such as when a new instance is selected in the Instance View. Class View The Class View displays a list of class names and an aggregate count of the number of instances in each class. The Class View can be used to 160 IBM Tivoli Business Service Manager: Customization Guide

169 verify that the correct number of instances has been discovered for each class. Clicking any row in the Class View refreshes the class in the Instance View. Use the Filter to filter classes by class name. Filtering is not case sensitive. Instance View The Instance View lists all of the instances that are currently defined in the selected class. Clicking any row in the Instance View refreshes all of attributes for the selected instance in the Attribute View. Right-click options Right-click an item in the Instance View to access the Get MSS option. Click Get MSS to display a list of the Management Software Systems (MSS) that have discovered this instance. Selecting the MSS generates an empty DLA book for that MSS. Loading this book into TBSM removes all references to that MSS from the database. Any resource that had only contains the MSS in the book is removed from the database. Attribute View Attribute View lists all of the attributes for the selected instance. The information in this view can be used to verify that attributes for the instance are complete and accurate. The values in the list can be used to show the details for the selected instance. Details View Details View displays the largest set of information for the selected instance. Tabs are provided in the Details View that organize the instance information. Information on each tab is described in the table below: Component Registry Viewer overview 161

170 Table 50. Details View tabs Tab Name Relationships Function This tab contains a list of all the relationships in which a selected instance participates. Direction column Each relationship has a direction as indicated by an arrow and a color. A green arrow pointing to the right indicates that the relationship is forward. A red arrow pointing left indicated a reversed relationship. A gray square indicated the relationship has no defined direction. Right-Click Context Menu Right click any row in the Relationships list and select Open In Attributes View to display the instance attribute values in the Attribute View. Note: This menu enables the Get Details button. The button refreshes the details for the new instance. Right-click options Right-click a relationship to access the right-click menu. Two options are provided: v v Click Open in Attributes View to display the attributes of the selected item. Click Get MSS Info to display a list of the Management Software Systems (MSS) that have discovered this relationship. Selecting the MSS generates an empty DLA book for that MSS. Loading this book into TBSM removes all references to that MSS from the database. Any resource that had only contains the MSS in the book is removed from the database. Templates Composite Components Component Of Composites Naming This tab lists TBSM service templates mapped to the selected service instance class. If the selected instance is a member of a composite instance, this tab contains a list of all other members of the composite instance. If the selected instance is a member of another composite instances, this tab contains a list of other composite instances. This tab contains a list of naming currently defined for the selected instance. 162 IBM Tivoli Business Service Manager: Customization Guide

171 Table 50. Details View tabs (continued) Tab Name Source Tokens Function This tab contains a list of values used to identify the selected instance on other systems such as IBM Tivoli Monitoring or TADDM. Exporting data from the Component Registry You might want to export the data in your Component Registry to XML files. These XML files can be used to view the contents of the Component Registry database without being connected to any database. These XML file can also be used for problem determination and troubleshooting. About this task The Component Registry Viewer copies all of your exported data to a folder named export located in the folder to which you have installed the Component Registry Viewer. To export your data: Procedure 1. From the Tools menu, choose Export. 2. Click Start. Your data is exported to the export directory. 3. Click Exit. Component Registry Viewer overview 163

172 164 IBM Tivoli Business Service Manager: Customization Guide

173 Business Service Composer The Business Service Composer assists in the organization of discovered Information Technology (IT) resources into a structured model that meets your business requirements. The Business Service Business Service Composer is a component of the TBSM Component Registry Viewer (CRViewer) that builds on the resource enrichment features of the Service Component Registry (SCR). To use TBSM effectively, you must build a service model that accurately represents your IT environment technically and logically within the context of your company's business structure. Building a service model requires that you have a detailed understanding of your IT resources and the roles that each resource plays. You must also have a clear idea of how you want to display the information generated by TBSM to your target audience. Changes to IT environments as well as changes to your TBSM user groups make maintaining service models a complex task. Tools such as TADDM allow you to gather information about your IT environment and can provide an important repository of IT resource information that can be used by TBSM. TBSM also allows you to import data from a variety of other sources including the ability to generate an resource representation as the result of a problem event entering the system. Customer databases can also provide IT resource information. One or more of the resource importing techniques can be used to provide a foundation for the desired TBSM logical model. However, though critical to the overall TBSM solution, it is rare for these import sources to provide the complete structure that you require. In these cases, using the Business Service Composer can simplify the task of building and maintaining service models that your requirements. The Business Service Composer is a utility that assists in the process of organizing discovered IT resource elements into a structure that allows you to take full advantage of TBSM. Scenarios for using the Business Service Composer The Business Service Composer is not appropriate in every circumstance. However, consider using the Business Service Composer if your service model requirements are similar to these examples: v The Database administration group would like their support of databases modeled as a service. This requires a service model structure that shows the subdivision of support across databases servicing external and internal customers as well as a simple grouping of the different types of databases. Metrics are required for these databases so that dashboards of the database activity can be created. v You want to provide views of a data center that show major infrastructure components so that you can accurately represent the IT backbone. v Geographical views of major office complexes are needed to provide the context needed for alarms and issues v You want to separate your systems, for example production, certification, development, and test, based on their role so that each system is given an appropriate level of support. Copyright IBM Corp. 2008,

174 v An imported source, such as TADDM or a CMDB, contains a business service model that you want to enhance with other critical resources that are not managed by the sources included in the existing model. You want to make these resources available to the TBSM service model using other resource creation methods including auto-populating a TBSM resource from an Netcool/OMNIbus event. v The resources that implement one or more business services follow a naming convention, share a common attribute, or can be programmatically detected based on the data imported into the Service Component Repository (SCR). v You want to take advantage of simple technology groupings, for example all CICS regions, to organize an imported resource model so that it can be used by internal organizations whose responsibility it is to maintain and service key resource types. v You want to provided a flattened tree for your service model. However the import source provides a complex dependency tree of resources. Using the Business Service Composer, you can simplify the service model into technology groupings scoped on the basis of the business service. The Business Service Composer allows you to address these and other similar requirements whenever you want to organize imported resources and it is difficult to achieve by other means. Features of the Business Service Composer The Business Service Composer is a stand-alone application that allows you to define your service model requirements in a project file. When loaded into the Service Component Repository (SCR), the Business Service Composer project file customizes the resource enrichment features of the SCR to create a service model that reflects the requirements you define in the Business Service Composer. This section outlines the features provided by the Business Service Composer user interface. The Business Service Composer allows you to: v define resources and relationships referred to as Static resources v create dependencies between resources based on criteria defined as Policy Patterns. Combining these two capabilities allows you to organize imported resource and relationship data in the SCR into service models that meet your requirements. To support these functions, the Business Service Composer creates projects that allow you to separate the service model work for an enterprise into multiple more manageable pieces. Starting the Business Service Composer The Business Service Composer is an integrated component of the Component Registry Viewer that provides a means of dynamically building business services based on rules defined within the Business Service Composer. To launch the Business Service Composer, follow the procedure outlined in this topic. Procedure 1. Launch the Component Registry Viewer by running the CRC-Start script located in the $TBSM_HOME/XMLtoolkit/tools/crviewer directory. 166 IBM Tivoli Business Service Manager: Customization Guide

175 2. From the Tools menu, choose Business Service Composer. Alternatively, click the Open the Business Service Composer workspace button on the Component Registry Viewer toolbar. The Business Service Composer Workspace is displayed. Business Service Composer Workspace The Business Service Composer Workspace contains the Project list and Composer Project workspace. Project list The Project list contains a list of projects. This pane also contains a number of toolbar buttons that you can use to manage the projects in the project list. Note: The project files created in the Business Service Composer are stored in the projects directory where the Component Registry Viewer is installed. The project list toolbar contains the following buttons: Table 51.. Project list toolbar options Create a new project Delete a selected project Edit information for a selected project Open a selected project in the Composer Project workspace Composer Project workspace The Composer Project workspace is used to create and edit the information in a project. When a project is opened, it is displayed in the Composer Project workspace. This workspace contains a common toolbar and 1 tab for each project that is currently opened. Each open project is displayed in a tab. You can toggle between projects by clicking on the project tabs. To close a project, click the button. If any changes have not been saved, a confirmation dialog is displayed to allow you to save your changes. The Composer Project workspace contains 3 panels. Each panel can be re-sized as required. The following sections describe each of these panels and their features. Project View tree The Project View tree provides a hierarchical view of the elements in a project. The tree is divided into 2 distinct containers: v Static Definitions: This container displays resource instances that are defined within the project. v Policy Patterns: This container displays the placement policy pattern instances defined within the project. Both the Static Definition and Policy Pattern panels have been implemented with 2 distinct modes. When adding either a new static definition or policy pattern, you must first enable the panel by right-clicking and clicking Add. This allows you to Business Service Composer 167

176 add new items without having to switch between panels. The panel stays in Add mode until you click Cancel or the panel is switched to Edit mode. The panel is in Edit mode when you select a static definition or policy pattern and choose Edit from the right-click menu. To end Edit mode, click Update or Cancel. The panel does not stay in Edit in the same way as it does for Add mode. Project View right-click menu: There are a number of options available in the Project View right-click menu: Table 52. Project View right-click menu options Option Add Edit Delete Select Link Remove Link Move Description Add either a new Static Definition or new Policy Pattern depending on the tree node selected Edit either a Static Definition or Policy Pattern depending on the tree node selected Delete either a Static Definition or Policy Pattern depending on the tree node selected Marks the selected Static Definition as the source of either a Link or Move option. Create a logical link between the current Static Definition and any other Static Definition that you select using the Select option. The selected Static Definition is made a child of the current Static Definition. Remove the logical link between the current Static Definition and any other Static Definition that you select using the Select option. Move a Static Definition and its children, selected using the Select option, under the current Static Definition Composer Project workspace toolbar The Composer Project workspace toolbar provides the following options: Table 53. Composer Project workspace toolbar buttons Button Description When enabled, save the current project Expand the branches of project tree Collapse the branches of project tree Creating a Business Service Composer project To use the Business Service Composer you create a project. Each project groups static definitions and policy pattern definitions into a single entity that can be created, edited, and deployed into the Service Component Repository. About this task When you save a Business Service Composer project, an XML file is created in the CRViewer projects directory. The file name given to this XML file is the same as the name you have given the Business Service Composer project. You can create 168 IBM Tivoli Business Service Manager: Customization Guide

177 separate projects for different sections of the overall service model. Procedure 1. Click on the Project list toolbar. The New project dialog box is displayed. 2. Enter the project information. The information required for each field is: Project Name Provide a name for your project that is meaningful to the work or business service model to be modeled in the project. This value is used as the display name for the project in the Business Service Composer and becomes the file name of the saved project file. The project name is also used in building the source identifier for policy pattern created resources and relationships. Comment Allows you to provide a brief description of the contents of the project. Product Name As all static resources and relationships that are created as a result of the definitions in the Business Service Composer must be associated with a source, the product name, manufacturer name, and product version are used to build source identifying information for this project. This name is also called the management software system (MSS). Label The label that you want to include in the source identifying information for this project. Manufacturer Name The manufacturer name that you want to include in the source identifying information for this project. Product Version The product version that you want to include in the source identifying information for this project. Note: An asterix (*) indicates that a value must be entered for a field. 3. Click OK to create the new project or Cancel to exit without saving your project. The new project is created, added to the project list, and automatically opened the in Composer Project workspace. Editing a Business Service Composer project This topic outlines the steps that you must complete to edit a project in Business Service Composer. About this task To edit a project: Procedure 1. Click on the Project list toolbar. The Edit project dialog box is displayed. 2. Edit the project information and click OK to save your changes or Cancel to exit without saving your project. Business Service Composer 169

178 Deleting a Business Service Composer project This topic outlines the steps that you must complete to delete a project in Business Service Composer. About this task To delete a project: Procedure 1. Select a project from the Project list. Static resources 2. Click on the Project list toolbar. Click Yes in the resultant dialog box to confirm the deletion or No to cancel the deletion. Opening a Business Service Composer project This topic outlines the steps that you must complete to open a project in Business Service Composer. Procedure 1. Select a project from the Project list. 2. Click on the Project list toolbar. The project selected opens in a new tab. Static resources allow you to define and organize resources and relationships in Business Service Composer projects. Static resources are defined by creating static definitions in the Static Definition panel of the Business Service Composer. You can create as many static resources as you require. You can arrange the resources in a hierarchy or as a flat list. If a resource is defined without a parent resource, it is displayed in the Business Service Composer as a child of the Static Definitions anchor. A resource can have one or more parents or one or more children. When they are loaded into the Service Component Repository (SCR), static resources that do not already exist are created. If the static resource already exists in the SCR because it has been imported from another source, the SCR maintains a reference count to the resource from the source defined in the Business Service Composer project. It also maintains the original source of the resource. Typically, you use the Business Service Composer to create a static resource for one of two reasons: 1. To build all or part of the top level structure of a service model that cannot be imported from another source. To take full advantage of the Business Service Composer, one of the static resources is referenced by a policy pattern definition. This allows you to define a link with policy rule-matching resources. These static resources, which are a bridge between discovered resource instances and customer-defined resources, are referred to as touch point resources. 2. The second reason that you might create a static resource is to reference one or more resources that are imported from another source. This allows you to use the imported resource as a touch point reference in a policy pattern. This technique allows the Business Service Composer to enhance business service models that might be partially provided by a source such as TADDM, with resources provided by another source. 170 IBM Tivoli Business Service Manager: Customization Guide

179 Information required for static definitions When you create a static definition, you must provide information about the resource. This information consists of: v A resource classification v The resource identity v A display name or label The Business Service Composer limits the list of Common Data Model (CDM) classes to: v cdm:sys.businesssystem v cdm:app.application v cdm:core.collection These classes have been chosen because they represent CDM classes that are typically at the higher levels of a service model and each can be properly identified with a single unique string. The identity string, also referred to as the naming string, is a string that uniquely identifies the resource that is being created. This string must be unique for all static resource that are created within a particular Business Service Composer project. When the project is loaded into the SCR, the identity string is used to uniquely identify the resource and provides the SCR with the information that allows it to determine whether a new resource needs to be created or whether the resource has already been imported into the SCR. For the cdm:sys.businesssystem, cdm:app.application, and cdm:core.collection classes, the cdm:name attribute contains the identity string. This approach to the unique naming of statically-created resources provides a manageable naming strategy as well as a simple strategy for referencing resources from other import sources for the purpose of creating a touch point resource. Although not required in the CDM specification, the Business Service Composer requires that you provide a display name value for the resource. This value is the string that is used as the label for the resource and does not have to be unique. The Static Definition panel The Static Definition panel allows you to add and edit static definitions. The panel is dynamic and its content change based on the value of the class selected from the Select a Class list. Required input values are denoted with an asterix (*). The input field with the colored background indicates that this is the identifier field for the selected static resource class. The identifier values for this input field must be unique across all instances of the static resource definition class within a project. Adding a new static definition The following topic outlines the steps that you must complete to add a static definition. Procedure 1. In the Project View tree, select the static definition to which you would like to add. 2. Right-click on the selected definition and click Add. Business Service Composer 171

180 Policy patterns 3. If it is not already enabled, the Static Definition panel is enabled and initialized to the default static definition. 4. Select a new class if required. 5. Enter the appropriate class values and click Add. Add is only enabled when the necessary data has been entered. 6. You can continue to add definitions by repeating these steps. Note: When editing a static definition, the value of the identifier can not be changed. The Static Definition panel displays the current identifier value but the input field is disabled. Editing a static definition The following topic outlines the steps that you must complete to edit a static definition. Procedure 1. In the Project View tree, select the static definition that you would like to edit. 2. Right-click on the selected definition and click Edit. 3. If it is not already enabled, the Static Definition panel is enabled and initialized to the default static definition. 4. Select a class. 5. Enter the appropriate class values and click Update. Update is only enabled when the necessary data has been entered. Deleting a static definition The following topic outlines the steps that you must complete to delete a static definition. Procedure 1. In the Project View tree, right-click the static definition that you want to delete and click Delete. 2. Click Yes in the resultant dialog box to confirm the deletion, or click No to exit without deleting the static definition. Policy patterns created in the Business Service Composer are used to enrich the resource model within the Service Component Repository (SCR) by providing rules that create relationships between the touch point resources in your static resources and the touch point resources provided by other import sources. Though the touch point resources can be provided by any import source, dependency discovery sources such as IBM Tivoli Application Dependency Discovery Manager (TADDM), IBM Tivoli Composite Application Manager (ITCAM), or other Discovery Library Adapters (DLA) are extremely useful. These sources provide a deep dependency tree to fill out the service model of a business service. For example, a source might provide information about transactions and dependency relationships to other components such as subsystems, middleware, databases, servers, or other transactions that it depends on. Creating a relationship between a touch point business service resource in the static resource model and one or more of the transactions that the business service depends on creates a rich dependency tree for that service that is provided and maintained by the discovery source rather than being manually defined. 172 IBM Tivoli Business Service Manager: Customization Guide

181 Though it can vary somewhat, a policy pattern typically consists of one of more individual inputs that are used to uniquely define the pattern instance and a set of multi-valued inputs that define criteria for matching a touch point static resource with one or more pattern matching touch point resources not defined in the project. Touch point static resource Many of the policy pattern input set require that you provide a value for the touch point static resource that is used as the parent resource of the resources that are matched to the policy pattern. This value references to an existing static definition within the project. This value is a reference or link to an existing static definition within the project. The value for this column is presented in a drop-down list. Select from this list as required. Note: At least one static resource definition must exist before an input set that requires a touch point reference is completed. Policy pattern descriptions This section briefly describes each policy pattern provided with the Business Service Composer. The general structure of the input that you must provide for each policy pattern is outlined as well as additional information that aims to outline the appropriate use of each policy pattern. Note: Each of the policy patterns are named to indicate the action that the Business Service Composer initiates within the Service Component Repository (SCR). When a resource meets the criteria of the policy pattern, it is placed under the static resource to create a relationship between the static resource which is the source of the relationship, and the matching resource which is the target resource. By default, this relationship is interpreted as a dependency from the source resource to the target and is managed with the static resource as a parent of the target resource. Placing resources by class The PlaceByClass policy pattern places all instances of the specified resource class. This policy pattern can be used for a resource class with a low number of instances. For example, common data model (CDM) classes such as those representing CICS Transactions, cdm:sys.zos.cicstransaction, often have a very large number of instances that could result in a unmanageable model, if they were all placed under a single parent. Consider using this policy pattern to place class instances representing key middleware and subsystem components into a service model especially when the management of those components is centralized within your organization. Using the PlaceByClass policy pattern, you can easily build a service model for your Customer Information Control System (CICS) support team. Placing resources by class and matching attribute criteria The PlaceByAttribute policy pattern places all instances of the specified resource class when an attribute matches the supplied pattern. Each instance of the PlacebyAttribute policy pattern specifies a single attribute name that identifies the static resource touch point and a single attribute name that is matched against the supplied pattern to locate resources to be placed. If a different attribute must be used in the pattern matching, create another policy pattern instance. All instances Business Service Composer 173

182 are evaluated independently of one another. For example, it is not uncommon for J2EE applications or CICS transactions to be named in a way that helps identify the application that they implement. Using the PlaceByAttribute policy pattern, you can take advantage of resource naming conventions to identify key resources that implement a business application. Placing resources by class and matching label criteria The PlaceByLabel policy pattern is a variation of the PlacebyAttribute policy pattern that matches the supplied pattern against the label, or display name, of the resource in the Service Component Repository (SCR) and TBSM. Using the PlaceByLabel policy pattern, you can use the resource display name to place resources under a static resource touch point instance. Placing resources that require pattern matching beyond a single attribute The PlaceByIdentifier policy pattern works similarly to the PlaceByAttribute pattern except that it matches against Service Component Repository (SCR) resource identifier values rather than the attributes of a resource. Because the SCR resource identifiers are generated by an SCR Identifier rule that can output a string and associate it with a resource that is a combination of any number of literals, attribute values, and source tokens of a single resource or any number of related resources, this policy pattern brings a significant amount of pattern matching capability to the Business Service Composer. For more information about SCR Identifier rules, see the TBSM Customization Guide. Although Identifier rules are typically used to generate event matching strings for the BSM_Identity field, Identifier rules can also be used to set the field name for the output string to a value other than BSM_Identity. This is to avoid incorrect event matching when identifier strings are used for other purposes. For example, consider a situation where you wanted to place all service oriented architecture (SOA) operations running on a WebSphere message broker application server using a naming convention given to the operations. The SOA operations have a CDM class of cdm:soa.wsoperation and have an attribute named cdm:activityname that starts with the letters op. The application server has a CDM class of cdm:app.appserver with an attribute name of cdm:productname that is set to IBM WebSphere Message Broker. To achieve this: 1. Create an Identifier rule to capture these values in a string with a field name of PlaceMe and assign the rule to the cdm:soa.wsoperation resource. This rule creates an Identifier with a field name of PlaceMe and assigns a value of PlaceMe:::op1:::IBM WebSphere Message Broker to a given SOA operation. 2. Create a PlaceByIdentifier policy pattern instance using a Placement Identifier field value of PlaceMe and at least one input set that specifies the cdm:soa.wsoperation class instances that are to be placed. 3. Set a placement pattern of PlaceMe:::op%::: IBM WebSphere Message Broker. When resource placement requires that multiple attributes from one or more related resources are evaluated, use the PlacebyIdentifier policy pattern and customized Service Component Repository (SCR) Identifier rules to build a Business Service Composer project that meets your needs. 174 IBM Tivoli Business Service Manager: Customization Guide

183 Placing application servers based on their network domain The PlaceAppServersByFQDN policy pattern places all instances of the specified middleware class when the supplied pattern matches one or more of the fully qualified domain names of the server it runs on. The policy pattern implements the most common mechanisms for accessing all server fully qualified domain names. This includes looking for fully qualified domain names on the related operating system resource, on the related computer system resource, and on the related FQDN objects. The pattern also requires an attribute pattern match against a single attribute of the application server resource. If this condition is not desired, use the wildcard (%) pattern to match any attribute value. The PlaceAppServersByFQDN pattern is very useful for geographical, data center, or role placement of resources when domain names lend themselves to such comparisons for example, host1.lizardlick.company.com and host2.lab.camden.company.com. Using the PlaceAppServersByFQDN policy pattern, you can use conventions used for fully qualified domain names of servers to place key middleware components into groups. Placing subsystems based on the subsystem identifier The PlaceSubsystemsBySMFID policy pattern places all instances of the specified subsystem class when the supplied pattern matches the system identifier of the z/os system. The pattern also requires an attribute pattern match against a single attribute of the subsystem. If this condition is not appropriate, use the wildcard (%) pattern to match any attribute value. Using the PlaceSubsystemsBySMFID policy pattern, you can use conventions used for system identifiers (SMFIDs) on z/os systems to place key subsystem components into groups. Placing subsystems based on the domain name The PlaceServersByFQDN policy pattern places all instances of the specified computer system class, for example cdm:sys.computersystem, cdm:sys.aix.aixunitarycomputersystem, or cdm:sys.windows.windowscomputersystem, when the supplied pattern matches one or more of the fully qualified domain names of the server. The policy pattern implements the most common mechanisms for accessing all server fully qualified domain names. This includes looking for fully qualified domain names on the computer system resource, on the related operating system resource, and on the related FQDN objects. The PlaceServersByFQDN pattern is very useful for geographical, data center, or role placement of resources when domain names lend themselves to such comparisons. For example, host1.lizardlick.company.com and host2.lab.camden.company.com. Using the PlaceServersByFQDN policy pattern, you can use conventions used for fully qualified domain names of servers to place the servers into groups. Reorganizing resources into technology groups within an imported business service Using the DefineTechGroups and DefineTechGroupsByAttr policy patterns, you can take advantage of deep service model dependency trees to reorganize the structure of a business service model. This allows you to highlight the key technology components upon which a business services depends. Business Service Composer 175

184 The DefineTechGroups and DefineTechGroupsByAttr policy patterns instruct the Service Component Repository (SCR) to create the specified class-based technology groupings within a business application or service. These policy patterns vary from the other policy patterns in a number of ways: v Unlike the PlaceByClass policy pattern, the DefineTechGroups and DefineTechGroupsByAttr policy patterns limit the resources they place to those already part of the dependency tree for the specified business service or application. v The Business Service Composer does not require a statically-defined business service within the project. Instead, you identify the business services or applications that you want the Service Component Repository (SCR) to organize and also specify the required technology groupings. By default, the resource enrichment places a group container within the business service and the appropriate class resources are placed within the container. You can use the DefineTechGroups and DefineTechGroupsByAttr policy patterns, in conjunction with other policy patterns, to create a maintainable up-to-date service model. The touch point approach to service model building focuses on linking dependency trees that represent a transition point from your service model to a disjointed, and typically discovered, dependency model. The deeper and richer dependency models are of most value when the touch point resource represents an entry point into a business application and the underlying dependency model is maintained by the discovery source. The source of the business application to dependency model relationship can be any input source to the Service Component Repository (SCR), including IBM Tivoli Application Dependency Discovery Manager (TADDM). For example, for J2EE applications that operate as the touch point entry points for a business application, the dependency model which flows from the J2EE application might contain the application server to which it is deployed, followed by the server system on which the application server runs, followed by the attached network switch. It is also possible that the discovery source could provide a dependency between the J2EE application or application server and the database to which it connects. From there, the database resource might have a dependency tree to a database instance, then to the server system on which the database instance runs, and finally its network switch. Creating the touch point relationship between your high-level service model and the appropriate J2EE applications also causes the dependency tree described above to be linked to your service model. Although, TBSM displays this model as described, some scenarios require a technology organized view of the dependent resources of a business service. For example, after creating the touch point to the J2EE application, you might also want to create organized groups of databases, system servers, or middleware components that the J2EE application depends on. This requirement is met by the DefineTechGroups policy pattern. The DefineTechGroups and DefineTechGroupsByAttr policy patterns require several pieces of information including: v identification of the business service or application class v attribute name and pattern that are used to identify the target business service or application for the technology groups v category type for the technology group v label of the technology group container that you are creating v technology group base class to identify the dependent objects that are placed in the container. 176 IBM Tivoli Business Service Manager: Customization Guide

185 v for a DefineTechGroupsByAttr policy pattern, an attribute name and pattern are provided to further identify the resources that are to be placed. There are some additional considerations when using this policy pattern: v The Selection Attribute, Selection Class, and Selection Pattern are used to identify the business service or application instances for technology group maintenance. Although it is easy to define a wildcard pattern that activates this feature for all instances of those classes, it might be appropriate to limit this selection to the instances where this policy pattern provides value. v The technology group class is a base class specification as defined by the meta model contained within the SCR. As the SCR has meta data related to the common data model (CDM), if a CDM class is specified here, the SCR applies this rule to that class and all subclasses of the class. For example, a specification of cdm:sys.computersystem also applies the rule to instances of classes cdm:sys.windows.windowscomputersystem, and cdm:sys.aix.aixunitarycomputersystem. No other policy pattern treats a class specification as a base class. v You can create additional rows to the input set if the technology groups need to include multiple resource classes. In that case, create an additional row with all the same values except for the additional technology group class. v When providing a category identifier and a category label, ensure that the label value is consistently used across multiple rows for the same business system and category identifier. This is important as the category identifier is used to create the container object. If different rows have different values for the category label, the resulting label used for the container resource is unpredictable. v For the DefineTechGroupsByAttr policy pattern, the Singleton Placement Attribute is used to define the attribute that is tested to determine if an input set Placement Pattern is matched resulting in the resource being added to the technology group. Adding a policy pattern The following topic outlines the steps that you must complete to add a policy pattern. Procedure 1. In the Project View tree, right-click the policy pattern and click Add. 2. If it is not already enabled, the Policy Pattern panel is enabled and initialized to the selected policy pattern. 3. Enter values for the displayed input fields. 4. Click to select an input value set in the Input Sets panel. The Input Values panel is activated. 5. Click on a row in the Input Values table. Select values for the columns provided. 6. To add additional rows, click the button. Note: Click the button. This allows you to select a value for each of the columns in the Input Values table. The fields that are displayed are the same as those displayed in the table view. 7. When you have updated the required values, click Add. Business Service Composer 177

186 Note: If you attempt to add a policy pattern that already exists, a dialog is displayed indicating that a duplicate has been identified. Click Update to update the existing policy pattern. Editing a policy pattern The following topic outlines the steps that you must complete to edit an existing policy pattern. Procedure 1. In the Project View tree, right-click the policy pattern and click Edit. 2. If it is not already enabled, the Policy Pattern panel is enabled and initialized to the selected policy pattern. 3. Edit, as required, the values for the displayed input fields. 4. Click to select an input value set in the Input Sets panel. The Input Values panel is activated. 5. Click on a row in the Input Values table. Select values for the columns provided. 6. To add additional rows, click the button. Note: Click the button. This allows you to select a value for each of the columns in the Input Values table. The fields that are displayed are the same as those displayed in the table view. 7. When you have updated the required values, click Update. Deleting a policy pattern The following topic outlines the steps that you must complete to delete a policy pattern. Procedure 1. In the Project View tree, right-click the policy pattern that you want to delete and click Delete. 2. Click Yes in the resultant dialog box to confirm the deletion, or click No to exit without deleting the policy pattern. Deploying a project After a project is created and saved, its contents are saved in a project file. This project file is stored in the CRViewer projects directory. Importing this project into the Service Component Repository (SCR) is a manual process that involves making the project file available to the Discovery Library Toolkit and running the loadbusinessbusinesscomposerdefinitions command located in the XMLToolkit/bin directory. This command has the syntax: loadbusinessbusinesscomposerdefinitions [-U dbuserid [-P dbpassword]] [[-n file_path]] where: -U The database user ID. If you do not specify a value for this parameter, you are prompted for the database user ID. -P The database used ID password. If you do not specify a value for this parameter, you are prompted for the database user ID password. 178 IBM Tivoli Business Service Manager: Customization Guide

187 -n The fully qualified path of the Business Service Composer project file that you want to load. Note: For additional information about the syntax of this command, enter the command followed by?. When you run this command: v A idml book is created and copied to the Discovery Library Toolkit import books directory for processing: The source identification, management software system (MSS), for the book is derived from the project properties and is set to BSCitbsm.ProductName=project product name value+manufacturer=project manufacturer name value+hostname=bsc.hostname of the XMLtoolkit machine.timestamp when file was generated.refresh.xml The book contains the static resource definitions of the project. The book contains the instructions for a refresh operation which instructs the Service Component Repository (SCR) to synchronize the resource and relationship information found in the current book with any previous information from the same MSS. Note: Ensure that you define the project properties in a way that does not remove previously loaded data from another project using the same MSS name. v An SCR notification file is created that contains the policy pattern notification rules that are used to implement the rules: Notifications instruct the SCR to monitor its import process for resources that are to be created or deleted according to the completed policy pattern. Notifications alert the SCR resource enrichment process to take the appropriate action to achieve the proper placement of resources. The name of the file is formed using project properties in the format: BC.ProductName=project product name value+manufacturer=project manufacturer name value+hostname=bsc.notifications.xml The notification file is inserted into the environment using the putartifact command. Note: For more information about the notifications and resource enrichment process, see the Import resource information into the SCR section of the TBSM Customization Guide. Note: For more information about the putartifact, see the TBSM Administrator's Guide. v After the Discovery Library Toolkit has imported the static resource idml book, the utils -e reload_notifications.xml command runs to reload and evaluate all current notifications. The utils -e reload_notifications.xml command causes the Discovery Library Toolkit to reload all current configuration artifacts, including the new notification file. Then notifications are evaluated by the resource enrichment engine and the resource enrichment process is initiated where appropriate. If for any reason the loadbusinessbusinesscomposerdefinitions command times out waiting for the IdML book to be loaded, it displays a warning requesting that the command is run manually. Business Service Composer 179

188 v If the reloaded notification rules result in notification trigger events, the resource enrichment process begins: The ResEnrichReader service is configured to run a Netcool/Impact policy name ResEnrichMain to process notifications. This policy has a switch clause to run the appropriate enrichment Netcool/Impact policy to properly handle the notification. The enrichment Netcool/Impact policies ensure resource and relationship changes are pushed to the SCR using the SCR API. For more information about the SCR API, see the TBSM Customization Guide. The Discovery Library Toolkit processes the SCR API resource and relationship requests and passes them to a process that causes notification rules to be evaluated with the potential for the complete process to repeat. Note: For more information about the notifications and resource enrichment process, see the Import resource information into the SCR section of the TBSM Customization Guide. Note: The Resource Enrichment Process requires that the Netcool/Impact service ResEnrichReader must be running. By default, this service is set to off. If it is not running, resource enrichment does not occur. After the load of a project is completed, the Discovery Library Toolkit is properly configured to monitor changes to the resource, attribute, and relationship data maintained in the SCR to determine in the resource enrichment process is required. Removing the impact of a project on the SCR The unloadbusinesscomposerdefinitions command allows you to unload a Business Service Composer project and the effect of its placement rules from the Service Component Repository (SCR). This command is located in the XMLToolkit/bin directory. Syntax The unloadbusinesscomposerdefinitions has the following syntax: unloadbusinesscomposerdefinitions [-U dbuserid [-P dbpassword]] [-n file_path] [-c project name] Parameters The parameters for this command are: -U The database user ID. If you do not specify a value for this parameter, you are prompted for the database user ID. -P The database used ID password. If you do not specify a value for this parameter, you are prompted for the database user ID password. -n The fully qualified path of the Business Service Composer project that you want to unload. This parameter is the file path and file name for the project. -c The name of the project that you want to unload. This parameter is the name of the project as it displays in the Projects list. Note: For additional information about the syntax of this command, enter the command followed by?. 180 IBM Tivoli Business Service Manager: Customization Guide

189 Samples Redeploying a project Reference information This example unloads the contents of the BSC_Project1 project: -unloadbusinesscomposerdefinitions -U dbuserid -P dbpassword -c BSC_Project1 This example unloads the contents of the BSC_Project1.xml file: -unloadbusinesscomposerdefinitions -U dbuserid -P dbpassword -n $TBSM_HOME/XMLtoolkit/tools/crviewer/projects/BSC_Project1.xml When a project is redeployed into the same Discovery Library Toolkit, it completes the same process as the previous load. When you redeploy a project: v A new static resource idml book with a refresh operation is loaded. As a result, the Service Component Registry (SCR) synchronizes its persisted data with the contents of the book. Resources that are currently persisted in the SCR and are also in the new book are left untouched, new resources in the book are created, and resources that are persisted but no longer referenced in the new book are removed. v Because of the naming convention used for notification files, the previous notification file is replaced and loaded into the system. v Any required policy pattern updates are completed appropriately resulting in the proper placement of resources according to the new guidelines. v New policy pattern instances are added to the environment and acted upon. The following section contains additional reference information that can be used when using the Business Service Composer. Identifying the MSS names for the resource and relationship references All inputs to the Service Component Repository (SCR), including those created as the result of a project deployment, must have an associated unique source identity, or MSS name. The SCR tracks the existence of an MSS source, or sources, for every resource and relationship. If more than one MSS source references the same resource, the resource is created once and a reference is maintained to each MSS source. If one MSS source instructs the SCR to delete a resource, the SCR deletes the reference to that MSS but only deletes the resource if no other references remain. When a Business Service Composer project is deployed, an MSS for the defined static resources and one or more MSS names for each instance of a policy pattern within the project. The MSS name for the static resource is derived by substituting the appropriate project property values into the following string: ProductName=project product name+manufacturer=project manufacturer name+hostname=bsc Although it varies somewhat, the MSS name used for notification rules for a policy patterns generated by the Business Service Composer are derived by the project name, the policy pattern that created the instances, the policy pattern singleton input, and literals that help to uniquely identify the source of the resource and Business Service Composer 181

190 relationship content. This complexity is required to assure that instances of policy patterns can act independently of one another thereby resulting in correct placement of resources. This list describes the patterns used to create MSS name identification strings for Business Service Composer notification rules. In each case, the italicized string is replaced with the appropriate information from the Composer project. PlaceByAttribute project name.placebyattribute+selection Attribute Name+Placement Attribute Name+policy PlaceByClass project name.placebyclass +Selection Attribute Name+policy PlaceByIdentifier project name.placebyidentifier+selection Attribute Name+Placement Identifier Field Name+policy PlaceByLabel project name.placebylabel+selection Attribute Name+policy PlaceSubsystemsBySMFID project name.placesubsystemsbysmfid+selection Attribute Name+Placement Attribute Name+policy PlaceAppServersByFQDN project name.placeappserversbyfqdn_os+selection Attribute Name+Placement Attribute Name+policy project name.placeappserversbyfqdn_cs+selection Attribute Name+Placement Attribute Name+policy project name.placeappserversbyfqdn_fq+selection Attribute Name+Placement Attribute Name+policy DefineTechGroup project name.a_definetechgroups+selection Attribute Name+policy+CreateShadow project name.z_definetechgroups+selection Attribute Name+policy+TechGrpBusCompCreateTechnologyGroups 182 IBM Tivoli Business Service Manager: Customization Guide

191 Configuration for z/os events This topic describes how to configure the IBM Tivoli Business Service Manager to monitor events from the IBM Tivoli Event Pump for z/os. Tivoli Event Pump for z/os Overview This topic provides an overview of how the IBM Tivoli Event Pump for z/os functions. The Tivoli Event Pump for z/os collects and forwards z/os status events to the Netcool/OMNIbus ObjectServer. TBSM release 4 monitors ObjectServer events and use these events to manage and update services. The IBM Tivoli Event Pump for z/os is a revised version of the source/390 object pump delivered with the Tivoli Business Systems Manager version 3 product. The Event Pump for z/os consists of the source collector, data space, and event distributor address spaces on each z/os image The Host to Tivoli Enterprise Console Interface allows event messages collected by the Event Pump to be sent to the Netcool/OMNIbus Tivoli Event Integration Facility probe and then to the ObjectServer. This capability carries forward from the source/390 object pump. The Event Pump includes the following elements: v Event Pump code, which runs on the host system with new features enabled by inclusion of DD cards v New utilities for converting message registration data into a new format used by the Event Pump v Tivoli Event Integration Facility probe rules for formatting the Event Interchange Facility (EIF) events into Netcool/OMNIbus alerts v Netcool/OMNIbus ObjectServer schema updates for z/os event fields and triggers, and lookup tables For detailed information about the Event Pump for z/os, see the Tivoli Event Pump for z/os Installation and Configuration Guide and Tivoli Event Pump for z/os Messages Guide. Event flow The TBSM Data server monitors the Netcool/OMNIbus ObjectServer for z/os events that are associated with defined business services. The incoming status rules associated with resources created through use of the z/os DLA and Discovery Library Toolkit use the alert field BSM_Identity to correlate events to service instances and determine service instance status. TBSM aggregation rules propagate service status to parent services. 1. Events are written by various subsystems. 2. z/os Message Registration Data determines messages to forward for some data sources. 3. Events are forwarded from the Event pump to the OMNIbus EIF probe where the event fields are mapped to ObjectServer fields. Copyright IBM Corp. 2008,

192 4. The mapped z/os events are inserted into the OMNIbus ObjectServer, the OMNIbus schema is updated to include z/os event fields. Message severity is set by OMNIbus triggers and lookup tables. Resolution messages are processed to clear previous messages. 5. Events are correlated with service instances created by the Discovery Library Toolkit from z/os DLA books or are used to create service instances from the event using Auto-Population Rules. Event pump and the Discovery Library Toolkit The TBSM Discovery Library Toolkit supports the import of z/os discovery data from the z/os DLA and correlation of status events from the Tivoli Event Pump for z/os (zpump) to these resources. The configuration files are included in the base TBSM installation package. After you install the Discovery Library Toolkit for z/os discovery processing there are no additional required configuration steps. You can change predefined discovery rules for class mapping, relationship mapping, or identity mapping to meet customer-specific requirements. See the section of TBSM Scenarios Guide for example mapping configurations for the Discovery Library Toolkit. Event pump and auto-population rules You can also create TBSM services directly from z/os events by using auto-population rules. For more information about auto-population rules see the TBSM Scenarios and Service Configuration guides. Related concepts: Energy Dashboard installation requirements and components on page 222 This section details the software requirements and other installation information. Event Pump and Netcool/OMNIbus This topic describes the Tivoli Event Pump for z/os components used by Netcool/OMNIbus. The Tivoli Event Pump for z/os includes EIF probe rules files that you use with TBSM. These rule files correlate events with z/os Discovery Library Support updates and include lookup tables that set the identity based on the class specified by an event. TBSM Event pump z/os rule files TBSM includes a small set of rules files that can be use by the event flow between z/os and TBSM. The set of files available form TBSM are : Table 54. TBSM Event pump z/os rule files File tivoli_eif_zos_tbsm.rules zos_classid.lookup zos_identity.rules zos_objectid.lookup Description TBSM z/os lookup table reference rule file. TBSM z/os lookup table by class ID. TBSM z/os BSM_Identity rule file. TBSM z/os lookup table by object ID. 184 IBM Tivoli Business Service Manager: Customization Guide

193 Table 54. TBSM Event pump z/os rule files (continued) File zos_objectid.low.lookup zos_objectid.medium1.lookup zos_objectid.medium2.lookup Description TBSM z/os lookup table by object ID example of minor behavior. TBSM z/os lookup table by object ID example 1 of major behavior. TBSM z/os lookup table by object ID example 2 of major behavior. In previous versions of TBSM, these files were only included as part of the TBSM Tivoli EIF Probe installation and were not available beyond the installer. The TBSM Tivoli EIF Probe installation was used to install the probe in order to see these files. In TBSM, the tbsm_extensions folder contains the same set of files that were previously only available through the installer. In addition to the new tbsm_extensions folder location, these files are also available in the following locations if the Tivoli EIF probe is installed using the TBSM installer: C:\Program Files\IBM\tivoli\netcool\omnibus\probes\win32\tbsm_extensions Opt/IBM/Tivoli/netcool/omnibus/probes/<arch>/tbsm_extensions The tivoli_eif.rules file contains comments about the use of the rules files contained in the tbsm_extensions folder. The following is an example of one of those comments: # Uncomment the following include line to use the TBSM z/os Identity Rules # provided with TBSM. The TBSM extension files can be fund in a folder named # "tbsm_extensions" located in the base directory of the TBSM installation media # include "tivoli_eif_zos_tbsm.rules" Rule file lookup tables The EIF probe rules files support the use of file-based lookup tables. These lookup tables are used to "lookup" a value, say from an event token, and return 1 or more values. The returned values can then be used within the rules file logic, assigned to variables or mapped to columns within the event. Note: All lookup table definitions must appear at the top of the first.rules file used by the EIF probe which for z/os event support is: tivoli_eif.rules. For TBSM z/os event support, the tivoli_eif_zos_tbsm.rules file references two lookup tables zos_classid and zos_objectid. These lookup tables are contained in the files: v zos_classid.lookup v zos_objectid.lookup Three additional sample lookup table files are included: v zos_objectid.low.lookup Configuration for z/os events 185

194 v zos_object.medium1.lookup v zos_object.medium2.lookup These additional sample lookup files can be used to control the placement of z/os within the service tree by setting the BSM_Identity to certain values. See the comments within each file for additional information. Enabling the z/os rule files By default, the TBSM z/os rule files are commented out in the tivoli_eif.rules file. To enable TBSM support for z/os events, the tivoli_eif.rules file must be updated to include the TBSM z/os specific rules files. Enabling the TBSM zos_identity.rules z/os rule files Follow these steps to include the zos_identity.rules provided by TBSM: 1. Make a backup copy of the tivoli_eif.rules file 2. Copy the following files from the tbsm_extensions folder : tivoli_eif_zos_tbsm.rules zos_identity.rules zos_classid.lookup zos_objectid.lookup Note: The tbsm_extensions folder can be found on the TBSM installation media or in one of these location if the Tivoli EIF Probe was installed using the TBSM Tivoli EIF Probe installer: C:\Program Files\IBM\tivoli\netcool\omnibus\probes\win32\tbsm_extensions opt/ibm/tivoli/netcool/omnibus/probes/<arch>/tbsm_extensions 3. Edit the tivoli_eif.rules file and locate this comment section: # Uncomment the following include line to use the TBSM z/os Identity Rules # provided with TBSM. The TBSM extension files can be found in a folder named "tbsm_extensions" located in the base directory of the TBSM installation media # include "tivoli_eif_zos_tbsm.rules" 4. Remove the # comment character from this line: # include "tivoli_eif_zos_tbsm.rules" 5. Locate the comment section: # Uncomment the following include line to use the TBSM Identify rules for the z/os Event Pump provided with TBSM in %OMNHOME%\probes \win23\tbsm_extensions on Windows and in $OMNHOME/probes/ tbsm_extensions for non-windows # include "zos_identity.rules" 6. Remove the # comment character from this line: # include "zos_identity.rules" 7. The 2 updated comment sections are now updated to: # Uncomment the following include line to use the TBSM z/os Identity Rules provided with TBSM. The TBSM extension files can be found in a folder named "tbsm_extensions" located in the base directory 186 IBM Tivoli Business Service Manager: Customization Guide

195 of the TBSM installation media include "tivoli_eif_zos_tbsm.rules" # Uncomment the following include line to use the TBSM Identify rules for the z/os Event Pump provided with TBSM in %OMNHOME%\ probes\win23\tbsm_extensions on Windows and in $OMNHOME/probes /tbsm_extensions for non-windows include "zos_identity.rules" 8. Save the tivoli_eif.rules file and restart the EIF probe. Event mappings for z/os Event Pump This section describes the special Netcool/OMNIbus event columns (fields) that the EIF probe creates from Event Pump for z/os data Purpose The Tivoli Event Integration Facility probe receives inbound z/os events, formats them into Netcool/OMNIbus event tokens using probe rule. The probe then forwards the resulting events to the Netcool/OMNIbus Object Server monitored by TBSM. ObjectServer event identity attributes When the EIF Probe maps Event Pump for z/os data into ObjectServer events, it sets both general Netcool/OMNIbus attributes and z/os specific attributes. These attributes become fields (columns) in the Netcool/OMNIbus alerts.status table. The identity columns listed here match the Event Pump for z/os events to TBSM resources. These columns are also used for de-duplication redundant events and for processing clearing events in Netcool/OMNIbus. BSM_Identity Identifies the resource the event is for for example, an IMS Subsystem on a z/os. used for matching events to instances in status rules in TBSM BSM_SubIdentity Identifies a component of the BSM_Identity that the event is related to. For example to distinguish events involving different IMS Transactions, the transaction name is in the BSM_SubIdentity column. The BSM_SubIdentity is optional. Used in TBSM ZOS_ResourceName Identifies the resource the event is for, for example, an IMS Subsystem on a z/os. used for event correlation in Netcool/OMNIbus clearing triggers ZOS_SubResourceName Identifies a component of the ZOS_ResourceName that the event is related to. For example to distinguish events involving different IMS Transactions, the transaction name is in the ZOS_SubResourceName column. This is used for event correlation in OMNIbus clearing triggers. ZOS_SubResourceType Identifies the resource class for example IMTX = transaction. This is used for event correlation in OMNIbus clearing triggers. ZOS_EventId Event identifier for the BSM_Identity + BSM_SubIdentity for example, IEF452I Configuration for z/os events 187

196 Other z/os attributes for ObjectServer events When the EIF probe maps Event Pump for z/os data, it also sets z/os-specific attributes in thenetcool/omnibus ObjectServer alerts.status table. ZOS_Action Identifies the type of event for example 03 = message, 04 = exception, 05 = resolution. ZOS_ClassID Identifies the resource class for example CITL = transaction. ZOS_SequenceNo Sequence number used to locate the event in mainframe logs. ZOS_MsgState Message events might also have State for example, Abended. This value is assigned from a lookup table in the Netcool/OMNIbus ObjectServer. ZOS_IsUserSeverity Flag used to indicate user assigned severity. Resource identity data formats This topic describes the identity field data formats for the z/os resource types. Purpose When the EIF Probe maps Event Pump for z/os data into ObjectServer events, it creates BSM_Identity and BSM_SubIdentity field values for the various z/os resource types. These attributes are used to match events to TBSM resources. BSM_Identity data formats This table describes the data formats for the z/os resource types in TBSM. Note: The z/os SMF ID for a resource has 1-4 characters and a z/os SYSNAME has 1-8 characters. Most sites configure the z/os images to have the same value for both the SMF ID and SYSNAME. Therefore you normally only see two BSM_Identity values if you view the resource in the TBSM Service Component Repository (SCR). Table 55. BSM_Identity data formats z/os Resource type ZOS AddressSpace IMSSubsystem IMSSysplexGroup Data format job name:smf id job name:sysname job name:netid.sscp job name:smf id job name:sysname job name:netid.sscp subsystem:smf id subsystem:sysname subsystem:netid.sscp imsplex:smf id imsplex:sysname imsplex:netid.sscp 188 IBM Tivoli Business Service Manager: Customization Guide

197 Table 55. BSM_Identity data formats (continued) z/os Resource type DB2Subsystem DB2DataSharingGroup CICSRegion Data format subsystem:smf id subsystem:sysname subsystem:netid.sscp datasharinggroup:smf id datasharinggroup:sysname datasharinggroup:netid.sscp job name:smf id job name:sysname job name:netid.sscp BSM_SubIdentity values The following table describes the values for the BSM_SubIdentity attribute. The BSM_SubIdentity is assigned based on the object type. The notation in this table shows the source of the object type in terms of the event field code. This table describes the values for DB2 objects. Table 56. BSM_SubIdentity values for DB2 objects Event Pump Object type Value Object description DBBP ssname Buffer Pools DB2 Buffer Pool DBDB Database Name DB2 Database DBDD DDF Address Space Name, for example: DB2SDIST DB2 Data Distribution Facility DBDG null DB2 Data Sharing Group DBDS Database Services Address Space Name, for example DB2SDBM1 DB2 Database Services DBEP ssname EDM Pool DB2 EDM Pool DBIP Owner.Index Partition Name DB2 Index Partition DBIX Owner.Index Name DB2 Index DBLG ssname DB2 Logs DB2 Logs DBLK IRLM Address Space Name DB2 Lock Manager DBMS Master Address Space Name, for example, DB2SMSTR DB2 Master Address Space DBPM ssname DB2PM DB2 Performance Monitor DBSP Stored Procedures Address Space Name DB2 Stored Procedures Manager DBSS null DB2 Subsystem DBTB Owner.Table Name DB2 Table DBTP DBTS Database Name: Tablespace Partition Name Database Name:Tablespace Name DB2 Tablespace Partition DB2 Tablespace DBVW null DB2 View OSPX z/os Sysplex Configuration for z/os events 189

198 This table describes the values for IMS objects. Table 57. BSM_SubIdentity values for IMS objects Event Pump Object type Value Object description IMSS null TMDB IMTM null DCCTL IMDB null DBCTL IMIR IMS Database Lock Manager IRLM IMCQ Common Queue Server CQS IMFD Fast Database Recovery FDR IMIT IMS Tcpip Otma Connection ITOC IMMP Message Processing Region MPR IMFP Fast Path Regions FPM IMLG IMS Online Logs LOG IMBM Batch Regions BMP IMTX IMS Transaction TRAN IMPG IMS Program PROG IMDA IMS Database DBS IMAR IMS Database: IMS Fast Path Area AREA AREA IMD2 IMS Attachment to DB2 DB2 IMMQ IMS Attachment to MQS MQS IMPA IMS Database: IMS Partitioned Database HALDB IMOM IMS Operation Manager Operation Manager IMRM IMS Resource Manager Resource Manager IMCI IMS Structured Call Interface Structured Call Interface OSPX OS Sysplex null This table describes the values for CICS objects. Table 58. BSM_SubIdentity values for CICS objects Event Pump Object type Value Object description CICM CMAS Name CMAS CIMA MAS Name MAS CITR Transaction ID Transaction, Remote CITL Transaction ID Transaction, Local CIFR Definition name Remote CIFL Definition name File, Local Resource Identity and z/os Discovery This topic describes how the identity data from the IBM Tivoli Event Pump for z/os works with z/os data retrieved with the TBSM Discovery Library Toolkit. 190 IBM Tivoli Business Service Manager: Customization Guide

199 Each of the individual z/os probe rules files sets values for BSM_Identity and BSM_SubIdentity for each event. BSM_Identity identifies the event resource at a subsystem level (such as an IMS Subsystem) and BSM_Sub_Identity identifies a lower-level component of the subsystem (such as an IMS Transaction within the IMS Subsystem). For example, to distinguish events involving different IMS Transactions, the transaction name is in the BSM_SubIdentity column. The BSM_SubIdentity is optional. Discovery Library Toolkit and event matching The TBSM Discovery Library Toolkit creates default incoming status rules for each imported resource mapped to a TBSM service instance. These status rules use the BSM_Identity event attribute to match incoming events to service instances. Accordingly, this identity value must be set correctly, for the event matching work properly. The Discovery Library Toolkit also creates objects based on class mapping rules and composite rules. Class mapping rules determine the service template assigned to a service instance created by the Discovery Library Toolkit. Composite rules create composite or group objects for specified discovered resources. For z/os objects, the default rules create objects for subsystem level entities like a CICS Region and then group objects for lower-level resources such as CICS Transactions. The result is that one object represents all CICS transactions associated with its parent region. You can customize these rules to produce objects that represent multiple CICS transactions with a common naming convention or to produce objects for each individual transaction. Rules files and the Discovery Library Toolkit The zos_identity_rules file is used in combination with the TBSM Discovery Library Toolkit updates for proper event correlation with resources discovered with the z/os DLA and imported into TBSM by reading the IdML book directly or importing the data from Tivoli Application Dependency Discovery Manager. This rule file contains logic for setting the event correlation ID, BSM_Identity. These rules must be included in the probe rules following the individual z/os rules files described in the installation section. This rule file would be included in the tivoli_eif_rules file or commented out if not in use. BSM_Identity is set based on a configured identity behavior which is configured in a set of lookup tables. The use of lookup tables allows the identity behavior to be changed with a simple table modification. This behavior can be set to one of three values. v Major specifies that BSM_Identity is set to subsystem level identity. BSM_Identity=BSM_Identity v Minor specifies that BSM_Identity is set to object level identity BSM_Identity=BSM_SubIdentity:BSM_Identity v Literal specifies that BSM_Identity is set to a group object where groupname is a literal value. BSM_Identity=literal:BSM_Identity Configuration for z/os events 191

200 Examples A Major specification results in an event describing an issue with an IMS transaction is associated with the IMS Subsystem Object that was created through a discovery technology for example, z/os DLA. A literal specification results in an event describing an issue with an IMS transaction is associated with a discovered object whose BSM_Identitiy identification assigned to a discovered resource within TBSM matches the literal value: and the IMS Subsystem BSM_Identity. The TBSM out of box configuration, and the literal assigned in the probe lookup file by default matches to assign the event to an object that represents all IMS transactions running on a particular IMS Subsystem. A Minor specification results in an event describing an issue with an IMS transactionis associated with the IMS Transaction Object that was created through a discovery technology for example, z/os DLA. If the object is not discovered, the event is not processed by TBSM. Please note, by default the z/os DLA does not include IMS transactions in its Idml book. Two lookup files are provided to set the identity behavior. The first table, zos_classid.lookup, looks up the behavior based the class as set in the ZOS_ClassID attribute. This allows identity to be set first by class. The second table provided, zos_object_id.lookup, looks up the behavior based on the object ID as set in the BSM_SubIdentity attribute. This allows identity behavior to be refined and set for a specific object within a class. The following section includes the rule logic in zos_identity.rules and illustrates how each table is used to assign an identity behavior: if (exists( $ClassName) AND match($classname,"tbsmv3_source390") AND exists($name_value_pairs)) { log(debug, "zos_identity.rules - Current event is a Z event.") log(debug, "ZOS_ClassID for current Z event := [" + "]") $behavior = "" $zbsm_subidentity # Lookup to assign identity behavior by class; table has default of Unknown [$behavior ] = lookup(@zos_classid,"zos_classid") log(debug, "--- zos_identity.rules - Table lookup returned :") log(debug, "--- zos_identity.rules - $behavior = [" + $behavior +"]") # Substring the BSM_SubIdentity before lookup by object id # e.g. Useful for assigning identity behavior for object ids based on naming convention # Use with sample zos_objectid.medium2.lookup # $zbsm_subidentity = substr($bsm_subidentity,1,2) # Lookup to override identity behavior by object id; table has no default # [$behavior ] = lookup($zbsm_subidentity,"zos_objectid") # log(debug, "--- zos_identity.rules - Table lookup returned :") # log(debug, "--- zos_identity.rules - $behavior = [" + $behavior +"]") # Test to see if there was no row in the lookup tables returned by testing all variables for default values. if( match($behavior,"unknown")) { 192 IBM Tivoli Business Service Manager: Customization Guide

201 $behavior = "Major" } else { if( match($behavior,"minor") ) { } + ":" if( match($behavior,"major") ) { # See if the behavior values is a literal from either lookup table if(!match($behavior,"major") AND!match($behavior,"Minor") AND!match($behavior,"Unknown")) { } = $behavior + ":" The following section includes the lookup table for setting identity behavior by class in zos_classid.lookup: ## Set identity behavior by class ## ##Key Behavior DBDB Db2DatabaseGroup IMTX IMSTransactionGroup IMPG IMSProgramGroup IMDA IMSDatabaseGroup CITR CICSTransactionGroup CITL CICSTransactionGroup CIFR CICSFileGroup CIFL CICSFileGroup ## ## ## Set identity behavior for objects of specified class ## Set identity behavior based on class id (ZOS_ClassID> ## Default behavior for all other classes will be Major ## ## Key Value = zos class id ## Behavior = Major or Minor or <literal> ## Major specifies that BSM_Identity is set to subsystem level identity ## BSM_Identity=BSM_Identity ## Minor specifies that BSM_Identity is set to object level identity ## BSM_Identity=BSM_SubIdentity:BSM_Identity ## <literal> specifies that BSM_Identity is set to group object where groupname is <literal> ## BSM_Identity=<literal>:BSM_Identity ## ## Example ## All CICSTransactions events will be assigned BSM_Identity=CICSTransactionGroup:BSM_Identity Configuration for z/os events 193

202 The following section includes the lookup table for setting identity behavior by object id in zos_objectid.lookup (this is actually an example table zos_objectid.low.lookup) ## Set identity behavior by object id ## ##Key Behavior CEMT Minor CEST Minor ## ## Set identity behavior for specified objects ## Set identity behavior based on object id (BSM_SubIdentity) ## Default behavior for all other objects will be specified by object type ## ## ## Key Value = object id ## Behavior = Major or Minor or <literal> ## Major specifies that BSM_Identity is set to subsystem level identity ## BSM_Identity=BSM_Identity ## Minor specifies that BSM_Identity is set to object level identity ## BSM_Identity=BSM_SubIdentity:BSM_Identity ## <literal> specifies that BSM_Identity is set to group object where groupname is <literal> ## BSM_Identity=<literal>:BSM_Identity ## ## Default table is empty ## Examples of setting identity behavior by object id (BSM_SubIdentity or eg transaction) ## Assign specific transactions 1,2 to a Group1 object id ## Assign specific transactions 3,4 to a Group2 object id ## Assign specific transaction 5 to Minor so identity will be set to specific transaction level identity ## Assign default identity behavior for all other transactions in zos_objecttypeid.lookup ## to Major so default identity will match subsystem level object Some additional lookup tables, zos_objectid.low.lookup, zos_object.medium1.lookup, and zos_object.medium2.lookup have been provided as examples to set identity behavior by class specified in event (BSM_SubIdentity). For more details about the IBM Tivoli Event Pump for z/os, see com.ibm.tivoli.eventzos.doc_422/ic-homepage.html 194 IBM Tivoli Business Service Manager: Customization Guide

203 OSLC hover preview configuration The Open Services Lifecycle Collaboration (OSLC) Hover Preview functionality uses Jazz for Service Management Registry Services to support hover preview. The Registry Services identify the products that register as providers of preview data for a particular resource. Jazz for Service Management is bundled with IBM Tivoli Business Service Manager and includes deployable shared services, including: v UI Services (IBM Dashboard Application Services Hub) v Reporting Services (Tivoli Common Reporting (TCR)) v Security Services (ESS for Single Sign-On Support for non-websphere applications) v Registry Services (Provider and Resource Registries supporting OSLC / linked data) v Administration Services (Configuration and Health Checking) Jazz for Service Management can deploy the services used by TBSM. These services include the User Interface and Registry Services for TBSM. The OSLC Hover Preview uses Registry Services to identify which products are registered as preview-data providers for a particular resource. Here is a component architecture view of the deployment: Figure 12. TBSM and Jazz for Service Management architecture Jazz for Service Management is required for the hover preview feature in TBSM. Required Products: Jazz for Service Management For more information, see the Jazz for Service Management Information Center at: Copyright IBM Corp. 2008,

204 OSLC com.ibm.psc.doc_1.1.0/psc_ic-homepage.html For a brief explanation of OSLC with links to more detailed information: Open Services for Lifecycle Collaboration home?lang=en#/wiki/tivoli%20monitoring/page/open%20services%20for %20Lifecycle%20Collaboration Tivoli Monitoring and OSLC Performance Management Service Provider For information about installing and configuring IBM Tivoli Monitoring components for Jazz for Service Management Registry Services, see the Tivoli Monitoring publications for version 6 release 3 at: home?lang=en#!/wiki/tivoli%20documentation%20central/page/tivoli %20Documentation%20Central Search for IBM Tivoli Monitoring under M: The OLSC features for Tivoli Monitoring require the installation of the Tivoli Enterprise Monitoring Automation Server component. Instructions for installing this component can be found here: Installation and Configuration Guides > Installation Guide > Installing IBM Tivoli Monitoring TADDM To view data from TADDM resources in the OSLC hover-preview dialog, you must install the TADDM (Fix Pack 4). See the TADDM Information center for the version (Fix Pack 4) at: home?lang=en#!/wiki/tivoli%20documentation%20central/page/tivoli %20Documentation%20Central Search for Tivoli Application Discovery and Dependency Manager under A: Note: Deprecation for Jazz for Service Management Registry Services is due with version and thus the Open Services Lifecycle Collaboration (OSLC) Hover Preview functionality, which uses this feature, is also deprecated, when used with versions or Jazz for Service Management equal to or greater than version Overview of TBSM OSLC support Open Services for Lifecycle Collaboration (OSLC) architecture used by TBSM. Linked data integration enables BSM users, including operators, SMEs, application owners, or line of business owners to view information about their managed services, applications, or resources that helps them isolate, diagnose, and route problems. The information appears as a UI preview in a hover dialog and may include contextual information about these resources, such as configuration or health and performance details. Both IBM Tivoli Business Service Manager (TADDM) and IBM Tivoli Monitoring 6.3 can be configured as OSLC service providers. 196 IBM Tivoli Business Service Manager: Customization Guide

205 TADDM acts as a service provider, registering the resource types such as: v ComputerSystem v Database v ServiceInstance v SoftwareServer v SoftwareModule v StorageVolume Tivoli Monitoring is a provider, registering resources such as: v ComputerSystem From a data import perspective, TBSM continues to import Common Data Model (CDM) data from TADDM and from CDM books. The information registered with the JazzSM Registry is also imported into TBSM; this information is reconciled with the previously imported data. The registry information provides the seed for the retrieval of information in the hover dialog. The following diagram illustrates the hover preview architecture. In this diagram, Tivoli Monitoring continues to generate a CDM book containing managed resources that is consumed by TADDM. TBSM continues to import these resources (as Common Data Model data) from TADDM using the Discovery Library Toolkit. This function has not changed from previous releases. In the diagram, both TADDM and Tivoli Monitoring are providers that register a subset of their resources with the Registry Service. Within the TBSM Data Server a servlet has been added that queries the registry. This servlet is controlled by a thread in the Discovery Library Toolkit. The toolkit runs the servlet on a predefined interval and the servlet then queries the Jazz for Service Management Registry for changes since the previous query. Any changes that are received are passed to the toolkit via the Service Component Registry (SCR) API. This data is reconciled with data that is in the SCR, enriching the data with the linked data from the registry. On the TBSM Dashboard Server, the Hover preview is triggered when the mouse is placed over an object in the service tree that has received linked data from the Registry Services. This starts a process that first queries the registry for a list of service providers for the object. Then, the linked data for each provider is used to retrieve the data from that provider. The information received from each provider is displayed within the hover dialog. OSLC hover preview configuration 197

206 The resulting preview displays as a flyover or hover dialog with a tab to display data from each of the providers that have registered with the Jazz for Service Management for this resource (service). TADDM, and Tivoli Monitoring have up to three tabs available. TADDM registers two service providers. The change provider returns change history associated with the resource. An example of the data from the change provider is: The TADDM discovery provider returns attribute information associated with the resource. An example of the data from the discovery provider is: 198 IBM Tivoli Business Service Manager: Customization Guide

207 The Tivoli Monitoring version 6.3 health provider returns information about the health of the resource. For a Computer System this includes: v CPU utilization v memory utilization v disk utilization v installed agents An example of the Tivoli Monitoring Provider data is: OSLC hover preview configuration 199

208 Enabling / Configuring OSLC You need to configure the Jazz for Service Management Registry and define other applications as service providers in the registry. About this task For the UI Preview to have data to work with, the following external products must be configured: v v Jazz for Service Management Registry - see Required Products for the link to JazzSM OSLC Service Providers v IBM Tivoli Monitoring OSLC Service Provider - see Required Products for the link to Tivoli Monitoring v TADDM OSLC Server Provider - see Required Products for the link to TADDM Configuring TBSM for hover preview To enable hover preview, configure the Data and Dashboard servers and the Discovery Library Toolkit. About this task TBSM configuration consists of: v On the Data server enable the Discovery Library Toolkit. v On the Data server define the OSLC Registry to the TBSM Data Server v In the TBSM user interface, enable OSLC hover preview on the your service tree pages Configuring the Data Server and DL Toolkit for hover preview Describes how to configure the Data Server and the Discovery Library Toolkit for OSLC hover preview. 200 IBM Tivoli Business Service Manager: Customization Guide

209 About this task The TBSM Data Server and Discovery Library Toolkit configuration is set with the oslcconfig script. This script is in the $TBSM_HOME/XMLtoolkit/bin directory. Procedure 1. The minimum configuration sets the Jazz for Service Management Registry hostname, port, user, and password: oslcconfig -alter -h <myoslchost> -p <registry_http_port> -U tipuser -P tippassword oslcconfig.sh -alter -h <myoslchost> -p <registry_http_port> -U tipuser -P tippassword Note: In the commands that follow, the Windows format: oslcconfig is shown. For UNIX/Linux system the command is: oslcconfig.sh 2. You can also set optional parameters such as: v v v the interval that the Registry is polled (default is 120 seconds) the protocol between the Discovery Library toolkit and the Data Server servlet (http or https) the protocol between the Data Server servlet and the Registry (http or https) To see all the available options enter the command: oslcconfig -? 3. To enable the connection, run the command: oslcconfig -enable 4. To test the connection enter the command: oslcconfig -test 5. If the 'oslcconfig -test' is successful: a. Restart the TBSM Data Server so that the servlet that communicates with the Registry and has access to the updated properties. b. Restart the Discovery Library Toolkit. c. Schedule a bulk load from Tivoli Application Dependency Discovery Manager. d. Reload your Discovery Library books. Initially, the toolkit requests that the servlet run a bulk import of the Registry data. Subsequent requests are delta requests. The Discovery Library Tookit's msggtm_xt.log.0file records each of the servlet requests oslcconfig: This topic describes the options for the oslcconfig command. Purpose To configure the Data server servlet, use the Discovery Library Toolkit oslcconfig command located in the $TBSM_HOME/XMLtoolkit/bin directory. OSLC hover preview configuration 201

210 Syntax The oslcconfig command has the following syntax: oslcconfig [-alter [properties]] [-disable] [-display] [-enable [properties]] [-test] UNIX/Linux: On UNIX and Linux systems, the command is: oslcconfig.sh Parameters The oslcconfig command has the following parameters: alter Updates one or more of the OSLC configuration properties. Additional properties can be assigned to this parameter. disable Disables OSLC enrichment support. display Displays the current property values. enable Enables OSLC enrichment support. test Allows you to test the connection to the Registry Service server. Additional properties A number of additional values can be set by applying properties to the alter and enable parameters. These properties can be applied to either the alter and enable. However, you must set values for the -h, -p, -U, and -P properties, since these properties do not have default values. If you do not set these values and attempt to run the oslcconfig command with the enable parameter, the command fails. It is only necessary to set these properties once. The remaining properties have default values and are optional. -i (Optional) This Discovery Library Toolkit property sets the default interval in seconds for which the Registry Service is queried. The minimum value is 5. If you enter a value lower than 5 it is set to 5. The default value is s (Optional) This Discovery Library Toolkit property sets the protocol used to communicate with the Data server servlet. Specify true to use HTTPS. The default value is false. -h This Registry Service property sets the IP address for the Registry Service. -p This Registry Service property sets the HTTP port on which the Registry Service listens. -b (Optional) This Registry Service property sets the batch size for records retrieved from the Registry Service. The default value is 1000 and the minimum value is 100. If you enter a value lower than 100 it is set to 100. Default: r (Optional) This Registry Service property sets the protocol used to communicate with the Registry Service. Specify true to use HTTPS. The default value is false. 202 IBM Tivoli Business Service Manager: Customization Guide

211 -U This Registry Service property sets the username used to connect to the Registry Service. -P This Registry Service property sets the password used to connect to the Registry Service. If you enter a username but do not provide a password, you are prompted for a password. Example This example represents the minimum configuration. The JazzSM Registry hostname, port, user, and password are set: oslcconfig -alter -h myoslchost -p U tipuser -P tippassword Configuring TBSM user interface for hover preview You need to enable hover preview in the Service Tree portlet preferences. About this task The Hover Preview option is disabled by default in a service tree portlet. In the service tree where you want to enable hover preview: Procedure 1. Click Edit Options in the Service Tree portlet. 2. Select Personalize or Edit Shared Settings. Personalize sets the defaults for your user ID, and Edit Shared Settings sets the defaults for all users. Edit shared settings is only available to user with administrator roles. The service tree preferences window opens. The General tab shows by default. 3. Click the View tab. 4. From the Tree Template drop-down list, Select the tree template where you want to enable hover preview. 5. Select the Enable Hover Preview option to activate hover preview for services configured for this feature. 6. Click OK. Configuring Service Navigation trees for hover preview How to enable hover preview in the Services and Service Component Repository trees in the Service Navigation portlet. About this task The Hover Preview option is disabled by default in the Services and Service Component Repository trees in the Service Navigation portlet. To enable hover preview for the Services and Service Component Repository trees, you need to edit the RAD_sla.props file. Procedure 1. On the Dashboard server host change to the directory: $TBSM_HOME/../tipv2/ profiles/tipprofile/installedapps/tipcell/isc.ear/sla.war/etc 2. Open the RAD_sla.props file in a text editor. 3. Set the impact.sla.enablehoverpreview property to true as shown in this example: OSLC hover preview configuration 203

212 impact.sla.enablehoverpreview=true 4. Save and close the file. 5. Restart the Dashboard server. Running OSLC servlet updates with a command The Discovery Library toolkit updates the Data Server servlet on a predetermined interval, but you a can also run a bulk or delta import with a command. After the first import of Jazz for Service Management Registry data, subsequent requests are delta imports, retrieving only information for objects that have changed since the last import. This command only updates the OSLC data, not the full Discovery Library Toolkit updates, such as a bulk update from TADDM. About this task Use the utils script in the $TBSM_HOME/XMLtoolkit/bin directory to run the imports. The specified utils script will be run immediately, independent of the normal polling interval. Procedure 1. Run a bulk import with the command: utils.sh -U tbsmdbid -P tbsmdbpw -e runoslcbulk.xml utils.bat -U tbsmdbid -P tbsmdbpw -e runoslcbulk.xml 2. Run a delta import with the command: utils.sh -U tbsmdbid -P tbsmdbpw -e runoslcdelta.xml utils.bat -U tbsmdbid -P tbsmdbpw -e runoslcdelta.xml 204 IBM Tivoli Business Service Manager: Customization Guide

213 Reformatting displayed numerical values Reformat function There are times when the default display of numerical values in a view definition prototype is awkward. For instance, customer KPI values are always internally stored as a double value even when they logically represent an integer value. The default display for these values includes a decimal point and tenths. At other times, you may want to have larger numbers formatted for easier readability. This topic describes the reformat cascading style sheet (CSS) function. Purpose The reformat CSS function changes the number format in a visual prototype. Syntax This function has the reformat(value[,format pattern]); Parameters value This value is required and refers to a previously formatted data model value. format pattern Optional format pattern. When this parameter is omitted, a built-in default is automatically used. The default value formats the number as an integer with grouping separators. The capabilities of the Java DecimalFormat class are used to perform the actual formatting. So the format pattern follows its conventions. The most common pattern symbols are described in this table. Table 59. Format pattern symbols Symbol Description 0 Unconditionally display a digit. # Conditionally display a digit; insignificant zero automatically suppressed.. Placeholder for locale-specific decimal separator., Placeholder for locale-specific grouping separator. For more information, see: Customizing Formats. Note: CSS parsing limitations require that every grouping separator in the format pattern, that is to say each comma, must be escaped with a backslash. Failure to do so results in either CSS parsing errors or too many arguments being passed to the reformat implementation These errors are visible in the Java console. Copyright IBM Corp. 2008,

214 The browser language preference is used to ensure that proper local formatting conventions are used for the decimal and grouping separators. Format pattern examples These samples show the reformat function with and without the optional format reformat(@value2,#\,##0.0##); This table shows how the default and some format patterns change how a number displays. Table 60. Format pattern examples Number Default #,##0 ##0 #,##0.00;(#,##0.00) (100.00) ,284 1, , , , , ,000, ,000, ,999, Reformat function example The formatted results were generated while running in the en_us locale. The separator values used vary depending on the runtime locale. This topic describes a simple implementation of the reformat function. Since the TBSM data model provides several integer values that can be used immediately after installation, this sample makes the two element prototype display them with 3 places of precision. This sample is for demonstration purposes only. Editing the CSS file Edit the server-side nodes_links_overrides.css file in the %TBSM_DASHBOARD_SERVER_HOME%\av\css\customer to enable this change. Tip: Ensure that you make a backup of this files before editing it. 1. Open the CSS file in a text editor. 2. Find the node[visualrepresentation="twoelementprototype"] selector. 3. Replace SDM { } with node[visualrepresentation="twoelementprototype"] { value2 reformat(@value2,#\,##0.000); } v v construct indicates that the value is to be processed as an expression. In this case, the reformat function is used to pass the current value2 data model field value. 206 IBM Tivoli Business Service Manager: Customization Guide

215 4. Save the file. 5. From a browser, open a view. 6. Create a custom canvas with a two element prototype. Ensure that you set the second value to an integer value. 7. Save the custom canvas and the node now has a decimal point in the number for value 2. Note: You might need to log off, refresh the browser, and log in to see the changes. Prototype selectors This list shows the names for the visual prototypes in the nodes_links_overrides.css file. Service Instance node[visualrepresentation="radprototype" 1 Element node[visualrepresentation="oneelementprototype"] { 2 Element node[visualrepresentation="twoelementprototype" 3 Element node[visualrepresentation="threeelementprototype" 4 Element node[visualrepresentation="fourelementprototype" 5 Element node[visualrepresentation="fiveoelementprototype" 6 Element node[visualrepresentation="sixelementprototype" Reformatting displayed numerical values 207

216 208 IBM Tivoli Business Service Manager: Customization Guide

217 Custom view definitions These topics describe how you can customize a view definition. You can customize the grid and concentric view definitions by modifying xml files for these view types. There are layout modes the let you make better use for the available screen space for these view definitions. These files are located in this directory: $TBSM_HOME/av/xmlconfig Each view definition has its own xml file. For example, the Concentric view is configured with the file: ViewDefinition_Concentric.xml View definition graph layout modes This topic describes graph layout modes for the Grid and Concentric views. Layout modes for Grid layout These layout parameters let you control how the Grid view displays. You set: TILE_TO_GRID_FIXED_WIDTH The nodes are placed in the cells of a grid (matrix) that has a fixed maximum number of columns. TILE_TO_GRID_FIXED_HEIGHT The nodes are placed in the cells of a grid (matrix) that has a fixed maximum number of rows. TILE_TO_ROWS The nodes are placed in rows. TILE_TO_COLUMNS The nodes are placed in columns. In this example, the layoutmode is set to TILE_TO_ROWS. <canvasconfig> <canvastemplate name = "Grid" populator = "ParentChildRelationship" basecss = "rad.css" backgroundcolor = "#DDDDDD" graphlayout = "Grid" layoutmode = "TILE_TO_ROWS" swimlanefield = "PrimaryTagName" useswimlanes = "false" linkvisibility = "false" seedvisibility = "false"> Layout modes for Concentric layout The layoutmode parameters let you control how the Concentric view displays. You can also set an aspect ratio for some of these layout options. FREE All links flow roughly in the flow direction. Nodes of different tree branches (that is, nodes with a different parent node) are not justified to each other. Copyright IBM Corp. 2008,

218 LEVEL All links flow roughly in the flow direction. Nodes are organized in levels TIP_OVER aspectratio Like the mode FREE. However, in mode TIP_OVER, the algorithm tries to optimize the layout to automatically fit best to the specified aspect ratio. Using a fast heuristic, it chooses the local alignment TIP_OVER for some nodes but keeps the alignment of all other nodes as specified. The heuristic is a fast compromise between the modes TIP_LEAVES_OVER, TIP_ROOTS_OVER, and TIP_ROOTS_AND_LEAVES_OVER. TIP_LEAVES_OVER aspectratio Like the mode TIP_OVER. The algorithm tries to optimize the layout to automatically fit best to the specified aspect ratio. This slow heuristic tries to tip over beginning with the leaves and then chooses the best layout. It checks the alignment mode TIP_OVER, but not TIP_OVER_BOTH_SIDES. It keeps the alignment of all nodes close to the root as specified. TIP_ROOTS_OVER aspectratio Like the mode TIP_OVER. The algorithm tries to optimize the layout to automatically fit best to the specified aspect ratio. This slow heuristic tries to tip over beginning with the roots and then chooses the best layout. It checks the alignment mode TIP_OVER, but not TIP_OVER_BOTH_SIDES. It keeps the alignment of all nodes close to the leaves as specified. TIP_ROOTS_AND_LEAVES_OVER aspectratio like the mode TIP_OVER. The algorithm tries to optimize the layout to automatically fit best to the specified aspect ratio. This slow heuristic tries to tip over beginning with the roots and with the leaves, and then chooses the best layout. It checks the alignment mode TIP_OVER, but not TIP_OVER_BOTH_SIDES. It keeps the alignment of all nodes in the middle between roots and leaves as specified. RADIAL aspectratio The root node is in the center, the links flow radially away from the center, and the nodes are placed in circular layers around the root node according to the level alignment. ALTERNATING_RADIAL aspectratio This is the same as mode RADIAL, with the exception that children of the same node are placed alternating in different circular layers when this results in a smaller radius and better usage of the space aspectratio: You can use Aspect ratio in the TIP_*, RADIAL, and ALTERNATING_RADIAL layout modes for the concentric layout. You can set this value from 0.1 to 10.0 Table 61. aspectratio values aspectratio value Default: 1.0 circle Description Place circle of nodes in a square layout. 210 IBM Tivoli Business Service Manager: Customization Guide

219 Table 61. aspectratio values (continued) aspectratio value Description 0.0 Calculated to ensure best match to the runtime visual space. Note: IBM recommends using this value for most cases. < 1.0 The greater the valuer, the taller the ellipse > 1.0 The smaller the value, the wider the ellipse Modifying a view definition In this example, ALTERNATING_RADIAL layoutmode is configured with a wider ellipse. <canvastemplate name = "Concentric" populator = "ParentChildRelationship" basecss = "rad.css" backgroundcolor = "#CCCCCC" graphlayout = "Concentric" layoutmode = "ALTERNATING_RADIAL" aspectratio = "0.8" linkvisibility = "true" seedvisibility = "true"> This topic describes how to modify a view definition XML file. Before you begin You need to make a backup copy of the XML files before you make you modifications. Note: Do not name the copy using the ViewDefinition_*.xml convention. TBSM loads all files in this directory named with this convention are loaded and it can cause unexpected results. For example, do not name your backup file: ViewDefinition_Concentric-original.xml About this task To modify a view definition: Procedure 1. To copy the view definition XML file for the custom view definition that you want to edit, from the TBSM database to your temporary file directory, at a command prompt type: %TBSM_TOOLKIT_BASE%\bin\getArtifact.bat -name ViewDefinition_<ViewDefName>.xml -category viewdefinition -directory <temp> $TBSM_TOOLKIT_BASE/bin/getArtifact.sh -name ViewDefinition_<ViewDefName>.xml -category viewdefinition -directory <temp> where <ViewDefName> is the view definition that you want to edit and <temp> is the location on your system that you use as a temporary file system directory. Custom view definitions 211

220 2. In a text editor, open the ViewDefinition_<ViewDefName>.xml file, make the necessary layout changes, and save the file. 3. To copy the updated view definition XML file into the TBSM database, at a command prompt type: %TBSM_HOME%\XMLtoolkit\bin\putArtifact.bat -name <temp>/viewdefinition_ <ViewDefName>.xml -category viewdefinition $TBSM_HOME/XMLtoolkit/bin/putArtifact.sh -name <temp>/viewdefinition_ <ViewDefName>.xml -category viewdefinition 4. To reinitialize the view definitions on the Dashboard server, at a command prompt type: cd %TBSM_HOME%\bin rad_reinitcanvas.bat cd $TBSM_HOME/bin rad_reinitcanvas Note: It might be necessary for you to log out and log in to TBSM, if the previous configuration was cached. 5. To test the changes: a. If you are currently logged in to TBSM, log out. b. Log in to TBSM. c. Select a service instance to display a view. d. If necessary, select the view definition from the drop-down list in the toolbar. e. Verify that the layout appearance. Example In this example, the ViewDefinition_Concentric.xml file is changed to make better use of all available screen space in the Concentric view. The default Concentric view shows the service in a circle and is configured as shown here. <canvastemplate name = "Concentric" populator = "ParentChildRelationship" basecss = "rad.css" backgroundcolor = "#CCCCCC" graphlayout = "Concentric" linkvisibility = "true" seedvisibility = "true"> To use configure the view to expand the view in to the available space, add the ALTERNATING_RADIAL layoutmode and set the aspectratio to 0 as shown in this example. <canvastemplate name = "Concentric" populator = "ParentChildRelationship" basecss = "rad.css" backgroundcolor = "#CCCCCC" 212 IBM Tivoli Business Service Manager: Customization Guide

221 graphlayout = "Concentric" layoutmode = "ALTERNATING_RADIAL" aspectratio = "0" linkvisibility = "true" seedvisibility = "true"> Custom view definitions 213

222 214 IBM Tivoli Business Service Manager: Customization Guide

223 Energy Dashboard customization Energy Dashboard overview This section describes the Energy Dashboard that displays IBM Tivoli Monitoring for Energy Management data. This section describes the Energy Dashboard purpose and features. The Energy Dashboard is a versatile, role-based information dashboard that can collect metrics from IT, facilities and physical assets and enables you to visualize and communicate both the environmental and economic impact of energy usage across your infrastructure. Using views from TBSM and drawing on information collected by IBM Tivoli Monitoring for Energy Management, and other potential sources, the Energy Dashboard enables you to consolidate the information you collect and present it in a highly consumable and insightful format. It can help address key questions such as: v How much energy am I using? v What services are costing the most in energy consumption? v Can I alter settings and still meet my service level agreements? v Since we made changes, how much are we saving on energy bills? Dashboard features The Energy Dashboard helps optimize energy resources for efficient data center operation by letting you examine power and thermal metrics for your data center and its resources, such as servers, cooling equipment, and other devices and facilities. From the Energy Dashboard, you can do the following: v View charts that visualize aggregated power and thermal metrics for your data center v From the charts, launch to reports that support the data center metrics on the dashboard v View the health of individual resources based on simple color-coded indicators (red, yellow, green) v View power and thermal metrics for individual resources v View related events for individual resources v From individual resources, launch to additional managed resource information. In addition, the energy resources might be incorporated into user-defined service models in order to tie business services to infrastructure energy metrics. The Energy Dashboard shown in this figure serves as a best-practice implementation that you can customize to fit your specific needs. This dashboard provides a data center operations view with data center and resource-specific energy metrics displayed in charts and a Service Tree. These metrics are provided for devices monitored by the following IBM Tivoli Monitoring for Energy Management monitoring agents: v Active Energy Manager Agent (AEM) Copyright IBM Corp. 2008,

224 v APC InfraStruXure Agent (APC) v Eaton Power Xpert Agent (Eaton) v Johnson Controls Metasys Agent (JCI) The Energy Dashboard also includes a Service Details view that includes events associated with the energy resources. Figure 13. Energy Dashboard example Energy Dashboard portlet details These topics describe the Energy Dashboard portlets. The Energy Dashboard shown in Figure 1 consists of five portlets that display power and thermal metrics for your data center through charts provided by the Reporting and Optimization feature of IBM Tivoli Monitoring for Energy Management, and the health of individual Energy Management devices through service-related portlets provided by TBSM. While the portlet content selected for the Energy Dashboard is intended to offer operational insight into energy usage and events across data center facilities and physical assets, many options exist for creating an Energy Dashboard that can meet your needs. Portlets containing reporting and optimization charts The Data Center Optimization for Energy Management provides a set of charts that visualize power usage and thermal metrics for your data center. The following charts have been selected for the Energy Dashboard. For more information about the following charts and other available predefined charts, see the Monitoring for Energy Management Data Center Optimization for Energy Management User's Guide Data Center infrastructure Efficiency (DCiE) This line chart plots over time the historical percentage index for the Data Center infrastructure Efficiency (DCiE). The purpose of this chart is to visualize the DCiE index that represents the total power consumed by the 216 IBM Tivoli Business Service Manager: Customization Guide