Impact 40 SG

Netcool/Impact
Version 4.0
IBM
Solutions Guide
frontmatter.fm November 30, 2006
Note Before using this information and the product it supports, read the information in Appendix B. "Notices" on page 227.
First Edition (December 1, 2006) This edition applies to version 4.0 of Netcool/Impact and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation, 2006. All rights reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
About this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xii Typographical notation . . . . . . . . . . . . . . . . . . . . .xii Note, Tip, and Warning information . . . . . . xiii Syntax and Sample subheadings. . . . . . . . . . xiv Associated publications . . . . . . . . . . . . . . . . . . . . xiv Netcool/Impact Administration Guide . . . . .xv Netcool/Impact User Interface Guide . . . . . .xv Netcool/Impact Policy Reference Guide . . . .xv Netcool/Impact DSA Reference Guide . . . . .xv Netcool/Impact Online Help. . . . . . . . . . . . . .xv Netcool/Impact Release Notes . . . . . . . . . . . .xv Operating system considerations . . . . . . . . . . . . .xv How to send your comments . . . . . . . . . . . . . . . xvi Data Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Solution Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Event Enrichment . . . . . . . . . . . . . . . . . . . . . . . 13 X Events in Y Time . . . . . . . . . . . . . . . . . . . . . . 13 Event Notification . . . . . . . . . . . . . . . . . . . . . . . 14 Event Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Setting Up a Solution . . . . . . . . . . . . . . . . . . . . . . . 14 Creating a Data Model . . . . . . . . . . . . . . . . . . . 15 Setting Up Services . . . . . . . . . . . . . . . . . . . . . . 15 Creating Policies . . . . . . . . . . . . . . . . . . . . . . . . 15 Running a Solution . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 3. Data Models . . . . . . . . . . . . . 17

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 How Do I Use This Part of the Guide? . . . . . . . . 18 About Data Models. . . . . . . . . . . . . . . . . . . . . . . . . 18 What Is a Data Model? . . . . . . . . . . . . . . . . . . . 18 What Are the Data Model Components? . . . . 18 How Do I Use a Data Model? . . . . . . . . . . . . . 19 How Do I Set Up a Data Model? . . . . . . . . . . .19 How Do I Manage a Data Model with Netcool/Impact? . . . . . . . . . . . . . . . . . . . . . . . . 19 Data Model Components. . . . . . . . . . . . . . . . . . . . 19 Data Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Data Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20 Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Data Model Architecture . . . . . . . . . . . . . . . . . . . . 21 Data Model Examples . . . . . . . . . . . . . . . . . . . . . . 22 Enterprise Service Model . . . . . . . . . . . . . . . . . 22 Web Services Hosting Model. . . . . . . . . . . . . . 23 Setting Up a Data Model . . . . . . . . . . . . . . . . . . . . 25
iii
Chapter 1. Getting Started . . . . . . . . . . . . 1

What Is Netcool/Impact? . . . . . . . . . . . . . . . . . . . . 1 The Netcool/Impact Software System . . . . . . . 1 Netcool/Impact As a Development Tool. . . . . 2 Netcool/Impact As an Automation Engine . . 3 What Do I Do With Netcool/Impact? . . . . . . . . . . 3 Core Netcool/Impact Features . . . . . . . . . . . . . 3 Typical Netcool/Impact Implementations . . . 7 Netcool/Impact and Workflow Analysis . . . . 9
Chapter 2. Netcool/Impact Solutions . . 11

About Netcool/Impact Solutions . . . . . . . . . . . . . 11 What Are Solutions? . . . . . . . . . . . . . . . . . . . . . 11 What Are the Solution Components? . . . . . . . 11 What Are the Solution Types? . . . . . . . . . . . . . 11 How Do I Set Up a Solution? . . . . . . . . . . . . . . 11 Solution Components. . . . . . . . . . . . . . . . . . . . . . . 12
Creating Data Sources . . . . . . . . . . . . . . . . . . . 25 Creating Data Types. . . . . . . . . . . . . . . . . . . . . 25 Creating Data Items . . . . . . . . . . . . . . . . . . . . . 26 Creating Links . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Creating Event Sources . . . . . . . . . . . . . . . . . . 26
Display Name . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Data Type Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Setting Up Data Types. . . . . . . . . . . . . . . . . . . . . . 38 Getting the Name of the Structural Element 38 Creating an Internal Data Type . . . . . . . . . . . 39 Creating an SQL Database Data Type . . . . . . 41 Creating an LDAP Data Type . . . . . . . . . . . . . 46 Creating a Mediator Data Type . . . . . . . . . . . 48 Data Type Caching. . . . . . . . . . . . . . . . . . . . . . . . . 48 Data Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Query Caching . . . . . . . . . . . . . . . . . . . . . . . . . 50 Count Caching. . . . . . . . . . . . . . . . . . . . . . . . . . 51
Chapter 4. Working with Data Sources 27

About Data Sources . . . . . . . . . . . . . . . . . . . . . . . . 27 What Is a Data Source? . . . . . . . . . . . . . . . . . . 27 What Are the Data Source Categories . . . . . . 27 How Do Data Sources Work? . . . . . . . . . . . . . 28 What Do I Do With Data Sources? . . . . . . . . . 28 How Do I Set Up Data Sources? . . . . . . . . . . . 28 Data Source Categories . . . . . . . . . . . . . . . . . . . . . 28 SQL Database Data Sources . . . . . . . . . . . . . . 28 LDAP Data Sources . . . . . . . . . . . . . . . . . . . . . 28 Mediator Data Sources. . . . . . . . . . . . . . . . . . . 28 Internal Data Repository . . . . . . . . . . . . . . . . . 29 Data Source Architecture . . . . . . . . . . . . . . . . . . . 29 Setting Up Data Sources . . . . . . . . . . . . . . . . . . . . 30 Getting the Connection Information . . . . . . . 30 Creating the Data Source . . . . . . . . . . . . . . . . . 30
Chapter 6. Working with Links. . . . . . 53

About Links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 What Are Links? . . . . . . . . . . . . . . . . . . . . . . . . 53 What Are the Links Categories? . . . . . . . . . . . 53 What Do I Do with Links? . . . . . . . . . . . . . . . . 54 How Do I Set Up Links? . . . . . . . . . . . . . . . . . 54 Link Categories. . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Static Links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54 Dynamic Links . . . . . . . . . . . . . . . . . . . . . . . . . 54 Setting Up Links . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Setting Up Static Links . . . . . . . . . . . . . . . . . . . 56 Setting Up Dynamic Links. . . . . . . . . . . . . . . . 57
Chapter 5. Working with Data Types . . 33

About Data Types . . . . . . . . . . . . . . . . . . . . . . . . . 33 What Are Data Types? . . . . . . . . . . . . . . . . . . . 33 What Are the Data Type Categories?. . . . . . . 34 How Do Data Types Work? . . . . . . . . . . . . . . 34 How Do I Use Data Types . . . . . . . . . . . . . . . . 34 How Do I Set Up Data Types? . . . . . . . . . . . . 34 Data Type Categories . . . . . . . . . . . . . . . . . . . . . . 34 SQL Database Data Types . . . . . . . . . . . . . . . . 34 LDAP Data Types . . . . . . . . . . . . . . . . . . . . . . . 35 Mediator Data Types . . . . . . . . . . . . . . . . . . . . 35 Internal Data Types . . . . . . . . . . . . . . . . . . . . . 35 Data Type Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . 36 ID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Actual Name . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Chapter 7. Working with Event Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

About Event Sources . . . . . . . . . . . . . . . . . . . . . . . 63 What Are Events? . . . . . . . . . . . . . . . . . . . . . . . 63 What Are Event Sources? . . . . . . . . . . . . . . . . 63 What are the Event Source Types? . . . . . . . . . 64 How Do I Use Event Sources? . . . . . . . . . . . . 64 How Do I Set Up Event Sources? . . . . . . . . . 64 How Do I Manage Event Sources? . . . . . . . . . 64 Event Source Types . . . . . . . . . . . . . . . . . . . . . . . . 64 ObjectServer Event Sources. . . . . . . . . . . . . . . 64 Non-ObjectServer Event Sources . . . . . . . . . . 65
iv
Impact Version 4.0 Solutions Guide
Event Source Architecture . . . . . . . . . . . . . . . . . . . 66 Setting Up Event Sources. . . . . . . . . . . . . . . . . . . . 66 Setting Up ObjectServer Event Sources . . . . . 67 Setting Up Non-ObjectServer Event Sources 69
Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Event Polling . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Event Querying . . . . . . . . . . . . . . . . . . . . . . . . .80 Delete Notification. . . . . . . . . . . . . . . . . . . . . . . 80 Event Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Event Reader Configuration . . . . . . . . . . . . . . . . . 81 Event Reader Name. . . . . . . . . . . . . . . . . . . . . . 81 ObjectServer Event Source . . . . . . . . . . . . . . . . 81 Polling Interval. . . . . . . . . . . . . . . . . . . . . . . . . . 81 Event Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Event Mapping. . . . . . . . . . . . . . . . . . . . . . . . . . 82 Event Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Setting Up Event Readers . . . . . . . . . . . . . . . . . . . 83
Chapter 8. Services . . . . . . . . . . . . . . . . . . 71
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 How Do I Use This Part of the Guide? . . . . . . . . 71 About Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 What Are Services? . . . . . . . . . . . . . . . . . . . . . . 72 What Are the Service Types? . . . . . . . . . . . . . . 72 What Do I Do with Services? . . . . . . . . . . . . . . 73 How Do I Set Up Services?. . . . . . . . . . . . . . . . 73 Service Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Event Readers. . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Event Listeners. . . . . . . . . . . . . . . . . . . . . . . . . . 74 E-Mail Sender. . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Policy Activators . . . . . . . . . . . . . . . . . . . . . . . . 74 Hibernating Policy Activator. . . . . . . . . . . . . . 74 Event Processor . . . . . . . . . . . . . . . . . . . . . . . . . 74 Policy Logger . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Command Line Manager Service . . . . . . . . . . 74 CORBA Name Service . . . . . . . . . . . . . . . . . . . 75 Setting Up Services . . . . . . . . . . . . . . . . . . . . . . . . . 75 Configuring Pre-Defined Services . . . . . . . . . 75 Creating and Configuring User-Defined Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Chapter 10. Working with Event Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

About Event Listeners . . . . . . . . . . . . . . . . . . . . . . 89 What Are Event Listeners?. . . . . . . . . . . . . . . . 89 How Do Event Listeners Work? . . . . . . . . . . . 89 How Do I Use Event Listeners?. . . . . . . . . . . . 90 How Do I Set Up Event Listeners? . . . . . . . . . 90 How Do I Manage Event Listeners? . . . . . . . . 90 How Event Listeners Work . . . . . . . . . . . . . . . . . . 90 Event Listening . . . . . . . . . . . . . . . . . . . . . . . . .90 Event Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Event Listener Configuration . . . . . . . . . . . . . . . . 91 Event Listener Name. . . . . . . . . . . . . . . . . . . . . 91 Listener Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Event Listener Policy. . . . . . . . . . . . . . . . . . . . . 91 CORBA Name Service Hostname . . . . . . . . . . 91 CORBA Name Service Port . . . . . . . . . . . . . . .91 CORBA Name Service Context . . . . . . . . . . . . 92 CORBA Name Service ObjectName . . . . . . . . 92 Direct Mode Class Name . . . . . . . . . . . . . . . . . 92 Direct Mode Source Name . . . . . . . . . . . . . . . . 92 Setting Up Event Listeners . . . . . . . . . . . . . . . . . . 93
Chapter 9. Working with Event Readers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

About Event Readers . . . . . . . . . . . . . . . . . . . . . . . 77 What Are Event Readers?. . . . . . . . . . . . . . . . . 77 What Are ObjectServer Events? . . . . . . . . . . . 77 How Do Event Readers Work? . . . . . . . . . . . . 78 How Do I Use Event Readers?. . . . . . . . . . . . . 78 How Do I Set Up Event Readers? . . . . . . . . . . 78 How Do I Manage Event Readers? . . . . . . . . . 78 How Do I Monitor Event Readers?. . . . . . . . . 78 Event Reader Architecture . . . . . . . . . . . . . . . . . . 79 How Event Readers Work . . . . . . . . . . . . . . . . . . . 79
Chapter 11. Working with the Database Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

About the Database Listener . . . . . . . . . . . . . . . . . 95
What Is the Database Listener?. . . . . . . . . . . . 95 What Is the Database Client? . . . . . . . . . . . . . 96 What Are Database Events? . . . . . . . . . . . . . . 96 How Do I Set Up the Database Server? . . . . . 96 How Do I Set Up the Database Listener? . . . 96 How Do I Write Database Listener Policies? 96 Setting Up the Database Server . . . . . . . . . . . . . . 96 Copying the Client Tar File to the Oracle System 97 Editing the Nameserver Properties File . . . . 97 Editing the Listener Properties File . . . . . . . . 98 Installing the Client Files Into Oracle . . . . . . 99 Granting Database Permissions . . . . . . . . . . 100 Setting Up the Database Listener. . . . . . . . . . . . 100 Sending Database Events . . . . . . . . . . . . . . . . . . 101 Creating the Call Spec . . . . . . . . . . . . . . . . . . 101 Creating Triggers . . . . . . . . . . . . . . . . . . . . . . 102 DDL Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 System Events . . . . . . . . . . . . . . . . . . . . . . . . . 106 User Events . . . . . . . . . . . . . . . . . . . . . . . . . . . 107 Writing Database Event Policies . . . . . . . . . . . . 108 Handling Incoming Database Events . . . . . 108 Returning Events to the Database . . . . . . . . 109 Example Triggers . . . . . . . . . . . . . . . . . . . . . . . . . 111 Insert Event . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 Update Event. . . . . . . . . . . . . . . . . . . . . . . . . . 112 Delete Event. . . . . . . . . . . . . . . . . . . . . . . . . . . 113 Before Create Event . . . . . . . . . . . . . . . . . . . . 114 After Create Event . . . . . . . . . . . . . . . . . . . . . 115 Before Alter Event. . . . . . . . . . . . . . . . . . . . . . 115 After Alter Event. . . . . . . . . . . . . . . . . . . . . . . 116 Before Drop Event . . . . . . . . . . . . . . . . . . . . . 116 After Drop Event. . . . . . . . . . . . . . . . . . . . . . . 117 Server Startup Event. . . . . . . . . . . . . . . . . . . . 117 Server Shutdown Event . . . . . . . . . . . . . . . . . 118 Server Error Event . . . . . . . . . . . . . . . . . . . . . 118 Logon Event. . . . . . . . . . . . . . . . . . . . . . . . . . . 119 Logoff Event . . . . . . . . . . . . . . . . . . . . . . . . . . 119
About Policy Activators . . . . . . . . . . . . . . . . . . . 121 What Are Policy Activators? . . . . . . . . . . . . . 121 How Do Policy Activators Work? . . . . . . . . 121 How Do I Use Policy Activators? . . . . . . . . . 121 How Do I Set Up Policy Activators? . . . . . . 121 How Do I Manage Policy Activators? . . . . . 122 Policy Activator Configuration . . . . . . . . . . . . . 122 Policy Activator Name . . . . . . . . . . . . . . . . . . 122 Activation Interval . . . . . . . . . . . . . . . . . . . . . 122 Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 Startup and Logging Options . . . . . . . . . . . . 122 Setting Up Policy Activators. . . . . . . . . . . . . . . . 123
Chapter 13. Working with Other Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Policy Logger . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 Policy Logger Configuration. . . . . . . . . . . . . 125 Setting Up the Policy Logger . . . . . . . . . . . . 127 Hibernating Policy Activator . . . . . . . . . . . . . . . 127 Hibernating Policy Activator Configuration128 Setting Up the Hibernating Policy Activator128 Command Execution Manager . . . . . . . . . . . . . 129 Command Execution Manager Configuration Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 Setting Up the Command Execution Manager. 129 Command Line Manager . . . . . . . . . . . . . . . . . . 130 Command Line Manager Configuration. . . 130 Setting Up the Command Line Manager . . 130 CORBA Name Service . . . . . . . . . . . . . . . . . . . . . 131 CORBA Name Service Configuration . . . . . 131 Setting Up the CORBA Name Service . . . . . 131
Chapter 14. Policy Fundamentals 133

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 How Do I Use This Part of the Guide? . . . . . . . 134 About Netcool/Impact Policies . . . . . . . . . . . . . 134 What Is a Policy? . . . . . . . . . . . . . . . . . . . . . . . 134 What Is the Policy Language? . . . . . . . . . . . . 135 What Can I Do with the Policy Language? . 135
Chapter 12. Working with Policy Activators . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

vi Impact Version 4.0 Solutions Guide
Before You Begin. . . . . . . . . . . . . . . . . . . . . . . . . . 135 Policy Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Policy Context . . . . . . . . . . . . . . . . . . . . . . . . . 136 Policy Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Printing to the Policy Log. . . . . . . . . . . . . . . . 137 User-Defined Variables. . . . . . . . . . . . . . . . . . 138 Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Contexts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 If Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 While Statements . . . . . . . . . . . . . . . . . . . . . . . 141 Action Functions . . . . . . . . . . . . . . . . . . . . . . . 143 Parser Functions . . . . . . . . . . . . . . . . . . . . . . . 144 User-Defined Functions . . . . . . . . . . . . . . . . . 144
Populating the Event Fields . . . . . . . . . . . . . .152 Adding a Journal Entry. . . . . . . . . . . . . . . . . .152 Sending the Event to the Event Source. . . . .152 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153 Deleting Events . . . . . . . . . . . . . . . . . . . . . . . . . . .153 Setting the DeleteEvent Variable. . . . . . . . . .153 Sending the Event to the Event Source. . . . .153 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Chapter 16. Handling Data. . . . . . . . . 155

About Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155 What Kind of Data Can I Handle in a Policy?. . 155 What Can I Do With Data in a Policy? . . . . .155 About Data Items . . . . . . . . . . . . . . . . . . . . . . . . .156 What Are Data Items?. . . . . . . . . . . . . . . . . . .156 What Are Field Variables? . . . . . . . . . . . . . . .156 What Are the DataItems and DataItems Variables? . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156 Retrieving Data By Filter . . . . . . . . . . . . . . . . . . .156 What Does It Mean to Retrieve Data By Filter? 157 What Is a Filter? . . . . . . . . . . . . . . . . . . . . . . . .157 How Do I Retrieve Data By Filter? . . . . . . . .159 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159 Retrieving Data By Key . . . . . . . . . . . . . . . . . . . .162 What Does It Mean to Retrieve Data By Key?. . 162 What Is a Key? . . . . . . . . . . . . . . . . . . . . . . . . .162 What Is a Key Expression? . . . . . . . . . . . . . . .162 How Do I Retrieve Data By Key? . . . . . . . . .163 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163 Retrieving Data By Link. . . . . . . . . . . . . . . . . . . .164 What Does It Mean to Retrieve Data By Link? . 164 What Is a Link? . . . . . . . . . . . . . . . . . . . . . . . .165 How Do I Retrieve Data By Link?. . . . . . . . .165 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165 Adding Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . .167 Creating a New Context . . . . . . . . . . . . . . . . .167 Populating Context Member Variables . . . .167
vii
Chapter 15. Handling Events . . . . . . 147

About Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 What are Events? . . . . . . . . . . . . . . . . . . . . . . . 147 What are Event Sources? . . . . . . . . . . . . . . . . 148 How Does Netcool/Impact Obtain Events? 148 How Does Netcool/Impact Handle Events?148 What Can I Do with Events in a Policy? . . . 148 About Event Containers. . . . . . . . . . . . . . . . . . . . 148 What Is an Event Container? . . . . . . . . . . . . . 149 What Is the EventContainer Variable? . . . . . 149 What Are Event Field Variables? . . . . . . . . . 149 What Are Event State Variables?. . . . . . . . . . 149 What Are User-Defined Event Container Variables? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 Accessing Event Fields. . . . . . . . . . . . . . . . . . . . . 149 Using the Dot Notation. . . . . . . . . . . . . . . . . . 149 Using the @ Notation . . . . . . . . . . . . . . . . . . . 150 Updating Event Fields . . . . . . . . . . . . . . . . . . . . . 150 Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 Adding Journal Entries to Events. . . . . . . . . . . . 151 Assigning the JournalEntry Variable . . . . . . 151 Sending the Event to the Event Source . . . . 151 Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 Sending New Events . . . . . . . . . . . . . . . . . . . . . . 152 Creating a New Event Container . . . . . . . . . 152
Adding the Data Item. . . . . . . . . . . . . . . . . . . 167 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Updating Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 Updating Single Data Items . . . . . . . . . . . . . 168 Updating Multiple Data Items . . . . . . . . . . . 169 Deleting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 Deleting Single Data Items . . . . . . . . . . . . . . 170 Deleting Multiple Data Items . . . . . . . . . . . . 171 Calling Database Functions . . . . . . . . . . . . . . . . 173 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
What Is Netcool/Impact IM? . . . . . . . . . . . . 183 What Are the Netcool/Impact IM Components? 184 How Does Netcool/Impact IM Work? . . . . 184 How Do I Set Up Netcool/Impact IM? . . . . 184 Writing Instant Messaging Policies . . . . . . . . . . 184 Handling Incoming Messages. . . . . . . . . . . . 185 Sending Messages . . . . . . . . . . . . . . . . . . . . . . 185 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Chapter 17. Handling Hibernations 175

About Hibernations . . . . . . . . . . . . . . . . . . . . . . . 175 What Are Hibernations? . . . . . . . . . . . . . . . . 175 What Is the Hibernation Data Type? . . . . . . 175 What Are Action Keys? . . . . . . . . . . . . . . . . . 176 What Is the Hibernation Timeout Value? . . 176 What Can I Use Hibernations For? . . . . . . . 176 What Can I Do with Hibernations in a Policy? 176 Hibernating a Policy . . . . . . . . . . . . . . . . . . . . . . 176 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 Retrieving Hibernations . . . . . . . . . . . . . . . . . . . 177 Retrieving Hibernations by Action Key Search 178 Retrieving Hibernations By Filter. . . . . . . . . 178 Waking a Hibernation . . . . . . . . . . . . . . . . . . . . . 179 Retrieving the Hibernation . . . . . . . . . . . . . . 179 Calling ActivateHibernation . . . . . . . . . . . . . 179 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 Removing Hibernations . . . . . . . . . . . . . . . . . . . 179 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
Chapter 20. Executing External Commands . . . . . . . . . . . . . . . . . . . . . . . . . 187

About External Command Execution . . . . . . . . 187 What is External Command Execution? . . . 187 How Do I Execute External Commands? . . 187 What Kind of External Commands Can I Use? 187 Using the JRExec Server . . . . . . . . . . . . . . . . . . . 188 What Is the JRExec Server? . . . . . . . . . . . . . . 188 How Do I Set Up the JRExec Server? . . . . . . 188 How Do I Execute a Command Using the JRExec Server? . . . . . . . . . . . . . . . . . . . . . . . . . 188 JRExec Server Logging . . . . . . . . . . . . . . . . . . 189 Command and Response . . . . . . . . . . . . . . . . . . 189 What Is Command and Response? . . . . . . . 189 How Do I Execute Commands Using Command and Response? . . . . . . . . . . . . . . . . . . . . . . . . . 189
Chapter 21. Handling Strings and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Handling Strings . . . . . . . . . . . . . . . . . . . . . . . . . 193 Concatenating Strings . . . . . . . . . . . . . . . . . . 193 Finding the Length of a String . . . . . . . . . . . 194 Splitting a String into Substrings . . . . . . . . . 194 Extracting a Substring from Another String 194 Replacing a Substring in a String . . . . . . . . . 195 Stripping a Substring from a String . . . . . . . 195 Trimming Whitespace from a String . . . . . . 196 Changing the Case of a String. . . . . . . . . . . . 196 Encrypting and Decrypting Strings . . . . . . . 196 Handling Arrays. . . . . . . . . . . . . . . . . . . . . . . . . . 197
Chapter 18. Sending E-Mail . . . . . . . . 181

About Sending E-Mail . . . . . . . . . . . . . . . . . . . . . 181 Sending an E-Mail . . . . . . . . . . . . . . . . . . . . . . . . 181
Chapter 19. Instant Messaging . . . . 183

About Netcool/Impact IM . . . . . . . . . . . . . . . . . 183 What Is Instant Messaging?. . . . . . . . . . . . . . 183
viii
Finding the Length of an Array. . . . . . . . . . . 197 Finding the Distinct Values in an Array . . . 197
Reviewing the Data Model. . . . . . . . . . . . . . .212 Setting Up Services . . . . . . . . . . . . . . . . . . . . . . . .212 Creating the Event Reader . . . . . . . . . . . . . . .212 Reviewing the Services . . . . . . . . . . . . . . . . . .214 Writing the Policy . . . . . . . . . . . . . . . . . . . . . . . . .214 Looking Up Device Information . . . . . . . . . .215 Adding Device Information to the Journal .215 Looking Up Business Departments . . . . . . .216 Increasing the Alert Severity . . . . . . . . . . . . .217 Reviewing the Policy. . . . . . . . . . . . . . . . . . . .218 Running the Solution . . . . . . . . . . . . . . . . . . . . . .219
Chapter 22. Event Enrichment Tutorial 199

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Tutorial Goal . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Sample Environment. . . . . . . . . . . . . . . . . . . . 200 Understanding the Netcool Installation . . . . . . 200 Understanding the Business Data . . . . . . . . . . . 200 Analyzing the Workflow . . . . . . . . . . . . . . . . . . . 201 Creating the Project . . . . . . . . . . . . . . . . . . . . . . . 202 Setting Up the Data Model . . . . . . . . . . . . . . . . . 203 Creating the Event Source . . . . . . . . . . . . . . . 203 Creating the Data Sources . . . . . . . . . . . . . . . 205 Creating the Data Types . . . . . . . . . . . . . . . . . 207 Creating a Dynamic Link . . . . . . . . . . . . . . . . 209
Appendix A. Glossary. . . . . . . . . . . . . . 221

Glossary of Terms . . . . . . . . . . . . . . . . . . . . . . . . .221
Appendix B. Notices . . . . . . . . . . . . . . . 227

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227 Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
ix
preface.fm November 30, 2006
Preface
This preface contains the following sections: "Audience" on page xviii "About this guide" on page xvii "Associated publications" on page xx "Typographical notation" on page xviii "Operating system considerations" on page xxi
About this guide

This guide contains the following chapters: Chapter 1. "Getting Started" on page 1 Chapter 2. "Netcool/Impact Solutions" on page 11 Chapter 3. "Data Models" on page 17 Chapter 4. "Working with Data Sources" on page 27 Chapter 5. "Working with Data Types" on page 33 Chapter 6. "Working with Links" on page 53 Chapter 7. "Working with Event Sources" on page 63 Chapter 8. "Services" on page 71 Chapter 9. "Working with Event Readers" on page 77 Chapter 10. "Working with Event Listeners" on page 89 Chapter 12. "Working with Policy Activators" on page 119 Chapter 13. "Working with Other Services" on page 123 Chapter 14. "Policy Fundamentals" on page 131 Chapter 15. "Handling Events" on page 145 Chapter 16. "Handling Data" on page 153 Chapter 17. "Handling Hibernations" on page 181 Chapter 18. "Sending E-Mail" on page 187 Chapter 19. "Instant Messaging" on page 189 Chapter 20. "Executing External Commands" on page 193
Preface xvii
Chapter 21. "Handling Strings and Arrays" on page 199 Chapter 22. "Event Enrichment Tutorial" on page 205
Audience
This guide contains information on implementing Netcool/Impact in your environment. It contains information on setting up a data model, working with services and developing policies. This guide is intended for Netcool/Impact administrators and for other users who are responsible for implementing Netcool/Impact.
Typographical notation
Table 1 shows the typographical notation and conventions used to describe commands, SQL syntax, and graphical user interface (GUI) features. This notation is used throughout this book and other Netcool publications.
Table 1. Typographical Notation and Conventions (1 of 2) Example Monospac e Description The following are described in a monospace font: Commands and command line options Screen representations Source code Object names Program names SQL syntax elements File, path, and directory names Values Italicized monospace text indicates a variable that the user must populate. For example, -password password. Bold The following application characteristics are described in a bold font style: Buttons Note: Text in the pop-up tooltips is used to name buttons with icons. These button names are described in plain text. Frames Text fields Menu entries A bold arrow symbol indicates a menu entry selection. For example, FileSave.
xvi- Impact Version 4.0 Solutions Guide
Table 1. Typographical Notation and Conventions (2 of 2) Example Italic Description The following are described in an italic font style: An application window name; for example, the Login window Information that the user must enter The introduction of a new term or definition Emphasized text References to external documents [1] Code or command examples are occasionally prefixed with a line number in square brackets. For example: [1] First command... [2] Second command... [3] Third command... { a | b } [ ] | ... ,... In SQL syntax notation, curly brackets enclose two or more required alternative choices, separated by vertical bars. In SQL syntax notation, square brackets indicate an optional element or clause. Multiple elements or clauses are separated by vertical bars. In SQL syntax notation, vertical bars separate two or more alternative syntax elements. In SQL syntax notation, ellipses indicate that the preceding element can be repeated. The repetition is unlimited unless otherwise indicated. In SQL syntax notation, ellipses preceded by a comma indicate that the preceding element can be repeated, with each repeated element separated from the last by a comma. The repetition is unlimited unless otherwise indicated. In SQL syntax notation, an underlined element indicates a default option. In SQL syntax notation, parentheses appearing within the statement syntax are part of the syntax and should be typed as shown unless otherwise indicated.
a ( )
Many Netcool commands have one or more command line options that can be specified following a hyphen (-). Command line options can be string, integer, or BOOLEAN types: A string can contain alphanumeric characters. If the string has spaces in it, enclose it in quotation (") marks. An integer must contain a positive whole number or zero (0). A BOOLEAN must be set to TRUE or FALSE.
SQL keywords are not case-sensitive, and may appear in uppercase, lowercase, or mixed case. Names of ObjectServer objects and identifiers are case-sensitive.
Note, Tip, and Warning information

The following types of information are used in the documentation:
Preface xix
Note: Note is used for extra information about the feature or operation that is being described. Essentially, this is for extra data that is important but not vital to the user. Tip: Tip is used for additional information that might be useful for the user. For example, when describing an installation process, there might be a shortcut that could be used instead of following the standard installation instructions.
Attention: Attention is used for highlighting vital instructions, cautions, or critical information. Pay close attention to this information, as it is vital to the successful use of IBMs products.
Syntax and Sample subheadings

The following types of constrained subheading are used in the documentation:
Syntax:
Syntax subheadings contain examples of ObjectServer SQL syntax commands and their usage. For example:
CREATE DATABASE database_name;
Sample:
Sample subheadings describe typical or generic scenarios, or samples of code. For example:
[1] [2] [3] [4] [5] [6] <body> <img src="ChartView?template=barchart&format=PNG &request=image&chart=quote&width=800&height=400" border="0" height="400" width="800" alt="Events by Severity" > </body>
Associated publications
Netcool/Impact 4.0 provides the following additional documentation: Netcool/Impact Administration Guide Netcool/Impact User Interface Guide Netcool/Impact Policy Reference Guide Netcool/Impact DSA Reference Guide Netcool/Impact Online Help Netcool/Impact Release Notes
xx
Netcool/Impact Administration Guide

This guide contains information on installing, configuring and running Netcool/Impact. It is intended for administrators and for other users who are responsible for setting up and managing Netcool/Impact.
Netcool/Impact User Interface Guide

This guide provides step-by-step instructions on using the Netcool/Impact user interface. It is intended for all Netcool/Impact users.
Netcool/Impact Policy Reference Guide

This guide contains reference information about the Netcool/Impact Policy Language (IPL). It contains complete information about policy language syntax, data types, operators and functions. It is intended for users who are responsible for writing and running Netcool/Impact policies.
Netcool/Impact DSA Reference Guide

This guide contains reference information about Netcool/Impact data source adaptors (DSA). This information includes instructions for setting up the DSAs, creating data models that work with the DSAs and writing policies that use the DSAs. This guide is intended for Netcool/Impact administrators.
Netcool/Impact Online Help

This online help system provides step-by-step instructions on using the Netcool/Impact user interface. It also provides a complete policy language reference. This help system is intended for all Netcool/Impact users.
Netcool/Impact Release Notes

This guide provides information about new features, system requirements and known issues for this version of Netcool/Impact.
Operating system considerations

Unless otherwise specified, command files are located in the $NCHOME/impact/bin directory, where $NCHOME is the environment variable that contains the path to the Netcool Suite home directory. On UNIX platforms, replace $NCHOME with $$NCHOME. All command line formats and examples are for the standard UNIX shell. UNIX is case-sensitive. You must type commands in the case shown in the book. On Microsoft Windows platforms, replace $NCHOME with %$NCHOME% and the forward slash (/) with a backward slash (\).
Preface
xxi
How to send your comments

Your feedback is important in helping to provide the most accurate and highest quality information. If you have any comments about this book or any other IBM Tivoli documentation: Go to the Tivoli Support home page at http://www.tivoli.com/support. There you will find the feedback page where you can enter and submit comments. Send your comments by e-mail to pubs@tivoli.com. Be sure to include the name of the book, the part number of the book, the version the product, and, if applicable, the specific location of the text you are commenting on (for example, a page number or table number).
xxii Impact Version 4.0 Solutions Guide
01_Getting_Started.fm November 30, 2006
Chapter 1. Getting Started

This chapter contains information on getting started with Netcool/Impact. It contains the following sections: "What Is Netcool/Impact?" on page 1 "What Do I Do With Netcool/Impact?" on page 3
What Is Netcool/Impact?
Netcool/Impact is a set of runnable server components that work together to provide event management and integration functionality for the Netcool suite of products.
The Netcool/Impact Software System

From a software perspective, you can best understand Netcool/Impact as a set of interrelated, runnable server components, each of which must be installed and configured separately. These components are: Netcool/Impact Server Netcool Security Manager Netcool GUI Server
The Netcool/Impact Server

The Netcool/Impact Server is the primary software component of the system. This component is responsible for the core functionality of Netcool/Impact, including managing the Netcool/Impact data model, running services and executing policies. Depending on how you use the product, you can run a single instance of the Netcool/Impact Server or run multiple instances as part of a server cluster. Most of the tasks you perform with Netcool/Impact require you to work with this server component. For information on installing, configuring and running the Netcool/Impact Server, see the Netcool/Impact Administration Guide.
The Netcool Security Manager

The Netcool Security Manager is the component is responsible for managing authentication for Netcool/Impact and the Netcool/Impact GUI. Typically, you run a single installation of the Security Manager for all compatible Netcool products running in your environment. For information on installing, configuring and running the Netcool Security Manager, see the Netcool Security Manager Installation Guide.
Chapter 1. Getting Started 1
The Netcool GUI Server

The Netcool GUI Server is the component that is responsible for hosting and serving the Netcool/Impact GUI. Typically, you have a single installation of the GUI Server for all compatible Netcool products running in your environment. For information on installing, configuring and running the Netcool GUI Server, see the Netcool/Impact Administration Guide.
Netcool/Impact As a Development Tool

From an implementation perspective, you can understand Netcool/Impact as a development tool that you use to customize, enhance and expand the functionality of an existing Netcool installation. Netcool/Impact is not an out-of-the-box event management or integration solution. Rather, it is a platform that you can use to build new functionality into your current installation of the Netcool product suite. Because it is a development tool, most of the work that you do with Netcool/Impact is done during initial setup. Like other development tools, Netcool/Impact requires you to understand your implementation goals and to plan your implementation before you begin. Some of the development tasks that you perform using Netcool/Impact are: Modeling data Configuring services Writing policies
Modeling Data
Modeling data is the task in which you create an abstract representation of the business data and metadata that you want to use with Netcool/Impact. This task requires you to be able to identify and locate physical sources of data in your environment and to create a representation of this data.
Configuring Services
Configuring services is the development task in which you set up the runnable sub-components of the Netcool/Impact Server to perform such operations as monitoring an ObjectServer for events, or triggering the execution of a policy at timed intervals.
Writing Policies
Writing policies is the task in which you define the operations that you want to automate with Netcool/Impact. You write policies using the Netcool/Impact policy scripting language and then configure Netcool/Impact to run them when certain conditions occur in your environment.
Netcool/Impact As an Automation Engine

From a real-time operations perspective, you can understand Netcool/Impact as an automation engine that runs invisibly in the background and does not require end user interaction. This means that once you set up Netcool/Impact, it does not require any additional management unless you want to change your implementation.
What Do I Do With Netcool/Impact?

You can use Netcool/Impact in a very wide variety of ways, depending on the needs of your environment. One way to figure out what you can do with Netcool/Impact is to analyze its core features and determine how you can put together a solution that enhances the value of your Netcool installation. Another way is to look at typical solutions implemented by other Netcool users and see how you can adapt them for use in your environment. Finally, you can also examine the workflow in your network environment and see what parts of the process can be improved using Netcool/Impact.
Core Netcool/Impact Features

As noted above, one way to figure out what you can do with Netcool/Impact is to analyze its core features and determine how you can put them to use in your environment. The sections below discuss some of the most important features of Netcool/Impact and how they relate to event management as a whole and to the Netcool suite of products in particular. The core features of Netcool/Impact are: Automation Event source access Data access Integration with third-party applications Pre-defined actions
Automation
In a general sense, automation is Netcool/Impacts most important feature. The essence of Netcool/Impact is its ability to automate event management tasks that you would otherwise have to accomplish manually, or would not be able to accomplish at all. These tasks, which include event monitoring, event enrichment and event notification, are discussed in the next section of this chapter. Automation, however, is really the foundation of what Netcool/Impact does. Automation is the act of setting up a task so that it is performed automatically at certain times or when certain conditions are met. For example, you can set a wristwatch to beep once per hour, or once per day at a certain hour. You might also be able to set a more advanced wristwatch to monitor your calendar and beep at different times of the day to notify you when meetings or other appointments are about to occur. In this case, the benefit
of automation is that it saves you the time and effort involved in performing a routine task over and over. In the wristwatch example, you are saved the time and effort of constantly looking at your watch to check the time, or having to continually refer to a calendar to see when your next meeting begins. A more complicated example of automation is the factory assembly line. As items move down the assembly line, operations must be performed on them in order for the products to be finished. In some situations, these operations are performed by human workers, who each complete a designated action and pass the items down the line to the next person. This might be effective for a small factory making simple objects with a small number of users. However, the larger the number of workers you have and the more complicated the operations, the higher the risk of error is. In addition, the more items you need to produce, the faster the operations must be accomplished. At some point, the human workers cannot work fast or well enough. In the assembly line, automation comes in where you want to take some of the routine, repeatable parts of the process and set up them up so that they are performed automatically with a minimum of human intervention. For example, you might add various clocks, machines and monitors to the process, or even intelligent robots that can perform some operations previously accomplished by human workers. A Netcool operations environment is, in some ways, like a factory assembly line. Instead of items moving down a conveyer belt, however, you have Netcool alerts. In a purely manual environment, network operators process each alert by hand. As they appear in the event list, the operators must acknowledge them, investigate them, notify other personnel that they have occurred and perform a variety of other tasks like creating new trouble tickets or work orders in other applications. Finally, when the alert condition is resolved, the operator must delete the alerts out of the event list. For a small network of a few devices and one or two operators, manual processing of events might be satisfactory. As with the assembly line, however, the more alerts you have and the more complicated the operator response, the more difficult and costly it is to manage the operation on a manual basis. Like the assembly line, the network operations environment can benefit from automating certain processes. For example, tasks like notifying technicians or system administrators when an alert reaches a certain severity, or updating an event to include related business data can require time and effort on the part of one or more network operators. If you automate these processes, the operators can spend time on higher-priority tasks or be redeployed to other roles in the business. This translates into an event management environment that is less costly than a manual one and less prone to human error. The framework that Netcool/Impact provides for automations consists of the policy engine, the policy scripting language and various triggers that you can use to "program" Netcool/Impact to start the policies under different conditions. The policy engine is the feature of Netcool/Impact that performs the tasks you want to automate. These tasks are specified the policy scripting language, which is a programming language similar in syntax to C/C++ and Java.
Event Access
After automation, event access is the next most important feature of Netcool/Impact. Event access is the feature that allows Netcool/Impact to tap into the event stream that flows from Netcool probes and monitors into the Netcool/OMNIbus ObjectServer. This feature is an essential part of most implementations of the product. In order to see how and why event access is important, you must first understand the Netcool event stream and how it is generated. The Netcool event stream is the flow of alerts from Netcool probes and monitors into the ObjectServer. Each alert represents some sort of status or activity on the network and can originate from any of hundreds of different kinds of systems, devices or applications. Typically, alerts are designed to inform network operators that a fault condition has occurred somewhere in the environment, but they can be used to communicate other types of status or event information as well. Alerts themselves are generated by software components called probes and monitors, which watch the systems, devices or applications and generate the alerts when various conditions occur. After the probes and monitors generate the alerts, they are sent to the ObjectServer, where they can be viewed by network operators via the Netcool/OMNIbus event list. As noted in the previous section, the network management environment benefits from automated event management tasks. This automation relies on Netcool/Impacts ability to tap into the Netcool event stream. The framework that Netcool/Impact provides for event access consists of three features: the event reader, the event listener and the event processor. These are runnable services that you control from within Netcool/Impact. The event reader works by monitoring an instance of the ObjectServer. When it discovers new and/or updated events, or discovers that an event has been deleted, it takes the event and pulls it back into Netcool/Impact for processing. Similarly, the event listener monitors other, non-ObjectServer sources of events, such as SQL databases. As with the event reader, it takes new and/or updated events when it discovers them and pulls them back to Netcool/Impact. The event processor is responsible for what happens after the events have been retrieved. When you set up an event reader or event listener, you define one or more policies that are to be executed when an event matches a specified criteria. As noted in the previous section, a policy is a set of instructions for Netcool/Impact that specifies the tasks that you want to automate. When coupled with the event reader or event listener, you can use a policy to specify a set of tasks that you want Netcool/Impact to perform automatically when certain kinds of alerts appear in the ObjectServer or other events appear in other event sources. This combination of event access and automation functionality allows you to create a wide variety of event management solutions. These solutions include event enrichment, X events in Y time, event notification and event gateways, as described later in this chapter.
Data Access
Like automation and event access, data access is also an important feature of Netcool/Impact. Data access is the feature that allows Netcool/Impact to connect to external data sources, such as SQL databases and LDAP servers. To understand how this feature is important, you can think about all of the ways you use data that is external to Netcool/OMNIbus in your network management environment. You might have one database that contains network inventory information and another database that contains information on billing and customer service. In addition, you might have an LDAP directory that you use to store information on the company personnel. In an environment without Netcool/Impact, it is possible for network operators to be responsible for manually retrieving data from one or more of these data sources and using that information to deduce the importance of events or to decide how events must be handled. With Netcool/Impact, you can integrate this type of data directly into alerts at the ObjectServer level or use this data to perform various types of analysis on the severity or relevance of individual alerts. The mechanism for accessing data used by Netcool/Impact consists of data source adaptors (DSAs) and Netcool/Impact data models. At the software component level, DSAs provide the means for Netcool/Impact to connect to a wide variety of SQL databases, LDAP servers and other data sources. At the solution level, the data model is an abstract representation of the data in your environment. Netcool/Impact uses the data model within policies when it retrieves, adds, updates and deletes data from the data sources.
Third-Party Integration
The ability to integrate with third-party applications is another important feature of Netcool/Impact. In many network operations environments, you have systems in place that have been created by more than one software provider. For example, in addition to the Netcool suite of products, you might have a separate third-party applications for network inventory management, billing, problem tracking, customer service and the help desk. You might also have messaging systems and other infrastructure software that is not provided by Micromuse. Netcool/Impact provides interfaces to a wide array of such third-party applications, including GE Smallworld, Portal Infranet, TIBCO TIB/Rendezvous and Cramer Dimension. Netcool/Impact can interface with a wide variety of other applications by interfacing directly with their underlying databases.
Pre-Defined Actions
In addition to the features described above, Netcool/Impact allows provides a built-in set of pre-defined actions that you can include among your automated tasks. One of the most important of these is the embedded e-mail client software that you can use to send e-mail notifications to administrators and end-users when faults or other conditions on your network occur. Another important pre-defined action is the ability of Netcool/Impact to execute shell commands, scripts and applications on local and/or remote systems.
Typical Netcool/Impact Implementations

As noted earlier in this chapter, another way to figure out what you can do with Netcool/Impact is to look at typical solutions implemented by other Netcool users and see how you can adapt them for use in your environment. The sections below discuss some of the most typical implementations. Other parts of this guide go into greater detail about these solutions. Some typical Netcool/Impact solutions are: Event enrichment X events in Y time Event notification Event gateways
Event Enrichment
Event enrichment is the process in which Netcool/Impact monitors an event source for new events, looks up information related to them in an external data source and then adds the information to them. Event enrichment is the one of the most common and valuable things that users do with Netcool/Impact. To understand the value of event enrichment, you must first understand how Netcool probes work and some of their intrinsic limitations. Netcool probes are runnable software components that you install on the devices that they monitor. Of probes and monitors, probes are the most common means for generating alerts in the Netcool event stream. Each probe has a rules file that specifies how the alert data is formatted and sent to the ObjectServer when certain activities or status levels on the device occur. One characteristic of the probe rules file is that it is essentially static. This means that, once you install and configure the probe, the contents of the rules file rarely change. Not only is change rare, but changing the rules file on the fly to adjust to the constantly changing parameters of a network environment would be impossible. As a result, it is difficult to include dynamic information about the network in the contents of alerts generated by probes. Another characteristic of the probes rules file is that, generally, it is best to use an identical copy of the file on every instance of a device that you have in your inventory. For example, if you have dozens of routers in your network, it is most likely that you will want to use the same rules file for each device. This ensures that every probe reports activity or status information to the ObjectServer in the exact same way and eliminates any complications that might occur if each probe was configured differently. Because of this, however, the probes are not able to send alerts to the ObjectServer that contain information specific to the individual device, beyond a few basic parameters like the hostname and IP address. In addition to the limitations given above, the scope of alert data provided by a probe is generally restricted to information that directly describes the alert condition. The probe cannot provide additional information about how the condition affects the network as a whole, or perform any sort of analysis or correlation regarding the alert.
Chapter 1. Getting Started 7
Although these limitations are primarily associated with probes, they exist to some degree with other Netcool components that generate alert data. Event enrichment allows you to bypass these and other limitations by combining the event and data access features of Netcool/Impact. In an event enrichment scenario, Netcool/Impact "catches" new and updated alerts as they are sent to the ObjectServer and then goes to one or more external data sources to correlate information in the alerts with business data. The Netcool/Impact policy language provides the means to intelligently determine which data in your environment is related to the alert and then to add that information to the alert on the fly. The process of event enrichment can be configured to run completely in the background, so that the intervention of Netcool/Impact in the event flow is not noticeable to a network operator. One simple example of event enrichment is an environment where you are managing a network of servers, each of which is used by a different department in the business. In this environment, you use the ping probe to monitor the uptime of the server systems. If a ping does not reach the target system, the probe sends an alert to the ObjectServer that says that the server is not reachable. In an environment without Netcool/Impact, network operators would have to manually look up the business department associated with the server in order to deduce the priority of any incoming alert. They might also have to use a separate calendar or scheduling program to find the on-call administrator responsible for maintaining the system. With Netcool/Impact, you can "catch" each alert as it comes into the ObjectServer, look up the affected business department and automatically adjust the severity of the alert accordingly. In environments with a higher level of complexity and a large number of network devices, systems and applications, the need for event enrichment becomes more critical. This automated process can then be used to supplement Netcool alerts with a wide variety of topological, technical, contact and other information.
X Events in Y Time
X events in Y time is the process in which Netcool/Impact monitors an event source for groups of events that occur together and takes the appropriate action based on the event information. X events in Y time solutions acknowledge the fact that few fault conditions in a network environment occur in a vacuum. When one device fails, for example, it is often possible that other parts of the system will also fail, or that the probe that monitors it will continue to report faults from the device until the problem is resolved. X events in Y time solutions allow you to "program" Netcool/Impact to take action when a group of related events occurs within the same time window. An example of an X events in Y time solution is an environment where you are monitoring a set of telecommunication switches. A potential fault condition exists in the environment where a device will cause an alert to appear multiple times in the same time window as a particular link goes up and down. Taken alone, the fault is a low priority, but if it occurs more than a dozen or so times within the same 5 second period, it indicates a continuing problem that needs to be addressed.
8 Impact Version 4.0 Solutions Guide
Without Netcool/Impact, a network operator might not be able to detect this fault condition by simply monitoring the ObjectServer event list, especially if there are a large number of other devices in the network reporting other status and fault conditions. With Netcool/Impact, you can define a set of operations that you want to take place automatically every time this happens, including increasing the severity of the alert in order to make sure it is detected by network operators.
Event Notification
Event notification is the process in which Netcool/Impact monitors an event source for new events and then notifies an administrator or end users when a certain event or combination of events occurs. Event notification is often part of a more complicated event management automation that includes aspects of Netcool/Impact functionality discussed elsewhere in this section. Netcool/Impact provides a built-in e-mail client that allows you to send mail via any SMTP server. You can use this feature to send mail notifications to administrators and other users, or you can use the remote execution feature provided by the JRExec server to launch an external e-mail program from the command line. You can also use the JRExec server to send notifications via a paging system that provides a command line interface.
Event Gateways
An event gateway is an implementation of Netcool/Impact in which you send event information from the ObjectServer to a third-party application for processing. Because Netcool/Impact can interface with so many different types of databases and other software, you can use Netcool/Impact to build event gateways where that do not otherwise exist as part of the Netcool suite.
Netcool/Impact and Workflow Analysis

As discussed earlier in this chapter, you can also figure out what you to do with Netcool/Impact by analyzing the current workflow in your environment and seeing which parts of your event management process it is most effective to automate. Before you analyze the workflow, you should review the core features of Netcool/Impact, as discussed earlier in this chapter, as well as the concepts and techniques discussed in the remainder of this guide.
10
02_Solutions.fm November 30, 2006
Chapter 2. Netcool/Impact Solutions

This chapter contains general information about Netcool/Impact solutions. This chapter contains the following sections: "About Netcool/Impact Solutions" on page 11 "Solution Components" on page 12 "Solution Types" on page 13 "Setting Up a Solution" on page 14 "Running a Solution" on page 15
About Netcool/Impact Solutions

This section contains overview information about Netcool/Impact solutions.
What Are Solutions?

A solution is an implementation of Netcool/Impact that provides a specific type of event management functionality.
What Are the Solution Components?

The components of a Netcool/Impact solution are a data model, services and/or one or more policies. Most solutions use a combination of these three components. For more information, see "Solution Components" on page 12.
What Are the Solution Types?

Netcool/Impact allows you to implement a wide variety of solution types. Some common types are event enrichment, X events in Y time, event notification and event gateways.
How Do I Set Up a Solution?

To set up a solution, you do the following: Create a data model Set up services Create policies
For more information, see "Setting Up a Solution" on page 14.
11
Solution Components
The following are the components of a Netcool/Impact solution: Data model Services Policies
Data Models
A data model is model of the business and meta-data used in a Netcool/Impact solution. A data model consists of the following components: Data sources Data types Data items Links Event sources
Services
Services are runnable subcomponents that you control from within Netcool/Impact. Netcool/Impact provides the following services: Event readers Event listeners E-Mail sender E-Mail readers Policy activators Hibernating policy activator Event processor Policy logger Command line manager service CORBA name service
The most important Netcool/Impact service is the event reader, which you can use to monitor an ObjectServer for new, updated and/or deleted events. The event processor, which processes the events retrieved from the ObjectServer is also important to the function of Netcool/Impact.
12
Policies
A policy is a set of operations that you want Netcool/Impact to perform. These operations are specified using a programming language called the Netcool/Impact policy language, or IPL. 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. It also allows you to create your own variables and functions, just as in other programming languages.
Solution Types
You can use Netcool/Impact in a very wide variety ways, depending on the needs of your environment. The following are typical types of Netcool/Impact solutions: Event enrichment X events in Y time Event notification Event gateway
Event Enrichment
Event enrichment is a process in which Netcool/Impact monitors an event source for new events, looks up information related to them in an external data source and then adds the information to them. Event enrichment is the one of the most common and valuable things that users do with Netcool/Impact. An event enrichment solution consists of the following components: A data model that represents the data you want to add to events An event reader service that monitors the event source One or more event enrichment policies that look up information related to the events and add the information to them
For a sample event enrichment solution, see Chapter 22. "Event Enrichment Tutorial" on page 199.
X Events in Y Time
X events in Y time is a process in which Netcool/Impact monitors an event source for groups of events that occur together and takes the appropriate action based on the event information.
13
An X events in Y time solution consists of the following components: A data model that contains internal data types used to store meta-data for the solution An event reader service that monitors the event source The hibernation activator service, which wakes hibernating policies at timed intervals One or more policies that check the event source to see if a specified group of events is occurring and then take the appropriate action
Event Notification
Event notification is a process in which Netcool/Impact monitors an event source for new events and then notifies an administrator or end users when a certain event or combination of events occurs. Event notification is often part of a more complicated event management automation that includes aspects of Netcool/Impact functionality discussed elsewhere in this section. An event notification solution has the following components: An event reader service that monitors the event source An e-mail sender service that sends e-mail to administrators or end users, or the JRExec server used to launch an external notification program One or more policies that perform the event notification
Event Gateway
An event gateway is an implementation of Netcool/Impact in which you send event information from the ObjectServer to a third-party application for processing. Because Netcool/Impact can interface with so many different types of databases and other software, you can use Netcool/Impact to build event gateways where that do not otherwise exist as part of the Netcool suite. An event gateway solution has the following components A data model that includes a data source and data type representing the third-party application An event reader service that monitors the event source One or more policies that send event information to the third-party application
Setting Up a Solution
To set up a Netcool/Impact solution, you do the following: Create a data model Set up services Create policies
14
Creating a Data Model

The first step in setting up a solution is to create a data model. While it is possible to design a solution that does not require a data model, almost all uses of Netcool/Impact require the ability to handle some sort of internal or external data. To create a data model, you create a data source for each real-world source of data that you want to use in the solution. Then, you create a data type for each structural element (for example, a database table) that contains the data you want to use. Optionally, you can create also dynamic links between data types or static links between data items that make it easier to traverse the data programmatically from within a policy. For more information, see Chapter 3. "Data Models" on page 17.
Setting Up Services
The next step is to set up services. Different types of solutions require different sets of services. Most solutions require an event reader. Solutions that use hibernations also require the hibernating policy activator. Solutions that receive or send e-mail require an e-mail reader and the e-mail sender service. Netcool/Impact has two categories of services. The first category are built-in services like the event processor and the command line service manager. Netcool/Impact only allows you to have single instances of this type of service. The second category are services like the event reader and policy activator. You can create and configure multiple instances of this type of service. For more information, see Chapter 8. "Services" on page 71.
Creating Policies
After you have created a data model and set up the services you need, you can start creating the policies required by your solution. You create policies using the Netcool/Impact GUI, which contains a policy editor, a syntax checker and other tools you need to write, run, test and debug your policies. For more information, see Chapter 14. "Policy Fundamentals" on page 133.
Running a Solution
To start a solution, you start each of the service components. You should start the components in the following order: Hibernating policy activator, e-mail sender, command execution manager and/or CORBA name service Event processor Event reader, event listener, e-mail reader or policy activator
15
You can configure services to run automatically at startup, or you can start them manually using the Netcool/Impact GUI and CLI. By default, services that run automatically at startup run in the proper order. If all other services are already running, starting services like the event processor that trigger policies effectively starts the solution. To stop a solution, you stop any services, like the event processor, that trigger your policies.
16
03_Data_Models.fm November 30, 2006
Chapter 3. Data Models

This chapter contains information about Netcool/Impact data models. It contains the following sections: "Introduction" on page 17 "How Do I Use This Part of the Guide?" on page 18 "About Data Models" on page 18 "Data Model Components" on page 19 "Data Model Architecture" on page 21 "Data Model Examples" on page 22 "Setting Up a Data Model" on page 25
Introduction
This is the beginning of Part Two of this guide. Part Two provides information about Netcool/Impact data models. This part of the guide contains the following chapters: Chapter 3. "Data Models" on page 17. This chapter contains general information on Netcool/Impact data models. Chapter 4. "Working with Data Sources" on page 27. This chapter contains information on how to work with Netcool/Impact data sources. Chapter 5. "Working with Data Types" on page 33. This chapter contains information on how to work with Netcool/Impact data types. Chapter 6. "Working with Links" on page 53. This chapter contains information on how to work with Netcool/Impact links. Chapter 7. "Working with Event Sources" on page 63. This chapter contains information on how to work with Netcool/Impact event sources.
17
How Do I Use This Part of the Guide?

If you are new to working with Netcool/Impact data models, you should read the chapters in this part of the guide in order, paying special attention to conceptual and overview information. Because you must master a variety of concepts and procedures before you can create your own data model, you should review any information that you do not understand before progressing to the next part of this book. If you are an experienced Netcool/Impact user, or you are upgrading a data model from a previous version of Netcool/Impact for the first time, you should first read Chapter 4. "Working with Data Sources" on page 27, which presents basic information about the new data source feature in Netcool/Impact. Then you can read any of the following chapters as needed in order to review information that you already know, or learn how to upgrade the your existing data model so that it is compatible with this version of the product. Once you have a firm understanding of Netcool/Impact data models, you can go on to Part Four of this guide, which starts with Chapter 8. "Services" on page 71. Part Four contains instructions on working with Netcool/Impact services.
About Data Models

This section contains overview information about data models. It contains the following topics: What Is a Data Model? What Are the Data Model Components? How Do I Use a Data Model? How Do I Manage a Data Model with Netcool/Impact How Do I Set Up a Data Model?
What Is a Data Model?

A data model is model of the business data and metadata used in a Netcool/Impact solution.
What Are the Data Model Components?

A data model consists of the following components: Data sources Data types Data items Links Event sources
18
How Do I Use a Data Model?

Generally, you set up a data model once, when you first design your Netcool/Impact solution. After that, you do not need to actively manage the data model unless you change the solution design.
How Do I Set Up a Data Model?

To set up a data model, you must first determine what data you need to use in your solution and where that data is stored. Then, you create a data source for each real-world source of data and create a data type for each structural element that contains the data you need. Optionally, you can also create dynamic links between data types or static links between data items that make it easier to traverse the data programmatically from within a policy.
How Do I Manage a Data Model with Netcool/Impact?

You manage a data model using the Netcool/Impact GUI. The GUI provides the means to view, create, edit and delete all of the components of a data model.
Data Model Components

A Netcool/Impact data model is made up of components that represent real-world sources of data and the actual data inside them. A data model can also includes components called links that represent relationships between different elements of data. A data model consists of the following components: Data sources Data types Data items Links Event sources
Data Sources
Data sources are elements of the data model that represent real-world sources of data in your environment. Netcool/Impact supports SQL databases, LDAP servers and a variety of other external third-party data sources. Netcool/Impact also allows you to use its own internal data repository as a data source. For more information on data sources, see Chapter 4. "Working with Data Sources" on page 27.
19
Data Types
Data types are elements of the data model that represent sets of data stored in a data source. The structure of this depends on the category of data source where it is stored. For example, if the data source is an SQL database, each data type corresponds to a database table. If the data source is an LDAP server, each data type corresponds to a type of node in the LDAP hierarchy. For more information on data types, see Chapter 5. "Working with Data Types" on page 33.
Data Items
Data items are elements of the data model that represent actual units of data stored in a data source. The structure of this unit of data depends on the category of the associated data source. For example, if the data source is an SQL database data type, each data item corresponds to a row in a database table. If the data source is an LDAP server, each data item corresponds to a node in the LDAP hierarchy.
Links
Links are elements of the data model the define relationships between data types and data items. Dynamic links define relationships between data type. Static links define relationships between data items. Link are an optional component of a Netcool/Impact data model. For more information on links, see Chapter 6. "Working with Links" on page 53.
20
Data Model Architecture

The following diagram shows the relationship between data sources, data type and data items in a Netcool/Impact solution.
Netcool/Impact
SQL Database Data Source
SQL Database Data Source
Mediator Data Source
LDAP Data Source
SQL Database Data Type
Mediator Data Type
LDAP Data Type
Data Items
Data Items
Data Items
Data Items
Data Items
Data Items
Data Items
Figure 1. Data Model Architecture
21
Data Model Examples

This section contains examples of data models. The examples in this section are, most likely, scaled-down versions of data models you might be required to implement in the real world. They are designed to give you an idea of how all of the different parts of a data model work together, rather than provide a realistic sampling of every type of data you might access with Netcool/Impact. If you are uncertain about the definition of major concepts mentioned in these examples, such as data sources or data types, you can skip ahead to the next four chapters of this book, which provide detailed information about the various components of the data model. Once you have a better understanding of these concepts, you can return to this section. This section contains the following data model examples: Enterprise Service Model Web Services Hosting Model
Enterprise Service Model

The first example is a data model designed for use in an enterprise service environment. The enterprise service environment is one of the most common network management scenarios for the Netcool product suite. While the data model described in this section is relatively simple, real-world enterprise environments can often rival a small telecommunications or ISP environment in complexity. The goal of the data model in this example is to provide the means to access a set of business data that has been previously collected and stored in an external database. This business data contains information about the users, departments, locations and servers in the enterprise. If you were designing a complete Netcool/Impact solution for this environment, you would tap into this data model from within policies whenever you needed to access this data. The enterprise service environment in this example consists of 125 users in five business departments, spread over three locations. Each user in the environment has a desktop computer and uses it to connect to a file server and an e-mail server. The solution proposed to manage this environment is designed to monitor the file servers and e-mail servers for uptime. When a file server goes down, it notifies the on-call administrator via e-mail with a service request message. It also determines which business units are served by the file server and e-mails each user in the unit with a service interruption message. When an e-mail server goes down, it notifies the on-call administrator via pager. All of the data used by this solution is stored in a MySQL database. This database has six tables, named USER, ADMIN, DEPT, LOC, FILESERVER and EMAILSERVER.
22
Data Sources
Because all of the data needed is stored in a single MySQL database, this data model only requires one data source. For the purposes of this example, the data source is named MYSQL_01.
Data Types
Each table in the MYSQL database is represented by a single SQL database data type. For the purposes of this example, the data types are named User, Admin, Department, Location, Fileserver and Emailserver. In this case, the names of the data types are the same as the table names.
Data Items
Because the data is stored in an SQL database, the data items in the model are rows in the corresponding database tables.
Links
The relationship between the data types in this data model can be described as a set of dynamic links. This data model has the following linking relationships: User -> Department User -> Location Location -> Emailserver Department -> Fileserver Emailserver -> Location. Fileserver -> Departments Administrator -> Location
Event Sources
This data model has a single event source, which represents the Netcool/OMNIbus ObjectServer that stores events related to activity in their environment.
Web Services Hosting Model

The next example is a data model designed for use in a web hosting environment. The web hosting environment is another common network management scenario for the Netcool product suite. Managing a web hosting environment presents some unique challenges. This is because it requires you to assure the uptime of services, such as the availability of customer websites, that consist of groups of interrelated software and hardware devices, in addition to assuring the uptime of the devices themselves. As with the other examples in this chapter, the web services hosting environment described here is scaled-down from what you might encounter in the real world.
23
The goal of the data model in this example is to provide the means to access a set of device inventory and service management data that is generated and updated in real time by a set of third-party application. This data contains information about the server hardware located in racks in the hosting facility and a variety of other data that describes how instances of HTTP and e-mail server software is installed and configured on the hardware. As with the previous example, policies developed for use with this information would tap into this data model whenever they needed to access this data. The web services hosting model in this example consists of ten HTTP server clusters and three e-mail servers clusters, spread over 20 machines. Each HTTP cluster and each e-mail cluster consist of one primary and one backup server. This environment serves 15 customers whose use is distributed across one or more clusters depending on their service agreement. The solution that manages this environment is designed to monitor the uptime of the HTTP and e-mail services. When a problem occurs with one of these services, it determines the identity of the cluster that is causing the problem and the hardware where the component server instances are installed. It then modifies the original alert data in Netcool/OMNIbus to reflect this information. This solution also determines the customer that is associated with the service failure and sets the priority of the alert to reflect the customers service agreement. The data in this model is stored in two separate Oracle databases. The first database has five tables named Node, HTTPInstance, HTTPCluster, EmailInstance and EmailCluster. The second database is a customer service database that has, among other tables, one named Customer.
Data Sources
Because this model has two real-world sources of data, it requires two data sources. For the purpose of this example, these are called ORACLE_01 and ORACLE_02.
Data Types
Each table in the MySQL database is represented by a single SQL database data type. For the purposes of this example, the data types are named Node, HTTPInstance, HTTPCluster, EmailInstance, EmailCluster and Customer.
Data Items
Because the data is stored in an SQL database, the data items in the model are rows in the corresponding database tables.
24
Links
The relationship between the data types in this data model can be described as a set of dynamic links. This data model has the following linking relationships: HTTPServer -> Node EmailServer -> Node HTTPServer -> HTTPCluster EmailServer -> EmailCluster Customer -> HTTPCluster Customer -> HTTPServer
Setting Up a Data Model

Before you can set up your data model, you must first look at the kinds of data required by your solution. To set up a data model, you do the following: Create data sources Create data types Create data items (optional) Create links (optional) Create event sources
Creating Data Sources

The first step in setting up a data model is to identify the data you want to use and where it is stored. Then, you create one data source for each real world source of data. For example, if the data is stored in one MySQL database and one LDAP server, you must create one MySQL and one LDAP data source. For more information, see "Setting Up Data Sources" on page 30.
Creating Data Types

After you have set up the data sources, the next step is to create the required data types. You must create one data type for each database table (or other data element, depending on the data source) that contains data you want to use. For example, if the data is stored in two tables in an Oracle database, you must create one data type for each table. For more information, see "Setting Up Data Types" on page 38.
25
Creating Data Items

For most data types, Micromuse recommends that you create data items using the native tools provided by the data source. For example, if your data source is an Oracle database, you should add any required data to the database using the native Oracle tools. If the data source is the internal data repository, you must create data items using the Netcool/Impact GUI. For more information, see the Netcool/Impact User Interface Guide.
Creating Links
After you have created data types, you can define linking relationships between them using dynamic links. You can also define linking relationships between internal data items using static links. Use of links in Netcool/Impact is optional. For more information, see "Setting Up Links" on page 56.
Creating Event Sources

Most Netcool/Impact process events retrieved from a Netcool/OMNIbus ObjectServer. The ObjectServer is represented in the data model as an event source. For more information, see "Setting Up Event Sources" on page 66.
26
04_Working_With_Data_Sources.fm November 30, 2006
Chapter 4. Working with Data Sources

This chapter contains information about working with Netcool/Impact data sources. It contains the following sections: "About Data Sources" on page 27 "Data Source Categories" on page 28 "Data Source Architecture" on page 29 "Setting Up Data Sources" on page 30
About Data Sources

This section contains overview information about data sources. It contain the following topics: What Is a Data Source? What Are the Data Source Categories? How Do Data Sources Work? How Do I Do With Data Sources? How Do I Set Up Data Source?
What Is a Data Source?

A data source is an element of the Netcool/Impact data model that represents a real-world source of data in your environment.
What Are the Data Source Categories

Netcool/Impact provides the following categories of data sources: SQL database data sources LDAP data sources Mediator data sources
In addition, Netcool/Impacts internal data repository can also be used as a data source. For more information on data source categories, see "Data Source Categories" on page 28.
27
How Do Data Sources Work?

Data sources provide an abstract layer between Netcool/Impact and real-world source of data. Internally, data sources provide connection and other information that Netcool/Impact uses to access the data.
What Do I Do With Data Sources?

When you create a Netcool/Impact data model, you must create one data source for every real-world source of data you want to access in a policy.
How Do I Set Up Data Sources?

You create data sources using the Netcool/Impact GUI. For more information, see "Setting Up Data Sources" on page 30.
Data Source Categories

Netcool/Impact provides the following categories of data sources: SQL database data sources LDAP data sources Mediator data sources
SQL Database Data Sources

SQL database data sources represent relational databases. Netcool/Impact supports most of the popular commercial relational databases, such as Oracle, Sybase and Microsoft SQL Server. In addition, it also supports freely-available databases like MySQL and PostgreSQL. The Netcool/OMNIbus ObjectServer is also supported as a SQL data source. For a complete list of supported data sources, see your Micromuse account manager.
LDAP Data Sources

LDAP data source represent LDAP directory servers. Netcool/Impact supporters the Netscape, iPlanet and OpenLDAP servers.
Mediator Data Sources

Mediator data sources represent third-party applications that are integrated with Netcool/Impact via the DSA Mediator. These data sources include a wide variety of network inventory, network provisioning and messaging system software. In addition, providers of XML and SNMP data can also be used as mediator data sources. For a complete list of supported data source, see your Micromuse account manager.
28
Internal Data Repository

The internal data repository is a built-in data source for Netcool/Impact. The primary responsibility of the internal data repository is to store system data. However, you can also use it to store the data in predefined and user-defined internal data types.
Data Source Architecture

The following diagram shows the relationship between Netcool/Impact, data sources and the real-world source of data in your environment.
Netcool/Impact SQL Database Data Source SQL Database Data Source Mediator Data Source LDAP Data Source
DSA
DSA
DSA
SQL Database
Network Inventory Manager or Other Third-Party Application
LDAP Server
Figure 2. Data Source Architecture
29
Setting Up Data Sources

When you create a Netcool/Impact data model, you must set up a data source for each real-world source of data in your environment. You set up data sources using the Netcool/Impact GUI. To set up a data source, you do the following: Get the connection information for the data source Use the Netcool/Impact GUI to create and configure the data source
Getting the Connection Information

Before you create a new event source, you must get the connection information for the underlying application. The connection information you need varies depending on the type of event source. For most SQL database data sources, this information is the hostname and the port where the application is running, and a valid username and password. For LDAP and Mediator data sources, see the Netcool/Impact DSA Reference Guide for the connection information required.
Creating the Data Source

Once you have the connection information for the underlying application, you can create the data source using the Netcool/Impact GUI. The following table shows the configuration properties for an SQL database data source.
Table 2. Data Source Configuration Properties Property Data Source Name Username Password Primary Source Hostname Primary Port Backup Hostname Backup Port Description Unique name for the data source. Valid username for the data source. Valid password for the data source. Hostname or IP address of the system where the data source is located. Port used by the data source. Default port is 4100. Hostname or IP address of the system where the backup data source is located. Optional. Port used by the backup data source. Optional. Default port is 4100.
30
To create the data source: 1. 2. Log into the Netcool/Impact GUI. Select a project from the Projects list.
Figure 3. Projects List
3.
Open the Data Sources tab and select the category of data source from the Sources list. The Data Source Editor window appears.
Figure 4. Data Source Editor Window
4. 5.
Enter the required configuration properties. Click OK.
31
32
05_Working_With_Data_Types.fm November 30, 2006
Chapter 5. Working with Data Types

This chapter contains information about working with Netcool/Impact data types. It contains the following sections: "About Data Types" on page 33 "Data Type Categories" on page 34 "Data Type Fields" on page 36 "Data Type Keys" on page 38 "Setting Up Data Types" on page 38 "Data Type Caching" on page 48
About Data Types

This section contains general information about data type. It contains the following topics: What Are Data Types? What Are the Data Type Categories? How Do Data Types Work? How Do I Use Data Types? How Do I Set Up Data Type?
What Are Data Types?

Data types are an element of the Netcool/Impact data model that represent sets of data stored in a data source. The structure of this data depends on the category of the data source where it is stored. For example, if the data source is an SQL database, each data type corresponds to a database table. If the data source is an LDAP server, each data type corresponds to a type of node in the LDAP hierarchy. A data type definition contains the following information: The name of the underlying table or other structural element in the data source A list of fields that represent columns in the underlying table or another structural element (for example, a type of attribute in an LDAP node) Settings that define how Netcool/Impact caches data in the data type
33
What Are the Data Type Categories?

Netcool/Impact supports the following categories of data types: SQL database data types LDAP data types Mediator data types Internal data types
For more information, see "Data Type Categories" on page 34.
How Do Data Types Work?

Data types provide an abstract layer between Netcool/Impact and the associated set of data in a data source. Netcool/Impact uses data types to locate the data you want to use in a policy.
How Do I Use Data Types

You must create one data type for each table or other data structure in your data source that contains information you want to use in a policy.
How Do I Set Up Data Types?

You set up data types using the Netcool/Impact GUI. For more information, see "Setting Up Data Types" on page 38.
Data Type Categories

Netcool/Impact supports the following categories of data types: SQL database data types LDAP data types Mediator data types Internal data types
SQL Database Data Types

SQL database data types represent data stored in a database table. Each data item in an SQL database data type corresponds to a row in the table and each field in the data item corresponds to a column. An SQL database data type can include all of the columns in a table or just a subset of the columns.
34
LDAP Data Types

LDAP data types represent data stored at a certain base context level of an LDAP hierarchy. Each data item in an LDAP data type corresponds to an LDAP node that exists at that level and each field corresponds to an LDAP attribute. LDAP data types are read-only. This means that you cannot add, update or delete data items in an LDAP data type.
Mediator Data Types

Mediator data types represent data that is managed by third-party applications such as a network inventory manager or a messaging service. Typically, Mediator data types do not represent data stored in database tables. Instead, they represent collections of data that are stored and provided by the data source in various other formats, such as sets of data objects, or as messages.
Internal Data Types

Netcool/Impact provides the following categories of internal data types: System data types Pre-defined internal data types User-defined internal data types
System Data Types

System data types are used to stored and manage data used internally by Netcool/Impact. These types include Policy, Service and Hibernation. In most cases, you do not directly access the data in these data types. However, there are some occasions in which you can use them in a policy. Some examples are when you start a policy from within another policy or work with hibernating policies.
Pre-Defined Internal Data Types

Netcool/Impact provides the following pre-defined internal data types: Schedule TimeRangeGroup Doc
You use Schedule and TimeRangeGroup data types to manage Netcool/Impact scheduling. You can use the Doc data type to store information about URLs located on your intranet.
35
User-Defined Internal Data Types

User-defined internal data types are internal data types that you create. The data items in these data types are stored in the Netcool/Impact internal data repository, rather than in an external data source. User-defined data types function in much the same way as SQL database data types. Micromuse recommends that you use internal data types solely for testing and demonstrating Netcool/Impact, or for very low-load tasks. User-defined internal data types are slower than external SQL database data types.
Data Type Fields

A field is a unit of data as defined within a data type. The nature of this unit of data depends on the category of the data type that contains it. If the data type corresponds to a table in an SQL database, each field corresponds to a table column. If the data type corresponds to a base context in an LDAP server, each field corresponds to a type of LDAP attribute. When you set up an SQL database data type, the fields are auto-populated from the underlying table by Netcool/Impact. For other data types, you must manually define the fields when the data type is created. Fields have the following attributes: ID Actual name Display name Description Format
ID
The ID attribute specifies the internal name used by Netcool/Impact to refer to the field. By default, the field ID is the same as the name of the data element that corresponds to the field in the underlying data source. For example, if the data type is an SQL database data type, the underlying field corresponds to a column in the table. By default, the field ID is the same as the column name in the database. You can change the field ID to any other unique name. For example, if the underlying column names in the data source are not human-readable, or are difficult to type and remember, you can use the ID field to provide a more easy-to-use alias for the field. The field ID overrides the actual name and display name attributes for the field in all cases.
36
Actual Name
The actual name attribute is the name of the corresponding data element in the underlying data source as described in the section above. Although the Netcool/Impact GUI allows you to freely edit this field, it must be identical to how it appears in the data source in order to work. Otherwise, Netcool/Impact will report an error when trying to access the data type.
Display Name
The display name attribute allows you to specify a label for the field that is displayed only when you browse data items using the Netcool/Impact GUI. This attribute does not otherwise have an effect on the functionality of the data type.
Description
The description attribute allows you to specify a short description for the field. This description is only visible when you edit the data type using the Netcool/Impact GUI. Like the display name, it does not otherwise have an effect on the functionality of the data type.
Format
The format is the data format of the field. For SQL database data types, Netcool/Impact auto-discovers the columns in the underlying table and automatically deduces the data format for each field when you set up the data type. For other data types, you must manually specify the format for each field that you create. The following table shows the Netcool/Impact data formats:
Table 3. Netcool/Impact Data Formats (1 of 2) Format String Integer Long Float Double Date Boolean Clob Description Represents text strings up to 4 KB in length. Represents whole numbers. Represents long whole numbers. Represents floating point decimal numbers. Represents double-precision floating point decimal numbers. Represents formatted date/time strings. Represents boolean values of true and false. Represents large-format binary data.
37
Table 3. Netcool/Impact Data Formats (2 of 2) Format Long_String Password String Description Represents text strings up to 16 KB in length (internal data types only). Represents password strings (internal data types only). The password appears in the Netcool/Impact GUI as a string of asterisks, rather than the actual password text.
Data Type Keys

Key fields are fields whose value or combination of values can be used to identify unique data items in a data type. For SQL database data types, you must specify at least one key field for each data type you create. Most often, the key field that you specify is a key field in the underlying data source. Internal data items contain a default field named KEY that is automatically used as the data type key. The Netcool/Impact policy language provides a function called GetByKey that allows you to retrieve data from the data type using the key field value as a query condition. Keys are also used when you create GetByKey dynamic links between data types.
Setting Up Data Types

When you create a Netcool/Impact data model, you must set up a data type for each structural element in a data source whose data you want to use. For example, if you are using an SQL database data source, you must set up a data type for each table that contains the data. If you are using an LDAP data source, you must set up a data type for each base context in the LDAP hierarchy that contains nodes that you want to access. You set up data types using the Netcool/Impact GUI. To set up a data type, you do the following: Get the name of the structural element (for example, the table) where the data is located Use the Netcool/Impact GUI to create and configure the data type
Getting the Name of the Structural Element

If the data type is an SQL database data type, you must know the fully-qualified name of the underlying table in the database before you can set it up. This name consists of the database name and the table name. Some databases use case-sensitive table names, so make sure that you record the proper case when you get this information. If the data type is an LDAP data type, you must know the name of the base context level of the LDAP hierarchy where the nodes you want to access are located.
38
Creating an Internal Data Type

You create user-defined internal data types using the Netcool/Impact GUI. To create this type of internal data type, you do the following: Provide a unique name for the data type Browse the graphic library and select and icon for the data type Create a set of data type fields and assign their attribute values Select a display name for the data type
The display name is the name of the data type field that is displayed when you browse data items in the data type using the Netcool/Impact GUI. To create a user-defined internal data type: 1. 2. In the Netcool/Impact GUI, open the Data Types task pane in the Navigation panel. Select Internal from the Data Sources list and click the New Data Type button. A new Data Type Editor tab appears in the Main Work panel.
Figure 5. Data Type Editor - Internal Data Type
3. 4.
Enter a unique name for the data type in the Data Type Name field. Click the Browse button and select an icon for the data type from the dialog that opens.
39
5.
For each field you want to create in the data type, do the following: Click the New Field button. The New Field window opens. You use this window to define the attributes for the data type fields.
Figure 6. New Field Window - Internal Data Type
Enter a unique ID in the ID field. Select the data format for the field from the Format list. The other fields in this dialog box are optional. For fields in internal data types, the actual name and display name should always be the same as the field ID. If you leave these fields empty, Netcool/Impact populates them automatically with the ID value. Click OK. 6. 7. Specify a key field in the list of fields located in the Table Description area of the Data Type Editor. You must specify at least one key field. In the Data Type Editor, select a display name from the Display Name field. This display name appears when you browse data items in the data type using the Netcool/Impact GUI. It does not otherwise effect the behavior of the data type.
40
8.
Click the Save button in the Data Type Editor.
Figure 7. Data Type Editor - Save Button
The new name of the data type appears in the Data Type Editor tab.
Figure 8. Data Type Editor Tab
9.
Close the Data Type Editor.
After you create the internal data type, you must manually populate it with data you need using the Netcool/Impact GUI. For more information, see the Netcool/Impact User Interface Guide. You can also use static and dynamic links to create relationships between the internal data type and other data types in the data model. For more information, see Chapter 6. "Working with Links" on page 53.
Creating an SQL Database Data Type

You create SQL database data types using the Netcool/Impact GUI. To create an SQL database data type, you do the following: Provide a unique name for the data type Specify the name of the underlying data source for the data type Browse the graphic library and select an icon for the data type Specify the name database and table where the underlying data is stored Auto-populate the fields in the data type Select a display name for the data type Specify key fields for the data type Specify a data item filter (optional) Specify which field in the data type to use to order data items (optional) Specify the direction to use when ordering data items (optional)
41
Getting Started
To start creating an SQL database data type: 1. 2. In the Netcool/Impact GUI, open the Data Types task pane in the Navigation panel. Select the underlying data source from the Data Sources list and click the New Data Type button. A new Data Type Editor tab appears in the Main Work panel. The Data Type Editor displays the name of the data source as a temporary name for the data type.
Figure 9. Data Type Editor - General Settings
3. 4. 5.
Enter a unique name for the data type in the Data Type Name field. Enter the name of the underlying data source in the Data Source Name field. Click the Browse button and select an icon for the data type from the dialog that opens.
Specifying the Database and Table

The next step is to specify the underlying database and table where the data in the data type is stored. Netcool/Impact automatically retrieves the names of all of the databases and tables from the data source so that you can choose them from a list.
42
To specify the database and table: 1. In the Data Type Editor, scroll down so that the Table Description area is visible.
Figure 10. Data Type Editor - Table Description
2.
Enter the name of the database and the table in the Base Table lists. The first list contains the databases in the data source. The second list contains the tables in the selected database.
Auto-Populating the Data Type fields

After you have specified the name of the database and table, the next step is to auto-populate the data type fields. You can also specify the fields manually in the same way that you do for internal data types, but in most cases, using the auto-populate feature saves time and ensures that the field names are accurate. When you auto-populate data type fields, Netcool/Impact retrieves the table description from the underlying data source and creates a new field in the data type for each column in the table. The ID, actual name and display name for the fields are defined using the exact column name as it appears in the table. Netcool/Impact uses a set of built-in rules to determine the data format for each of the auto-populated fields. Columns in the database that contain text data, such as varchar, are represented as string fields. Columns that contain whole numbers, such as int and integer, are represented as integer fields. Columns that contain decimal numbers are represented as float fields. Generally, you can allow Netcool/Impact to automatically assign the formats for data type fields without having to manually attempt to recreate the database data formats in the data type. If you only want a subset of the fields in a table to be represented in the Netcool/Impact data type, you can manually remove the unwanted fields after auto-population. Removing unwanted fields can speed the performance of a data type. To auto-populate data type fields, you click the Refresh button in the Table Description area of the Data Type Editor.
43
Netcool/Impact retrieves the table description from the data source and populates the fields. The fields are displayed in the Table Description area.
After you auto-populate the data type fields, you can manually change the attributes of any field definition. Do not change the value of the actual name attribute. If you change this value, Netcool/Impact will report errors when you try to retrieve data from the data type.
Setting the Display Name

The display name is the field that you want to use to label data items when you browse them using the Netcool/Impact GUI. Generally, you choose a field that contains a unique value that can be used to identify the data item. The display name does not otherwise affect the behavior of the data type. To set the display name, you choose the name of the field from the Display Name Field list in the Table Description area of the Data Type Editor.
Specifying Key Fields

Netcool/Impact requires you to set at least one key field for the data type. Key fields are used when you retrieve data from the data type in a policy using the GetByKey function. They are also used when you define a GetByKey dynamic link. You must define at least one key field, even if you do not intend to use the GetByKey functionality in your policy. Generally, the key fields you define correspond to key fields in the underlying database table. To specify key fields, check the Key option for the desired field in the Table Description area of the Data Type Editor.
44
Specifying a Data Item Filter

The data item filter specifies which rows in the underlying database table can be accessed as data items in the data type. This filter is an optional setting. The syntax for the data item filter is the same as the contents of the WHERE clause in the SQL SELECT statement supported by the underlying database. For example, if you want to specify that only rows where the Location field is New York should be accessible via this data type, you can use the following data item filter:
Location = New York
If you want to specify that only rows where the Location is either New York or New Jersey, you can use the following:
Location = New York OR Location = New Jersey
Make sure that you enclose any strings in single quotation marks. To specify the data item filter, enter the filter string in the Filter text box in the Data Item Filter and Ordering area of the Data Type Editor.
Figure 12. Data Type Editor = Data Item Filtering and Ordering
Specifying Data Item Ordering

Data item ordering defines the order in which Netcool/Impact retrieves data items from the data type. The order settings are used both when you retrieve data items using the GetByFilter function in a policy and when you browse data items using the Netcool/Impact GUI. You can order data items in ascending or descending alphanumeric order by any data type field. Data item ordering is an optional part of the data type configuration. To specify data item ordering: 1. 2. 3. In the Data Type Editor, scroll down so that the Data Filtering and Ordering area is visible. Select the field that you want to order by from the Order By Field list. Select Ascending or Descending from the Sort Direction list.
45
Saving the Data Type

To save the data type, you click the save button in the Data Type Editor tab.
The data type name appears in the Data Type Editor tab after when you save.
After you have saved the data type, you can close the Data Type Editor or you can continue on to configuring caching and dynamic links for the data type. For more information on caching see "Data Type Caching" on page 48. For more information on dynamic links, see Chapter 6. "Working with Links" on page 53.
Creating an LDAP Data Type

You create LDAP data types using the Netcool/Impact GUI. To create an LDAP database data type, you do the following: Provide a unique name for the data type Specify the name of the underlying data source for the data type Browse the graphic library and select and icon for the data type Specify the base context level in the LDAP hierarchy where the elements you want to access are located Specify a display name field Specify a restriction filter (optional)
46
To create an LDAP data type: 1. 2. In the Netcool/Impact GUI, open the Data Types task pane in the Navigation panel. Select the underlying data source from the Data Sources list and click the New Data Type button. A new Data Type Editor tab appears in the Main Work panel. The Data Type Editor displays the name of the data source as a temporary name for the data type.
Figure 15. Data Type Editor - LDAP Data Type
3. 4. 5. 6.
Enter a unique name for the data type in the Data Type Name field. Enter the name of the underlying data source in the Data Source Name field. Click the Browse button and select an icon for the data type from the dialog that opens. Enter the base context for the data type in the Base Context field in the General Settings area of the Data Type Editor. An example of a base context is the following: ou=people, o=micromuse.com. Enter the display name field for the data type in the Display Name Field text field. The display name is the name of the data type field that is displayed when you browse data items in the data type using the Netcool/Impact GUI. Optionally, enter a restriction clause in the Restriction Clause field. The restriction clause is an LDAP search filter as defined in Internet RFC 2254. For a description of LDAP search filter syntax, see the Netcool/Impact Policy Reference Guide.
7.
8.
47
9.
Click the Save button in the Data Type Editor tab.
The new name of the data type appears in the Data Type Editor tab.
10. Close the Data Type Editor.
Creating a Mediator Data Type

Mediator data types are a special category of data type. These data types are typically created using scripts or other tools provided by the corresponding DSA. For more information about the Mediator data types used with a particular DSA, see the DSA documentation.
Data Type Caching

Data type caching is a feature that allows you to temporarily store data items that have been retrieved from a data source. These data items are stored internally in Netcool/Impact. You can use data type caching to reduce performance load on data sources when the underlying data does not change often, or to reduce the total number of queries that Netcool/Impact makes against a data source for performance or other reasons. Data type caching works with SQL database and LDAP data types. Internal data types do not require data type caching. You configure caching on a per data type basis within the Netcool/Impact GUI. Netcool/Impact allows you to control the following aspects of data type caching: Data caching Count caching Query caching
48
Data Caching
Data caching is when Netcool/Impact temporarily stores individual data items retrieved from a data source. You can configure the following data caching properties using the Netcool/Impact GUI: Maximum number of data items to cache Expiration time for data items in the cache
Netcool/Impact calculates the expiration time for separately each data item in the cache. You must enable data caching for any other type of caching to work. To configure data caching: 1. 2. In the Netcool/Impact GUI, open the Data Type Editor for the data type whose caching you want to configure. Select the Cache Settings tab in the Data Type Editor. The Cache Settings area appears in the Data Type Editor.
Figure 18. Data Type Editor - Cache Settings
3. 4. 5.
Select the Enable Data Caching checkbox. Enter a number in the Maximum Number of Data Items field. Enter the amount of time to cache each data item in the Invalidate Cached Items After fields.
49
6.
7.
Query Caching
Query caching is when Netcool/Impact temporarily stores sets of data items retrieved during individual queries to a data source. You can configure the following query caching properties using the Netcool/Impact GUI: Maximum number of queries to cache Expiration time for query results in the cache
Netcool/Impact calculates the expiration time separately for each query in the cache. You must also enable data caching for query caching to work. To configure query caching: 1. 2. 3. In the Netcool/Impact GUI, open the Data Type Editor for the data type whose caching you want to configure. Select the Cache Settings tab in the Data Type Editor. The Cache Settings area appears in the Data Type Editor. Scroll down until the Enable Query Caching area is visible.
4. 5.
Select the Enable Query Caching checkbox. Enter a number in the Maximum Number of Queries field.
50
6. 7.
Enter the amount of time to cache each data item in the Invalidate Cached Queries After fields. Click the Save button in the Data Type Editor tab.
8.
Count Caching
Count caching is when Netcool/Impact temporarily stores the count values obtained in a policy using the GetByFilter function with the CountOnly parameter set to True. You can configure the expiration time for items counted using this feature. To configure count caching: 1. 2. 3. In the Netcool/Impact GUI, open the Data Type Editor for the data type whose caching you want to configure. Select the Cache Settings tab in the Data Type Editor. The Cache Settings area appears in the Data Type Editor. Scroll down until the Enable Count Caching area is visible.
4. 5.
Select the Enable Count Caching checkbox. Enter the amount of time to cache query counts in the Invalidate Cached Count After fields.
51
6.
7.
52
06_Working_With_Links.fm November 30, 2006
Chapter 6. Working with Links

This chapter contains information about working with Netcool/Impact links. It contains the following sections: "About Links" on page 53 "Link Categories" on page 54 "Setting Up Links" on page 56
About Links
This section contains overview information about links. It contains the following topics: What Are Links? What Are the Links Categories? How Do Links Work? What Do I Do With Links? How Do I Set Up Links?
What Are Links?

Links are an element of the Netcool/Impact data model that allow you to specify relationships between data items and between data types. Links are an optional part of a data model. They can save time during the development of policies because they allow you to define a data relationship once and then re-use it several times when you need to find data related to other data in a policy.
What Are the Links Categories?

Netcool/Impact provides the following categories of links: Static links Dynamic links
53
What Do I Do with Links?

You set up links after you have created the data types required by your solution and after you have populated any internal data types in the model with the information you need. When you write policies, you use the GetByLinks function to traverse the links and retrieve data items that are linked to other data items.
How Do I Set Up Links?

You can view, create, edit and delete static and dynamic links using the Netcool/Impact GUI.
Link Categories
Netcool/Impact provides the following categories of links: Static links Dynamic links
Static Links
Static links define a relationship between data items in internal data types. Static links are not supported for other categories of data types, such as SQL database and LDAP types, because there is no way for Netcool/Impact to ensure the persistence of data items that are stored externally.
Dynamic Links
Dynamic links define a relationship between data types. This relationship is specified when you create the link and is evaluated in real time when Netcool/Impact encounters a call to the GetByLinks function in a policy. Dynamic links are supported for internal, SQL database and LDAP data types. Netcool/Impact supports the following types of dynamic links: Link by Filter Link by Key Link By Policy
54
Link By Filter
A link by filter is a type of dynamic link where the relationship between two data types is specified using the link filter syntax. The link filter syntax is as follows:
target_field = %source_field% [AND (target_field = %source_field%) ...]
where target_field is the name of a field in the target data type and source_field is the name of the field in the source data type. When you call the GetByLinks function in a policy, Netcool/Impact evaluates the data items in the target data type and returns those items whose target_field value is equal to the specified source_field. If the value of source_field is a string, you must enclose it in single quotation marks. The following are examples of valid link filters:
Location = %Name% (NodeID = %ID%) AND (Location = %Name%)
Link By Key
A link by key is a type of dynamic link where the relationship between two data types is specified by a foreign key expression. The foreign key expression is the value that the key field in data items in the target data type must have in order to be considered linked to the source. The syntax of the foreign key expression is the name or names of fields in the source data type whose value must equal the key field in the target. You can concatenate fields using the addition (+) operator. When you call the GetByLinks function in a policy, Netcool/Impact evaluates the data items in the target data type and returns those whose key field values match the specified key expression. The following are examples of valid key expressions:
LastName FirstName + " " + LastName LastName + ", " + FirstName
Link By Policy
A link by policy is a type of dynamic link where the relationship between two data types is specified by a policy. The policy contains the logic that Netcool/Impact uses to retrieve data items from the target data type. The linking policy specifies which data items to return by setting the value of the DataItems variable.
55
Setting Up Links
This section describes how to set up static and dynamic links.
Setting Up Static Links

To set up a static link: 1. 2. In the Netcool/Impact GUI, open the Data Types task pane in the Navigation panel. Click the name of the internal data type that contains the source data items you want to link.
Figure 24. Data Types Task Pane
A Data Type Editor tab appears in the Main Work panel.
Figure 25. Data Type Editor
3. 4. 5.
Click the Links button for the data item you want to link. In the Static Links window that opens, select the data type that contains the data items you want to link to. Select the data item to link to from the list of data items that appears.
56
Setting Up Dynamic Links

You can set up the following categories of dynamic links: Link by Filter Link by Key Link By Policy
Setting Up a Dynamic Link By Filter

To set up a dynamic link by filter: 1. 2. In the Netcool/Impact GUI, open the Data Types task pane in the Navigation panel. Click the name of the data type you want to use as the source for the link.
A Data Type Editor tab appears in the Main Work panel. 3. Select the Dynamic Links tab in the Data Type Editor.
Figure 27. Data Type Editor - Dynamic Links
57
4.
Click the New Link By Filter button. The Link By Filter window appears.
Figure 28. Link By Filter Window
5. 6. 7.
Select the target data type from the Target Data Types list. Enter the filter syntax for the link in the Filter into Target Data Type field. Click OK.
58
Setting Up a Dynamic Link By Key

To set up a dynamic link by filter: 1. 2. In the Netcool/Impact GUI, open the Data Types task pane in the Navigation panel. Click the name of the data type you want to use as the source for the link.
A Data Type Editor tab appears in the Main Work panel. 3. Select the Dynamic Links tab in the Data Type Editor.
59
4.
Click the New Link By Key button. The Link By Key window appears.
Figure 31. Link By Key Window
5. 6. 7.
Select the target data type from the Target Data Type field. Enter the key expression in the Foreign Key Expression field. Click OK.
Setting Up a Dynamic Link By Policy

To set up a dynamic link by policy: 1. 2. In the Netcool/Impact GUI, open the Data Types task pane in the Navigation panel. Click the name of the data type you want to use as the source for the link.
A Data Type Editor tab appears in the Main Work panel.

3. 4.
Select the Dynamic Links tab in the Data Type Editor. Scroll down so that the Link By Policy area is visible.
5.
Click the New Link By Policy button. The Link By Policy window appears.
Figure 34. Link By Policy Window
6. 7. 8.
Select the target data type from the Target Data Type list. Select the linking policy from the Policy To Execute to Find Links list. Click OK.
61
62
07_Working_With_Event_Sources.fm November 30, 2006
Chapter 7. Working with Event Sources

This chapter contains information about working with Netcool/Impact event sources. It contains the following sections: "About Event Sources" on page 63 "Event Source Types" on page 64 "Event Source Architecture" on page 66 "Setting Up Event Sources" on page 66
About Event Sources

This section contains overview information about event sources. It contains the following topics: What Are Events? What Are Event Sources? What Are the Event Source Types? How Do I Use Event Sources? How Do I Set Up Event Sources? How Do I Manage Event Sources?
What Are Events?

An event is a set of data that represents a status or an activity on a network. The structure and content of the data varies depending on the device, system or application that generated it. In most cases, events handled by Netcool/Impact are Netcool/OMNIbus alerts. These events are generated by Netcool probes and monitors and are stored in the ObjectServer database.
What Are Event Sources?

An event source is a special type of data source. Each event source represents an application that stores and manages events. The most common such application is the ObjectServer database. Netcool/Impact also allows you to use other applications as event sources. For a current list of applications that you can use as event sources, see your Micromuse account representative.
63
What are the Event Source Types?

Netcool/Impact supports two types of event sources: ObjectServer event sources and non-ObjectServer event sources. See "Event Source Types" on page 64 for more information.
How Do I Use Event Sources?

When you design your Netcool/Impact solution, you must create one event source for each application that you want to monitor for events. Then you can create event reader or event listener services and associate them with the event source. Typically, a Netcool/Impact solution uses a single event source. This event source is most often an ObjectServer database.
How Do I Set Up Event Sources?

When you install Netcool/Impact, the installer automatically creates a default ObjectServer event source named DefaultObjectServer. This event source is configured using information you provide to the installer during installation. You can create other event sources using the Netcool/Impact GUI. See "Setting Up Event Sources" on page 66 for more information.
How Do I Manage Event Sources?

After you have set an event source, you do not need to actively manage it unless you change the solution design. If necessary, you can use the Netcool/Impact GUI to modify or delete event sources.
Event Source Types

Netcool/Impact provides the following types of event sources: ObjectServer event sources Non-ObjectServer event sources
ObjectServer Event Sources

ObjectServer event sources represent instances of the Netcool/OMNIbus ObjectServer database. These are the most common type of event source. ObjectServer event are alerts stored in the alerts.status table of the database. These alerts have a predefined set of alert fields that can be supplemented by additional fields that you define. Netcool/Impact monitors ObjectServer event sources using an event reader service. The event reader service queries the ObjectServer at intervals and retrieves any new, updated and/or deleted events that matches its pre-defined filter conditions. The event reader then passes each event to the Netcool/Impact policy engine for processing.
64
Non-ObjectServer Event Sources

Non-ObjectServer event sources represent instances of other applications, such as external databases or messaging systems, that provide events to Netcool/Impact. Non-ObjectServer events can take a wide variety of forms, depending on the nature of the event source. For SQL database event sources, an event might be the contents of a row in a table. For a messaging system event source, an event might be the contents of a message. Netcool/Impact monitors non-ObjectServer event sources using an event listener service. The event listener service passively receives events from the event source and then passes them to the policy engine for processing.
65
Event Source Architecture

The following diagram shows how event sources interact with Netcool/Impact event sources and event listeners and with their underlying event management applications.
Netcool/Impact
Event Reader
Event Listener
ObjectServer Event Source
Non-ObjectServer Event Source
ObjectServer
Figure 35. Event Source Architecture
Other Event Management Applications
Setting Up Event Sources

This section contains information on setting up event sources.
66
It contains the following topics: Setting Up ObjectServer Event Sources Setting Up Non-ObjectServer Event Sources
Setting Up ObjectServer Event Sources

You set up ObjectServer event sources in the same way that you set up any other type of data source. To set up an ObjectServer event source, you do the following: Get the connection information for the ObjectServer Use the Netcool/Impact GUI to create and configure the event source
Getting Connection Information

Before you create a new event source, you must get the connection information for the underlying application. For ObjectServer event sources, this information is the hostname or IP address of the ObjectServer host system and the port number. The default port number for the ObjectServer is 4001.
Creating the Event Source

Once you have the connection information for the ObjectServer, you can create the event source using the Netcool/Impact GUI. You create the event source in the same way that you create any other data source. The following table shows the configuration properties for an event source.
Table 4. Event Source Configuration Properties Property Data Source Name Username Password Primary Source Hostname Primary Port Backup Hostname Backup Port Description Unique name for the event source. Valid username for the event source. Valid password for the event source. Hostname or IP address of the system where the event source is located. Port used by the event source. Default port is 4100. Hostname or IP address of the system where the backup event source is located. Optional. Port used by the backup event source. Optional. Default port is 4100.
67
To create the event source: 1. 2. Log into the Netcool/Impact GUI. Select a project from the Projects list.
Figure 36. Projects List
3.
Open the Data Sources tab and select the category of data source from the Sources list. The Data Source Editor window appears.
Figure 37. Data Source Editor Window
4. 5.
Enter the required configuration properties. Click OK.
After you have created the event source, you can then create and configure an associated event reader service. For more information, see "Setting Up Event Readers" on page 83.
68
Setting Up Non-ObjectServer Event Sources

For information on setting up non-ObjectServer event sources, see the corresponding DSA documentation. After you have created the event source, you can then create and configure an associated event listener service. For more information, see "Setting Up Event Listeners" on page 93.
69
70
08_Services.fm November 30, 2006
Chapter 8. Services
This chapter contains overview information about Netcool/Impact services. It contains the following sections: "Introduction" on page 71 "How Do I Use This Part of the Guide?" on page 71 "About Services" on page 72 "Service Types" on page 73 "Setting Up Services" on page 75
Introduction
This is the beginning of Part Three of this guide. Part Three provides information about Netcool/Impact services. This part of the guide contains the following chapters: Chapter 8. "Services" on page 71. This chapter contains general information on Netcool/Impact services. Chapter 9. "Working with Event Readers" on page 77. This chapter contains instructions on setting up event readers. Chapter 10. "Working with Event Listeners" on page 89. This chapter contains instructions on setting up event listeners. Chapter 12. "Working with Policy Activators" on page 121. This chapter contains instructions on setting up policy activators. Chapter 13. "Working with Other Services" on page 125. This chapter contains instructions on setting up the e-mail sender, policy logger and other basic services.

If you are new to working with Netcool/Impact services, you should read the chapters in this part of the guide in order, paying special attention to conceptual and overview information. Because you must master a variety of concepts and procedures before you can set up your own services, you should review any information that you do not understand before progressing to the next part of this book.
Chapter 8. Services
71
If you are an experienced Netcool/Impact user, or you are upgrading an installation from a previous version of Netcool/Impact for the first time, you should first read Chapter 9. "Working with Event Readers" on page 77. Then you can read any of the following chapters as needed in order to review information that you already know, or learn how to upgrade your existing services so that they are compatible with this version of the product. Once you have a firm understanding of Netcool/Impact services, you can go on to Chapter 14. "Policy Fundamentals" on page 133 of this guide, which contains instructions on writing Netcool/Impact policies.
About Services
This section contains overview information about Netcool/Impact services. It contains the following topics: What Are Services? What Are the Service Types? How Do Services Work? What Do I Do With Services? How Do I Set Up Services? How Do I Manage Services?
What Are Services?

Services are runnable sub-components that you control from within Netcool/Impact. Services perform much of the functionality associated with the Netcool/Impact server, including monitoring event sources, sending and receiving e-mail, and triggering policies.
What Are the Service Types?

Netcool/Impact provides the following services: Event readers Event listeners E-mail readers E-mail sender Policy activators Hibernating policy activator Event processor Policy logger Command line manager service CORBA name service
72
For more information, see "Service Types" on page 73.
What Do I Do with Services?

Generally, you set up services once, when you first design your Netcool/Impact solution. After that, you do not need to actively manage the services unless you change the solution design.
How Do I Set Up Services?

To set up services, you must first determine what service functionality you need to use in your solution. Then, you create and configure the required services using the Netcool/Impact GUI. After you have set up the services, you can use the Netcool/Impact to start and stop them, and to manage the service logs. For more information, see "Setting Up Services" on page 75.
Service Types
Netcool/Impact provides the following services: Event readers Event listeners E-mail readers E-mail sender Policy activators Hibernating policy activator Event processor Policy logger Command line manager service CORBA name service
Event Readers
Event readers are services that monitor a Netcool/OMNIbus ObjectServer event source. When an event reader discovers a new, updated and/or deleted alerts in the ObjectServer, it retrieves the alert and sends it to an event queue, where it waits to be handled by the event processor. Event readers are the most important Netcool/Impact service. For more information, see Chapter 9. "Working with Event Readers" on page 77.
Chapter 8. Services
73
Event Listeners
Event listeners are services that monitor a non-ObjectServer event source. As with event readers, when they discover a new, updated and/or deleted event in the event source, they retrieve the event and send it in the event queue, where it waits to be handled by the event processor. Event listeners typically work with specially-configured DSAs, such as the JMS DSA, that allow bi-directional access to a source of data. For more information, see Chapter 10. "Working with Event Listeners" on page 89.
E-Mail Sender
The e-mail sender is a service that sends e-mail via an external SMTP service. For more information, see Chapter 13. "Working with Other Services" on page 125.
Policy Activators
Policy activators are services that run policies at timed intervals. For more information, see Chapter 12. "Working with Policy Activators" on page 121.
Hibernating Policy Activator

The hibernating policy activator is a service that is responsible for waking hibernations at timed intervals. You use the hibernating policy activator with X events in Y time solutions and similar solutions that require the use of hibernating policies. For more information, see Chapter 13. "Working with Other Services" on page 125.
Event Processor
The event processor is the service responsible for managing events coming into Netcool/Impact via event reader, event listener and e-mail reader services. The event processor manages the incoming event queue and is responsible for sending queued events to the policy engine for processing.
Policy Logger
The policy logger is the service responsible for managing the policy log. The policy log is a text stream used by Netcool/Impact to record messages during the runtime of a policy. The policy log contains both system messages issued by Netcool/Impact and messages that you define in a policy. For more information, see Chapter 13. "Working with Other Services" on page 125.
Command Line Manager Service

The command line manager is the service that manages the Netcool/Impact CLI. For more information, see Chapter 13. "Working with Other Services" on page 125.
74
CORBA Name Service

The CORBA name service is the service that manages the CORBA interface used by some Mediator DSAs. For more information, see Chapter 13. "Working with Other Services" on page 125.
Setting Up Services
To set up services, you do the following: Configure pre-defined services like the event processor, e-mail sender and/or CORBA name service Create and configure user-defined services like event readers, event listeners and e-mail readers
Configuring Pre-Defined Services

Pre-defined services are services that are created automatically when you install Netcool/Impact. You can configure pre-defined services, but you cannot create new instances of the pre-defined services and you cannot delete existing ones. The following Netcool/Impact services are pre-defined: Event processor E-mail sender Hibernating policy activator Policy logger Command line manager
Creating and Configuring User-Defined Services

User-defined services are services that you can create, modify and delete. You can also use the default instance of these services that Netcool/Impact creates automatically at installation. The following Netcool/Impact services are user-defined: Event readers Event listeners E-mail readers Policy activators
Chapter 8. Services
75
76
09_Working_With_Event_Readers.fm November 30, 2006
Chapter 9. Working with Event Readers

This chapter contains information about working with Netcool/Impact event readers. It contains the following sections: "About Event Readers" on page 77 "Event Reader Architecture" on page 79 "How Event Readers Work" on page 79 "Event Reader Configuration" on page 81 "Setting Up Event Readers" on page 83
About Event Readers

This section contains overview information about event readers. It contains the following topics: What Are Event Readers? What Are ObjectServer Events? How Do Event Readers Work? How Do I Use Event Readers? How Do I Set Up Event Readers? How Do I Manage Event Readers? How Do I Monitor Event Readers?
What Are Event Readers?

An event reader is a Netcool/Impact service that reads events from an ObjectServer event source.
What Are ObjectServer Events?

ObjectServer events are alerts stored in the ObjectServer database. The ObjectServer stores alerts as rows in the alerts.status table.
77
How Do Event Readers Work?

An event reader works by querying the ObjectServer at intervals. During each query, the event reader retrieves those new and/or updated events that match its filter conditions. The event reader then places the retrieved events in an event queue, where they can be processed by the event processor service.
How Do I Use Event Readers?

You must have an event reader for each instance of the ObjectServer that you want to monitor. Most uses of Netcool/Impact require only one event reader. It is very uncommon to use Netcool/Impact to monitor more than one ObjectServer.
How Do I Set Up Event Readers?

You set up an event reader using the Netcool/Impact GUI. For more information, see "Setting Up Event Readers" on page 83.
How Do I Manage Event Readers?

You can use the Netcool/Impact GUI to view, create, edit and delete event readers. You can use both the GUI and the CLI to start and stop event readers.
How Do I Monitor Event Readers?

The event reader provides a log that you can use to monitor the activities of the service.
78
Event Reader Architecture

The following diagram shows the relationship between Netcool/Impact, an event reader and an ObjectServer.
Probe
Netcool/ Impact
Event Reader ObjectServer Probe
Probe
Figure 38. Event Reader Architecture
How Event Readers Work

The event reader process has the following phases: Startup Event Polling Event Querying Deleted Event Notification Event Queueing
Startup
If the event reader is configured to get all unprocessed events at startup, it queries the ObjectServer during this phase for new and/or updated events that have occurred since the last query. If the event reader is not configured to get all unprocessed events, it proceeds to the event polling phase without querying the ObjectServer.
Event Polling
During the event polling phase, the event reader queries the ObjectServer at intervals for all new and/or unprocessed events. You set the polling interval when you configure the event reader.
Chapter 9. Working with Event Readers 79
Event Querying
When the event reader queries the ObjectServer, either at startup or when polling for events at intervals, it does the following: Reads the state file to find the Serial or StateChange value of the last read event Connects to the ObjectServer and retrieves new and/or updated events that have occurred since the last read event
Reading the State File

The state file is a text file used by the event reader to cache state information about the last event read from the ObjectServer. If the event reader is configured to get only new events from the ObjectServer, the state file contains the Serial value of the last event read from the ObjectServer. If the event reader is configured to get both new and updated events from the ObjectServer, the file contains the StateChange value of the last read event. The event reader reads the contents of the state file whenever it polls the ObjectServer and passes the Serial or StateChange value as part of the query.
Retrieving New and/or Updated Events

During this phase, the event reader retrieves all of the new and/or updated events from the ObjectServer, using information from the state file to specify the correct subset of events.
Recording the State File

After the event reader retrieves the events from the ObjectServer, it caches the Serial or StateChange value of the last processed event.
Delete Notification
If the event reader is configured to run a policy when an event is deleted from the ObjectServer, it listens to the ObjectServer via the IDUC interface for notification of deleted alerts. The IDUC delete notification includes the event field data for the deleted alert.
Event Queuing
After it retrieves new and/or updated events, or has received events through delete notification, the event reader compares the field data in the events to its set of filters. If the event matches one or more of its filters, the event reader places the event in the event queue with a pointer to the corresponding policy. Once the events are in the event queue, they can be picked up by the event processor service. The event processor passes the events and pointers to the corresponding policies to the policy engine for processing.
80
Event Reader Configuration

You can configure the following properties of an event reader: Event reader name ObjectServer event source you want the event reader to monitor Interval at which you want the event reader to poll the ObjectServer Event fields you want to retrieve from the ObjectServer Event mapping Event locking Order in which the event reader retrieves events from the ObjectServer Startup, service log and reporting options
Event Reader Name

The event reader name is a unique name that identifies the service. This name appears in the Service Status panel of the Netcool/Impact GUI after the service has been created.
ObjectServer Event Source

The ObjectServer event source represents the instance of the Netcool/OMNIbus ObjectServer that you want to monitor using this service. You must have previously created the event source before you can configure the event reader to monitor it. For more information, see Chapter 9. "Working with Event Readers" on page 77.
Polling Interval
The polling interval is the interval in milliseconds at which the event reader polls the ObjectServer for new and/or updated events. The default polling interval is 3000 milliseconds.
Event Fields
Netcool/Impact allows you to specify which event fields you want to retrieve from the ObjectServer. By default, Netcool/Impact retrieves all fields in the alerts. However, you can improve the event reader performance and reduce the performance impact on the ObjectServer if you configure the event reader to retrieve only those fields that are used in the corresponding policies.
81
Event Mapping
Event mapping allows you to map incoming events to one or more specific policies. You can configure the following aspects of event mapping: Mappings Event matching Actions Event locking
Mappings
Event mappings allow you to specify which policies you want Netcool/Impact to run when certain events are retrieved. Each mapping consists of a filter that specifies the type of event and a policy name. You must specify at least one event mapping for the event reader to work. The syntax for the filter is the same as the WHERE clause in an SQL SELECT statement. This clause consists of one or more comparisons that must be true in order for the specified policy to be executed. For more information on the SQL filter syntax, see the Netcool/Impact Policy Reference Guide. The following are examples of event mapping filters.
AlertKey = Node not responding AlertKey = Node not reachable by network ping AND Node = ORA_Host_01
Event Matching
You can specify whether to run only the first matching policy in the event mappings or to run every policy that matches. If you choose to run every policy that matches, the event reader will place a duplicate of the event in the event queue for every matching policy. The event will be processed as many times as their are matching filters in the event reader.
Actions
By default, the event broker monitors the ObjectServer for new alerts. However, you can also configure it to monitor for updated alerts and/or to be notified when an alert is deleted. In addition, you can configure it to get all of the unprocessed alerts from the ObjectServer at startup.
Event Locking
Event locking is a feature that allows a multi-threaded event broker to categorize incoming alerts based on the values of specified alert fields and then to process them within a category one at a time in the order that they were sent to the ObjectServer. Event locking locks the order in which the event broker processes alerts within each category.
82
You use event locking in situations where you want to preserve the order in which incoming alerts are processed, or in situations where you want to prevent a multi-threaded event processor from attempting to access a single resource from more than one instance of a policy running simultaneously. You specify the way the event broker categorizes incoming alerts using an expression called a locking expression. The locking expression consists of one or more alert field names concatenated with a plus sign (+) as follows:
field[+field...]
where field is the name of an alert field in the ObjectServers alerts.status table. When an event broker retrieves alerts from the ObjectServer, it evaluates the locking expression for each incoming alert and categorizes it according to the contents of the alert fields in the expression. For example, when using the following locking expression Node, the event broker categorizes all incoming alerts based on the value of the Node alert field and then processes them within a category one at a time in the order that they were sent to the ObjectServer. In the following example:
Node+AlertKey
the event broker categorizes all incoming alerts based on the concatenated values of the Node and AlertKey fields. In this example, an alert whose Node value is Node1 and AlertKey value is 123456 is categorized separately
Event Order
You can specify an alert field that you want the event reader to use to order alerts retrieved from the ObjectServer. When you specify a field, the event reader sorts the incoming alerts by the field value in ascending order.
Setting Up Event Readers

Before you set up an event reader, you must have previously created an event source that represents the ObjectServer you want to monitor. For information on event sources, see Chapter 7. "Working with Event Sources" on page 63. To set up an event reader: 1. In the Netcool/Impact GUI, open the Services task pane in the Navigation panel.
Figure 39. Services Task Pane
83
2.
Select Event Reader from the Types list and click the New Service button. The Event Reader Configuration window appears.
Figure 40. Event Reader Configuration Window
3. 4. 5.
Enter a unique name for the event reader in the Service Name field. Select the ObjectServer event source that you want to monitor from the ObjectServer Data Sources list. Enter a polling interval in milliseconds in the Polling Interval field. If you leave this field empty, the event reader will poll the ObjectServer every three seconds.
84
6.
Click the Fields button. The ObjectServer Fields window appears.
Figure 41. ObjectServer Fields Window
7. 8.
Select the fields that you want to retrieve from the ObjectServer in the Available list and click Add. Select the fields that you do not want to retrieve in the Selected list and click Remove.
85
9.
Select the Event Mapping tab that is located at the top of the Event Reader Configuration window. The Event Mapping area of the window appears.
Figure 42. Event Reader Configuration - Event Mapping
10. Select an Event Matching option. You can choose to test events with all filters and run any matching policies or to stop testing after the first matching policy. 11. If you want to get updated events as well as new events from the ObjectServer, select Get Updated Events in the Actions area. Optional. 12. If you want to get unprocessed events at startup, select Get Unprocessed Events in the Actions area. Optional. 13. If you want the event reader to receive notification when alerts are deleted from the ObjectServer, select Run Policy on Deletes in the Actions area. Then, select the policy you want to run when notification occurs from the Policy list. Optional. 14. If you want to use event order locking, select Event Locking and enter the locking expression in the Expression field. Optional.
86
15. For each event type that you want to associate with a policy, do the following: Click the New Mapping button. The Create Event Filter window appears.
Figure 43. Create Event Filter Window
Enter a filter string in the Filter Expression field. This filter specifies the type of event that maps to the policy. Select the policy you want to run for the event type from the Policy to Run list. Select the Active checkbox. Click OK. 16. If you want to order incoming events, enter the name of an alert field in the Order text box. The event reader will sort incoming events in ascending order by the contents of this field. 17. Click OK.
87
88
10_Working_With_Event_Listeners.fm November 30, 2006
Chapter 10. Working with Event Listeners

This chapter contains information about working with Netcool/Impact event listeners. It contains the following sections: "About Event Listeners" on page 89 "How Event Listeners Work" on page 90 "Event Listener Configuration" on page 91 "Setting Up Event Listeners" on page 93
About Event Listeners

This section contains overview information about event listeners. It contains the following topics: What Are Event Listeners? How Do Event Listeners Work? How Do I Use Event Listeners? How Do I Set Up Event Listeners?
What Are Event Listeners?

An event listener is a Netcool/Impact service that monitors a non-ObjectServer event source for new, updated and/or deleted events. Event listeners typically work with specially-configured DSAs, such as the JMS DSA, that allow bi-directional communication with a source of data. For information on which DSAs support the event listener functionality, contact your Micromuse account manager.
How Do Event Listeners Work?

An event listener establishes a connection with the event source via a corresponding DSA. This connection allows it to listen for events asynchronously with respect to policies running in Netcool/Impact. When the event listener receives an event from the event source, it places it on the event queue, where it can be processed by the event processor service. The exact behavior of an event listener depends heavily on the DSA it uses to connect to the event source. For more information on how event listeners work with particular DSAs, see the corresponding DSA documentation.
89
How Do I Use Event Listeners?

You must have an event listener for each non-ObjectServer event source you want to monitor.
How Do I Set Up Event Listeners?

You set up an event listener using the Netcool/Impact GUI. For more information, see "Setting Up Event Listeners" on page 93.
How Do I Manage Event Listeners?

You can use the Netcool/Impact GUI to view, create, edit and delete event listeners. You can use both the GUI and the CLI to start and stop event listeners.
How Event Listeners Work

The e-mail reader process has the following phases: Event Listening Event Queueing
Event Listening
During the event listening phase, the event listener connects to the event source and waits passively for the event source to send events. When the event listener receives an event from an event source, it converts it into the Netcool/Impact event format.
Event Queuing
After the event listener has converted the event into Netcool/Impact format, it places the event on the event queue with a pointer to the policy specified in the event listener configuration. Once the event is in the event queue, it can be picked up by the event processor service. The event processor passes the event and the pointer to the corresponding policies to the policy engine for processing.
90
Event Listener Configuration

You can configure the following properties of an event listener: Event listener name Listener filter Policy you want the event listener to run CORBA name service hostname CORBA name service port CORBA name service context CORBA name service object name Direct mode class name Direct mode source name Startup options
Event Listener Name

The event listener name is a unique name that identifies the service. This name appears in the Service Status panel of the Netcool/Impact GUI after the service has been created.
Listener Filter
The listener filter allows you to specify which incoming events the event listener passes to the event processor for handling. The syntax for the listener filter varies, depending on the DSA that provides the connection to the event source. If the DSA does not specify a listener syntax, you can specify an empty string ( ) as the filter.
Event Listener Policy

You must specify a policy to run when new events are received by the event listener.
CORBA Name Service Hostname

If the DSA that works with the event listener runs in CORBA mode, you must provide the hostname for the corresponding CORBA name service. Typically, the host system is the same as the host where the Netcool/Impact server is running.
CORBA Name Service Port

If the DSA that works with the event listener runs in CORBA mode, you must provide the port for the corresponding CORBA name service. The CORBA name service embedded in Netcool/Impact runs on port 4500 by default.
91
CORBA Name Service Context

The CORBA name service context is specified by the DSA that works with the event listener. You can find the context string in the DSA documentation.
CORBA Name Service ObjectName

The CORBA name service object name is specified by the DSA that works with the event listener. You can find the object name in the DSA documentation.
Direct Mode Class Name

If the DSA that works with the event listener runs in direct mode, you must provide the class name of the direct mode interface. You can find the class name in the DSA documentation.
Direct Mode Source Name

If the DSA that works with the event listener runs in direct mode, you must provide the source name for the direct mode interface. You can find the source name in the DSA documentation.
92
Setting Up Event Listeners

To set up an event listener: 1. In the Netcool/Impact GUI, open the Services task pane in the Navigation panel.
Figure 44. Services Task Pane
2.
Select Event Listener from the Types list and click the New Service button. The Create New Event Listener window appears.
Figure 45. Create New E-Mail Reader Window
3. 4. 5.
Enter a unique name for the e-mail reader in the Service Name field. Enter a listener filter, if any, in the Listener Filter field. Optional. Select the policy you want to run when new events are received by the event listener from the Action Tree To Execute list.
93
6.
If the DSA that works with the event listener is running in CORBA mode, do the following: Enter the hostname or IP address of the system where the CORBA name service is running in the NSHost field Enter the port where the CORBA name service is running in the NSPort field. Enter the CORBA name service context in the NSContext field. Enter the CORBA name server object name in the NSObjectName field.
7.
If the DSA that works with the event listener is running in direct mode, do the following: Enter the name of the direct mode interface class in the Direct Mode Class Name field. Enter the name of the direct mode source in the Direct Mode Source field.
8.
Click OK.
94
09_Working_With_Database_Listeners.fm November 30, 2006
Chapter 11. Working with the Database Listener

This chapter contains information about working with the Netcool/Impact database listener. It contains the following sections: "About the Database Listener" on page 95 "Setting Up the Database Server" on page 96 "Setting Up the Database Listener" on page 100 "Sending Database Events" on page 101 "Writing Database Event Policies" on page 108 "Example Triggers" on page 111
About the Database Listener

This section contains overview information about the database listener service. It contains the following topics: What Is the Database Listener? What Is the Database Client? What Are Database Events? How Do I Set Up the Database Listener? How Do I Set Up the Database Server? How Do I Write Database Listener Policies? How Do I Monitor the Database Listener?
What Is the Database Listener?

The database listener is a Netcool/Impact service that listens asynchronously for events generated by an Oracle database server and then runs one or more policies in response. The database listener allows Netcool/Impact to analyze, correlate and enrich data stored in Oracle in real time. For example, you can configure the database so that every time you insert, update or delete rows in a table, they are sent as events to Netcool/Impact for processing. Netcool/Impact can then analyze the row data, correlate it with information from other data sources, and/or enrich the rows before sending them back to the database. In this version of Netcool/Impact, you can use the database listener to listen for Oracle database events only. Oracle 8i and 9i cannot be used with the database listener service.
Chapter 11. Working with the Database Listener 95
What Is the Database Client?

The database client is the software component that acts as an intermediary between the database server and the database listener. The client software is distributed with the Netcool/Impact server and consists of a set of Java schema objects that you install into the database server using the Oracle loadjava tool. The client exposes a function named sendEvent() that you publish to the database as a stored procedure.
What Are Database Events?

A database event is a set of name/value pairs sent to Netcool/Impact by the database server. Database events are generated by triggers defined in the database server. Each trigger populates an Oracle VARRAY with the desired event data and calls the sendEvent() stored procedure exposed by the database client. The client converts the array data to Netcool/Impact format and sends it to the database listener as an event.
How Do I Set Up the Database Server?

To set up the database server, you first install the database client software into the database server. Then, you configure the client so that it can locate the hostname and port where the database listener is running. Finally, you can use the tools provided with the database server to create the call spec and triggers that send events to Netcool/Impact.
How Do I Set Up the Database Listener?

To set up the database listener, you set its configuration properties using the Netcool/Impact GUI or CLI. The configuration properties allow you to specify one or more policies that are to be run when the listener receives incoming events from the database server.
How Do I Write Database Listener Policies?

You can write policies that handle incoming event data in the same way that you write any other Netcool/Impact policy. The database listener passes event information to the policy using the built-in EventContainer variable. You can access the contents of this variable within a policy using the standard IPL notations.
Setting Up the Database Server

Before you can use the database listener, you must configure the database client and install it into the Oracle database server. The database client is the component that sends events from the database server to Netcool/Impact. It consists of a set of Oracle Java schema objects and related properties files. When you install the Netcool/Impact server, the installer copies a tar file containing the client program files to the local system.
96
To set up the database server, you do the following: Copy the client tar file to the system where Oracle is running and extract its contents Edit the nameserver properties file Edit the listener properties file (optional) Install the client files into the database server using the Oracle loadjava utility Grant database permissions
Copying the Client Tar File to the Oracle System

The first step in setting up the database server is to copy the client tar file into a temporary directory on the system where Oracle is running. The tar file is named oracleclient.tar and is installed in the $NCHOME/impact/install/agents directory when you install the Netcool/Impact server. After you have copied the client tar file, you can extract its contents using the UNIX tar command or a Windows archive utility like Winzip.
Editing the Nameserver Properties File

The client tar file contains a file called nameserver.props that the database client uses to determine the hostname and port where the Netcool/Impact nameserver is located. The database client uses the nameserver to find and connect to the primary instance of the Netcool/Impact server. In clustering configurations of Netcool/Impact, the database listener only runs in the primary server. You must edit the contents of the nameserver properties file so that it contains the correct settings for your environement. Table 5 shows the properties in the nameserver properties file.
Table 5. Database Client Nameserver Properties File (1 of 2) Property nameserver.n.host Description Hostname or IP address of the system where the nameserver is running, where n is the unique index value starting with 0 that identifies the nameserver in the nameserver cluster. The default value for this property is localhost. HTTP port where the containing Java application server is listening for incoming connections. The default value for this property is 8080. URL location on the Java application server where the nameserver is located. The default value for this property is /nameserver/services. Do not change the value of this property.
nameserver.n.port
nameserver.n.location
nameserver.userid
97
Table 5. Database Client Nameserver Properties File (2 of 2) Property nameserver.password nameserver.count Description Do not change the value of this property. Number of nameserver instances in the namserver cluster. The default value for this property is 1.
The following example shows a properties file that the database client can use to connect to a single-server configuration of the nameserver. In this example, the nameserver is located on a system named NCI_GUI_01 and is running on the default port.
nameserver.0.host=NCI_GUI_01 nameserver.0.port=8080 nameserver.0.location=/nameserver/services nameserver.userid=admin nameserver.password=netcool nameserver.count=1
The following example shows a properties file that the database client can use to connect to a cluster that consists of two nameserver instances. In this example, the nameservers are located on systems named NCI_GUI_01 and NCI_GUI_02 and are running on the default port.
nameserver.0.host=NCI_GUI_01 nameserver.0.port=8080 nameserver.0.location=/nameserver/services nameserver.1.host=NCI_GUI_02 nameserver.1.port=8080 nameserver.1.location=/nameserver/services nameserver.userid=admin nameserver.password=netcool nameserver.count=2
Editing the Listener Properties File

The client tar file also contains a file named impactdblistener.props that contains additional settings for the database client. You must edit this file so that it contains the correct name for the Netcool/Impact server cluster. You can also change debug and delimiter properties.
98
Table 6 shows the properties in the listener properties file:

Table 6. Database Client Listener Properties File Property impact.cluster.name Description Name of the Netcool/Impact server cluster where the database listener is running. The default value for this property is NCICLUSTER. Specifies whether to run the database client in debug mode. The default value for this property is false. Specifies the delimiter character that separates name/value pairs in the VARRAY sent by Java stored procedures to the database client. The default value for this property is the pipe character (|). You cannot use the colon (:) as a delimiter.
impact.dblistener.debug
impact.dblistener.delim
Installing the Client Files Into Oracle

Oracle provides a utility named loadjava that you can use to install the client files into the database server. This file is located in the $ORACLE_HOME/bin directory. You must install the client files in the following order: cryptix32.jar nameserver.jar impactdblistener.jar nameserver.props impactdblistener.props
If you do not install the files in this order, loadjava will not be able to resolve external references between files and will report errors during installation. To install the client files, change the current directory to ORACLE_HOME/bin and enter the following commands at a command prompt:
loadjava loadjava loadjava loadjava loadjava -U -U -U -U -U username/password username/password username/password username/password username/password -resolve -resolve -resolve -resolve -resolve cryptix32.jar nameserver.jar impactdblistener.jar nameserver.props impactdblistener.props
where username and password are a valid username and password for a user whose schema contains the database resources where the Java stored procedures will be run.
99
Granting Database Permissions

You must grant a certain set of permissions in the Oracle database server in order for the database listener to function. You can grant the permissions by entering the following at an Oracle command prompt, where SCHEMA_NAME is the name of your database schema, hostname is the name of the host where you are running the Netcool/Impact server, port is the HTTP port on the server and listenerport is the port used by the database listener.
exec dbms_java.grant_permission( 'SCHEMA_NAME','SYS:java.net.SocketPermission', 'hostname:port', 'connect,resolve' ) / exec dbms_java.grant_permission( 'SCHEMA_NAME','SYS:java.net.SocketPermission', 'hostname:listener_port', 'connect,resolve' ) / exec dbms_java.grant_permission( 'SCHEMA_NAME','SYS:java.lang.RuntimePermission', 'shutdownHooks' , ''); / exec dbms_java.grant_permission( 'SCHEMA_NAME', 'SYS:java.security.SecurityPermission', 'insertProvider.Cryptix', '' ); / exec dbms_java.grant_permission( 'SCHEMA_NAME', 'SYS:java.util.logging.LoggingPermission', 'control', '' ); / exec dbms_java.grant_permission( 'SCHEMA_NAME', 'SYS:java.io.FilePermission', '$NCHOME/wasce/repository/log4j/jars/-', 'read'); / exec dbms_java.grant_permission( 'SCHEMA_NAME', 'SYS:java.io.FilePermission', '$NCHOME/wasce/config-store/32/-', 'read'); /
Oracle might also require you to grant socket permissions to additional ports (for example, the next two port numbers in the allocation sequence) for use in connecting to the database listener service.
Setting Up the Database Listener

To set up the database listener, you set its configuration properties using the Netcool/Impact GUI. The configuration properties allow you to specify one or more policies that are to be run when the listener receives incoming events from the database server. To set up a database listener: 1. 2. In the Netcool/Impact GUI, open the Services task pane in the Navigation panel. Click on the DatabaseListener link. The Database Listener Configuration window appears.
100
3. 4.
Select an Event Matching option. You can choose to test events with all filters and run any matching policies or to stop testing after the first matching policy. For each type of event that you want to associate with a policy, do the following: Click the New Mapping button. Enter a filter string in the Filter Expression field. This filter specifies the type of event that maps to the policy. For information on the filter syntax, see "Event Mapping" on page 82. Select the policy you want to run for the event type from the Policy to Run list. Select the Active checkbox. Click OK.
5. 6. 7.
Select Startup to start the service automatically when you start the Netcool/Impact server. Select Write to File to print the service log to a file. Click OK.
Sending Database Events

To configure the database to send events, you do the following: Create a call spec that publishes the sendEvent() function from the database client library Create triggers that call the resulting stored procedure
Before you create these objects in the database, you must understand what kind of database events you want to send and what conditions should cause them to be sent. For example, if you want to send an event to Netcool/Impact every time a row is inserted into a table, you should know the identity of the table, the subset of row information to send as part of the event and the name of the condition (for example, after insert) that triggers the operation. For more information on Java stored procedures, call specs and triggers, see the Oracle Java Stored Procedure Developers Guide.
Creating the Call Spec

The database client exposes a function named sendEvent() that allows Oracle schema objects (in this case, triggers) to send events to Netcool/Impact. This function has the following syntax:
sendEvent(java.sql.Array x)
where each element in array x is a string that contains a name/value pair in the event. The sendEvent() function is located in the class com.micromuse.response.service.listener.database. DatabaseListenerClient, which you compiled and loaded when you installed the client into the database server.
Chapter 11. Working with the Database Listener 101
In order for Oracle objects to call this function, you must create a call spec that publishes it to the database as a stored procedure. The following example shows a call spec that publishes sendEvent() as a procedure named test_varray_proc:
CREATE OR REPLACE PROCEDURE test_varray_proc(v_array_inp db_varray_type) AS LANGUAGE JAVA NAME 'com.micromuse.response.service.listener.database.DatabaseListenerClie nt. sendEvent(java.sql.Array)'; /
In this example, db_varray_type is a user-defined VARRAY that can be described using the following statement:
CREATE TYPE db_varray_type AS VARRAY(30) OF VARCHAR2(100);
The above call spec and VARRAY type are used in examples elsewhere in this chapter. When you call the procedure published with this call spec, you pass it an Oracle VARRAY in which each element is a string that contains a name/value pair in the event. The name and value in the string are separated using the pipe character (|) or another character as specified when you configured the database client.
Creating Triggers
You can create triggers for the following types of database events: DML events DDL events System events User events
DML Events
DML events are sent to Netcool/Impact when the database performs operations that change rows in a table. These include the standard SQL INSERT, UPDATE and DELETE commands. You configure the database to send DML events by creating triggers that are associated with these operations. Most often, these triggers take field data from the rows under current change and pass it to the database client using the call spec you previously created. In this way, the database reports the inserts, updates and deletes to Netcool/Impact for processing as events. When the database client receives the field data from the trigger, it performs a SELECT operation on the table to determine the underlying data type of each field. Because the corresponding row is currently under change, Oracle is likely to report a mutating table error (ORA-04091) when the database client performs the SELECT. To avoid receiving this error, your DML triggers should create a copy of the row data first and then use this copy when sending the event.
The following example contains table type declarations, variable declarations and trigger definitions that create a temporary copy of row data. You can modify this example for your own use. This example uses the type db_varray_type described in the previous section. The triggers in the example run in response to changes made to a table named dept. This example contains the following: Type declaration for deptTable, which is a nested table of db_varray_type. Variable declaration for dept1, which is a table of type deptTable. This table stores the copy of the row data. Variable declaration for emptyDept, which is a second table of type deptTable. This table is empty and is used to reset dept1. Trigger definition for dept_reset, which is used to reset dept1. Trigger definition for dept_after_row, which populates dept1 with field data from the changed row(s). Trigger definition for dept_after_stmt, which loops through the copied rows and sends the field data to the database client using the call spec defined in the previous section.
The trigger definition for dept_after_row is intentionally left incomplete in this example, because it will vary depending on whether you are handling INSERT, UPDATE or DELETE operations. Examples in the following sections contain possible definitions for this trigger.
CREATE OR REPLACE PACKAGE dept_pkg AS /* deptTable is a nested table of VARRAYs that will be sent to the database client */ TYPE deptTable IS TABLE OF db_varray_type INDEX BY BINARY_INTEGER; /* dept1 will store the actual VARRAYs dept1 deptTable; /* emptyDept is used for initializing dept1 */ emptyDept deptTable; end; / CREATE OR REPLACE TRIGGER dept_reset BEFORE INSERT OR UPDATE OR DELETE ON dept BEGIN /* Initialize dept1 */ dept_pkg.dept1 := dept_pkg.emptyDept; end; /
103
/* /* /* /*
CREATE OR REPLACE TRIGGER dept_after_row AFTER INSERT OR UPDATE OR DELETE ON dept FOR EACH ROW BEGIN
/* This trigger intentionally left incomplete. */ /* See examples in following sections of this chapter. */ end; / CREATE OR REPLACE TRIGGER dept_after_stmt AFTER INSERT OR UPDATE OR DELETE ON dept BEGIN /* Loop through rows in dept1 and send field data to database client */ /* using call proc defined in previous section of this chapter */ for i in 1 .. dept_pkg.dept1.count loop test_varray_proc(dept_pkg.dept1(i)); end loop; end; /
Insert Events
To send an event to Netcool/Impact when Oracle performs an INSERT operation, you must first create a trigger that copies the inserted row data to a temporary table. You then use another trigger as shown in the example above to loop through the temporary table and send the row data to the database client for processing. A typical insert trigger contains a statement that populates a VARRAY with the desired field data and then assigns the VARRAY as a row in the temporary table. Each element in the VARRAY must contain a character-delimited set of name/value pairs that the database client converts to event format before sending it to Netcool/Impact. The default delimiter character is the pipe symbol (|). The VARRAY must contain an element for a field named EVENTSOURCE. This field is used by the database client to determine the table where the database event originated. The following example shows a typical VARRAY for insert events:
db_varray_type(EVENTSOURCE | SCOTT.DEPT, DEPTNO | ||:NEW.DEPTNO, LOC | ||:NEW.LOC, DNAME | ||:NEW.DNAME, IMPACTED | ||:NEW.IMPACTED);
In this example, the VARRAY contains an EVENTSOURCE field and fields that contain values derived from the inserted row, as contained in the NEW pseudo-record passed to the trigger. The value of the EVENTSOURCE field in this example is the dept table in the Oracle SCOTT schema.
104
The following example shows a complete trigger that copies new row data to the temporary table dept1 in packpage dept_pkg.
CREATE OR REPLACE TRIGGER dept_after_row AFTER INSERT ON dept FOR EACH ROW BEGIN dept_pkg.dept1(dept_pkg.dept1.count + 1) := db_varray_type(EVENTSOURCE | SCOTT.DEPT, DEPTNO | ||:NEW.DEPTNO, LOC | ||:NEW.LOC, DNAME | || :NEW.DNAME, IMPACTED | ||:NEW.IMPACTED); end; /
For a complete example that shows how to send an insert event, see "Example Triggers" on page 111.
Update and Delete Events

You can send update and delete events using the same technique you use to send insert events. When you send update and delete events, however, you must obtain the row values using the OLD pseudo-record instead of NEW. The following example shows a trigger that copies updated row data to the temporary table dept1 in packpage dept_pkg.
CREATE OR REPLACE TRIGGER dept_after_row AFTER UPDATE ON dept FOR EACH ROW BEGIN dept_pkg.dept1(dept_pkg.dept1.count + 1) := db_varray_type(EVENTSOURCE | SCOTT.DEPT, DEPTNO | ||:OLD.DEPTNO, LOC | ||:OLD.LOC, DNAME | || :OLD.DNAME, IMPACTED | ||:OLD.IMPACTED); end; /
The following example shows a trigger that copies deleted row data to the temporary table dept1.
CREATE OR REPLACE TRIGGER dept_after_row AFTER DELETE ON dept FOR EACH ROW BEGIN dept_pkg.dept1(dept_pkg.dept1.count + 1) := db_varray_type(EVENTSOURCE | SCOTT.DEPT, DEPTNO | ||:OLD.DEPTNO, LOC | ||:OLD.LOC, DNAME | || :OLD.DNAME, IMPACTED | ||:OLD.IMPACTED); end; /
105
DDL Events
DDL events are sent to Netcool/Impact when the database performs an action that makes a change to a schema object. These include the SQL CREATE, ALTER and DROP commands. To send DDL events, you create a trigger that populates a VARRAY with data that describes the DDL action and the database object that is changed by the operation. Then, you pass the VARRAY element to the database client for processing. As with DML events, the VARRAY contains a character-delimited set of name/value pairs that the database client converts to event format before sending to Netcool/Impact. DDL events require two VARRAY elements: EVENTSOURCE, as described in the previous section, and TRIGGEREVENT. Typically, you populate the TRIGGEREVENT element with the current value of Sys.sysevent. The following example shows a typical VARRAY for DDL events.
db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE | || Sys.database_name, USERNAME | ||Sys.login_user, INSTANCENUM | || Sys.instancenum, OBJECTTYPE | ||Sys.dictionary_obj_type, OBJECTOWNER | | |Sys.dictionary_obj_owner);
The following example shows a complete trigger that sends an event to Netcool/Impact before Oracle executes a CREATE command.
CREATE OR REPLACE TRIGGER ddl_before_create BEFORE CREATE ON SCOTT.schema DECLARE my_before_create_varray db_varray_type; BEGIN my_before_create_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE | ||Sys.database_name, USERNAME | ||Sys.login_user, INSTANCENUM | ||Sys.instancenum, OBJECTTYPE | || Sys.dictionary_obj_type, OBJECTOWNER | ||Sys.dictionary_obj_owner); test_varray_proc(my_before_create_varray); end; /
For more examples that show how to create triggers that send DDL events, see "Example Triggers" on page 111.
System Events
System events are sent to Netcool/Impact when the Oracle server starts up, shuts down or reports a system-level error. System events only work if the user who owns the corresponding triggers has SYSDBA privileges (for example, the SYS user).
106
To send DDL events, you create a trigger that populates a VARRAY with data that describes the system action. Then, you pass the VARRAY element to the database client for processing. As with DDL events, system events require the TRIGGEREVENT element to be populated, typically with the value of Sys.sysevent. The following example shows a typical VARRAY for system events.
db_varray_type(TRIGGEREVENT | ||Sys.sysevent, OBJECTNAME | || Sys.database_name, USER_NAME | ||Sys.login_user, INSTANCE_NUM | || Sys.instance_num);
The following example shows a complete trigger that sends an event to Netcool/Impact at Oracle startup.
CREATE OR REPLACE TRIGGER databasestartuptrigger AFTER STARTUP ON database BEGIN v_array_inp := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, OBJECTNAME | ||Sys.database_name, USER_NAME | ||Sys.login_user, INSTANCE_NUM | | |Sys.instance_num); test_varray_proc(v_array_inp);
For more examples that show how to create triggers that send system events, see "Example Triggers" on page 111.
User Events
User events are sent to Netcool/Impact when a user logs into or out of Oracle. To send user events, you create a trigger that populates a VARRAY with data that describes the user action. Then, you pass the VARRAY element to the database client for processing. As with system events, user events require the TRIGGEREVENT element to be populated, typically with the value of Sys.sysevent. If you do not specify a value for the EVENTSOURCE element, the database client uses the name of the database, The following example shows a typical VARRAY for user events.
db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE ||| Sys.database_name, LOGINUSER | ||Sys.login_user, INSTANCENUM | || Sys.instance_num, TRIGGERNAME | USER_LOGIN);
107
The following example shows a complete trigger that sends an event to Netcool/Impact at when a user logs in.
CREATE OR REPLACE TRIGGER user_login AFTER logon on schema DECLARE my_login_varray db_varray_type; BEGIN my_login_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE |||Sys.database_name, LOGINUSER | ||Sys.login_user, INSTANCENUM | ||Sys.instance_num, TRIGGERNAME | USER_LOGIN); test_varray_proc(my_login_varray); end; /
For more examples that show how to create triggers that send user events, see "Example Triggers" on page 111.
Writing Database Event Policies

Netcool/Impact policies that work with database events can perform the following actions: Handle incoming events Return events to the database
Handling Incoming Database Events

The database listener passes incoming events to Netcool/Impact using the built-in EventContainer variable. When the database listener receives an event from the database, it populates the EventContainer member variables with the values sent by the database trigger using the Oracle VARRAY. You can access the values of EventContainer using the @ or dot notations in the same way you access the field values in any other type of event. The following example shows how to handle an incoming database event. In this example, the event was generated using the example trigger described in "Insert Events" on page 104. This example prints the field values in the event to the policy log.
// Log incoming event values Log("Department number: " + @DEPTNO); Log("Location: " + @LOC); Log("Database name: " + @DNAME); Log("Impacted: " + @IMPACTED);
108
Returning Events to the Database

The database listener supports the use of the ReturnEvent function in a policy to update or delete events. To use ReturnEvent in a database event policy, you must do the following: Make sure that the database trigger that sends the event populates a special set of connection event fields Call the ReturnEven function in the policy that handles the events
Populating the Connection Event Fields

In order for the policy that handles events to return them to the event source, you must populate a special set of event fields in the database trigger. These fields specify connection information for the database server. The database listener uses this information to connect to the database when you return an updated or deleted event. Table 7 shows the event fields that you must populate in the trigger:
Table 7. Database Trigger Connection Event Fields Field RETURNEVENT USERNAME PASSWORD HOST PORT SID KEYFIELD Description You must set a value of TRUE in this event field. Username to use when connecting to the Oracle database server. Password to use when connecting to the Oracle database server. Hostname or IP address of the system where Oracle is running. Connection port for the Oracle database server. Oracle server ID. Key field in the database table, or any other field that uniquely identifies a table row.
When the database client sends the event to Netcool/Impact, it encrypts the connection information (including the database username and password) specified in the event fields. The connection information is then unencrypted when it is received by Netcool/Impact.
109
The following example shows a trigger that sends an event to Netcool/Impact when a new row is inserted into the dept table. In this example, you populate the connection event fields by specifying elements in the Oracle VARRAY that you pass to the database.
CREATE OR REPLACE TRIGGER dept_after_row AFTER INSERT ON dept FOR EACH ROW BEGIN dept_pkg.dept1(dept_pkg.dept1.count + 1) := db_varray_type(EVENTSOURCE | SCOTT.DEPT, DEPTNO | ||:NEW.DEPTNO, LOC | ||:NEW.LOC, DNAME | || :NEW.DNAME, IMPACTED | ||:NEW.IMPACTED, RETURNEVENT | TRUE, USERNAME | ora_user, PASSWORD | ora_passwd, HOST | ora_host, PORT | 4100, SID | ora_01, KEYFIELD | DEPTNO); end; /
Returning Events to the Database

You can send updated or deleted events to the database server using the ReturnEvent function. ReturnEvent sends the event information to the database listener, which assembles an UPDATE or DELETE command using the information. The database listener then sends the command to the database server for processing. The UPDATE or DELETE command updates or deletes the row that corresponds to the original sent event. For more information on ReturnEvent, see the Netcool/Impact Policy Reference Guide. The following policy example shows how to return an updated event to the database.
// Log incoming event values Log("Department number: " + @DEPTNO); Log("Location: " + @LOC); Log("Database name: " + @DNAME); Log("Impacted: " + @IMPACTED); // Update the value of the Location field @LOC = "New York City"; // Return the event to the database ReturnEvent(EventContainer);
The following example shows how to delete an event from the database.
// Set the value of the DeleteEvent variable to true @DeleteEvent = true; // @DeleteEvent name is case-sensitive
110
// Set the event field variables required by the database listener // in order to connect to Netcool/Impact // Return the event to the database ReturnEvent(EventContainer);
Example Triggers
The following examples show how to create Oracle triggers that send the following types of events: Insert Update Delete Server startup Server shutdown Server error User logon User logoff
In these examples, test_varray_proc is a call spec that publishes the sendEvent() function exposed by the database client. The type db_varray_type is a user-defined data type that represents an Oracle VARRAY. The examples use the Oracle SCOTT sample schema. The examples for insert, update and delete events use the package and triggers described in "DML Events" on page 102 to create a copy of row data before performing operations on it.
Insert Event
The following example shows how to create a set of Oracle triggers that send an insert event to Netcool/Impact.
CREATE OR REPLACE PACKAGE dept_pkg AS TYPE deptTable IS TABLE OF db_varray_type INDEX BY BINARY_INTEGER; dept1 deptTable; emptyDept deptTable; end; /
111
CREATE OR REPLACE TRIGGER dept_reset BEFORE INSERT OR UPDATE OR DELETE ON dept BEGIN dept_pkg.dept1 := dept_pkg.emptyDept; end; / CREATE OR REPLACE TRIGGER dept_after_row AFTER INSERT ON dept FOR EACH ROW BEGIN dept_pkg.dept1(dept_pkg.dept1.count + 1) := db_varray_type(EVENTSOURCE | SCOTT.DEPT, DEPTNO | ||:NEW.DEPTNO, LOC | ||:NEW.LOC, DNAME | || :NEW.DNAME, IMPACTED | ||:NEW.IMPACTED); end; / CREATE OR REPLACE TRIGGER dept_after_stmt AFTER INSERT OR UPDATE OR DELETE ON dept BEGIN for i in 1 .. dept_pkg.dept1.count loop test_varray_proc(dept_pkg.dept1(i)); end loop; end; /
Update Event
The following example shows how to create a set of Oracle triggers that send an update event to Netcool/Impact.
112
CREATE OR REPLACE TRIGGER dept_reset BEFORE INSERT OR UPDATE OR DELETE ON dept BEGIN dept_pkg.dept1 := dept_pkg.emptyDept; end; / CREATE OR REPLACE TRIGGER dept_after_row AFTER UPDATE ON dept FOR EACH ROW BEGIN dept_pkg.dept1(dept_pkg.dept1.count + 1) := db_varray_type(EVENTSOURCE | SCOTT.DEPT, DEPTNO | ||:OLD.DEPTNO, LOC | ||:OLD.LOC, DNAME | || :OLD.DNAME, IMPACTED | ||:OLD.IMPACTED); end; / CREATE OR REPLACE TRIGGER dept_after_stmt AFTER INSERT OR UPDATE OR DELETE ON dept BEGIN for i in 1 .. dept_pkg.dept1.count loop test_varray_proc(dept_pkg.dept1(i)); end loop; end; /
Delete Event
The following example shows how to create a set of Oracle triggers that send a delete event to Netcool/Impact.
113
CREATE OR REPLACE TRIGGER dept_reset BEFORE INSERT OR UPDATE OR DELETE ON dept BEGIN dept_pkg.dept1 := dept_pkg.emptyDept; end; / CREATE OR REPLACE TRIGGER dept_after_row AFTER DELETE ON dept FOR EACH ROW BEGIN dept_pkg.dept1(dept_pkg.dept1.count + 1) := db_varray_type(EVENTSOURCE | SCOTT.DEPT, DEPTNO | ||:OLD.DEPTNO, LOC | ||:OLD.LOC, DNAME | || :OLD.DNAME, IMPACTED | ||:OLD.IMPACTED); end; / CREATE OR REPLACE TRIGGER dept_after_stmt AFTER INSERT OR UPDATE OR DELETE ON dept BEGIN for i in 1 .. dept_pkg.dept1.count loop test_varray_proc(dept_pkg.dept1(i)); end loop; end; /
Before Create Event

The following example shows how to create a trigger that sends an event before Oracle executes a CREATE command.
CREATE OR REPLACE TRIGGER ddl_before_create BEFORE CREATE ON SCOTT.schema DECLARE my_before_create_varray db_varray_type; BEGIN my_before_create_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE | ||Sys.database_name, USERNAME | ||Sys.login_user, INSTANCENUM | ||Sys.instancenum, OBJECTTYPE | || Sys.dictionary_obj_type, OBJECTOWNER | ||Sys.dictionary_obj_owner); test_varray_proc(my_before_create_varray); end; /
114
After Create Event

The following example shows how to create a trigger that sends an event after Oracle executes a CREATE command.
CREATE OR REPLACE TRIGGER ddl_after_create AFTER CREATE ON SCOTT.schema DECLARE my_after_create_varray db_varray_type; BEGIN my_after_create_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE | ||Sys.database_name, USERNAME | ||Sys.login_user, INSTANCENUM | ||Sys.instancenum, OBJECTTYPE | || Sys.dictionary_obj_type, OBJECTOWNER | ||Sys.dictionary_obj_owner); test_varray_proc(my_after_create_varray); end; /
Before Alter Event

The following example shows how to create a trigger that sends an event before Oracle executes an ALTER command.
CREATE OR REPLACE TRIGGER ddl_before_alter BEFORE ALTER ON SCOTT.schema DECLARE my_before_alter_varray db_varray_type; BEGIN my_before_alter_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE | ||Sys.database_name, USERNAME | ||Sys.login_user, INSTANCENUM | ||Sys.instancenum, OBJECTTYPE | || Sys.dictionary_obj_type, OBJECTOWNER | ||Sys.dictionary_obj_owner); test_varray_proc(my_before_alter_varray); end; /
115
After Alter Event

The following example shows how to create a trigger that sends an event after Oracle executes an ALTER command.
CREATE OR REPLACE TRIGGER ddl_after_alter AFTER ALTER ON SCOTT.schema DECLARE my_after_alter_varray db_varray_type; BEGIN my_after_alter_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE | ||Sys.database_name, USERNAME | ||Sys.login_user, INSTANCENUM | ||Sys.instancenum, OBJECTTYPE | || Sys.dictionary_obj_type, OBJECTOWNER | ||Sys.dictionary_obj_owner); test_varray_proc(my_after_alter_varray); end; /
Before Drop Event

The following example shows how to create a trigger that sends an event before Oracle executes an DROP command.
CREATE OR REPLACE TRIGGER ddl_before_drop BEFORE DROP ON SCOTT.schema DECLARE my_before_drop_varray db_varray_type; BEGIN my_before_drop_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE | ||Sys.database_name, USERNAME | ||Sys.login_user, INSTANCENUM | ||Sys.instancenum, OBJECTTYPE | || Sys.dictionary_obj_type, OBJECTOWNER | ||Sys.dictionary_obj_owner); test_varray_proc(my_before_drop_varray); end; /
116
After Drop Event

The following example shows how to create a trigger that sends an event after Oracle executes an DROP command.
CREATE OR REPLACE TRIGGER ddl_after_drop AFTER DROP ON SCOTT.schema DECLARE my_after_drop_varray db_varray_type; BEGIN my_after_drop_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE | ||Sys.database_name, USERNAME | ||Sys.login_user, INSTANCENUM | ||Sys.instancenum, OBJECTTYPE | || Sys.dictionary_obj_type, OBJECTOWNER | ||Sys.dictionary_obj_owner); test_varray_proc(my_after_drop_varray); end; /
Server Startup Event

The following example shows how to create a trigger that sends an event to Netcool/Impact at Oracle startup.
CREATE OR REPLACE TRIGGER databasestartuptrigger AFTER STARTUP ON database BEGIN v_array_inp := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, OBJECTNAME | ||Sys.database_name, USER_NAME | ||Sys.login_user, INSTANCE_NUM | | |Sys.instance_num); test_varray_proc(v_array_inp);
117
Server Shutdown Event

The following example shows how to create a trigger that sends an event to Netcool/Impact at Oracle shutdown.
CREATE OR REPLACE TRIGGER databaseshutdowntrigger BEFORE SHUTDOWN ON database DECLARE v_array_inp db_varray_type; BEGIN v_array_inp := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, OBJECTNAME | ||Sys.database_name, USER_NAME | ||Sys.login_user, INSTANCE_NUM | | |Sys.instance_num); test_varray_proc(v_array_inp); end; /
Server Error Event

The following example shows how to create a trigger that sends an event to Netcool/Impact when Oracle encounters a server error.
CREATE OR REPLACE TRIGGER server_error_trigger_database AFTER SERVERERROR ON database DECLARE my_varray db_varray_type; BEGIN my_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE | ||Sys.database_name, INSTANCENUM | ||Sys.instance_num, LOGINUSER | || Sys.login_user, ERRORNUM | ||Sys.server_error(1)); test_varray_proc(my_varray); end; /
118
Logon Event
The following example shows how to create a trigger that sends an event to Netcool/Impact when a user logs into the database.
CREATE OR REPLACE TRIGGER user_login AFTER logon on schema DECLARE my_login_varray db_varray_type; BEGIN my_login_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE |||Sys.database_name, LOGINUSER | ||Sys.login_user, INSTANCENUM | ||Sys.instance_num, TRIGGERNAME | USER_LOGIN); test_varray_proc(my_login_varray); end; /
Logoff Event
The following example shows how to create a trigger that sends an event to Netcool/Impact when a user logs out of the database.
CREATE OR REPLACE TRIGGER user_logoff BEFORE logoff on schema DECLARE my_logoff_varray db_varray_type; BEGIN my_logoff_varray := db_varray_type(TRIGGEREVENT | ||Sys.sysevent, EVENTSOURCE |||Sys.database_name, LOGINUSER | ||Sys.login_user, INSTANCENUM | ||Sys.instance_num, TRIGGERNAME | USER_LOGOFF); test_varray_proc(my_logoff_varray); end; /
119
120
11_Working_With_Policy_Activators.fm November 30, 2006
Chapter 12. Working with Policy Activators

This chapter contains information about working with Netcool/Impact policy activators. It contains the following sections: "About Policy Activators" on page 121 "Policy Activator Configuration" on page 122 "Setting Up Policy Activators" on page 123
About Policy Activators

This section contains overview information about policy activators. It contains the following topics: What Are Policy Activators? How Do Policy Activators Work? How Do I Use Policy Activators? How Do I Set Up Policy Activators?
What Are Policy Activators?

A policy activator is a Netcool/Impact service that executes a policy at timed intervals.
How Do Policy Activators Work?

The policy activator starts its associated policy at intervals specified in the service configuration. The policy activator does not populate the value of the built-in EventContainer variable or any other member of the policy context when it starts the policy.
How Do I Use Policy Activators?

You must have a policy activator for each policy that you want to run at timed intervals.
How Do I Set Up Policy Activators?

You set up a policy activator using the Netcool/Impact GUI. For more information, see "Setting Up Policy Activators" on page 123.
121
How Do I Manage Policy Activators?

You can use the Netcool/Impact GUI to view, create, edit and delete policy activators. You can use both the GUI and the CLI to start and stop policy activators.
Policy Activator Configuration

You can configure the following properties of an policy activator: Policy activator name Activation interval Policy you want to run at intervals Startup and logging options
Policy Activator Name

The policy activator name is a unique name that identifies the service. This name appears in the Service Status panel of the Netcool/Impact GUI after the service has been created.
Activation Interval
The activation interval is the interval in seconds at which the policy activator runs the policy.
Policy
You must specify the name of the policy that you want the policy activator to run.
Startup and Logging Options

You can configure the policy activator to run automatically at startup. You can also specify whether or not the policy activator prints its log to file.
122
Setting Up Policy Activators

To set up a policy activator: 1. In the Netcool/Impact GUI, open the Services panel in the Navigation panel.
Figure 46. Services Panel
2.
Select Policy Activator from the Types list and click the New Service button. The Create New Policy Activator window appears.
Figure 47. Create New Policy Activator Window
3. 4. 5. 6.
Enter a unique name for the policy activator in the Service Name field. Enter the interval in seconds at which you want the policy activator to run the policy in the Activation Interval field. Select the policy that you want the policy activator to run from the Policy list. Click OK.
123
124
12_Working_With_Other_Services.fm November 30, 2006
Chapter 13. Working with Other Services

This chapter contains information about working with other Netcool/Impact services. It contains the following sections: "Policy Logger" on page 125 "Hibernating Policy Activator" on page 127 "Command Execution Manager" on page 129 "Command Line Manager" on page 130 "CORBA Name Service" on page 131
Policy Logger
The policy logger is the service responsible for managing the policy log. The policy log is a text stream used by Netcool/Impact to record messages generated during the runtime of a policy. The policy log contains both system messages issued by Netcool/Impact and messages that you create when you write a policy.
Policy Logger Configuration

You can configure the following properties of the policy logger: Error-handling policy Highest log level Logging of SQL statements Logging of pre-execution function parameters Logging of post-execution function parameters Policy profiling Logging and reporting options
Error-Handling Policy
The error-handling policy is the policy that is executed by default, in the situation where an error is not handled by an error handler within the policy where the error occurred.
Highest Log Level

Netcool/Impact allows you to specify a log level for messages that you print to the policy log from within a policy using the Log function. For more information on the Log function, see the Netcool/Impact Policy Reference Guide.
Chapter 13. Working with Other Services 125
Logging of SQL Statements

You can configure the policy logger to print all the contents of all SQL statements made in calls to SQL database data sources. Logging SQL statements can help you debug a policy that uses external data sources.
Logging of Pre-Execution Function Parameters

You can configure the policy logger to print the values of all of the parameters passed to a built-in action function before the function is called in a policy. These parameters include the values of built-in variables such as DataItems and DataItem.
Logging of Post-Execution Function Parameters

You can configure the policy logger to print the values of all of the parameters passed to a built-in action function after the function is called in a policy. These parameters include the values of built-in variables such as DataItems and DataItem.
Policy Profiling
Policy profiling is a feature of Netcool/Impact that calculates the total time that it takes to run a policy and prints this time to the policy log. You can enable policy profiling when you configure the policy logger.
Logging and Reporting Options

You can configure the policy logger to print the contents of the log to a text file. You can also enable the collecting of report information via the service. For more information on reporting, see the Netcool/Impact User Interface Guide.
126
Setting Up the Policy Logger

To set up the policy logger: 1. In the Netcool/Impact GUI, click the PolicyLogger name in the Service Status panel of the Navigation panel. The Policy Logger Configuration window appears.
Figure 48. Policy Logger Configuration Window
2. 3. 4. 5. 6. 7. 8.
Select a policy from the Error-Handling Policy list. Select a log level from the Highest Log Level list. Optional. Select the types of message you want to see in the policy log from the Log area. To enable policy profiling, select the Policy Profiling checkbox. Optional. To print the contents of the policy log to file, select the Service Log Write To File checkbox. Optional. To enable reporting, select the Collect Reports checkbox. Optional. Click OK.
Hibernating Policy Activator

The hibernating policy activator is a service that is responsible for waking hibernations at timed intervals. You use the hibernating policy activator with X events in Y time solutions and similar solutions that require the use of hibernating policies.
Chapter 13. Working with Other Services 127
Hibernating Policy Activator Configuration

You can configure the following properties of the hibernation policy activator: Wakeup interval Startup and logging options
Wakeup Interval
The wakeup interval is the interval in seconds at which the hibernating policy activator checks hibernating policies in the internal data repository to see if they are ready to be woken.
Startup and Logging Options

You can configure the hibernating policy activator to start automatically when you start the Netcool/Impact server. You can also configure the service to print its log to a file.
Setting Up the Hibernating Policy Activator

To set up the hibernating policy activator: 1. In the Netcool/Impact GUI, click the HibernatingPolicyActivator name in the Service Status panel of the Navigation panel. The Hibernating Policy Activator Configuration window appears.
Figure 49. Hibernating Policy Activator Configuration Window
2. 3.
Enter the wakeup interval in seconds in the Polling Interval field. To enable the service to start automatically when you start Netcool/Impact, select the Startup checkbox. Optional.
128
4. 5.
To print the contents of the service log to file, select the Service Log Print to File checkbox. Optional. Click OK.
Command Execution Manager

The command execution manager is the Netcool/Impact service responsible for operating the command and response feature. For more information on command and response, see Chapter 20. "Executing External Commands" on page 187.
Command Execution Manager Configuration Properties

The command execution manager only allows you to specify whether or not to print the service log to a file. There are no other configuration properties.
Setting Up the Command Execution Manager

To set up the command execution manager: 1. In the Netcool/Impact GUI, click the CommandExecutionManager name in the Service Status panel of the Navigation panel. The Command Execution Manager Configuration window appears.
Figure 50. Command Execution Manager Configuration Window
2. 3.
To print the service log to file, select the Service Log Print to File checkbox. Click OK.
129
Command Line Manager

The command line manager is the service that manages the Netcool/Impact CLI.
Command Line Manager Configuration

You can configure the port that where the command line service runs, and the startup and logging options for the service.
Setting Up the Command Line Manager

To set up the command line manager: 1. In the Netcool/Impact GUI, click the CommandLineManager name in the Service Status panel of the Navigation panel. The Command Line Manager Configuration window appears.
Figure 51. Command Line Manager Configuration Window
2. 3. 4. 5.
Enter the port where you want to run the service in the Port field. You telnet to this port when you use the Netcool/Impact CLI. To enable the service to start automatically when you start Netcool/Impact, select the Startup checkbox. Optional. To print the contents of the service log to file, select the Service Log Print to File checkbox. Optional. Click OK.
130
CORBA Name Service

The CORBA name service is the service that manages the CORBA interface used by some Mediator DSAs.
CORBA Name Service Configuration

Netcool/Impact allows you to specify the port where the CORBA name service is running and startup options.
Setting Up the CORBA Name Service

To set up the CORBA name service: 1. In the Netcool/Impact GUI, click the CORBANameService name in the Service Status panel of the Navigation panel. The CORBA Name Service Configuration window appears.
Figure 52. CORBA Name Service Configuration Window
2. 3. 4.
Enter the port number where you want to run the CORBA name service in the NSPort field. The default is 4500. To enable the service to start automatically when you start Netcool/Impact, select the Startup checkbox. Optional. Click OK.
131
132
13_Creating_Basic_Policies.fm November 30, 2006
Chapter 14. Policy Fundamentals

This chapter contains basic information about Netcool/Impact policies. It contains the following sections: "Introduction" on page 133 "How Do I Use This Part of the Guide?" on page 134 "About Netcool/Impact Policies" on page 134 "Before You Begin" on page 135 "Getting Started" on page 137
Introduction
This is the beginning of Part Four of this guide. Part Four provides information about Netcool/Impact policies. This information includes general concepts and instructions for working with the Netcool/Impact policy language (IPL). This part of the guide contains the following chapters: Chapter 14. "Policy Fundamentals" on page 133. This chapter contains information on creating basic policies using the Netcool/Impact policy language. Chapter 15. "Handling Events" on page 147. This chapter contains information on handling events from with a policy. This includes working with incoming events, updating existing events, and sending and deleting events. Chapter 16. "Handling Data" on page 155. This chapter contains information on working with data located in data sources. This includes retrieving data, and adding, updating and deleting data. Chapter 17. "Handling Hibernations" on page 175. This chapter contains information on causing policies to hibernate, waking hibernations and removing existing hibernations from the internal data repository. Chapter 18. "Sending E-Mail" on page 181. This chapter contains information on sending e-mail from within a policy. Chapter 19. "Instant Messaging" on page 183. This chapter contains information on sending and receiving instant messages from within a policy.
133
Chapter 20. "Executing External Commands" on page 187. This chapter contains information on executing external commands, scripts and applications from within a policy. Chapter 21. "Handling Strings and Arrays" on page 193. This chapter contains information on handling strings and arrays in a policy. This includes finding the length of strings and arrays, finding unique objects in an array and using regular expressions to manipulate string data.

If you are new to writing Netcool/Impact policies, you should read the chapters in this part of the guide in order, paying special attention to conceptual and overview information. Because you must master a variety of concepts and procedures before you can write your own policies, you should review any information that you do not understand before progressing to the next part of this book. If you are an experienced Netcool/Impact user, or you are upgrading policies from a previous version of Netcool/Impact for the first time, you should first read Chapter 14. "Policy Fundamentals" on page 133, which presents basic information about the policy language and how to use it to perform basic tasks. Then you can read any of the following chapters as needed in order to review information that you already know, or learn how to upgrade the your existing policies so that they are compatible with this version of the product. Once you have a firm understanding of Netcool/Impact policies, you can go on to Chapter 22. "Event Enrichment Tutorial" on page 199 of this guide, which contains a set of tutorials that help you learn how to write your own Netcool/Impact solutions.
About Netcool/Impact Policies

This section contains overview information about Netcool/Impact policies. It contains the following topics: What is a Policy? What is the Policy Language? What Can I Do with the Policy Language?
What Is a Policy?
A policy is a set of operations that you want Netcool/Impact to perform. These operations are specified using a programming language called the Netcool/Impact policy language, or IPL.
134
What Is the Policy Language?

The Netcool/Impact policy language (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. It also allows you to create your own variables and functions, just as in other programming languages.
What Can I Do with the Policy Language?

The policy language gives you the means to perform the following core operations: Handle events. You can use the policy language to handle incoming events, send new events, update existing events and delete events in an event source. Handle data. You can use the policy language to retrieve data from a data source. You can also use the policy language to add new data, update existing data and delete data. Send e-mail. You can use the policy language to send e-mail to administrators and end users via an SMTP server. Execute commands. You can use the policy language to execute external commands, scripts and applications on local and remote systems. Perform other tasks. You can use the policy language to perform many other tasks, such as calling database stored procedures and functions, and manipulating strings and arrays.
Before You Begin

Before you begin developing policies with Netcool/Impact, you should be familiar with the following aspects of the product: Policy Log Policy Context Policy Scope
Policy Log
The policy log is a text stream that records messages created by Netcool/Impact during the runtime of a policy. The messages in the policy log provide information about the system status and about any exceptions that might occur. You can write custom messages to the log from within a policy using the Log function. You can view the contents of the policy log using the Netcool/Impact GUI.
135
To view the contents of the policy log: 1. In the Netcool/Impact GUI, click view log button for the Policy Logger service in the Service Status panel.
Figure 53. Service Status Panel
A new Policy Log tab opens in the Main Work panel and displays the policy log.
Figure 54. Policy Log Tab
Policy Context
The policy context is the set of all the variables whose values are assigned in the current policy. The policy context includes built-in variables such as EventContainer as well as the variables that you define. You can access the value of this context from within a policy using the CurrentContext function. This function returns a string that contains the names and current value of all of the variables in the policy.
136
Policy Scope
The scope of all variables in a policy is global. This means that everywhere you use a function, it will reference the same value, regardless of whether you use it in the main program body or within a user-defined function.
Getting Started
This section contains sample policies that can help you get started developing your own policies. It contains the following examples: Printing to the Policy Log User-Defined Variables Arrays Contexts If Statements While Statements Action Functions Parser Functions User-Defined Functions
Printing to the Policy Log

This example in this section is a version of the classic "Hello, World!" program used to teach developers how to program in the C programming language. In the C version, you print Hello, World! to the standard output. Netcool/Impact does not permit you to access the standard output stream using the policy language. You can, however, print the message to the policy log. Printing messages to the policy log is one of the most useful capabilities of Netcool/Impact when it comes to testing and debugging policies. You print messages to the policy log using the Log function. The Log function takes the message you want to print as its input parameter. The policy, which consists of a single line, is as follows.
Log("Hello, World!");
Here, you simply call the Log function and pass the string Hello, World! as an input parameter. As in programming languages like C/C+ and Java, you enclose string literals in double quotation marks.
137
When you run the policy, it prints the following to the policy log:
Hello, World!
User-Defined Variables
In the example in this section, you create a set of variables and assign values to them. Then, you use the Log function in two different ways to print the value of the variables to the policy log. The first way you use Log is to print out each of the values as a separate call to the function. The second way is the print out all of the variables in the policy context at once, using the CurrentContext function. As discussed in the previous section of this chapter, the CurrentContext function returns a string that contains the names and values of all of the variables currently defined in the policy.
VarOne = "One"; VarTwo = 2; VarThree = 3.0; VarFour = VarOne + ", " + VarTwo + ", " + VarThree; Log(VarOne); Log(VarTwo); Log(VarThree); Log(VarFour); Log(CurrentContext());
When you run this policy, it prints the following to the policy log:
One 2 3.0 One, Two, Three "Prepared with user supplied parameters "=(Escalation=5, EventContainer=(), VarTwo=Two, VarOne=One, ActionNodeName=TEMP, VarFour=One, Two, Three, VarThree=Three, ActionType=1)
As shown above, you do not have to declare variables before assigning their values in the way that you do in languages like C/C++ and Java. Arrays and scalar variables like integers or strings are created automatically the first time you assign a value to them. Contexts and event containers, however, must be explicitly created using the NewObject and NewEvent functions, as described later in this guide.
Arrays
The array is a native Netcool/Impact data type that you can use to store sets of related values. Unlike arrays in C/C++ or Java, a Netcool/Impact array can store elements of any combination of data types, including other arrays and contexts. You assign values to arrays using the curly braces notation. This notation requires you to enclose a comma separated list of the values to assign in curly braces. The values can specified as literals or as variables whose values you have previously defined in the policy.
You access the value of arrays using the square bracket notation, just as in C/C++ or Java. This notation requires you to specify the name of the array followed by the index number of the element enclosed in square brackets. Arrays in Netcool/Impact are zero-based, which means that the first element in the array has an index value of 0. In the following policy, you assign a set of values to arrays and then print the values of their elements to the policy log.
Array1 = {"One", "Two", "Three", "Four", "Five"}; Array2 = {1, 2, 3, 4, 5}; Array3 = {"One", 2, "Three", 4, "Five"}; String1 = "One"; String2 = "Two"; Array4 = {String1, String2}; Log(Array1[0]); Log(Array2[2]); Log(Array3[4]); Log(Array4[1]); Log(CurrentContext());
Here, you assign sets of values to four different arrays. In the first three arrays, you assign a variety of string and integer literals. In the fourth array, you assign variables as the array elements. When you run the policy, it prints the following to the policy log:
One 3 4 Two "Prepared with user supplied parameters "=(String2=Two, ActionType=1, String1=One, EventContainer=(), ActionNodeName=TEMP, Escalation=6, Array4={One, Two}, Array3={One, 2, Three, 4, Five}, Array2={1, 2, 3, 4, 5}, Array1={One, Two, Three, Four, Five})
Contexts
Contexts are another native Netcool/Impact data type that you can use to store sets of data. Contexts are similar to the struct data type in C/C++. Like arrays, contexts can be used to store elements of any combinations of data types, including other contexts and arrays. The data elements in a context are a set of named variables called member variables. You access member variables using the dot notation. In this notation, you specify the name of the context and the name of the member variable separated by a period (.). You use this notation when you assign values to member variables and when you reference the variables elsewhere in a policy.
139
Unlike arrays and scalar variables, you must explicitly create a new context using the NewObject function before you can use it in a policy. You do not need to create the member variables in the context. These are created automatically the first time you assign their value. The following policy shows how to create a context called MyContext and assign a set of values to its member variables.
MyContext = NewContext(); MyContext.One = "One"; MyContext.Two = 2; MyContext.Three = 3.0; String1 = MyContext.One + ", " + MyContext.Two + ", " + MyContext.Three; Log(String1)
One, 2, 3.0
If Statements
The If statement allows you to control which statements in a policy are executed by testing the value of an expression to see if it is true. The If statement in the Netcool/Impact policy language is the same as that used in programming languages like C/C++ and Java. The syntax for an If statement is the If keyword followed by a boolean expression enclosed in parentheses. This expression is followed by a block of statements enclosed in curly braces. Optionally, the If statement can be followed by the Else or ElseIf keywords, which are also followed by a block of statements. When Netcool/Impact encounters the If keyword in a policy, it evaluates the boolean expression to see if it is true. If the expression is true, the statement block that follows is executed. If it is not, true Netcool/Impact skips the statements in the block. If an Else statement follows in the policy, Netcool/Impact executes the corresponding Else statement block. The following policy shows how to use the If statement.
Integer1 = 0; If (Integer1 == 0) { Log("The value of Integer1 is zero."); }
Here, you use the If statement to test the value of the Integer1 variable. If the value of Integer1 is 0, the policy will execute the statements in the statement block.
140
The value of Integer1 is zero.
The following example shows how to use the Else statement.

Integer1 = 2; If (Integer1 == 1) { Log("The value of Integer1 is one."); } Else { Log("The value of Integer1 is not one."); }
Here, you set the value of the Integer1 variable to 2. Since the first test in the If statement fails, the statement block that follows the Else statement is executed. When you run this example, it prints the following to the policy log:
The value of Integer1 is not one.
While Statements
The While statement allows you to repeat a set of operations until a specified condition is true. The While statement in the Netcool/Impact policy language is the same as that used in programming languages like C/C++ and Java. The syntax for the While statement is the While keyword followed by a boolean expression enclosed in parentheses. This expression is followed by a block of statements enclosed in curly braces. When Netcool/Impact encounters the While keyword in a policy, it evaluates the boolean expression to see if it is true. If the expression is true, the statements in the following block are executed. After the statements are executed, Netcool/Impact again tests the expression and continues executing the statement block repeatedly until the condition is false. The most common way to use the While statement is to construct a loop that is executed a certain amount of times depending on other factors in a policy. To use the While statement in this way, you use an integer variable as a counter. You set the value of the counter before the While loop begins and decrement it inside the loop. The While statement tests the value of the counter each time the loop is executed and exits when the value of the counter is zero. The following example shows a simple use of the While statement:
Counter = 10; While (Counter > 0) { Log("The value of Counter is " + Counter); Counter = Counter - 1; }
141
Here, you assign the value of 10 to a variable named Counter. In the While statement, the policy tests the value of Counter to see if it is greater than zero. If Counter is greater than zero, Netcool/Impact executes the statements in the block that follows. The final statement in the block decrements the value of Counter by one. The While loop in this example executes ten times before exiting. When you run this example, it prints the following to the policy log:
The The The The The The The The The The value value value value value value value value value value of of of of of of of of of of Counter Counter Counter Counter Counter Counter Counter Counter Counter Counter is is is is is is is is is is 10 9 8 7 6 5 4 3 2 1
The following example shows how to use the While statement to iterate through an array. You often use this technique when you handle data items retrieved from a data source.
MyArray = {"One", "Two", "Three", "Four"}; Counter = Length(MyArray); While (Counter > 0) { Index = Counter - 1; Log(MyArray[Index]); Counter = Counter - 1; }
Here, you set the value of Counter to the number of elements in the array. The While statement loops through the statement block once for each array element. You set the Index variable to the value of the Counter minus one. This is because Netcool/Impact arrays are zero-based. This means that the index value of the first element is 0, rather than 1. When you run this example, it prints the following to the policy log:
Four Three Two One
As you can see in the examples above, when you use this technique to iterate through the elements in an array, you access the elements in reverse order. To avoid this, you can increment the counter variable instead of decrementing it in the loop. This requires you to test whether the counter is less than the number of elements in the array inside the While statement.
142
The following example shows how to loop through an array while incrementing the value of the counter variable.
MyArray = {"One", "Two", "Three", "Four"}; ArrayLength = Length(Array); Counter = 0; While (Counter < ArrayLength) { Log(MyArray[Counter]); Counter = Counter + 1; }
One Two Three Four
Action Functions
Netcool/Impact provides a pre-defined set of functions called action functions that you can use to perform the core functionality of a Netcool/Impact policy. You use action functions to handle events, handle data, send e-mail, execute external commands and perform a variety of other tasks. For a complete list of the available action functions, see the Netcool/Impact Policy Language Reference. You call action functions in the same way you call functions in programming languages like C/C++ and Java. The syntax for calling an action function is the name of the function followed by a comma-separated list of input parameters. The parameters are enclosed in parentheses. If the function returns a value, you must specify a return variable for the function. The following example shows how to call the SendEmail function. The SendEmail function sends an e-mail to the specified addressee.
User = NULL; Address = "admin@example.com"; Subject = "URGENT: Node not responding"; Message = "This is an urgent message from Netcool/Impact. Node ID3849 is not responding to network ping."; Sender = "Netcool/Impact"; ExecuteOnQueue = False; SendEmail(User, Address, Subject, Message, Sender, ExecuteOnQueue);
Here, you define a set of variables and then pass them as input parameters to the SendEvent function. It is also possible to pass literal values to the function instead of variables. However, you can increase the readability of your policies by using meaningful variable names in this way.
Chapter 14. Policy Fundamentals 143
The following example shows how to call the GetByFilter function. The GetByFilter function retrieves data from a data source using a filter as the query condition.
DataType = "Admin"; Filter = "Location = London"; CountOnly = False; MyResults = GetByFilter(DataType, Filter, CountOnly);
Here, as in the previous example, you define a set of variables and then pass them as input parameters to the function. GetByFilter returns an array. In this example, the array is stored in a variable named MyResults.
Parser Functions
Parser functions are another set of functions that are pre-defined by Netcool/Impact. These functions help you perform common tasks such as manipulating strings, converting values to different data types and formatting date and time strings. For a complete list of the available parser functions, see the Netcool/Impact Policy Language Reference. As with action functions, you call parser functions in the same way you call functions in programming languages like C/C++ and Java. The syntax for calling an parser function is the name of the function followed by a comma-separated list of input parameters. The parameters are enclosed in parentheses. If the function returns a value, you must specify a return variable for the function. The following example shows how to call the Split function. The Split function splits a string into multiple substrings.
MyString = "This|is|a|test."; Delimiter = "|"; MyArray = Split(MyString, Delimiter);
Here, you define a set of variables and then pass them as input parameters to the function. The function returns an array of substrings.
User-Defined Functions
Netcool/Impact also allows you to declare your own functions and call them within a policy. User-defined functions help you encapsulate and re-use functionality in your policy. The syntax for a function declaration is the Function keyword followed by the name of the function and a comma-separated list of input parameters. The list of input parameters is followed by a statement block enclosed in curly braces. Unlike action and parser functions, you cannot specify a return value for a user-defined function. However, because the scope of variables in a Netcool/Impact policy is global, you can approximate this functionality by setting the value of a return variable inside the function.
Function declarations must appear in a policy before any instance where the function is called. The best practice is to declare all functions at the beginning of a policy. The following example shows how to declare a user-defined function called GetNodeByHostname. This function looks up a node in an external data source using the supplied hostname.
Function GetNodeByHostName(Hostname) { DataType = "Node"; Filter = "Hostname =" + Hostname + ""; CountOnly = False; MyNodes = GetByFilter(DataType, Filter, CountOnly); MyNode[0] = MyNodes; }
You call user-defined functions in the same way that you call other types of functions. The following example shows how to call the function declared above.
GetNodeByHostName("ORA_HOST_01");
Here, the name of the node that you want to look up is ORA_HOST_01.The function looks up the node in the external data source and returns a corresponding data item named MyNode. For more information on looking up data and on data items, see the next chapter in this book.
145
146
14_Handling_Events.fm November 30, 2006
Chapter 15. Handling Events

This chapter contains information about handling events in a policy. It contains the following sections: "About Events" on page 147 "About Event Containers" on page 148 "Accessing Event Fields" on page 149 "Updating Event Fields" on page 150 "Adding Journal Entries to Events" on page 151 "Sending New Events" on page 152 "Deleting Events" on page 153
About Events
This section contains overview information about events. It contains the following topics: What are Events? What are Event Sources? How Does Netcool/Impact Obtain Events? How Does Netcool/Impact Handle Events? What Can I Do with Events in a Policy?
What are Events?

An event is a set of data that represents a status or an activity on a network. The structure and content of the data varies depending on the device, system or application that generated the event. In most cases, events handled by Netcool/Impact are Netcool/OMNIbus alerts. These events are generated by Netcool probes and monitors and are stored in the ObjectServer database.
147
What are Event Sources?

An event source is a special type of data source. Each event source represents an application that stores and manages events. The most common such application is the ObjectServer database. Netcool/Impact also allows you to use other applications as event sources. For a current list of applications that you can use as event sources, ask your Micromuse account representative.
How Does Netcool/Impact Obtain Events?

Netcool/Impact obtains events using the following services: Event readers Event listeners E-mail readers
How Does Netcool/Impact Handle Events?

Netcool/Impact stores incoming event data using the built-in EventContainer variable. This variable is passed to the policy engine as part of the context when a policy is executed. When you write a policy, you can access the fields in the event using the member variables of EventContainer.
What Can I Do with Events in a Policy?

You can do the following with events in a policy: Access field values of incoming events Update field values of incoming events Add journal entries to events Send new events to the event source Delete events in the event source
About Event Containers

This section contains information about event containers. It contains the following topics: What Is an Event Container? What Is the EventContainer Variable? What Are User-Defined Event Container Variables? What Are Event Field Variables What Are Event State Variables
148
What Is an Event Container?

The event container is a native Netcool/Impact data type used to store event data. The event container consists of a set of event field and event state variables.
What Is the EventContainer Variable?

The EventContainer is a built-in variable that stores the field data for incoming events. Each time Netcool/Impact passes an event to the policy engine for processing, it creates a new instance of EventContainer, populates the event field variables and stores it in the policy context. You can then access the values of the event fields from within the policy.
What Are Event Field Variables?

Event field variables are member variables of an event container that store the field values in an event. There is one event field variable for each field in an event. The names of event field variables are the same as the event field names. For example, if an event has fields named AlertKey, Node, Severity and Summary, the corresponding event container has event field variables with the same names.
What Are Event State Variables?

Event state variables are a set of pre-defined member variables that you can use to specify the state of an event when you send it to the event source using the ReturnEvent function. Netcool/Impact uses two event state variables: JournalEntry and DeleteEvent. For information on using JournalEntry, see "Adding Journal Entries to Events" on page 151. For information on using DeleteEvent, see "Deleting Events" on page 153.
What Are User-Defined Event Container Variables?

User-defined event container variables are variables that you create using the NewEvent function. You use these variables when you send new events to the event source, or when you want to temporarily store event data within a policy.
Accessing Event Fields

You can use either the dot notation or the @ notation to access the values of event fields.
Using the Dot Notation

You use the dot notation to access the value of event fields in the same way you access the values of member variables in a struct in languages like C and C++.
149
Example
The following policy shows how to use the dot notation to access the value of the Node, Severity and Summary fields in an incoming event and print them to the policy log:
Log(EventContainer.Node); Log(EventContainer.Severity); Log(EventContainer.Summary);
Using the @ Notation

The @ notation is a special shorthand that you can use the reference the event fields in the built-in EventContainer variable without having to spell out the EventContainer name.
Example
The following policy shows how to use the @ notation to access the value of the Node, Severity and Summary fields in an incoming event and print them to the policy log:
Log(@Node); Log(@Severity); Log(@Summary);
Updating Event Fields

To update fields in an incoming event, you assign new values to event field variables in the EventContainer. All updates on an event are performed in real time. Whenever a field is updated in a policy, Netcool/Impact performs a corresponding update action on the event source. If you perform multiple updates on field values in a policy, Netcool/Impact performs multiple update actions on the underlying data source.
Examples
The following examples show how to update the Summary and Severity fields in an incoming event.
@Summary = "Node down"; @Summary = @Summary + ": Updated by Netcool/Impact"; @Severity = 3; @Severity = @Severity + 1;
150
Adding Journal Entries to Events

To add a journal entry to an event, you do the following: Assign the journal text to the JournalEntry variable Send the event to the event source using the ReturnEvent function
Assigning the JournalEntry Variable

JournalEntry is an event state variable used to add new journal entries to an event. Netcool/Impact uses special rules for interpreting string literals assigned to JournalEntry. Text stored in JournalEntry must be assigned using single quotation marks, with the exception of special characters such as \r, \n and \t, which must be assigned using double quotation marks. If you want to use both kind of text in a single entry, you must specify them separately and then concatenate the string using the + operator. To embed a line break in a journal entry, you use an \r\n string. The following examples show how to assign journal text to the JournalEntry variable.
@JournalEntry @JournalEntry @JournalEntry Modified = Modified by Netcool/Impact; = Modified on + LocalTime(GetDate()); = Modified on + LocalTime(GetDate()) + "\r\n" + by Netcool/Impact;
Sending the Event to the Event Source

After you have assigned text to the JournalEntry variable, you can send the event to the event source using the ReturnEvent function. To send the event, call ReturnEvent and pass the event container as an input parameter. The following example shows how to send an event using ReturnEvent.
ReturnEvent(EventContainer);
Example
The following example shows how to add a new journal entry to an incoming event.
// Assign the journal entry text to the JournalEntry variable @JournalEntry = Modified on + LocalTime(GetDate()) + "\r\n" + Modified by Netcool\Impact.; // Send the event to the event source using ReturnEvent ReturnEvent(EventContainer);
151
Sending New Events

To send new events to an event source, you do the following: Create a new event container using the NewEvent function Populate the event fields Add a journal entry (optional) Send the event to the data source using the ReturnEvent function
Creating a New Event Container

To create a new event container, you call the NewEvent function and pass the name of the event reader associated with the event source. The function returns an empty event container. The following example shows how to create a new event container:
MyEvent = NewEvent("defaulteventreader");
Populating the Event Fields

After you have created the new event container, you can populate the event fields by assigning values to its event field variables. The following example shows how to populate the event field variables:
MyEvent.Node = "192.168.1.1"; MyEvent.Summary = "Node down"; MyEvent.Severity = 5; MyEvent.AlertKey = MyEvent.Node + ":" + MyEvent.Summary;
Adding a Journal Entry

You can also add a journal entry to the event by setting the value of the JournalEntry variable. The following example shows how to add a journal entry:
MyEvent.JournalEntry = Modified on + LocalTime(GetDate()) + "\r\n" + Modified by Netcool/Impact";
For more information on adding journal entries, see "Assigning the JournalEntry Variable" on page 151.

To send the event to the event source, you call the ReturnEvent function and pass the new event container as an input parameter.
152
The following example shows how to send the event to the event source.
ReturnEvent(MyEvent);
Example
The following example shows how to create, populate and send a new event to an event source.
// Create a new event container MyEvent = NewEvent("defaulteventreader"); // Populate the event container member variables MyEvent.Node = "192.168.1.1"; MyEvent.Summary = "Node down"; MyEvent.Severity = 5; MyEvent.AlertKey = MyEvent.Node + ":" + MyEvent.Summary; // Add a journal entry (optional) MyEvent.JournalEntry = Modified on + LocalTime(GetDate()) + "\r\n" + Modified by Netcool/Impact"; // Send the event to the event source ReturnEvent(MyEvent);
Deleting Events
To delete an incoming event from the event source, you do the following: Set the DeleteEvent variable in the event container Send the event to the event source using the ReturnEvent function
Setting the DeleteEvent Variable

The DeleteEvent variable is an event state variable that you use to specify that an event is to be deleted when it is sent back to the event source. You must set the value of DeleteEvent to True in order for an event to be deleted. The following example shows how to set the DeleteEvent variable.
@DeleteEvent = True;

After you have set the DeleteEvent variable, you can send the event to the event source using the ReturnEvent function.
153
The following example shows how to send an event using ReturnEvent.

ReturnEvent(EventContainer);
Example
The following example shows how to delete an incoming event from the event source.
// Set the DeleteEvent Variable @DeleteEvent = True; // Send the event to the event source ReturnEvent(EventContainer);
154
15_Handling_Data.fm November 30, 2006
Chapter 16. Handling Data

This chapter contains information about handling data in a Netcool/Impact policy. It contains the following sections: "About Data" on page 155 "About Data Items" on page 156 "Retrieving Data By Filter" on page 156 "Retrieving Data By Key" on page 162 "Retrieving Data By Link" on page 164 "Adding Data" on page 167 "Updating Data" on page 168 "Deleting Data" on page 170 "Calling Database Functions" on page 173
About Data
This section contains overview information about handling data in a Netcool/Impact policy. It contains the following topics: What Kind of Data Can I Handle in a Policy? What Can I Do with Data in a Policy?
What Kind of Data Can I Handle in a Policy?

Netcool/Impact allows you to access data stored in a wide variety of data sources. These include many popular commercial databases, such as Oracle, Sybase and Microsoft SQL Server. You can also access data stored in LDAP data source and data stored by a variety of third-party applications, including network inventory managers and messaging systems.
What Can I Do With Data in a Policy?

You can perform the following tasks on data from within a policy: Retrieve data from a data source by filter Retrieve data from a data source by key Retrieve data from a data source by link
155
Add data to a data source Update data in a data source Delete data in a data source Call database functions Call stored procedures
About Data Items

This section contains overview information about data items. It contains the following topics: What Is a Data Item? What Are Field Variables? What Are the DataItems and DataItem Variables?
What Are Data Items?

Data items are elements of the data model that represent actual units of data stored in a data source. The structure of this unit of data depends on the category of the associated data source. For example, if the data source is an SQL database, each data item corresponds to a row in a database table. If the data source is an LDAP server, each data item corresponds to a node in the LDAP hierarchy.
What Are Field Variables?

Field variables are member variables in an data item. There is one field variable for each data item field. Field variable names are the same as the names in the underlying data item fields. For example, if you have a data item with two fields named UserID and UserName, it will also have two field variables named UserID and UserName.
What Are the DataItems and DataItems Variables?

The DataItems variable is a built-in variable of type array that is used by default to store data items returned by GetByFilter, GetByKey, GetByLinks or other functions that retrieve data items. If you do not specify a return variable when you call these functions, Netcool/Impact assigns the retrieved data items to the DataItems variable. The DataItem variable references the first item (index 0) in the DataItems array.
Retrieving Data By Filter

This section contains information on retrieving data from a data item by filter.
156
It contains the following sections: What Does It Mean to Retrieve Data By Filter? What Is a Filter? How Do I Retrieve Data By Filter? Examples
What Does It Mean to Retrieve Data By Filter?

Retrieving data by filter means that you are getting data items from a data type where you already know the value of one or more of the fields. When you retrieve data by filter, you are telling Netcool/Impact, "Give me all the data items in this type, where certain fields contain these values."
What Is a Filter?
A filter is a text string that sets out the conditions under which Netcool/Impact retrieves the data items. When you compose the filter string, you are telling Netcool/Impact, "Give me all the data items in this type, where the value of the Location field is New York," or "Give me all the data items in this type, where the IPAddress field is 192.168.1.1." The format of the filter string varies depending on the category of the data type.
SQL Filters
For SQL database and internal data types, the filter is an SQL WHERE clause that provides a set of comparisons that must be true in order for a data item to be returned. These comparisons are typically between field names and their corresponding values. The type of comparison is specified by one of the standard comparison operators (<, >, =, <=, >=, != and LIKE). Multiple comparisons can be used together with the AND and NOT operators. Any string literals in an SQL filter must be enclosed in single quotation marks. For SQL database data types, the syntax of the SQL filter is specified by the underlying data source. When Netcool/Impact goes to the data source to retrieve the data items, it passes this filter directly to the data source for processing. For internal data types, the SQL filter is processed internally by Netcool/Impact. The following examples show some typical SQL filters.
157
To get all data items where the value of the Location field is New York:
Location = New York
To get all data items where the value of the Location field is New York or New Jersey:
Location = New York OR Location = New Jersey
To get all data items where the value of the Location field is Chicago or Los Angeles and the value of the Level field is 3:
(Location = New York OR Location = New Jersey) AND Level = 3
Complete syntax and additional examples for SQL filters are provided in the Netcool/Impact Policy Reference Guide.
LDAP Filters
For LDAP database types, the filter is an LDAP filter string as described in Internet RFC 2254. As with SQL filters, LDAP filters provide a set of comparisons that must be true in order for a data item to be returned. These comparisons are typically between field names and their corresponding values. The comparison operators supported in LDAP filters are =, ~=, <, <=, >, >= and !. One difference between LDAP filters and SQL filters is that any boolean operators used to specify multiple comparisons must be prepended to the expression. Another difference is that string literals are not specified using quotation marks. The following examples show some typical LDAP filters. To get all data items where the common name value is Mahatma Gandhi:
(cn=Mahatma Gandhi)
To get all data items where the value of the location attribute does not begin with the string NYC.
(!(location=NYC*))
To get all data items where the value of the facility attribute is Wandsworth or Putney:
(|(facility=Wandsworth)(facility=Putney))
Complete syntax and additional examples for LDAP filters are provided in the Netcool/Impact Policy Reference Guide.
Mediator Filters
The syntax for Mediator filters vary depending on the underlying DSA. For more information on the Mediator syntax for a particular DSA, see the DSA documentation.
158
How Do I Retrieve Data By Filter?

To retrieve data by filter, you call the GetByFilter function and pass the name of the data type and the filter string. The function returns an array of data items that match the conditions in the filter. If you do not specify a return variable, GetByFilter assigns the array to the built-in variable DataItems.
Examples
The examples below show how to retrieve data by filter.
Example 1
The following example shows how to retrieve data from an SQL database data type. In this example, you get all of the data items from a data type named Node where the value of the Location field is New York and the value of the TypeID field is 012345. Then, you print the data item fields and values to the policy log using the Log and CurrentContext functions.
// Call GetByFilter and pass the name of the data type // and the filter string. DataType = "Node"; Filter = "Location = New York AND TypeID = 012345"; CountOnly = False; MyNodes = GetByFilter(DataType, Filter, CountOnly); // Log the data item field values. Log(CurrentContext());
A shorter version of this example is as follows:

MyNodes = GetByFilter("Node", "Location = New York AND TypeID = 012345", False); Log(CurrentContext());
159
Example 2
The following example also shows how to retrieve data from an SQL database data type. In this example, you get all of the data items from a data type named Node where the value of the IPAddress field equals the value of the Node field in an incoming event. As above, you print the fields and values in the data items to the policy log.
// Call GetByFilter and pass the name of the data type // and the filter string. DataType = "Node"; Filter = "IPAddress = " + @Node + ""; CountOnly = False; MyNodes = GetByFilter(DataType, Filter, CountOnly); // Log the data item field values. Log(CurrentContext());
Make sure that you understand the filter syntax used in the sample code above. When using the value of a variable inside an SQL filter string, the value must be encapsulated in single quotation marks. This is because Netcool/Impact processes the filter string in two stages. During the first stage, it evaluates the variable. During the second stage, it concatenates the filter string and sends it to the data source for processing. A shorter version of this example is as follows:
MyNodes = GetByFilter("Node", "Location = " + @Node + "", False); Log(CurrentContext());
Example 3
The following example shows how to retrieve data from an LDAP data type. In this example, you get any data items from a data type named User where the value of the cn (common name) field is Brian Huang. Then, you print the data item fields and values to the policy log using the Log and CurrentContext functions.
// Call GetByFilter and pass the name of the data type // and the filter string. DataType = "User"; Filter = "(cn=Brian Huang)"; CountOnly = False; MyUsers = GetByFilter(DataType, Filter, CountOnly); // Log the data item field values. Log(CurrentContext());
160

MyUsers = GetByFilter("User", "(cn=Brian Huang)", False); Log(CurrentContext());
Example 4
The following example also shows how to retrieve data from an LDAP data type. In this example, you get all data items from a data type named Node where the value of the Location field is New York or New Jersey. As above, you print the fields and values in the data items to the policy log.
// Call GetByFilter and pass the name of the data type // and the filter string. DataType = "Node"; Filter = "(|(Location=NewYork)(Location=New Jersey))"; CountOnly = False; MyNodes = GetByFilter(DataType, Filter, CountOnly); // Log the data item field values Log(CurrentContext());

MyNodes = GetByFilter("Node", "(|(Location=New York)(Location=New Jersey))", False); Log(CurrentContext());
Example 5
The following example shows how to look up data from a Smallworld DSA Mediator data type. Smallworld is a network inventory manager developed by GE Network Solutions. Netcool/Impact provides a Mediator DSA and a set of predefined data types that allow you to read network data from the Smallworld NIS. In this example, the you get all of the data items from the SWNetworkElement data type where the value of ne_name is DSX1 PNL-01 (ORP). Then, you print the data item fields and values to the policy log using the Log and CurrentContext functions.
// Call GetByFilter and pass the name of the data type // and the filter string. DataType = "SWNetworkElement"; Filter = "ne_name = DSX1 PNL-01 (ORP)"; CountOnly = False; MyElements = GetByFilter(DataType, Filter, CountOnly); // Log the data item field values. Log(CurrentContext());
161

MyElements = GetByFilter("SWNetworkElement", "ne_name = NSX1 PNL-01 (ORP)", False); Log(CurrentContext());
Retrieving Data By Key

This section contains information on retrieving data by key. It contains the following topics: What Does It Mean to Retrieve Data By Key? What Is a Key? How Do I Retrieve Data By Key? Examples
What Does It Mean to Retrieve Data By Key?

Retrieving data by key means that you are getting data items from a data type where you already know the value one or more key fields. When you retrieve data items by key, you are telling Netcool/Impact, "Give me a certain number of data items in this type, where the key fields equal these values." Because key fields typically designate a unique data item, the number of data items returned is usually one.
What Is a Key?
A key is a special field in a data type that uniquely identifies a data item. You specify key fields when you create a data type. The most common way to use the key field is to use it to identify a key field in the underlying data source. For more information on data type keys, see "Data Type Keys" on page 38.
What Is a Key Expression?

The key expression is a value or array of values that key fields in the data item must equal in order to be returned. Netcool/Impact supports both single key and multiple key expressions.
Single Key Expressions

A single key expression is an integer, float or string that specifies the value that the key field in a data item must match in order to be retrieved.
Multiple Key Expressions

A multiple key expression is an array of values that the key fields in a data item must match in order to be retrieved.
162
Netcool/Impact determines if the key field values match by comparing each value in the array with the corresponding key field on a one-by-one basis. For example, if you have a data type with two key fields named Key_01 and Key_02 and you use a key expression of {"KEY_12345", "KEY_93832"}, the function compares KEY_12345 with the value of Key_01 and KEY_93832 with the value of Key_02. If both fields match the specified values, the function returns the data item. If only one field or no fields match, the data item is not returned.
How Do I Retrieve Data By Key?

To retrieve data by key, you call the GetByKey function and pass the name of the data type and the filter string. The function returns an array of data items that match the conditions in the filter. If you dont specify a return variable, GetByKey assigns the array to the built-in variable DataItems.
Examples
The examples below show how to retrieve data by key.
Example 1
The following example shows how to return data from a data type using a single key expression. In this example, you retrieve a data item from a data type called Node where the value of the key field is ID-00001. Then, you print the data item fields and values to the policy log using the Log and CurrentContext functions.
// Call GetByKey and pass the name of the data type // and the key expression. DataType = "Node"; Key = "ID-00001"; MaxNum = 1; MyNodes = GetByKey(DataType, Key, MaxNum); // Log the data item field values. Log(CurrentContext());

MyNodes = GetByKey("Node", "ID-00001", 1); Log(CurrentContext());
163
Example 2
The following example shows how to return data by key using a multiple key expression. In this example, you retrieve a data item from a data type called Customer where the value of its key fields are R12345 and D98776. As above, you print the fields and values in the data items to the policy log.
// Call GetByKey and pass the name of the data type. // the key expression. Type = "Customer"; Key = {"R12345", "D98776"}; MaxNum = 1; MyCustomers = GetByKey(Type, Key, MaxNum); // Log the data item field values. Log(CurrentContext());

MyCustomers = GetByKey("Customer", {"R12345", "D98776"}, 1); Log(CurrentContext());
Retrieving Data By Link

This section contains information on retrieving data by link. It contains the following topics: What Does It Mean to Retrieve Data By Link? What Is a Link? How Do I Retrieve Data By Link? Examples
What Does It Mean to Retrieve Data By Link?

Retrieving data by link means that you are getting data items from a data type that are linked to one or more data items that you have previously retrieved. When you retrieve data items by link, you are telling Netcool/Impact, "Give me data items in these data types that are linked to these data items that I already have." The data items that you already have are called the source data items. The data items that you want to retrieve are known as the targets.
164
What Is a Link?
A link is an element of the data model that defines a relationship between different units or sets of data. Netcool/Impact supports two type of links: dynamic links and static links. Dynamic links define a relationship between two data types. Static links define a relationship between two data items. For more information on links, see Chapter 6. "Working with Links" on page 53.
How Do I Retrieve Data By Link?

To retrieve data items by link, you call must first retrieve source data items using GetByFilter, GetByKey or another call to GetByLinks. Then, you call GetByLinks and pass an array of target data types and the sources. The function returns an array of data items in the target data types that are linked to the source data items. Optionally, you can specify a filter that defines a subset of target data items to return. You can also specify the maximum number of returned data items.
Examples
The examples below show how to retrieve data by link.
Example 1
This example shows how to retrieve data by link. In this example, you call GetByFilter and retrieve a data item from the Node data type whose Hostname value matches the Node field in an incoming event. Then you call GetByLinks to retrieve all of the data items in the Customers data type that are linked to the Node. In this example, you print the fields and values in the data items to the policy log before exiting.
// Call GetByFilter and pass the name of the data type // and the filter string. DataType = "Node"; Filter = "Hostname = " + @Node + ""; CountOnly = False; MyNodes = GetByFilter(DataType, Filter, CountOnly); // Call GetByLinks and pass the target data type, // the maximum number of data items to retrieve and // the source data item. DataTypes = {"Customer"}; Filter = ""; MaxNum = "10000"; DataItems = MyNodes; MyCustomers = GetByLinks(DataTypes, Filter, MaxNum, DataItems); // Log the data item field values. Log(CurrentContext()); Chapter 16. Handling Data 165
A shorter version of this example is:

MyNodes = GetByFilter("Node", "Hostname = " + @Node + "", False"); MyCustomers = GetByLinks({"Customer"}, "", 10000, MyNodes); Log(CurrentContext());
Example 2
This example also shows how to retrieve data by link. In this example, you use a link filter to specify a subset of data items in the target data type to return. As above, you call GetByFilter and retrieve a data item from the Node data type whose Hostname value matches the Node field in an incoming event. Then you call GetByLinks to retrieve all of the data items in the Customers data type whose Location is New York that are linked to the Node. You then print the fields and values in the data items to the policy log before exiting.
// Call GetByFilter and pass the name of the data type // and the filter string. DataType = "Node"; Filter = "Hostname = " + @Node + ""; CountOnly = False; MyNodes = GetByFilter(DataType, Filter, CountOnly); // Call GetByLinks and pass the target data type, // the maximum number of data items to retrieve and // the source data item. DataTypes = {"Customer"}; Filter = "Location = New York"; MaxNum = "10000"; DataItems = MyNodes; MyCustomers = GetByLinks(DataTypes, Filter, MaxNum, DataItems); // Log the data item field values. Log(CurrentContext());
A shorter version of this example is:

MyNodes = GetByFilter("Node", "Hostname = " + @Node + "", False"); MyCustomers = GetByLinks({"Customer"}, "Location = New York", 10000, MyNodes); Log(CurrentContext());
166
Adding Data
To add a data item to a data type, you do the following: Create a new context using the NewObject function Populate the member variables in the context Add the data item
Creating a New Context

The first step in adding a data item is to create a new context using the NewObject function. The following example shows how to create a new context named MyNode.
MyNode = NewObject();
Populating Context Member Variables

After you have created the context, you can populate its member variables with data that corresponds to the values you want to set in the new data item. The name of each member variable must be exactly as it appears in the data type definition. The following example shows how to populate the member variables in the context.
MyNode.Name = "Achilles"; MyNode.IPAddress = "192.168.1.1"; MyNode.Location = "London";
Adding the Data Item

You can add the data item to the data type by calling the AddDataItem function and passing the name of the data type and the context as input parameters. The following example shows how to add the data item to a data type.
AddDataItem("Node", MyNode);
167
Example
The following example shows how to add a data item to a data type. In this example, the data type is named User. The User data type contains the following fields: Name, Location and ID.
// Create new context. MyUser = NewObject(); // Populate the member variables in the context. MyUser.ID = "00001"; MyUSer.Name = "Jennifer Mehta"; MyUser.Location = "New York"; // Call AddDataItem and pass the name of the data type // and the context. DataType = "User"; AddDataItem(DataType, MyUser);
A shorter version of this example would be as follows:

MyUser=NewObject(); MyUser.ID = "00001"; MyUser.Name = "Jennifer Mehta"; MyUser.Location = "New York"; AddDataItem("User", MyUser);
Updating Data
This section contains information on deleting data items from a data type. It contains the following topics: Updating Single Data Items Updating Multiple Data Items
Updating Single Data Items

To update single a data item, you must first retrieve the data from the data type using GetByFilter, GetByKey or GetByLinks. Then you can update the data item fields by changing the values of the corresponding field variables. When you change the value of the field variables, the values in the underlying data source are updated in real time. This means that every time you set a new field value, Netcool/Impact requests an update at the data source level.
168
The following example shows how to update a single data item. In this example, you call GetByFilter and retrieve a data item from a data type called Node. Then you change the value of the corresponding field variables.
// Call GetByFilter and pass the name of the data type // and the filter string. DataType = "Node"; Filter = "Location = " + @Node + ""; CountOnly = False; MyNodes = GetByFilter(DataType, Filter, CountOnly); MyNode = MyNodes[0]; // Update the values of the field variables in MyNode // Updates are made in real time in the data source MyNode.Name = "Host_01"; MyNode.ID = "00001"; // Log the data item field values. Log(CurrentContext());

MyNodes = GetByFilter("Node", "Location = " + @Node + "", False); MyNodes[0].Name = "Host_01"; MyNodes[0].ID = "00001"; Log(CurrentContext());
Updating Multiple Data Items

To update multiple data items in a data type, you call BatchUpdate and pass the name of the data type, a filter string that specifies which data items to update and an update expression. Netcool/Impact updates all of the matching data items with the specified values. The update expression uses the same syntax as the SET clause in the UPDATE statement supported by the underlying data source. This clause consists of a comma-separated list of the fields and values to be updated. Updating multiple data items is only supported for SQL database data types.
169
The following example shows how to update multiple data items. In this example, you update all of the data items in the Customer data type whose Location is New York. The update changes the values of the Location and Node fields. Then, you retrieve the same data items using GetByFilter to verify the update. Before exiting, you print the data item field values to the policy log.
// Call BatchUpdate and pass the name of the data type, // the filter string and an update expression DataType = "Customer"; Filter = "Location = New York"; UpdateExpression = "Location = London, Node = Host_02"; BatchUpdate(DataType, Filter, UpdateExpression); // Call GetByFilter and pass the name of the data type // and a filter string DataType = "Customer"; Filter = "Location = London"; CountOnly = False; MyCustomers = GetByFilter(DataType, Filter, CountOnly); // Log the data item field values. Log(CurrentContext());

BatchUpdate("Customer", "Location = New York", "Location = London, Node = Host_02"); MyCustomers = GetByFilter("Customer", "Location = London", False); Log(CurrentContext());
Deleting Data
This section contains information on deleting data items from a data type. It contains the following topics: Deleting Single Data Items Deleting Multiple Data Items
Deleting Single Data Items

Before you can delete a single data item from a data type, you must first retrieve it from the data source. You can retrieve the data item using the GetByFilter, GetByKey or GetByLinks functions. After you have retrieved the data item, you can call the DeleteDataItem function and pass the data item as an input parameter.
170
Example
The following example shows how to delete a data item. In this example, you delete a data item from a data type named User where the value of the Name field is John Rodriguez. Because the data type (in this case) only contains one matching data item, you can reference it as MyUsers[0].
// Call GetByFilter and pass the name of the data type // and the filter string. DataType = "User"; Filter = "Name = John Rodriguez"; CountOnly = False; MyUsers = GetByFilter(DataType, Filter, CountOnly); MyUser = MyUsers[0]; // Call DeleteDataItem and pass the data item. DeleteDataItem(MyUser);

MyUsers = GetByFilter("User", "Name = John Rodriguez", False); DeleteDataItem(MyUsers[0]);
Deleting Multiple Data Items

To delete multiple data items, you call the BatchDelete function and pass it the name of the data type, and either a filter or the data items you want to delete.
Deleting Data Items By Filter

When you delete data items by filter, you are telling Netcool/Impact, "Delete all data items in this type, where certain fields contain these values." The filter is a text string that sets out the conditions that a data item must match in order for it to be deleted. The syntax for the filter is that of an SQL WHERE clause that provides a set of comparisons that must be true in order for a data item to be returned. This syntax specified by the underlying data source. When Netcool/Impact goes to the data source to delete the data items, it passes this filter directly to the data source for processing. Deleting data items by filter is only supported for SQL database data types.
171
The following example shows how to delete multiple data items by filter. In this example, you delete all of the data items in a data type named Node, where the value of Location is New York.
// Call BatchDelete and pass the name of the data type // and a filter string that specifies which data items to delete DataType = "Node"; Filter = "Location = New York"; DataItems = NULL; BatchDelete(DataType, Filter, DataItems);

BatchDelete("Node", "Location = New York", NULL);
Deleting Data Items by Item

You can also delete data items by passing them directly to the BatchDelete function as an array. The following example shows how to delete multiple data items by passing them directly to BatchDelete. In this example, you delete all of the data items in a data type named Customer, where the value of Location is London.
// Call GetByFilter and pass the name of the data type // and a filter string DataType = "Customer"; Filter = "Location = New York"; CountOnly = False MyCustomers = GetByFilter(DataType, Filter, CountOnly); // Call BatchDelete and pass the array // returned by GetByFilter BatchUpdate(DataType, NULL, MyCustomers);

MyCustomers = GetByFilter("Customer", "Location = London", False); BatchDelete("Customers", NULL, MyCustomers);
172
Calling Database Functions

Netcool/Impact allows you to call functions that are defined in the underlying data source of an SQL database data type. These functions allow you to obtain such useful data as the number of rows in the database that match a specified filter. To call a database function, you call CallDBFunction and pass the name of the data type, a filter string and the function expression. CallDBFunction then returns the results of the function. CallDBFunction uses the same SQL filter syntax as GetByFilter and BatchDelete. Complete syntax and additional examples for SQL filters are provided in the Netcool/Impact Policy Reference Guide.
Example
The following example shows how to call the database COUNT function within a policy. In this example, you count the number of data items in the Node data type, where the value of the Location field is New York. Then, you print the number of items counted to the policy log.
// Call CallDBFunction and pass the name of the data type, // a filter string and the function expression. DataType = "Node"; Filter = "Location = New York"; Function = "COUNT()"; NumItems = CallDBFunction(DataType, Filter, Function); // Print the number of counted items to the policy log. Log(NumItems);

NumItems = CallDBFunction("Node", "Location = New York", "COUNT()"); Log(NumItems);
173
174
16_Handling_Hibernations.fm November 30, 2006
Chapter 17. Handling Hibernations

This chapter contains information about handling hibernations in a Netcool/Impact policy. It contains the following sections: "About Hibernations" on page 175 "Hibernating a Policy" on page 176 "Retrieving Hibernations" on page 177 "Waking a Hibernation" on page 179 "Removing Hibernations" on page 179
About Hibernations
This section contains overview information about hibernations. It contains the following topics: What Are Hibernations? What Is the Hibernation Data Type? What Are Action Keys? What Is the Hibernation Timeout Value? What Can I Use Hibernations For? What Can I Do with Hibernations in a Policy?
What Are Hibernations?

Hibernations are policies that have been temporarily put to sleep. While a policy is asleep, it is stored internally at its current state and all processing is paused until it is woken by the hibernating policy activator service or by another policy.
What Is the Hibernation Data Type?

The Hibernation data type is a system data type that stores hibernating policies. You do not typically create or modify Hibernation data items using the Netcool/Impact GUI. However, you can use the GUI to delete stored hibernations in the case that an error condition occurs and the hibernations are not woken by the hibernation policy activator or another policy.
175
What Are Action Keys?

An action key is a string that uniquely identifies a hibernation. When you hibernate a policy, you must specify a unique action key.
What Is the Hibernation Timeout Value?

The hibernation timeout value is the number of seconds that a policy hibernates before it can be woken by the hibernating policy activator. The hibernation timeout value does not affect the time at which the hibernation can be woken by another policy.
What Can I Use Hibernations For?

Hibernations are designed to be used in X events in Y time solutions. This type of solution monitors an event source for a certain number of same events to occur within a time frame, it takes the designated event management action (for example, notifying an administrator of a repeating event condition).
What Can I Do with Hibernations in a Policy?

You can cause a policy to hibernate. You can also wake a hibernating policy or remove hibernations.
Hibernating a Policy
To hibernate a policy, you call the Hibernate function and pass an action key and the number of seconds for it to hibernate. The action key can be any unique string you want to use to identify the policy. Typically, you obtain this string by doing any combination of the following: Use the value of the Identifier field in an incoming ObjectServer event. The ObjectServer generates a unique Identifier value for each event. Use the Random function to generate a random value. Use the GetDate function to generate a value based on the current system time. This is only appropriate for scenarios in which you are processing or fewer events per second.
176
Examples
The following examples show how to hibernate a policy.
Example 1
In this example, the action key is the value of the Identifier field in an incoming ObjectServer event. This policy will hibernate for sixty seconds before being woken by the hibernating policy activator.
// Call Hibernate and pass an action key and the timeout // value for the hibernation. ActionKey = @Identifier; Reason = NULL; Timeout = 60; Hibernate(ActionKey, Reason, Timeout);
A shorter version of this policy is as follows.

Hibernate(@Identifier, NULL, 60);
Example 2
In this example, the action key is a combination of the current system time and a random value. This policy will hibernate for two minutes before being woken by the hibernating policy activator.
// Call Hibernate and pass an action key and the timeout // value for the hibernation. ActionKey = GetDate() + "_" + Random(9999); Reason = NULL; Timeout = 120; Hibernate(ActionKey, Reason, Timeout);
A shorter version of this policy is as follows.

Hibernate(GetDate() + Random(9999), NULL, 120);
Retrieving Hibernations
Retrieving hibernations is the way that you get data items from the Hibernation data type. You must retrieve a hibernation before you can wake it from within a policy or remove it. You can retrieve hibernations by: Action key search Filter
177
Retrieving Hibernations by Action Key Search

You can use the GetHibernatingPolicies function to retrieve hibernations using a lexicographical search of action key values. GetHibernatingPolicies returns an array of Hibernation data items whose action keys fall within the specified start and end action keys. The following example shows how to retrieve hibernations using an action key search. This search returns all of the Hibernation data items whose action keys fall between ActionKeyAAA and ActionKeyZZZ. The example also prints the contents of the policy context to the action tree log.
// Call GetHibernatingPolicies and pass the start action key // and end action key values. StartActionKey = "ActionKeyAAA"; EndActionKey = "ActionKeyZZZ"; MaxNum = 10000; MyHibers = GetHibernatingPolicies(StartActionKey, EndActionKey, MaxNum); Log(CurrentContext());
A shorter version of this example is as follows.

MyHibers = GetHibernatingPolicies("ActionKeyAAA", "ActionKeyZZZ", 10000); Log(CurrentContext());
Retrieving Hibernations By Filter

You can use the GetByFilter function to retrieve hibernations using a filter. GetByFilter returns an array of Hibernation data items whose action keys match the specified filter string. The filter is an SQL filter as defined in "Retrieving Data By Filter" on page 156. The following example shows how to retrieve hibernations using GetByFilter. In this example, you retrieve the Hibernation data item whose action key is 76486467. Then, you print the contents of the current policy context to the policy log.
// Call GetByFilter and pass the name of the data type // and a filter string. DataType = "Hibernation"; Filter = "ActionKey = 76486467"; CountOnly = False; MyHibers = GetByFilter(DataType, Filter, CountOnly); Log(CurrentContext());
A shorter version of this example is as follows.

MyHibers = GetByFilter("Hibernation", "ActionKey = 76486467, False); Log(CurrentContext());
178
Waking a Hibernation
To wake a hibernation, you do the following: Retrieve the hibernation using GetHibernatingPolicies or GetByFilter Call ActivateHibernation
Retrieving the Hibernation

The first step in waking a hibernation is to retrieve it from the Hibernation data type using GetHibernatingPolicies or GetByFilter. This step is described in the previous section of this guide.
Calling ActivateHibernation
After you have retrieved the hibernation, you can call the ActivateHibernation function and pass the data item as an input parameter.
Example
The following example shows how to wake a hibernation. In this example, you wake a hibernation policy whose action key value is ActionKeyABC.
// Call GetHibernatingPolicies and pass the start action key // and end action key values. StartActionKey = "ActionKeyAAA"; EndActionKey = "ActionKeyZZZ"; MaxNum = 10000; MyHibers = GetHibernatingPolicies(StartActionKey, EndActionKey, MaxNum); MyHiber = MyHibers[0]; // Call ActivateHibernation and pass the Hibernation data item as // an input parameter. ActivateHivernation(MyHiber);
Removing Hibernations
To remove a hibernation from the internal data repository, you call the RemoveHibernation function and pass the action key of the hibernation as an input parameter.
179
Example
The following example shows how to remove a hibernation. In this example, the action key for the hibernation is ActionKeyABC.
RemoveHibernation("ActionKeyABC");
180
17_Sending_Email.fm November 30, 2006
Chapter 18. Sending E-Mail

This chapter contains information about sending e-mail in a Netcool/Impact policy. It contains the following sections: "About Sending E-Mail" on page 181 "Sending an E-Mail" on page 181
About Sending E-Mail

Netcool/Impact allows you to send e-mail from within a policy. You can use this feature to send e-mail notification to administrators and end users when a certain event or combination of events occur. Netcool/Impact does not provide a built-in mail server. Before you can send e-mail, you must make sure that an SMTP server is available in your environment. The Netcool/Impact e-mail sender service must also be running before a policy can successfully send e-mail.
Sending an E-Mail
To send e-mail you call the SendEmail function and pass the following information as input parameters: The e-mail address of the recipient The subject line text for the e-mail The body content of the e-mail The name of the e-mail sender
The following example shows how to send an e-mail. In this example, you send the e-mail to the address admin@example.com.
// Call SendEmail and pass the addressee, subject, body content and sender as // input parameters. Address = "admin@example.com"; Subject = "URGENT: Node down"; Message = "URGENT MESSAGE: Node 1237ASDS is not responding to network ping."; Sender = "Netcool/Impact"; ExecuteOnQueue = False; SendEmail(Address, Subject, Message, Sender, ExecuteOnQueue);
Chapter 18. Sending E-Mail
181
182
18_Instant_Messaging.fm November 30, 2006
Chapter 19. Instant Messaging

This chapter contains information about sending and receiving instant messages from within a Netcool/Impact policy. It contains the following sections: "About Netcool/Impact IM" on page 183 "Writing Instant Messaging Policies" on page 184
About Netcool/Impact IM
This section contains overview information about Netcool/Impact instant messaging (IM). It contains the following topics: What Is Instant Messaging? What Is Netcool/Impact IM? What Are the Netcool/Impact IM Components? How Does Netcool/Impact IM Work? How Do I Set Up Netcool/Impact IM?
What Is Instant Messaging?

Instant messaging (IM) is a network service that allows two participants to communicate via text in real time. The most popular IM services are ICQ, AOL Instant Messenger (AIM), Yahoo! Messenger and Microsoft Messenger.
What Is Netcool/Impact IM?

Netcool/Impact IM is a feature that allows you to send and receive instant messages from within a policy. Using this feature, Netcool/Impact can monitor an IM account on any of the most popular services for incoming messages and perform operations when specific messages are received. Netcool/Impact can also send instant messages to any other IM account. This allows you to use IM to notify administrators, operators and other users when certain events occur in your environment. Netcool/Impact IM uses Jabber to send and receive instant messages. Jabber is a set of protocols and technologies that provide the means for two software entities to exchange streaming data over a network. For more information, see the Jabber website at http://www.jabber.org.
183
What Are the Netcool/Impact IM Components?

Netcool/Impact has two types of services that work together with your policies to provide IM functionality. The Jabber reader service listens for incoming instant messages and then starts a specified policy when a new message is received. The Jabber service sends messages to other IM accounts. Netcool/Impact requires access to a Jabber server in order to send and receive instant messages. A list of public Jabber servers is available from the Jabber website at http://www.jabber.org/user/publicservers.php.
How Does Netcool/Impact IM Work?

The Netcool/Impact IM process has the following phases: Message listening Message sending
Message Listening
During the message listening phase, the Jabber reader service listens for new messages from one or more IM accounts. When a new message is received, the Jabber reader creates a new EventContainer and populates it with the contents of the incoming message. Then, the Jabber reader starts the policy specified in its configuration settings and passes it the EventContainer. Netcool/Impact then processes the policy.
Message Sending
Message sending is the phase during which Netcool/Impact sends new messages via the Jabber service. Message sending occurs during the execution of a policy when Netcool/Impact encounters a call to the SendInstantMessage function. When Netcool/Impact processes a call to SendInstantMessage, it passes the message content, recipient and other information to the Jabber service. The Jabber service then assembles the message and sends it to a Jabber server where it is routed to the specified recipient.
How Do I Set Up Netcool/Impact IM?

Before you can send and receive instant messages using a policy, you must set up the Jabber service and the Jabber reader service as described in the Netcool/Impact User Interface Guide. After you have set up these services, you can start writing instant messaging policies using the information in "Writing Instant Messaging Policies" on page 184.
Writing Instant Messaging Policies

You can do the following with instant messages in a Netcool/Impact policy:
184
Handle incoming messages Send messages
Handling Incoming Messages

When the Jabber reader receives an incoming message, it starts the policy specified in the Jabber reader service configuration and passes the contents of the message to the policy using the EventContainer variable. The policy can then handle the incoming message in the same way it handles information passed in an incoming event. When the Jabber reader receives an incoming message, it populates the following fields in the EventContainer variable: From and Body. The From field contains the username of the account from which the message was sent. Body contains the contents of the message. You can access the contents of these fields using either the dot notation or the @ notation.
Sending Messages
You send instant messages from within a policy using the SendInstantMessage function. This function requires you to specify the recipient and the body content of the message. You can also specify a subject, a chatroom ID and whether to send the message directly or put it on the message queue for processing by the command execution manager service. For a complete description of this function, see the Netcool/Impact Policy Reference Guide.
Example
The following example shows how to send and receive instant messages using Netcool/Impact IM. In this example, the Jabber reader service calls the policy whenever an incoming message is received. The policy then confirms receipt of the message and performs a different set of actions, depending on whether the message sender is NetcoolAdmin or NetcoolOps.
// Call SendInstantMessage and pass the name of the recipient and the content // of the message as message parameters To = @From // Recipient is sender of the original message TextMessage = "Message receipt confirmed."; SendInstantMessage(To, NULL, NULL, TextMessage, False); If (@From == "NetcoolAdmin") { Log("Message received from user NetcoolAdmin."); Log("Message contents: " + @Body); If (@From == "NetcoolOps") { Log("Message received from user NetcoolOps."); Log("Message contents: " + @Body); } Else { Log("Message received from unrecognized user."); Log("Message contents: " + @Body);
185
186
19_Executing_Commands.fm November 30, 2006
Chapter 20. Executing External Commands

This chapter contains information about executing external commands from within a Netcool/Impact policy. It contains the following sections: "About External Command Execution" on page 187 "Using the JRExec Server" on page 188 "Command and Response" on page 189
About External Command Execution

This section contains information on external command execution. It contains the following topics: What Is External Command Execution? How Do I Execute External Commands What Kind of External Commands Can I Use?
What is External Command Execution?

External command execution is the process of running external commands, scripts and/or applications from within a policy.
How Do I Execute External Commands?

You can execute external commands using the JRExec server or the command and response feature. The JRExec server is a runnable component of Netcool/Impact that allows you to external commands on the system where the Netcool/Impact server is located. Command and response is a more advanced feature that lets you run interactive and non-interactive programs on both local and remote systems.
What Kind of External Commands Can I Use?

You can execute any type of external command that can be started from a command line. This includes operating system commands, shell scripts and many other types of applications.
187
Using the JRExec Server

This section contains information on using the JRExec server to execute external commands. It contains the following topics: What Is the JRExec Server? How Do I Set Up the JRExec Server? How Do I Execute a Command Using the JRExec Server JRExec Server Logging
What Is the JRExec Server?

The JRExec server is a runnable component of Netcool/Impact that allows you execute external commands on the same system where Netcool/Impact is installed.
How Do I Set Up the JRExec Server?

The JRexec server is installed automatically when you install Netcool/Impact. To start the JRexec server, you enter the following at a command line prompt:
$NCHOME/impact/bin/nci_jrexec
How Do I Execute a Command Using the JRExec Server?

To execute a command using the JRExec server, you call the JRExecAction function and pass the name of the command and any command line arguments as input parameters. You can also pass a value that specifies whether you want the JRExec server to wait for the command to be completed before executing any other commands, or to continue processing without waiting.
Example
The following example shows how to execute an external command using the JRExec server. In this example, you send a page to an administrator using a paging application named pageit that is installed in the /opt/pager/bin directory on the system. The pageit application takes the phone number of the pagee and the return contact number as command line arguments. In this application, the JRExec server waits for the application to finish before continuing to process any other commands.
// Call JRExecAction and pass the command string and // other parameters Command = "/opt/pager/bin/pageit"; Args = {"2125551212", "2126353131"}; ExecuteOnQueue = False; Timeout = 60; JRExecAction(Command, Args, ExecuteOnQueue, Timeout); 188 Impact Version 4.0 Solutions Guide
JRExec Server Logging

If you want to enable logging for the JRExec Server, you must set the following property in the JRExec Server properties file.
impact.jrexecserver.logfile=filename
where filename is the path and filename of the target JRExec Server logfile. The JRExec Server properties file is named jrexecserver.props and is located in the $NCHOME/impact/etc directory.
Command and Response

This section contains information on using command and response to execute external commands from within a policy. It contains the following sections: What Is Command and Response? How Do I Execute Commands Using Command and Response?
What Is Command and Response?

Command and response is a feature of Netcool/Impact that allows you to execute interactive commands on both local and remote systems. Command and response is modeled after the functionality provided by Expect. Expect is a popular system tool that allows you automate interactive processes. For more information on expect, see http://expect.nist.gov.
How Do I Execute Commands Using Command and Response?

The CommandResponse function allows you to execute commands using this feature. To connect to the remote or local system, you call CommandResponse and pass the hostname or IP address, a valid username and password for the system, an initial prompt substring and the port number used by the telnet application (by default, 23). You must also pass a session timeout and expiration value in seconds. CommandResponse connects to the telnet service on the system and returns a new context that identifies the session. To send a command, you set the value of the contexts SendCommand variable to the text of the command. Then, you assign one or more substrings that match the expected response to the contexts ExpectList variable. Netcool/Impact then sends the command to the remote system. If the value of the system response matches one or more of the substrings in the ExpectList array, Netcool/Impact sets the value of the contexts ResponseReceived variable to the full text of the response. To end the remote session, set the value of the contexts Disconnect variable to True.
189
Examples
The following example shows how to send a command to the local system. In this example, you connect to the telnet application running on port 23 on localhost and send the touch command.
// Call CommandResponse and pass the required values as // input paramaters Host = "localhost"; UserName = "user_01"; Password = "p4ssw0rd"; InitialPrompt = "localhost{user_01}:"; Port = 23; Timeout = 60; Expiration = 60; Session = CommandResponse(Host, UserName, Password, InitialPrompt, Port, Timeout, Expiration); // Send command Session.SendCommand = "touch cr_test.txt"; Session.ExpectList = {"ulysses{user_01}:"}; // Disconnect Session.Disconnect = True;
The following example shows how to send a command to a remote system for which you expect a response. In this example, you connect to the telnet application running on port 23 of a system named ulysses and send the ls command.
// Call CommandResponse and pass the required values as // input paramaters Host = "ulysses"; UserName = "user_01"; Password = "p4ssw0rd"; InitialPrompt = "ulysses{user_01}:"; Port = 23; Timeout = 60; Expiration = 60; Session = CommandResponse(Host, UserName, Password, InitialPrompt, Port, Timeout, Expiration); // Set the value of the ExpectList variable to a substring that // matches the expected response Session.SendCommand = "ls"; Session.ExpectList = {"ulysses{user_01}:"};
190
// Print the response received from the remote system to the policy log Log(Session.ResponseReceived); // Disconnect Session.Disconnect = True;
191
192
20_Handling_Strings_And_Arrays.fm November 30, 2006
Chapter 21. Handling Strings and Arrays

This chapter contains information on handling strings and arrays in a policy. It contains the following sections: "Handling Strings" on page 193 "Handling Arrays" on page 197
Handling Strings
The Netcool/Impact policy language allows you to manipulate strings in a variety of ways. You can do the following with strings: Concatenate strings Find the length of a string Split a string into substrings Extract a substring from another string Replace a substring in a string Strip a substring from a string Trim whitespace from a string Change the case of a string Encrypt and decrypt strings
Concatenating Strings
To concatenate strings, you use the addition operator (+). You can concatenate two strings or multiple strings at once. You can also concatenate a string with a numeric value. The following example shows how to concatenate strings.
String1 = "This"; String2 = "is a test"; String3 = String1 + " " + String2; Log(String3); String4 = "The value of X is" + 5; Log(String4);
193
When you run this example, it prints the following to the policy log:
This is a test The value of X is 5
Finding the Length of a String

You can find the length of a string using the Length function. The Length function returns the number of characters is any text string. The following example shows how to use the Length function.
NumChars = Length("This is a test."); Log(NumChars);
15
Splitting a String into Substrings

You can split a string into substrings using the Split function. The Split function takes a string and a set of delimiter characters as input parameters. It returns an array in which each element is a substring. The following example shows how to use the Split function.
MyString = "One, Two, Three, Four."; Delimiters = ",."; MyArray = Split(MyString, Delimiters); Count = Length(MyArray); While (Count > 0) { Index = Count - 1; Log(MyArray[Index]); Count = Count - 1; }
Four Three Two One
Extracting a Substring from Another String

You can extract a substring from another string in the following ways: Using the word position Using regular expression matching
194
Extracting a Substring Using the Word Position

To extract a substring using the word position, you call the Extract function and pass the string and the word position of the substring. The following example shows how to extract a string in this way.
MyString = "This is a test."; MySubstring = Extract(MyString, 2); Log(MySubstring);
is
Extracting a Substring Using Regular Expression Matching

You can use regular expression matching to retrieve a single substring or all substrings from a string. To extract a single substring, you use the RExtract function. The RExtract function takes a string and a regular expressions pattern as input parameters. It returns the first matching substring it finds in the string. To extract all matching substrings, you use the RExtractAll function. As with RExtract, The RExtractAll function takes a string and a regular expressions pattern as input parameters. It returns an array that contains all of the matching substrings.
Replacing a Substring in a String

You can replace a substring in a string using the Replace function. The Replace function takes the string, the substring to replace and its replacement as input parameters. It returns the string after the replacement has been made. The following example shows how to replace a substring.
MyString = "This is a test."; Substring1 = "is a"; Substring2 = "is not a"; MyString = Replace(MyString, Substring1, Substring2); Log(MyString);
This is not a test.
Stripping a Substring from a String

You can strip a substring from a string using the Strip function. The Strip function takes the string and the substring you want to strip as input parameters. It returns the string after the substring has been removed.
195
The following example shows how to strip a substring from a string.

MyString = "This is not a test."; Substring = " not"; MyString = Strip(MyString, Substring); Log(MyString);
This is a test.
Trimming Whitespace from a String

You can trim leading and trailing whitespace from a string using the Trim function. The Trim function takes the string as an input parameter and returns it without any leading or trailing whitespace. The following example shows how to trim the whitespace from a string.
MyString = " This is a test. MyString = Trim(MyString); Log(MyString); ";
This is a test.
Changing the Case of a String

You can change the case of a string to all lower case using the ToLower function. The following example shows how to change a string to lower case.
Log(ToLower("THIS IS A TEST.");
this is a test.
You can change the case of a string to all upper case using the ToUpper function. The following example shows how to change a string to upper case.
Log(ToUpper("this is a test.");
THIS IS A TEST.
Encrypting and Decrypting Strings

The policy language provides a feature that allows you to encrypt and decrypt strings. This feature is useful if you want to handle password data within a Netcool/Impact policy.
196
You can encrypt a string using the Encrypt function. This function takes the string as an input parameter and returns an encrypted version. The following example shows how to encrypt a string.
MyString = Encrypt("password");
You can decrypt a string that you have previously encrypted using the Decrypt function. This function takes an encrypted string as an input parameter and returns the plaintext version. The following example shows how to decrypt a string.
MyString = Decrypt("AB953E4925B39218F390AD2E9242E81A");
Handling Arrays
The Netcool/Impact policy language allows you to do the following with arrays: Find the length of an array Find the distinct values in an array.
Finding the Length of an Array

You can find the number of elements in an array using the Length function. The Length function takes the array as an input parameter and returns its number of elements. The following example shows how to find the number of elements in an array.
Elements = Length({"One", "Two", "Three"}); Log(Elements);
3
Finding the Distinct Values in an Array

You can find the distinct values in an array using the Distinct function. The Distinct function takes the array as an input parameter and returns another array that consists only of the unique, or non-duplicate, elements. The following example shows how to find the distinct values in an array.
MyArray = {"One", "One", "Two", "Three", "Three", "Four"}; MyArray = Distinct(MyArray}; Log(MyArray);
{One, Two, Three}
197
198
21_Event_Enrichment.fm November 30, 2006
Chapter 22. Event Enrichment Tutorial

This chapter contains a tutorial that you can use to learn about event enrichment. It contains the following sections: "Overview" on page 199 "Understanding the Netcool Installation" on page 200 "Understanding the Business Data" on page 200 "Analyzing the Workflow" on page 201 "Creating the Project" on page 202 "Setting Up the Data Model" on page 203 "Setting Up Services" on page 212 "Writing the Policy" on page 214 "Running the Solution" on page 219
Overview
Event enrichment is an automated process in which Netcool/Impact monitors an event source for new events, looks up information related to them in an external data source and then adds the information to them. Event enrichment is one of the most common and valuable things users do with Netcool/Impact. This chapter contains a tutorial that you can use to learn about event enrichment. You should read this chapter and become familiar with the concepts, tasks and other information that it provides before you start developing your own solutions with Netcool/Impact.
Tutorial Goal
The goal of this tutorial is to develop an event enrichment solution that will enhance the value of an existing Netcool installation. This solution should automate common tasks performed manually by the network operators and help to integrate related business data with alerts in the Netcool/OMNIbus ObjectServer. This tutorial leads you through the following steps: Understanding the Netcool installation Understanding the business data Analyzing the workflow in the environment
199
Creating a project Setting up a data model Setting up services Writing an event enrichment policy Configuring the event reader to run the policy Running the complete solution
Sample Environment
This tutorial uses a sample environment that provides the background for understanding various event enrichment concepts and tasks. This environment is a network operations center for a large enterprise where the company has installed and configured Netcool/OMNIbus and is currently using it to manage devices on its network. The sample environment is a scaled down representation of what you might actually find in a real-world operations center. It contains only the network elements and business data needed for this tutorial.
Understanding the Netcool Installation

The first step in this tutorial is to understand the current Netcool installation. Generally, before you start developing any Netcool/Impact solution, you must find out which products in the Netcool suite you have installed and which devices, systems or applications are being monitored in the environment. The Netcool installation in the sample environment consists of Netcool/OMNIbus and a collection of probes that monitor devices on the network. This installation uses two instance of an ObjectServer database named NCOMS that have been set up in a backup/failover configuration. These ObjectServers are located on host systems named NCO_HOST_01 and NCO_HOST_02 and run on the default port of 4100. The probes in this installation monitor a variety of network devices. The details of the devices are not important in this tutorial, but each probe sends the basic set of alert fields to the ObjectServer database, including Node, Summary, Severity, AlertKey, Identifier and Count
Understanding the Business Data

The next step in this tutorial is to understand the location and structure of the business data in your environment. In the sample environment, the company uses instances of the Oracle database to store network inventory information, customer service information and general organizational information about the business.
200
The information you want to use is stored in two databases named ORA_01 and ORA_02. ORA_01 is a network inventory database that stores information on the devices in the network, including their technical specification, facility locations and rack numbers. ORA_02 is a database that contains information about the various departments in the business. These are located on systems named ORA_HOST_01 and ORA_HOST_02 respectively. They run on port 1521
Analyzing the Workflow

After you have found the location and structure of the business data, the next step is to analyze the current event management workflow in your environment. The tutorial work environment is a network operations center. In this center, a number of operators are on duty at all times. They sit in an open work area and each one has access to a console that displays a Netcool/OMNIbus event list. On large projector screens on one wall of the operation center are large map visualizations that provide geographical views into the current network status. As alerts flow to the ObjectServer from the various Netcool probes and monitors installed in the environment, they appear in the event lists available to the operators. Depending on the severity of the alerts, the operators manually perform a set of tasks using the event list tools, third-party applications and normal office tools like cell phones and e-mail. For the sake of this tutorial, you will assume that, among other tasks, the operators are performing the following for each alert whose severity is critical or higher. The operators: Manually acknowledge the alert using the event list. Use an in-house database tool to find information about the device causing the alert. This tool runs a query against the network inventory database and returns technical specifications, the location and other information. Manually copy this information into the journal entry for the alert and update it in the ObjectServer database. Use another in-house tool to look up the business department being served by the device that caused the alert. If the business department is part of a mission critical business function, they increase the severity of the alert and update it in the ObjectServer database.
The operators might perform other actions, like looking up the administrators on call at the facility where the device is located and contacting them by phone or pager. After the problem that caused the alert has been addressed, the operators might also record the resolution in a problem log and delete the alert from the ObjectServer. For this tutorial, however, you will only use the workflow tasks listed above.
201
Creating the Project

After you have finished analyzing the workflow, the next step is to create a new project in the Netcool/Impact GUI. You will use this project to store the data model, services and policies used in this solution. The name of this project is NCI_TUT_01. To create a new project: 1. 2. Open the Netcool/Impact GUI in a web browser and log in. In the Projects tab of the Navigation panel, click the New Project button.
Figure 55. Projects Tab
3.
The Projects window opens.
Figure 56. Projects Window
4.
Enter NCI_TUT_01 in the Project Name field.
202
5. 6.
Click Apply. Click Close.
Setting Up the Data Model

After you have created a new project for this tutorial, the next step is to set up a Netcool/Impact data model. This data model consists of the event sources, data sources and data types required by the event enrichment solution. It also consists of a dynamic link used to define the relationship between the data types. You perform all of the tasks in this step using the Netcool/Impact GUI. To set up the data model, you do the following: Create the event source Create the data sources Create the data types Create the dynamic link
Creating the Event Source

The first task in setting up the data model is to create the event source. As you learned when you investigated the details of the Netcool installation, the example environment has one event source, an ObjectServer named NCOMS. Because you want to tap into the alerts that are stored in this ObjectServer, you must create an event source that represents it in Netcool/Impact. As noted earlier in this book, an event source is a special type of data source that Netcool/Impact can use to represent a physical source of event data in the environment. Since your source of event data is an ObjectServer database, you must create an ObjectServer data source and configure it with the connection information you discovered when you investigated the details of the Netcool installation. To create the event source: 1. 2. In the Netcool/Impact GUI, select the NCI_TUT_01 project from the Projects tab. Open the Data Sources panel in the Navigation panel.
Figure 57. Data Sources Panel
3.
Select ObjectServer from the Sources list.

Chapter 22. Event Enrichment Tutorial 203
4.
Click the New Data Source button. The New Data Source window appears.
Figure 58. New Data Source Window
5. 6. 7. 8. 9.
Enter NCOMS in the Data Source Name field. Enter the name and password of an ObjectServer user in the Username and Password fields. Enter NCO_HOST_01 in the Primary Hostname field. Enter 4100 in the Primary Port field. Click Test Connection to test the ObjectServer connection.
10. Enter NCO_HOST_02 in the Backup Hostname field. 11. Enter 4100 in the Backup Port field. 12. Click Test Connection to test the ObjectServer connection. 13. Click OK.
204
Creating the Data Sources

The next task in setting up the data model is to create the data sources. As you learned when you discovered the location and structure of the business data in your environment, the data you want to use in this solution is located in two Oracle databases named ORA_01 and ORA_02. Since you want to access these databases, you must create a data source that corresponds to each one. To create the data sources: 1. In the Netcool/Impact GUI, open the Data Sources panel in the Navigation panel.
Figure 59. Data Sources Panel
2.
Select Oracle from the Sources list.
205
3.
Click the New Data Source button. The New Data Source window appears.
Figure 60. New Data Source Window
4. 5. 6. 7. 8. 9.
Enter ORACLE_01 in the Data Source Name field. Enter an Oracle username and password in the Username and Password fields. Enter ORA_HOST_01 in the Primary Hostname field. Enter 1521 in the Primary Port field. Enter ORA_01 in the SID field. Click Test Connection to test the ObjectServer connection.
10. Click OK. Repeat the steps in the task above to create another data source that corresponds to the ORA_02 database. Name this data source ORACLE_02.
206
Creating the Data Types

The next task in setting up the data model is to create the data types. As you learned when you discovered the location and structure of the business data in your environment, the data that you want to use is contained in two tables. The first table is called Device and is located in the ORA_01 database. This table contains information about each device on the network. Columns in this table include Hostname, DeviceID, HardwareID, Facility and RackNumber. The second table is called Department and is located in the ORA_02 database. This table contains information about each functional department in the business. Columns in this table include DeptName, DeptID and Location. Since you want to access the data in both of these tables, you must create a new data type for each. These data types will be called Device and Department. To create the data types: 1. In the Netcool/Impact GUI, open the Data Types panel in the Navigation panel.
Figure 61. Data Types Panel
2. 3.
Select Oracle_01 from the data sources list. Click the New Data Type button. A new Data Type Editor tab appears in the Main Work panel of the GUI.
Figure 62. Data Type Editor - General Settings
207
4. 5. 6. 7. 8.
Enter Device in the Data Type Name field. Enter ORACLE_01 in the Data Source Name field. Click Browse and select an icon to use for the data type from the window that appears. Select the Enabled option. Scroll the Data Type Editor tab down so that the Table Description area is visible.
9.
Select Device from the Base Table list. Netcool/Impact queries the Oracle database and populates the Table Description browser with the names of each column in the Device table.
10. Click Refresh.
11. Specify that the DeviceID field is the key field for the data type by selecting the Key option in the DeviceID row. 12. Select Hostname from the Display Name Field list. 13. Click the Save button in the Data Type Editor tab.
14. Click the Close button in the Data Type Editor tab.
Repeat the steps in the task above to create another data type that corresponds to the Department table in the ORA_02 database. Name this data type Department.
Creating a Dynamic Link

The next step is to create a dynamic link between the Device and Department data types. One property of the business data that you are using in this solution is that there is a relationship between devices in the environment and departments in the business. All the devices that reside in a certain facility serve the business departments in the same location. You can make this relationship part of the data model by creating a dynamic link between the Device and Department data types. Once you have created the dynamic link, you can traverse it within a policy using the GetByLinks function. In this relationship, Device is the source data type and Department is the target data type. When you create the link between the two data types, you can define it using the following syntax:
Location = %Facility%
This filter tells Netcool/Impact that Device data items are linked to Department data items if the value of the Location field in the Department is equal to the value of the Facility field in the Device. To create the dynamic link: 1. 2. In the Netcool/Impact GUI, open the Data Types panel in the Navigation panel. Click the name of the Device data type. A new Data Type Editor tab opens in the Main Work panel of the GUI. This editor displays configuration information for the Device data type.
209
3.
Select the Dynamic Links tab in the editor. The Links From This Data Type area appears in the editor.
Figure 65. Data Type Editor- Dynamic Links
210
4.
Click the New Link By Filter button. The Link By Filter window appears.
Figure 66. Link By Filter Window
5. 6.
Select Department from the Target Data Type list. In the Filter ... field, enter the filter string that defines the relationship between the Device and Department list. As noted in the description of this task above, the filter string is Location = '%Facility%'. This means that you want Device data items to be linked to Department data items if the Location field in the Department is the same as the Facility field in the Device. Click OK.
7.
211
8.
9.
Click the Close button in the Data Type Editor tab.
Reviewing the Data Model

After you have created the dynamic links, you can review the data model using the Netcool/Impact GUI to verify that you have performed all of the tasks correctly. You can review the data model by opening the Data Source and Data Type panels in the Navigation panel and making sure that the event source, data sources and data types that you created are visible. The contents of the Navigation panel should appear as follows:
Figure 68. Navigation Pane
Setting Up Services
The next step in this tutorial is to set up the event reader required by the solution.
Creating the Event Reader

The event reader for this solution must check the NCOMS ObjectServer every three seconds and retrieve any new events.
212
To create the event reader: 1. In the Netcool/Impact GUI, open the Services panel in the Navigation panel.
Figure 69. Services Panel
2. 3.
Select Event Reader from the Type list. Click the New Service button. The Event Reader Configuration window appears.
Figure 70. Event Reader Configuration Window
4. 5. 6.
Enter TUT_READER_01 in the Service Name field. Select NCOMS from the ObjectServer Data Source list. Enter 3000 in the Polling Interval field.
213
7. 8.
Select the Startup option. This option specifies whether the service starts automatically when you run Netcool/Impact. Click OK.
Reviewing the Services

After you have created the event reader, you can use the Netcool/Impact GUI to verify that you have performed all of the tasks correctly. To review the service that you created, open the Services panel in the Navigation panel and make sure that the TUT_READER_01 event reader is visible. You can also check to make sure that the event reader appears in the Service Status panel. The contents of the Navigation panel should look as follows: The Service Status panel should appear as follows:
Figure 71. Service Status Panel
Writing the Policy

After you have set up the event reader service, the next step is to write the policy for the solution. This policy is named EnrichEvent and will automatically perform the tasks that you discovered when you analyzed the workflow in the environment. The EnrichEvent policy will perform the following tasks: Look up information about the device causing the alert. Add the information to the journal entry for the alert. Look up the business departments that are served by the device. If one of the business department is part of a mission critical business function, the policy increases the severity of the alert to critical.
This section assumes that you already know how to create, edit and save a policy using the policy editor tools in the Netcool/Impact GUI. For more information on these tools, see the Netcool/Impact User Interface Guide.
214
Looking Up Device Information

The first task that you want the policy to perform is to look up device information related to the alert in the network inventory database. Specifically, you want the policy to retrieve technical specifications for the device causing the alert, as well as information about the facility and the rack number where the device is located. To do this, the policy has to perform a SELECT at the database level on the table that contains the device data and return those rows that are related to the incoming alert. Viewed from the data model perspective, the policy must get data items from the Device data type where the value of the Hostname field is the same as the value of the Node field in the alert. In order to retrieve the data items, you enter the following code into the Netcool/Impact policy editor tab:
DataType = "Device"; Filter = "Hostname = " + @Node + ""; CountOnly = False; MyDevices = GetByFilter(DataType, Filter, CountOnly); MyDevice = MyDevices[0]; If (Length(MyDevices) < 1) { Log("No matching device found."); } If (Length(MyDevices) > 1) { Log("More than one matching device found."); }
Here, GetByFilter is retrieving data items from the Device data type where the value of the Hostname field is equal to the value of the Node field in the incoming alert. The data items are stored in an array named MyDevices. Although GetByFilter is capable of returning more than one data items in the array, you really only expect the array to contain one data item in this situation, as each device in the database has a unique Hostname. The first element of the MyDevices array is assigned to the MyDevice variable so that MyDevice can be used as shorthand later in the policy. Because you want to retrieve one and only one data item from the data type, the policy also prints error messages to the policy log if GetByFilter retrieves less than or more than one.
Adding Device Information to the Journal

The next task that you want the policy to perform is to add the device information that you retrieved to the journal of the incoming alert. To to this, the policy has to set the value of the JournalEntry field in the incoming alert so that it includes the desired information about the device. The information that you want to assign to the journal is contained in the HardwareID, Facility and RackNumber fields of the data item you retrieved previously in the policy.
215
In order to add the information, you enter the following in the policy editor tab below the code you entered above:
@JournalEntry = Device hardware ID is + MyDevice.HardwareID + .; @JournalEntry = 'Device located in ' + MyDevice.Facility + ' facility.'; @JournalEntry = 'Device located on ' + MyDevice.Rack + ' rack.';
When you update the journal entry in this way, Netcool/Impact sends a command to the ObjectServer each time the value of JournalEntry is changed. To reduce the load on the ObjectServer, you can combine these statements into one and use line feed and carriage return characters to enter line breaks in the journal.
@JournalEntry = Device hardware ID is + MyDevice.HardwareID + . + "\r\n" + 'Device located in ' + MyDevice.Facility + ' facility.' + "\r\n" + 'Device located on ' + MyDevice.Rack + ' rack.';
Note that string literals assigned to JournalEntry must be enclosed in single quotes, with the exception of special characters like \r and \n. As with other updates to events in an event source, updates to ObjectServer alerts are made in real time by Netcool/Impact.
Looking Up Business Departments

The next task that you want the policy to perform is to look up the business departments that are served by the device that caused the alert. When you set up the data model for this solution, you created a dynamic link. This link defined the relationship between the devices in the environment and departments in the business. To look up the business departments that are served by the device, the policy has to take the data item that it previous retrieved from the Device data type and traverse the links between it and the Department data type. In order to retrieve the Department data items that are linked to the Device, enter the following into the policy editor below the code you entered above:
DataTypes = {"Department"); Filter = NULL; MaxNum = 10000; MyDepts = GetByLinks(DataTypes, Filter, MaxNum, MyDevices); If (Length(MyDepts) < 1) { Log("No linked departments found."); }
Here, GetByLinks retrieves up to ten thousand Department data items linked to data items in the MyDevices array. Since you are certain that the business has less than ten thousand departments, you can use a large value such as this one to make sure that all Department data items are returned. The returned data items are stored in the MyDepts array. Because you want to at least one data item from the data type, the policy also prints an error message to the policy log if GetByLinks does not return any.
216
Increasing the Alert Severity

The final task that you want the policy to perform is to increase the severity of the alert, if the department that it affects has a mission critical function in the business. For the purposes of this tutorial, the departments in the business whose function are mission critical are the Data Center and Transaction Processing units. To perform this task, the policy has to iterate through each of the Department data items retrieved in the previous step. For each Department, it must test the value of the Name field against the names of the two departments in the business that have mission critical functions. If the Department name is that of one of the two departments, the policy must increase the severity of the alert to Critical.
Count = Length(MyDepts); While (Count > 0) { Index = Count - 1; MyDept = MyDepts[Index]; If (MyDept.Name = "Data Center" || MyDept.Name = "Transaction Processing") { @Severity = 5; } Count = Count - 1; }
Here, you use a While loop to iterate through the elements in the MyDepts array. MyDepts is the array of Department data items returned previously in the policy by a call the GetByLinks. Before the While loop begins, you set the value of the Count variable to the number of elements in the MyDepts array. Each time the loop runs, it tests the value of Count. If Count is greater than zero, the statements inside the loop are executed. If Count is less than or equal to zero, the statements are not executed. Because Count is decremented by one each time the loop is performed, the While loop runs once for each data item in MyDepts. A variable named Index is used to refer the current element in the array. The value of Index is the value of Count minus one, as Netcool/Impact arrays are zero-based structures whose first element is counted as zero instead of one. Inside the loop, the policy uses an If statement to test the name of the current Department in the array against the name of the two mission-critical business departments. If the name of the current Department is matches the mission-critical departments, the policy sets the value of the Severity field in the alert to 5, which signifies a critical severity.
217
Reviewing the Policy

After you have finished writing the policy, you can review it for accuracy and completeness. The following is the entire text of this policy.
// Look up device information DataType = "Device"; Filter = "Hostname = " + @Node + ""; CountOnly = False; MyDevices = GetByFilter(DataType, Filter, CountOnly); MyDevice = MyDevices[0]; If (Length(MyDevices) < 1) { Log("No matching device found."); } // Update event journal @JournalEntry = Device hardware ID is + MyDevice.HardwareID + . + "\r\n" + 'Device located in ' + MyDevice.Facility + ' facility.' + "\r\n" + 'Device located on ' + MyDevice.Rack + ' rack.'; // Look up business departments DataTypes = {"Department"}; Filter = NULL; MaxNum = 10000; MyDepts = GetByLinks(DataTypes, Filter, MaxNum, MyDevices); If (Length(MyDepts) < 1) { Log("No linked departments found."); } // If department is mission-critical, update severity of alert Count = Length(MyDepts); While (Count > 0) { Index = Count - 1; MyDept = MyDepts[Index]; If (MyDept.Name = "Data Center" || MyDept.Name = "Transaction Processing") { @Severity = 5; } Count = Count - 1; }
218
Running the Solution

The final step in this tutorial is to run the event enrichment solution. To start the solution, you simply start the event reader service. The event reader then begins to monitor the ObjectServer and will retrieve any new events that appear. When a new event appears, the event reader brings it back into Netcool/Impact, where it is processed by running the EnrichEvent policy.
219
220
AZ_Appendix.fm November 30, 2006
Appendix A. Glossary
This appendix contains the following section: "Glossary of Terms" on page 221
Glossary of Terms
Action function: An action function is a built-in IPL function that performs a high-level task such as retrieving data from a data source or sending e-mail. Action functions are pre-defined by the IPL and cannot be modified or extended when you write a policy. Assignment operator: The assignment operator is a built-in IPL function that assigns a value to a variable. The assignment operator is =. Boolean operator: A boolean operator is a built-in IPL function that specifies a logical operation of AND, OR or NOT when Netcool/Impact evaluates sets of operations. The boolean operators are &&, || and !. Command execution manager: The command execution manager is the Netcool/Impact service that manages remote command execution via the CommandResponse function in the IPL Command line manager: The command line manager is the service that manages the Netcool/Impact command line interface. Comparison operator: A comparison operator is a built-in IPL function that Netcool/Impact uses to compare two values. The comparison operators are ==, !=, <, >, <= and >=. Control structure: A control structure is a statement block in the IPL that is executed when the terms of the control condition are satisfied. The IPL supports If ... Then ... Else and When control structures. CORBA name service: The CORBA name service is the Netcool/Impact service that provides CORBA naming functionality for mediator DSAs. Data item: A data item is an element of a Netcool/Impact data model that represents an actual unit of data stored in a data source (for example, a row in relational database table). Data model: A data model is an abstract representation of the business data and meta data used in a Netcool/Impact installation. A data model contains data sources, data types, links and event sources. Data source: A data source is an element of a Netcool/Impact data model that represents an external source of data (for example, a relational database).
221
Data source adaptor: A data source adaptor (DSA) is a component of Netcool/Impact that allows the application to access data stored in an external source of data. Data type: A data type is an element of a Netcool/Impact data model that represents a set of data stored in a data source (for example, a table or view in a relational database). Database listener: A database listener is a Netcool/Impact service that listens for incoming messages from an SQL database data source and then triggers policies based on the incoming message data. DSA: See data source adaptor. Dynamic link: A dynamic link is an element of a Netcool/Impact data model that represents a dynamic relationship between data items in data types. E-mail reader: An e-mail reader is a Netcool/Impact service that polls a POP mail server at intervals for incoming e-mail and then triggers policies based on the incoming e-mail data. E-mail sender: An e-mail sender is a Netcool/Impact service that sends e-mail via an SMTP mail server. Event: An event is a set of data that represents a status condition or an activity that has occurred in your environment. Most commonly, events originate with Netcool probes and monitors and are stored in the Netcool/OMNIbus ObjectServer database. Event processor: The event processor is the service responsible for managing events coming into Netcool/Impact via event reader, event listener and e-mail reader services. The event processor manages the incoming event queue and is responsible for sending queued events to the policy engine for processing. Event reader: An event reader is a Netcool/Impact service that monitors an event source for new, updated and/or deleted events and triggers policies based on the event data. See standard event reader and generic event reader. Event source: An event source is a data source that stores and manages events. Most commonly, the event source used by Netcool/Impact is the ObjectServer database. Exception: An exception an occurrence during runtime that changes the normal flow of policy execution. Field: A field is a single named unit of data in a Netcool/Impact event or data item. Filter: A filter is an expression that Netcool/Impact uses to select data (for example, data items in a data type) from a larger set of data. See SQL filter, LDAP filter and Mediator filter. Function: A function is a named set of instructions in the IPL that accepts certain pre-defined input parameters and optionally returns a value or set of values. See action function, parser function and user-defined function. Generic event listener: A generic event listener is a Netcool/Impact service that listens to an external data source for incoming events and triggers policies based on the event data.
222
Generic event reader: A generic event reader is an event reader that monitors an SQL database event source for new and/or modified events and triggers policies based on the event information. GUI server: See Netcool/Impact GUI server. Hibernating policy activator: The hibernating policy activator is the Netcool/Impact service that is responsible for waking hibernating policies. IPL: See Netcool/Impact policy language. Jabber reader: A Jabber reader is a Netcool/Impact service that listens to external instant messaging servers for messages and triggers policies based on the incoming message data. Jabber service: The Jabber service is a Netcool/Impact service that sends instant messages to instant messaging clients like AOL Instant Messenger and Yahoo! Messenger via a Jabber server. JRExec server: See Netcool/Impact JRExec server. JMS DSA: The JMS DSA is a data source adaptor that allows Netcool/Impact to send and receive Java Message System (JMS) messages. Key field: A key field is a field that uniquely identifies a data item in a data type. Key expression: A key expression is an expression specify the value that one or more key fields in a data item must have in order to be retrieved by the GetByKey function in the IPL. LDAP DSA: The LDAP DSA is a data source adaptor that allows Netcool/Impact to read directory data managed by an LDAP server. LDAP filter: An LDAP filter is an expression that Netcool/Impact uses to select data elements located at a location in an LDAP directory tree. The syntax for LDAP filters is specified in Internet RFC 2254. Link: A link is an element of a Netcool/Impact data model that defines a relationship between data types and/or data items. See dynamic link and static link. Mathematic operator: A mathematic operator is a built-in IPL function that performs a mathematic operation on two values. The mathematic operators are +, -, *, / and %. Mediator DSAs: Mediator DSAs are a type of data source adaptor that allows Netcool/Impact to access data provided by third-party systems, devices and applications. The Cramer Dimension DSA is an example of a mediator DSA. NCHOME: NCHOME is an operating system environment variable that identifies the location of Netcool product installations on your file system. The default value for this variable is /opt/ibm/netcool. This variable is referenced as $NCHOME on UNIX platforms and %NCHOME% on Windows platforms. Netcool/Impact database: The Netcool/Impact database is a PostgreSQL database named Impact that is managed by the Netcool database server. This database stores reporting information used by the Netcool/Impact server. See Netcool database server.
223
Netcool database server. The Netcool database server is a specially configured version of PostgreSQL that has been prepared for use with Netcool/Impact and other Netcool products. See Netcool/Impact database. Netcool/Impact GUI server: The Netcool/Impact GUI server is the component of Netcool/Impact that serves the web-based graphical user interface to users web browsers via HTTP. Netcool/Impact JRExec server: The Netcool/Impact JRExec server is the component of Netcool/Impact that executes commands, scripts and applications triggered by the JRExecAction function in the IPL. Netcool/Precision DSA. The Netcool/Precision DSA is a data source adaptor that allows Netcool/Impact to access data managed by the Netcool/Precision application. Netcool/Impact Security Manager: The Netcool Security Manager is the component of the Netcool suite that is responsible for authenticating user logins. Netcool/Impact server: The Netcool/Impact server is the primary component of Netcool/Impact. This component is responsible for maintaining the data model, managing services and running policies. Netcool/Impact policy language: The Netcool/Impact policy language (IPL) is the programming language that you use to write policies. Operator: An operator is a built-in IPL function that assigns a value to a variable, performs an operation on a value or specifies how two values are to be compared in a policy. See assignment operator, mathematic operators, comparison operators, boolean operators and string operators. Parser function: A parser function is a built-in IPL function that performs a low-level task such as converting numeric and date formats or extracting a substring from a string. Parser functions are pre-defined by the IPL and cannot be modified or extended when you write a policy. Policy: A policy is a set of rules and actions that Netcool/Impact is required to perform when certain events or status conditions occur in your environment. Policies are implemented using the IPL. Policy activator: A policy activator is a Netcool/Impact service that runs a specified policy at intervals that you define. Policy logger: The policy logger is the Netcool/Impact services that writes messages to the policy log. Precision DSA: See Netcool/Precision DSA. Precision event listener: The Precision event listener is a Netcool/Impact service that listens to the Netcool/Precision application for incoming messages and triggers policies based on the message data. Security Manager: See Netcool/Impact Security Manager.
224
Self-monitoring service: The self-monitoring service is a Netcool/Impact service that monitors Netcool/Impact for memory and other status conditions and reports them to the Netcool/OMNIbus ObjectServer as events. Service: A service is a runnable sub-component of Netcool/Impact that you control from within the Netcool/Impact GUI. SNMP DSA: The SNMP DSA is a data source adaptor that allows Netcool/Impact to set and retrieve management information stored by SNMP agents. It also allows Netcool/Impact to send SNMP traps and notifications to SNMP managers. Socket DSA: The Socket DSA is a data source adaptor that allows Netcool/Impact to exchange information with external applications using a socket server as the brokering agent. SQL database DSAs: SQL database DSAs are data source adaptors that allow Netcool/Impact to retrieve information from relational databases and other data sources that provide a public interface via JDBC (Java Database Connectivity). SQL database DSAs also allow Netcool/Impact to add, modify and delete information stored in these data sources. SQL filter: An SQL filter is an expression that Netcool/Impact uses to select rows in a database table. The syntax for the filter is similar to the contents of an SQL WHERE clause. Standard event reader: A standard event reader is a Netcool/Impact service that monitors a Netcool/OMNIbus ObjectServer database for new, updated and/or deleted events and triggers policies based on the event data. Static link: A static link is an element of a Netcool/Impact data model that defines a static relationship between data items in internal data types. String operator: A string operator is a built-in IPL function that performs an operation on two strings. Netcool/Impact supports one string operator that you can use for string concatenation. The string concatenation operator is +. User-defined function: A user-defined function is a custom function that you use to organize code in a Netcool/Impact policy. Variable: A variable is an IPL keyword that represents a value or a set of values. WASCE (WebSphere Application Server Community Edition): IBM WASCE is a lightweight Java application server built using Apache Geronimo technology. The Netcool/Impact server and GUI server run as application instances inside a WASCE container by default. Web services DSA: The web services DSA is a data source adapter that allows Netcool/Impact to exchange information with external applications that provide a web services API. XML DSA: The XML DSA is a data source adapter that allows Netcool/Impact to read XML data from strings and files and to read XML data from web servers over HTTP.
225
226
appnotices.fm November 30, 2006
Appendix B. Notices
This appendix contains the following: "Notices" on page 227 "Trademarks" on page 229
Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT
227
LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation 958/NH04 IBM Centre, St Leonards 601 Pacific Hwy St Leonards, NSW, 2069 Australia IBM Corporation 896471/H128B 76 Upper Ground London SE1 9PZ United Kingdom IBM Corporation JBFA/SOM1 294 Route 100 Somers, NY, 10589-0100 United States of America Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us.
228
Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
Trademarks
The following terms are trademarks of International Business Machines Corporation in the United States, other countries, or both: AIX AIX 5L Netcool Intel, Intel Inside (logos), MMX, and Pentium are trademarks of Intel Corporation in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, or service names may be trademarks or service marks of others.
Appendix B. Notices
229
230
im40sgIX.fm November 30, 2006 3:35 pm
Index
A
action functions, 143 arrays, 138, 197 finding distinct values, 197 finding the length, 197 automation, 3 setting up, 30 data types, 33 caching, 48 categories, 34 fields, 36 keys, 38 setting up, 38 database functions, calling, 173 data-handling in a policy, 155 DataItem (built-in variable), 156 DataItems (built-in variable), 156 dynamic links, 54 event state variables, 149 EventContainer (built-in variable), 149 events, 63, 147 adding journal entries to, 151 deleting, 153 sending new, 152
C
command and response, 189 command execution manager, 129 configuration, 129 setting up, 129 command line manager, 130 configuration, 130 setting up, 130 contexts, 139 CORBA name service, 131 configuration, 131 setting up, 131
F
filters, 157 LDAP filters, 158 Mediator filters, 158 SQL filters, 157 functions action, 143 parser, 144 user-defined, 144
E
e-mail sending, 181 event access, 5 event container variables, user-defined, 149 event containers, 148 event enrichment, 7, 13 event fields accessing, 149 updating, 150 variables, 149 event gateway, 14 event gateways, 9 event listeners, 89 configuration, 91 process, 90 setting up, 93 event notification, 9, 14 event readers, 77 architecture, 79 configuration, 81 process, 79 setting up, 83 event sources, 63 Architecture, 66 non-ObjectServer, 65 ObjectServer, 64 setting up, 66 types, 64
G
glossary, 221
D
data adding, 167 deleting, 170 retrieving by filter, 156 retrieving by key, 162 retrieving by link, 164 updating, 168 data access, 6 data items, 156 field variables, 156 data models, 2, 18 architecture, 21 components, 19 examples, 22 setting up, 25 data sources, 27 architecture, 29 categories, 28
H
hibernating policy activator, 127 configuration, 128 setting up, 128 Hibernation data type, 175 hibernations, 175 removing, 179 retrieving, 177 waking, 179
I
If statements, 140 instant messaging, 183 IPL, 135
231
J
Jabber, 183 JRExec server, 188
setting up, 127 policy scope, 137 pre-defined actions, 6
X
x events in y time, 8, 13
K
keys, 162 multiple key expressions, 162 single key expressions, 162
S
services, 2, 72 setting up, 75 types, 73 single key expressions, 162 solutions, 11 setting up, 14 types, 13 SQL filters, 157 static links, 54 strings, 193 changing the case, 196 concatenating, 193 encrypting and decrypting, 196 extracting a substring, 194 finding the length, 194 replacing a substring, 195 splitting into substrings, 194 stripping a substring, 195 trimming whitespace, 196
L
LDAP filters, 158 links, 53 categories, 54 dynamic, 54 setting up, 56 static, 54
M
Mediator filters, 158 multiple key expressions, 162
T N
Netcool GUI Server, 2 Netcool Security Manager, 1 Netcool/Impact policy language, 135 Netcool/Impact Server, 1 third-party integration, 6
U
user-defined functions, 144
P
parser functions, 144 policies, 2, 134 hibernating, 176 policy activators, 121 configuration, 122 setting up, 123 policy context, 136 policy language, 135 policy log, 135 printing to, 137 policy logger, 125 configuration, 125
V
variables event field, 149 event state, 149 user-defined, 138
W
While statements, 141 workflow analysis, 9
232
backmatter.fm November 30, 2006 15-11-2006-Ice.5-IBM
IBM
Restricted Material of IBM Licensed Materials - Property of IBM
Copyright IBM Corporation, 2006 Printed in the United States of America

Impact 40 SG

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Impact 40 SG

Uploaded by

Copyright:

Available Formats

Netcool/Impact

Chapter 3. Data Models . . . . . . . . . . . . . 17

Chapter 1. Getting Started . . . . . . . . . . . . 1

Chapter 2. Netcool/Impact Solutions . . 11

Chapter 4. Working with Data Sources 27

Chapter 6. Working with Links. . . . . . 53

Chapter 5. Working with Data Types . . 33

Chapter 7. Working with Event Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Impact Version 4.0 Solutions Guide

Chapter 10. Working with Event Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Chapter 9. Working with Event Readers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Chapter 11. Working with the Database Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Chapter 13. Working with Other Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Chapter 14. Policy Fundamentals 133

Chapter 12. Working with Policy Activators . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Chapter 16. Handling Data. . . . . . . . . 155

Chapter 15. Handling Events . . . . . . 147

Chapter 17. Handling Hibernations 175

Chapter 20. Executing External Commands . . . . . . . . . . . . . . . . . . . . . . . . . 187

Chapter 21. Handling Strings and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

Chapter 18. Sending E-Mail . . . . . . . . 181

Chapter 19. Instant Messaging . . . . 183

Impact Version 4.0 Solutions Guide

Chapter 22. Event Enrichment Tutorial 199

Appendix A. Glossary. . . . . . . . . . . . . . 221

Appendix B. Notices . . . . . . . . . . . . . . . 227

Impact Version 4.0 Solutions Guide

preface.fm November 30, 2006

About this guide

xvi- Impact Version 4.0 Solutions Guide

Note, Tip, and Warning information

Syntax and Sample subheadings

Impact Version 4.0 Solutions Guide

Netcool/Impact Administration Guide

Netcool/Impact User Interface Guide

Netcool/Impact Policy Reference Guide

Netcool/Impact DSA Reference Guide

Netcool/Impact Online Help

Netcool/Impact Release Notes

Operating system considerations

How to send your comments

xxii Impact Version 4.0 Solutions Guide

01_Getting_Started.fm November 30, 2006

Chapter 1. Getting Started

The Netcool/Impact Software System

The Netcool/Impact Server

The Netcool Security Manager

The Netcool GUI Server

Netcool/Impact As a Development Tool

Impact Version 4.0 Solutions Guide

Netcool/Impact As an Automation Engine

What Do I Do With Netcool/Impact?

Core Netcool/Impact Features

Chapter 1. Getting Started

Impact Version 4.0 Solutions Guide

Chapter 1. Getting Started

Impact Version 4.0 Solutions Guide

Typical Netcool/Impact Implementations

Netcool/Impact and Workflow Analysis

Chapter 1. Getting Started

Impact Version 4.0 Solutions Guide

02_Solutions.fm November 30, 2006