Tivoli Module Builder TivoliReadyQuickStartUser sguide Version 2.4

Transcription

1 Tivoli Module Builder TivoliReadyQuickStartUser sguide Version 2.4

2

3 Tivoli Module Builder TivoliReadyQuickStartUser sguide Version 2.4

4 Tivoli Module Builder QuickStart User s Guide Copyright Notice Copyright (C) IBM Corp All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement or Addendum for Tivoli Products to IBM Customer or License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of Tivoli Systems. Tivoli Systems grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each such reproduction shall carry the Tivoli Systems copyright notice. No other rights under copyright are granted without prior written permission of Tivoli Systems. The document is not intended for production and is furnished as is without warranty of any kind. All warranties on this document are hereby disclaimed including the warranties of merchantability and fitness for a particular purpose. Note to U.S. Government Users -- Documentation related to restricted rights -- Use, duplication, or disclosure is subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp. Trademarks IBM, Tivoli, Tivoli Enterprise, Tivoli Enterprise Console, TME, and Tivoli Ready are trademarks or registered trademarks of International Business Machines Corporation or Tivoli Systems Inc. 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. Microsoft, Windows, Windows NT and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark in the United States and other countries licensed exclusively through The Open Group. Other company, product, and service names mentioned in this document may be the trademarks or service marks of others in the United States, other countries, or both. Notice References in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available in all countries in which Tivoli Systems or IBM operates. Any reference to these products, programs, or services is not intended to imply that only Tivoli Systems or IBM products, programs, or services can be used. Subject to the valid intellectual property or other legally protectable rights of Tivoli Systems or IBM, any functionally equivalent product, program, or service can be used instead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by Tivoli Systems or IBM, are the responsibility of the user. Tivoli Systems or IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, New York , U.S.A. Copyright International Business Machines Corporation All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Preface... ix Who Should Read This Document... ix What This Guide Contains.... x Prerequisite and Related Documents... xi Accessing Online Documentation... xii Accessing the Files on the Product CD-ROM... xii Typeface Conventions... xii Terminology.... xiii Contacting Tivoli Customer Support... xiv Chapter 1. Reviewing Modules... 1 Tivoli Plus Modules... 2 Tivoli GEM Modules... 3 Tivoli IT Director Modules... 3 Chapter 2. Planning to Use the Wizard... 5 Modeling Application Processes and Services... 5 Rules and Conventions... 6 Encoding Rules and Limitations... 6 File System Structure... 7 Naming Conventions... 8 Navigation Conventions Collecting Icon and Help Files Using User Exits and Flat Files Chapter 3. Using the Tivoli Ready QuickStart Wizard 15 Installing the Tivoli Ready QuickStart Wizard Tivoli Module Builder Tivoli Ready QuickStart User s Guide iii

6 Starting the Tivoli Ready QuickStart Wizard Using the Start Stage Using the Define Stage Using the Instrument Stage Using the Finish Stage Additional Customization Chapter 4. Selecting Enablers Chapter 5. Instance Discovery Enablers Selecting an Instance Discovery Enabler Monitor Enabler Dependencies NT Performance Objects Enabler (GEM) NT Service by Program Name Enabler (GEM) NT Services Enabler (GEM) Single Instance Application Enabler (GEM) Specific NT Service Enabler (GEM) Start Up Parameters Enabler (GEM) User Exit Enabler (GEM) User Exit (using File Pack) Enabler (GEM) User ID and Program Enabler (GEM) Chapter 6. Instance Information Enablers Instance Information by User Exit Enabler (GEM) Instance Information by User Exit (using File Pack) Enabler (GEM) Instance Information from Flat File (using File Pack) (GEM) Chapter 7. Inventory Enablers Inventory Signature Enabler (ITD, Plus) iv Version 2.4

7 Chapter 8. Task Enablers Specifying Command Parameters for Task Enablers Generic Task Enabler (GEM, ITD, Plus) Generic Task Enabler, Instance ID Passed In (GEM) IT Director Generic Task (with argument/response bean) Enabler (ITD) Launch Browser Enabler (GEM) Launch Telnet Enabler (GEM) Plus Application Launch Enabler (Plus) Recover Enabler (ITD, Plus) Recover Service Enabler (ITD, Plus) Start Task Enabler (GEM) Generic Start Task Enabler (GEM, ITD, Plus) Start Task using File Pack Enabler (GEM) Start NT Service Enabler (ITD, Plus) Stop NT Service Enabler (ITD, Plus) Stop Task Enabler (GEM) Generic Stop Task Enabler (GEM, ITD, Plus) Stop Task Using Filepack Enabler (GEM) Chapter 9. Monitor Enablers Monitor Enablers and Instance Context Filtering the List of Monitor Enablers Setting Monitor Enabler Thresholds Specifying Monitor Enabler Polling Intervals Polling Intervals for Multiple Instances Specifying Monitor Enabler Response Tasks Monitor Enabler Descriptions Tivoli Module Builder Tivoli Ready QuickStart User s Guide v

8 Custom Monitor Enabler (ITD, Plus) Instance NT Counter Monitor Enabler (GEM) Instance NT Service Monitor Enabler (GEM) Instance Process Attribute Monitor Enabler (GEM) Instance Process Count Monitor Enabler (GEM) Instance Process Time Monitor Enabler (GEM) NT Object Counter with no NT Instance Monitor Enabler (GEM, ITD) NT Object Counter with NT Instance Monitor Enabler (GEM) NT Object Monitor Enabler (ITD) NT Service Monitor Enabler (GEM, ITD, Plus) Predefined DM Monitor Enabler (Plus) Process Attribute Monitor Enabler (GEM) Process Count Monitor Enabler (GEM) Process Monitor Enabler (ITD, Plus) Process Time Monitor Enabler (GEM) State Monitor Enabler (GEM) User Exit Number Monitor Enabler (GEM) User Exit Number using File Pack Monitor Enabler (GEM) User Exit String Monitor Enabler (GEM) User Exit String using File Pack Monitor Enabler (GEM) Chapter 10. Connection Enablers Discover Connections by User Exit Enabler (GEM) Discover Connections by User Exit using File Pack Enabler (GEM) Discover Connections from Flat File using File Pack Enabler (GEM) Support Connection Enabler (GEM) Chapter 11. Event Enablers Custom Adapter Enabler (ITD) vi Version 2.4

9 Custom Adapter Enabler (Plus) Logfile Adapter Enabler (Plus) Using Existing Logfile Adapter Instrumentation Chapter 12. Deployment Enablers Add File to Filepack Enabler (GEM) InstallShield Enabler (ITD, Plus) Plus Module Implementation IT Director Module Implementation InstallShield Deployment Enabler (ITD) Appendix A. Programming User Exits User Exit Requirements Setting Up the Environment Instance Discovery User Exit Calling an Instance Discovery User Exit Instance Discovery User Exit Response Processing the Instance Discovery User Exit Response Monitor User Exits Calling a Monitor User Exit Monitor User Exit Response Processing the Monitor User Exit Response Instance Information User Exit Calling an Instance Information User Exit Instance Information User Exit Response Processing the Instance Information User Exit Response Task User Exit Calling a Task User Exit Task User Exit Response Tivoli Module Builder Tivoli Ready QuickStart User s Guide vii

10 Connection User Exit Calling a Connection User Exit Connection User Exit Response Processing the Connection User Exit Response Appendix B. Flat File Formats Instance Information Flat File File Format Example Discover Connections Flat File File Format Example Index viii Version 2.4

11 Preface The Tivoli Module Builder 2.4 Tivoli Ready QuickStart User s Guide describes how to use the Tivoli Ready QuickStart wizard to create modules that manage applications in Tivoli software environments. The QuickStart wizard supports the creation of the following types of management modules: Tivoli Global Enterprise Manager (Tivoli GEM) modules Tivoli Plus modules Tivoli IT Director modules Who Should Read This Document This document is intended for developers who integrate management of their applications with Tivoli management software. You should have knowledge of the following: The management requirements and features of the application for which you intend to build a management module. For example, you should understand those aspects of the application that are prone to failure or whose function can be facilitated by the Tivoli management software tools. You should also be familiar with the administrative tasks of the managed application, as well as any logfiles or application programming interfaces (APIs) that the managed application offers for retrieving status and performance data. The Tivoli Enterprise software environment, including Tivoli Management Framework, Tivoli Software Distribution, Tivoli Distributed Monitoring, and Tivoli Enterprise Console. The Tivoli IT Director management environment, the Tivoli IT Director Integration Toolkit, and the overall process for generating application management package (AMP) files. More advanced users may also want an understanding of the following: Tivoli Module Builder Tivoli Ready QuickStart User s Guide ix

12 Shell and script programming The Application Management Specification (AMS), an industry-endorsed specification for creating management-ready applications. You can find a copy of the AMS at the following Web site: What This Guide Contains The Tivoli Module Builder 2.4 Tivoli Ready QuickStart User s Guide contains the following chapters: Reviewing Modules This chapter provides conceptual information on generating management modules for the Tivoli GEM, Tivoli IT Director, and Tivoli Plus environments. This chapter assumes you have had some exposure to management modules, in the Tivoli GEM, Plus or IT Director environments. Planning to Use the Wizard This chapter reviews things you need to consider about your application or business system to model it correctly before using the QuickStart wizard. Using the Tivoli Ready QuickStart Wizard This chapter gives an overview of the QuickStart wizard, showing you the general flow of building one or more module types and describing the operation of the graphical user interface (GUI). Selecting Enablers This chapter provides information on predefined implementations that use programming interfaces common to the operating system to observe the application, discover software components, and report on their status. These implementations, called enablers, can be selected and tailored by providing required or optional parameter information. x Version 2.4

13 Chapter 5 through Chapter 12 describe each of the available enablers, their purpose, their required and optional parameters, and other information to help you choose the right ones for your instrumentation needs. Programming User Exits This appendix provides information for defining your own user exits to extend the Tivoli GEM instrumentation created with the QuickStart wizard. Flat File Formats This appendix contains formats for Tivoli GEM enabler flat files and examples of instance information and discovery connection enablers. Prerequisite and Related Documents Management modules interact with various management tools in the Tivoli environment. You can refer to the documentation for these tools when creating a management module. In particular, this guide contains references to the following documentation: For information on creating a Tivoli GEM module, see the Tivoli Global Enterprise Manager Business System Enablement Guide and the Tivoli Global Enterprise Manager Advanced Business System Enablement Guide. For other information on Tivoli GEM, see the Tivoli Global Enterprise Manager User s Guide and Tivoli Global Enterprise Manager Troubleshooting located at the following Web site: You must be a registered user to access this Web site. If you have not registered, when the Username and Password Required prompt is displayed, click Cancel and follow the registration directions. For information on creating a Tivoli Plus module, refer to the Tivoli Module Builder User s Guide. For information on creating an IT Director module, refer to the Tivoli IT Director Integration Toolkit. Included in this toolkit is a document, Managing Applications with Tivoli IT Director, Tivoli Module Builder Tivoli Ready QuickStart User s Guide xi

14 which describes how to use the Tivoli Module Designer to create an application management package to run in the IT Director environment. This document is also available in Microsoft Word format in the \module_dev\examples\it Director folder on the drive where you installed the Tivoli Module Builder. For more information on obtaining the complete toolkit, send an to or call Accessing Online Documentation The Tivoli Module Builder library is available in the following online formats on both the Tivoli Module Builder CD-ROM and the Tivoli Web site: Portable Document Format (.pdf), which you can view or print using the Adobe Acrobat Reader. If you do not already have Adobe Acrobat Reader, you can obtain it for free by clicking the Get Acrobat Reader icon and following the steps that are provided at the Adobe Web site: Hypertext Markup Language (.htm), which you can view using your default Web browser. Accessing the Files on the Product CD-ROM See the Tivoli Module Builder Release Notes for information on accessing the documentation on the product CD-ROM. Typeface Conventions This document uses several typeface conventions for special terms and actions. These conventions have the following meanings: Bold Italics Commands, keywords, file names, authorization roles, flags, universal resource locators (URLs), or other information that you must use literally appear in bold. The names or titles of screen objects also appear in bold. Variables and values that you must provide appear in italics. Words and phrases that are emphasized also appear in italics. xii Version 2.4

15 Terminology Bold Italics New terms appear in bold italics when they are defined in the text. Monospace Code examples, output, and system messages appear in a monospace font. The following table defines the Intel and UNIX terms as they are used in this document. For example, the term Intel refers to the Windows family of platforms, as well as OS/2 platforms. Term Intel UNIX Platform Windows 95 Windows 98 Windows NT Windows 2000 OS/2 AIX Solaris HP/UX For a complete glossary of Tivoli and related terms, refer to the glossary at the following Web site: Tivoli is in the process of changing product names. Products referenced in this manual may still be available under their old names, for example, TME 10 Enterprise Console instead of Tivoli Enterprise Console. Tivoli Module Builder Tivoli Ready QuickStart User s Guide xiii

16 Contacting Tivoli Customer Support For support for this or any other Tivoli product, you can contact Tivoli Customer Support in one of the following ways: Visit our Web site at Send to Customers in the United States can also call TIVOLI8 ( ). International customers should consult the Web site for customer support telephone numbers. You can also review the Customer Support Handbook which is available on our Web site at: When you contact Tivoli Customer Support, be prepared to provide identification information for your company, so that support personnel can assist you more readily. Company identification information may also be needed to access various online services available on the Web site. The Web site offers extensive information, including a guide to support services (the Customer Support Handbook); frequently asked questions (FAQs); and documentation for all Tivoli products, including Release Notes, Redbooks, and Whitepapers. The documentation sets for some product releases are available in both PDF and HTML formats. Translated documents are also available for some product releases. You can order documentation by at swdist@tivoli.com. Please provide the part number or order number of the desired document; alternatively, you can provide the document s title, version number, and date of publication. We are very interested in hearing about your experience with Tivoli products and documentation. We also welcome your suggestions for improvements. If you have comments or suggestions about our documentation, please contact us in one of the following ways: xiv Version 2.4

17 Send to: Fill out our customer feedback survey at: Tivoli Module Builder Tivoli Ready QuickStart User s Guide xv

18 xvi Version 2.4

19 1 Reviewing Modules 1. Reviewing Modules The Tivoli Ready QuickStart wizard enables you to provide information to the Tivoli management software tools to describe your applications and business systems and their relationships. This information is created in the form of a module that can be directly imported and interpreted by the Tivoli management software tools. Management modules supported by the QuickStart wizard include the following types: Plus modules, that provide specialized features for managing an application with the Tivoli Enterprise Tivoli GEM modules, which enable business systems management using the Tivoli Global Enterprise Manager product Tivoli IT Director modules, which are created as a series of Application Management Specification (AMS) components combined into an Application Management Package (AMP) for installation in the Tivoli IT Director environment The following sections describe in more detail each of the module types that can be built using the QuickStart wizard. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 1

20 Tivoli Plus Modules A Plus module provides a high-level integration of an application with the Tivoli Enterprise. The application s management information, along with the scripts and programs for integrating the application with the Tivoli environment, is built into a Tivoli install image. A Plus module is defined as an installable image of scripts and management information defined in accordance to the AMS. This information is comprised of logical units called components. Note: AMS components are not the same as QuickStart wizard components. A QuickStart wizard component contains one or more AMS components, depending on the module type. When building a Tivoli GEM module, a Tivoli GEM QuickStart wizard component will always map to exactly one AMS component. When building a Plus module, a Plus component will typically map to multiple AMS components. AMS components are typically used in Plus modules to group objects together logically. Each AMS component defines a slice of functionality of the module. For example, one AMS component may contain most of the operational tasks, while another contains the file package definition for the configuration of the Tivoli Enterprise Console (TEC) logfile adapter. In addition to customized and comprehensive applications management, Plus modules provide a common interface and, in some cases, enable data sharing with the Tivoli management software tools. The specific integration points, which include tasks, monitors, file distribution, and event management, are described in AMS format. If you are familiar with generating Plus modules using the Tivoli Module Builder (TMB), you may have used the Plus Template, available in the TMB. This template is used to populate the module with a number of generic objects. These objects have no actual functionality associated with them, but they serve as place holders to 2 Version 2.4

21 guide you in the process of creating an object. The QuickStart wizard can be thought of as a dynamic version of a TMB template, in that it is used to seed the TMB, but the initial objects are based on actual characteristics that you specify. When installed, Plus modules create a Tivoli Plus icon on the Tivoli desktop. Double-clicking on this icon brings up the TivoliPlus window, containing the collection of Plus modules that have been installed. This icon accesses the dialogs and other features for all installed Plus modules, avoiding the need to access the Plus management functions separately from each Tivoli management software tool. 1. Reviewing Modules Tivoli GEM Modules Tivoli Global Enterprise Manager (Tivoli GEM) modules enable an application to be managed in the context of a business system with Tivoli GEM. The module s management information, along with the scripts and programs that implement the management functions, is built into a Tivoli install image. A Tivoli GEM module describes the tasks and monitors that Tivoli GEM requires to build views for business systems management. These tasks and monitors are described in AMS format. Tivoli IT Director Modules Tivoli IT Director modules are also created as a series of AMS components. In general, Tivoli IT Director defines a component for each architectural component as distinguished by platform and function. A Tivoli IT Director component defines a single file package, tasks, monitors, monitor instances, thresholds, and response tasks associated with the component. The components and their associated files are combined into an AMP for installation in the Tivoli IT Director environment. For each platform and function, you will create a component in the QuickStart wizard. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 3

22 Additional information is available with the Tivoli IT Director Integration Toolkit, in a document entitled, Managing Applications with Tivoli IT Director. 4 Version 2.4

23 2 Planning to Use the Wizard Before using the Tivoli Ready QuickStart wizard, you need to consider the run-time model of your application or business system. You can more effectively develop the application components and the resulting modules by modeling the processes and services of your application or business system. You should also be familiar with encoding rules, naming conventions, and requirements for icon and help files. 2. Planning to Use the Wizard Modeling Application Processes and Services If you model your application processes and services prior to using the QuickStart wizard, you reduce the time needed for a successful instrumentation. For each operating system that your application supports, perform the following steps: 1. Identify the processes and services of your application as follows: Capture all application processes. For Windows NT, you can see any application processes in the Windows NT task manager. For UNIX, you can list any application processes by using the ps -e command. Determine which named processes are persistent for the life of the application. Identify all Windows NT services that your Windows NT application creates. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 5

24 You can see these services by opening the Services icon in the Control Panel window. Identify any prefix of displayable Windows NT service names that are dynamically created by your application. For example, your application might create multiple instances of a database manager and give them a unique name, but prefix the unique name with DB2 to form the displayable service name. 2. Group the related processes and services of your application using the following criteria: Group processes and services that require each other to be on the same system. Note: A client component is grouped separately from a server component because it would connect to the server through a network connection. Move processes or services that are optionally activated into their own grouping. 3. Identify the components to be instrumented. Each group in the preceding step is considered a software component of your application, but only those that are persistent for the life of the application should be instrumented. Rules and Conventions This section describes the QuickStart wizard encoding rules and limitations, the file system structure used by the QuickStart wizard, and the naming conventions for product names and component names. Encoding Rules and Limitations The following are rules for names to apply when encoding your instrumentation: Monitor Names Monitor names must be alphabetic (a-z, A-Z). Spaces are not allowed. Monitor names must be unique for each component. 6 Version 2.4

25 Task Names Task names must be alphanumeric (a-z, A-Z, 0-9, and underscores) and the first character must be alphabetic. Spaces are not allowed. Task names must be unique. Names that you assign to tasks that are generated by task enablers must have unique names. Mixed-case names are allowed, and task names that are identical except for case, such as Start or start, are considered unique, even in the Intel environment. For Plus modules, task names are used as the basis for profile manager names, which are case-sensitive. Manufacturer and Product Names Manufacturer and product names can be alphanumeric and can contain underscores. The first character must be alphabetic. Spaces are not allowed. File System Structure The QuickStart wizard uses the standard TMB file system organization, with the following general structure (as it would appear on a UNIX system): module_dev/projects/<projname>/<modulename>/ Planning to Use the Wizard The QuickStart wizard will create new subdirectories for each module type after building the project. For example, if you have a project with an application called CustomApp and two components called server and client, building modules of all three module types would result in the following directory structure: module_dev/projects/customapp/server/... module_dev/projects/customapp/client/... module_dev/projects/customapp/itd/... module_dev/projects/customapp/plus/... module_dev/projects/customapp/images/... The first two subdirectories shown above,...server/ and...client/, are specific to Tivoli GEM. The AMP file for IT Director is generated under the ITD subdirectory. For Plus modules, all QuickStart wizard components for a project are collated into one Plus module under the Plus subdirectory. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 7

26 Naming Conventions Establish and follow a naming convention for your instrumentation to ensure meaningful unique names. Names should not contain blank spaces. The following is an example convention for product names and component names: Product names Create an abbreviated version of the product name to carry into the naming of its components. Ideally, the abbreviated product name should match the installable entity that will be installed in the production environment. Your product naming convention should result in a common acronym for the product, along with the operating system specification, a package qualifier, and a reference to the particular version and release, if necessary. These names can be used as prefixes for the component names to ensure uniqueness. For example, given the applications named ABC Application Enterprise Edition for Windows NT, ABC Application Enterprise Edition for AIX, and ABC Application Workgroup Edition for Windows NT, the abbreviated names could be ABC_NT_EE, ABC_AIX_EE, and ABC_NT_WG, respectively. Component names Determine a short descriptive name for each component. Prefix this name with the abbreviated version of the product name. Using the above product name examples, this might result in component names such as ABC_NT_EE_QMgr, ABC_AIX_EE_QMgr, and ABC_NT_WG_Router. Component names need to be unique across platforms if unique instrumentation is created for each platform. Specifying Path Names for Multiple Module Types When you are specifying a path name in the QuickStart wizard that is to be interpreted as a path for multiple module types (and therefore on potentially different platforms), you should use a forward slash (/) as a path separator, instead of the backslash (\). 8 Version 2.4

27 For example, if, for a task enabler parameter field you specify a command to execute and that command is of the form mkdir /tmp/xyz you must specify the forward slash as the path separator to be handled correctly in the bash environment for all three module types. Task names must be unique. Navigation Conventions While using the QuickStart wizard, you should be aware of the following conventions for navigating the various stages: Where you are prompted to enter a file name, you will see a button with... next to the entry field. Clicking this button will bring up the file selection dialog, enabling you to navigate to the desired directory where your file is located, and select the file to be included in the entry field. You can clear these fields later if desired by right-clicking on the field and selecting Clear value from the pop-up dialog. 2. Planning to Use the Wizard Throughout the QuickStart wizard, you can proceed from one screen to the next, in either direction, by clicking the Next and Previous buttons at the bottom of each screen. You can also exit the QuickStart wizard at any time, preserving the current state of your session, by clicking the Exit button. Finally, you can view online help information using the Help button. At any time you can also skip ahead or back through the wizard dialogs by clicking any of the items displayed in the left pane, or tree view, of the tab page. You can also select any of the four tabs at the top of the left pane to skip to that stage in the overall process. You can change the size of the left and right panes by dragging the separating border between the two panes to the right or left. For fields that require input, an empty blue circle is displayed to the left of the input field. When you enter valid input, the circle turns a solid blue. If the field is an optional input, the solid blue circle is displayed by default. Even though you must enter valid information in all required fields before you can build the Tivoli Module Builder Tivoli Ready QuickStart User s Guide 9

28 module, you can still traverse the QuickStart wizard dialogs and even save your session while you have incomplete or incorrect information in one or more fields. If you change the size of the QuickStart wizard window, its location on your desktop, or the location of the vertical divider bar on the window, you can save your settings by right-clicking in the area just above the four tabs (Start, Define, Instrument and Finish) and floating your mouse over the Window Settings pop-up menu that is displayed (see Figure 1). You can save some or all of these settings by selecting the appropriate check boxes. The settings are saved when you exit the QuickStart wizard. Figure 1. Saving your QuickStart wizard display settings Navigating the QuickStart Wizard Using the Keyboard While normally you can use the mouse to navigate through the various steps in the QuickStart wizard, you can also navigate from window to window and across fields with the keyboard, using the following Java-standard key combinations: 10 Version 2.4

29 Action Navigate in, navigate out Navigate out of a component that accepts tabs Move focus left one character or component within a group Move focus right one character or component within a group Move focus up one character or component within a group Move focus down one character or component within a group Activate an input field to enter data Activate the default command button Dismiss a menu or dialog box without changes Activate or select the component (with keyboard focus) Move to the beginning of data; in a table, move to the beginning of a line Move to the end of data; in a table, move to the last cell in a row Keyboard Operation Tab (with Shift key to reverse the action) Control-Tab (with Shift key to reverse the action) Left arrow Right arrow Up arrow Down arrow F2 Enter or Return Escape Space bar Home End 2. Planning to Use the Wizard Figure 2 on page 12 shows the order in which the key focus is acquired using the Control-Tab keys. At the last item, Control-Tab loops back to the first item. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 11

30 Figure 2. Using the Control-Tab keys, you can navigate the QuickStart wizard windows and components in the order shown. Collecting Icon and Help Files If you are building a Tivoli GEM module, collect the icon files and help files for your application and its components. Know where they are located. If necessary, create applicable help files. The QuickStart wizard requests these files when defining the application and instrumenting the software components. See Tivoli GEM Specific Build Options on page 32 for more information. For Plus modules, find your application icon file which can also be input to the QuickStart wizard. You will also need another version of this icon superimposed with the standard Tivoli Plus symbol, and this Plus icon can be specified in the QuickStart wizard to appear in 12 Version 2.4

31 the Plus module dialog on the Plus module desktop, along with other Plus module icons. For more information, see Plus Specific Build Options on page 35. Using User Exits and Flat Files Using the QuickStart wizard you can select predefined implementations that use programming interfaces common to the operating system to observe the application, discover software components, and report on their status. In many cases you will specify parameters to customize these predefined implementations, and in the case of Tivoli GEM, you can extend your implementations by generating your own user exits and special parameter files called flat files that distinguish one instance of an application component from another. These user exits and flat files should be defined prior to using the QuickStart wizard. For more information on user exits, see Programming User Exits on page 169. For information on flat files and their unique formats, see Flat File Formats on page Planning to Use the Wizard Tivoli Module Builder Tivoli Ready QuickStart User s Guide 13

32 14 Version 2.4

33 3 Using the Tivoli Ready QuickStart Wizard The Tivoli Ready QuickStart wizard is included in the Tivoli Module Builder product (TMB), along with the Tivoli Module Designer (TMD). You can use the QuickStart wizard as a front end to the TMB (in the case of Plus and Tivoli GEM modules) and the TMD (in the case of Tivoli IT Director modules) to provide Application Management Specification (AMS) information and skeletons for common management functions, including tasks, monitors, deployment, and event handling. You can further customize this basic level of instrumentation by writing event adapters and customizing skeleton files. The QuickStart wizard helps you get started in this process and helps cut the development time to generate your instrumentation. The QuickStart wizard provides both a sequential stepwise tour through the definition of management functionality for the novice user, as well as the ability for advanced users to skip to any area of the definition. 3. Using the Tivoli Ready QuickStart Wizard Installing the Tivoli Ready QuickStart Wizard The QuickStart wizard is installed automatically during the installation of the TMB. See the Tivoli Module Builder Release Notes for complete information on installing the TMB product and the QuickStart wizard. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 15

34 Starting the Tivoli Ready QuickStart Wizard To start the QuickStart wizard, do the following: For Intel: From the Start menu, select Programs -> Tivoli Module Builder -> QuickStart. Figure 3. Starting the QuickStart wizard On NT systems, you can also start the QuickStart wizard by double-clicking on the QuickStart.bat file in the /module_dev directory on the drive where you installed the TMB, or your install directory, if you installed to a different directory. For UNIX: From the default install directory, /module_dev or your install directory, if you installed to a different directory, enter the command: quickstart.sh Once the QuickStart wizard loads, the Getting Started window is displayed, as shown in Figure 5 on page 18. If this is not the first time you have started the QuickStart wizard, you will also see the Restart dialog, as shown in Figure 4 on page 17, giving you the option to do the following: 16 Version 2.4

35 Resume the previous session The QuickStart wizard remembers the previous state of your last session and returns to the previous session location at which you stopped. Start over You can erase your previous session and start fresh again with a new session by selecting this option. Figure 4. Resuming the previous session or starting over Even if you exit the QuickStart wizard without saving your previous selections, the state of the QuickStart wizard at the time you exit is preserved until the next time you use it. Note: If you save your QuickStart wizard session and build your module, you can further customize your instrumentation using the Tivoli Module Builder or Tivoli Module Designer. However, if you then return to the QuickStart wizard and resume your saved session, you may lose whatever customized instrumentation you added in the TMB or TMD the next time you build the module. 3. Using the Tivoli Ready QuickStart Wizard Tivoli Module Builder Tivoli Ready QuickStart User s Guide 17

36 Figure 5. The Getting Started window is displayed when you start a new session. Four tabs are available that represent the four main stages of the overall QuickStart wizard process. These four main stages are as follows: 1. Start From the Getting Started window, you can click Next to advance through two more information windows that describe what you can expect, along with a brief overview of the four-stage process, bringing you to the Select Instrumentation dialog. You can also skip directly to this dialog by clicking Select Instrumentation from the tree view in the left pane. See Using the Start Stage on page 19 for more details. 2. Define In the Define stage, you identify the application to be managed, specifying application level information such as the name, manufacturer, version, and release level. You can also declare which module types you intend to build, selecting from Tivoli GEM, Plus, or IT Director module types. 18 Version 2.4

37 See Using the Define Stage on page 21 for more details. 3. Instrument In the Instrument stage, you define the specific software component parts of your application, specifying component level information such as name, manufacturer, version and release level. You also select the desired platform type and customize the desired enablers for each software component. See Using the Instrument Stage on page 23 for more details. 4. Finish In the Finish stage, you can further refine the platform type for the modules to be built. You can save your session to continue at a future time, or you can build your modules into a Tivoli installable image and, for Tivoli GEM and IT Director modules, an AMP file. If you need additional customization, you can use the Tivoli Module Builder and Tivoli Module Designer products. See Using the Finish Stage on page 30 for more details. Using the Start Stage The Start stage is the initial stage of the Tivoli Ready QuickStart process. The Getting Started window, along with the What to Expect and Requirements windows, gives you a brief overview of the general process. Advancing to the Select Instrumentation dialog, you can do the following: 3. Using the Tivoli Ready QuickStart Wizard Tivoli Module Builder Tivoli Ready QuickStart User s Guide 19

38 Figure 6. Selecting your desired instrumentation Continue working If you had started a previous session and exited the QuickStart wizard, the state of your session is preserved. The next time you return you can select this option to continue where you left off. Create a new module Select this option to start a new module, erasing any previous session information. Load from an existing module Select this option to load a module previously created using the QuickStart wizard. Then you can edit the module, rebuild it, or use it as a template to create a new module. The list of available modules will be shown in the selection box under this radio button. Highlight the one you want to select. Note: If you have previously used the QuickStart wizard to build a module and then further customized your instrumentation using the TMB or TMD, you cannot re-load the module into the QuickStart wizard. 20 Version 2.4

39 Load a QuickStart session file Select this option to continue work on an existing session file that you saved using the Yes - Save the QuickStart session to a file option during the Finish stage (see Using the Finish Stage on page 30) in a previous session. Enter the path in the field provided, or navigate to the desired directory and select the desired file. If you select Start Over during startup, the Create a new module radio button will be selected by default. If you leave this window and return again later, the Continue working radio button will be selected by default. If you select Resume previous session during startup, the Continue working radio button is selected by default. If you then select an option other than Continue working, you will be warned about losing existing session information if you proceed further. Be sure to select the right option to avoid losing previous session information. Figure 7. Be careful not to lose existing data you want to keep. 3. Using the Tivoli Ready QuickStart Wizard Using the Define Stage In the Define stage, you provide information about the application to be managed by your Tivoli GEM, IT Director or Plus module. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 21

40 Figure 8. Identifying the application level information In the Information pane, you enter application level information, such as the following: Name This is the name you give to the module. You can specify up to 20 alphanumeric characters, and the first character must be alphabetic. Blanks are not allowed, but you can use underscores. This is a required field, and is initially filled in with NewApplication when you first enter this stage. You should replace NewApplication with your application name. Manufacturer This is the name of the manufacturer of the application. You can specify up to 20 alphanumeric characters, and the first character must be alphabetic. Blanks are not allowed, but you can use underscores. This is a required field. Version This is the version number for the module, and has a major, minor, and revision component. You specify a numeric value for the major version number, the minor version number, and the revision level. The version number is a good way to track code changes. The major and minor version numbers are required fields, while the Rev revision field is optional. You can specify up to 5 numeric characters in these fields. Note: If you are building Tivoli GEM modules and plan to do further customization using templates in the TMB, the field 22 Version 2.4

41 lengths for the Name and Manufacturer fields may be more restricted. See the Tivoli Module Designer Release Notes for details. After you fill in these fields (notice the empty blue circles change to solid blue circles when valid data has been entered into required fields), click Next to continue, or click Module Type from the tree view in the left pane. Also in this stage, in the Module Type pane, you select which of the three module types you want to build: Tivoli GEM, Plus, or IT Director modules. You can select one, two, or all three types. Figure 9. Select the desired module types you want to build. Finally, in the Summary pane, you see the application information and the module types you entered in the previous panes. While you are in the Define stage, you can skip ahead to this Summary pane at any time, if you do not want to step through the panes sequentially. Use the Summary pane to confirm your definition information before proceeding on. You can make changes to the information in the Summary pane or go back to the previous panes at any time to modify what you entered. When you are satisfied, click Next to continue. Using the Instrument Stage In the Instrument stage, you enter information about each software component in your application to be managed. 3. Using the Tivoli Ready QuickStart Wizard When you first enter the Instrument stage, you may see the first component already added for you in the Components in this Tivoli Module Builder Tivoli Ready QuickStart User s Guide 23

42 module list box in the dialog window. The default component name of NewComponent0 is used. This field may be empty, however, if you did not previously define your application information in the Define stage. Figure 10. The first component is added to the list for you. In the tree view in the left pane, the new component is also shown, and below this name is a list of the available enabler categories you can choose from. (See Selecting Enablers on page 45 for details about enablers.) 24 Version 2.4

43 Figure 11. The tree view shows the new component and available enabler types. Click Add to add additional new components to the component list. For each new component you add, a new entry in the tree view is made, along with its corresponding list of enabler types, as shown in Figure 12 on page 26. Note also that the default component name, NewComponentn, is incremented by one to create a unique combination of Name, Manufacturer, and Version for each component. You can change these default component names to names that are of meaning to you, but you must maintain a unique Name, Manufacturer and Version combination for each component. You can also remove a component from the list and the tree view by selecting the component in the list box and then clicking Remove. 3. Using the Tivoli Ready QuickStart Wizard Tivoli Module Builder Tivoli Ready QuickStart User s Guide 25

44 Figure 12. The Add button lets you add new components to the list. When you have added the desired number of new components, click Next to continue on to the component level definitions. For each new component, you must define the following component level information: Name Here is where you can override the default NewComponent0 name with your own desired name. You can specify up to 20 alphanumeric characters, and the first character must be alphabetic. Underscores are permitted, but blank spaces are not allowed. Notice that as you modify this name in the Name field, the corresponding name in the tree view in the left pane changes as well. Manufacturer This field is already filled in with the same manufacturer name you entered at the application level in the Define stage. You can override the component level manufacturer name here if it is different. You can specify up to 20 alphanumeric characters, and 26 Version 2.4

45 the first character must be alphabetic. Underscores are permitted, but blank spaces are not allowed. Note: If you are building Tivoli GEM modules and plan to do further customization using templates in the TMB, the field lengths for the Name and Manufacturer fields may be more restricted. See the Tivoli Module Designer Release Notes for details. Version The version field has the same major, minor, and revision level information as you defined at the application level. You can override these numeric fields for the component level. You can specify up to 5 numeric characters in these fields. Platform Select the desired platform on which the software component can run, from the Platform drop down list. This selection serves as an early filter for the QuickStart wizard. The enabler list you can select from will include only those enablers which support your intended platforms. You can further refine this platform selection later in the Finish stage. 3. Using the Tivoli Ready QuickStart Wizard Figure 13. Select the platform type from the drop down list. You can select from the following platform types: Tivoli Module Builder Tivoli Ready QuickStart User s Guide 27

46 v v v Generic: This selection applies to all supported platforms, both Intel and UNIX. Generic UNIX: This selection applies only to the list of supported UNIX platforms. Microsoft Windows 32: This selection applies only to the list of supported Windows platforms. Note: Plus modules do not refer to the component platform. You can just use the default input of Generic. When your component level information is complete, proceed on to the selection of enablers for your component. At any time, you can click on any of the enabler categories in the tree view to skip to the selection panel for that enabler category. You can also click on the Information branch of the tree view to return to the component level information panel. In the tree view, you can select from any of the following enabler categories: Instance Discovery Enablers Instance Information Enablers Inventory Enablers Task Enablers Monitor Enablers Connection Enablers Event Enablers Deployment Enablers When you select an enabler category, the right pane of the dialog window displays a scrollable list of available enablers for that enabler category. This list is also filtered by the module type (Tivoli GEM, Plus, or IT Director) you specified during the Define stage. Only those enablers that are applicable to the types of modules you intend to build are shown in this window. 28 Version 2.4

47 You can select a desired enabler in the scrollable list, and see a corresponding list of parameters that the selected enabler uses to further customize its operation. Click the Description field to fully display the description of the selected enabler or parameter, or move the cursor over any field to display the full field text. To select this enabler and add it to your software component, click Add. Your selected enabler is then added to the list of selected enablers at the top of the window, and also appears in the tree view under the appropriate enabler type. Figure 14. Click Add to add your selected Instance Discovery enabler to the list. For some enabler types, you can select more than one enabler. Just continue to select the desired enablers from the list and click Add to add them to the selected enablers list at the top. You can also remove selected enablers at any time by selecting the enabler in the selected list and clicking Remove. 3. Using the Tivoli Ready QuickStart Wizard For each enabler you selected, you may need to fill in some parameter information to complete the customization of the enabler. You can select any of your chosen enablers in the tree view, Tivoli Module Builder Tivoli Ready QuickStart User s Guide 29

48 resulting in the right pane displaying the corresponding parameters needed for that enabler. See Selecting Enablers on page 45 for details on specific enablers and their parameter values. For monitor enablers, you may also need to specify threshold values and polling intervals. You will navigate through additional dialogs to supply this information to the QuickStart wizard. When you have filled in all of your parameter information for all of your selected enablers in each of your software components, you can proceed to the Finish stage. Using the Finish Stage The Finish stage is the final stage of the QuickStart wizard. You can select this stage when you have completed the definition of your application s software components, selected the desired enablers and filled in each enabler s parameter values during the previous stages. In this stage you can do the following: Save your work to a QuickStart session file to continue at a later time Quit the QuickStart wizard (the last state of the QuickStart wizard is preserved) Reconfirm or change the types of modules you wish to build Make some final module-type specific choices for application and component options, and then build the Tivoli install image or AMP files. Items you can select, based on the types of modules you are building, include: v v v Icon files, containing the icon of the application or component to be displayed on the management console. Help files that display help information about your application or component on the management console. Further refinement of the specific platform for which your module is to be built, based on the platform group (Generic, Generic UNIX, Windows 32) you selected during the Define stage. 30 Version 2.4

49 See Tivoli GEM Specific Build Options on page 32 for more information on icon and help files. Saving the Session You can save your session for subsequent work by selecting Yes - Save the QuickStart session to a file radio button on the Finish page. Figure 15. Saving your QuickStart session to a file You must specify a fully qualified file name and path in the field provided. Click Exit to save the session. When you return to the QuickStart wizard to continue working on your session, you can load this session file into the QuickStart wizard by selecting the Load a QuickStart session file option on the Start tab page. Quitting the Current Session You can exit the QuickStart wizard without saving the session file by selecting the No - Do not save the QuickStart session radio button and selecting Exit on the Finish tab page. The current session is not saved to a user-specified file. However, the current state of the QuickStart wizard is preserved in a default session file. The next time you start the QuickStart wizard you can restore this previous session and pick up where you left off, or you can start over again. 3. Using the Tivoli Ready QuickStart Wizard You can also select this option if you want to build your module but do not want to save it to a QuickStart session as well. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 31

50 Confirming Your Module Type Selection Though you previously declared which module types (Tivoli GEM, Plus, or IT Director) to build during the Define stage (see page 23), you can still change your selection of module types to build during the Finish stage. For example, you may have elected to build all three module types, and defined components and configured enablers for all three module types, but now only want to build one of the modules and build the others at a later time. In this case, you can deselect one or two of the module types so they are not built into Tivoli install images, though their component definitions and enabler configurations can still be saved in the QuickStart session file, to be loaded and built at a later time. Figure 16. Confirm your module type selection one last time before building the modules. Click Next to continue with specifying optional module-specific information for each module type you intend to build, or select the desired module specific dialog from the Finish stage tree view. Tivoli GEM Specific Build Options During the Finish stage you can specify a few final options specific to building Tivoli GEM modules. From the Finish stage tree view, select GEM Specifics to display the dialog for entering options applicable to Tivoli GEM modules. 32 Version 2.4

51 Figure 17. Specifying final build options for Tivoli GEM modules Under Application Options, you can optionally specify the following: Icon File Name This is the fully qualified (including file path) name of the file containing the icon, representing the application being managed, to be displayed on the management console. If you know the exact name of the file, enter it in the field provided, or click the... button to navigate to the desired folder where the icon file is located. Help Text File Name This is the fully qualified (including file path) name of the file containing help information for the application being managed, to be displayed on the management console. If you know the exact name of the file, enter it in the field provided, or click the... button to navigate to the desired folder where the help file is located. 3. Using the Tivoli Ready QuickStart Wizard Which branch of the GEM tree? Tivoli Module Builder Tivoli Ready QuickStart User s Guide 33

52 You can define whether your application should appear on the management console under either the Application or Middleware/DB branch of the Tivoli GEM tree view, by selecting the appropriate radio button. Under Component Options, for each component you have defined, you can optionally specify the following: Icon File Name This is the fully qualified (including file path) name of the file containing the icon, representing the component being managed, to be displayed on the management console. When defining an application or component, you can specify the icon file for displaying the icon of the application or component on the management console. The icon file you specify must reside at the path location you indicate in order to build the module. The following requirements apply to these icon files: v v v Animated icons are not supported. You can only add and customize icons that represent resources. Icons must be in the graphical interchange format (GIF), and 32x32 pixels in size. Help Text File Name This is the fully qualified (including file path) name of the file containing help information for the component being managed, to be displayed on the management console. Note: Help files must remain at the location specified so that they can be found during the module build. The following requirements apply to help files: v v v Use only lowercase letters in the help file name and file name extension. Use only basic HTML tags in the help file. Within the HTML help file, specify a charset value. For example: 34 Version 2.4

53 <META HTTP-EQUIV="Content-Type" CONTENT="text/html;charset=name"> Use the same name value as used in existing help files to ensure a consistent and valid charset value. Platform You can refine the platform selection you made during the Instrument stage (see page 27) by clicking on the drop down list and selecting the specific supported platform or platform group for each component. Figure 18. Refining the platform selection Plus Specific Build Options During the Finish stage you can specify a few final options specific to building Plus modules. From the Finish stage tree view, select Plus Specifics to display the dialog for entering options applicable to Plus modules. 3. Using the Tivoli Ready QuickStart Wizard Tivoli Module Builder Tivoli Ready QuickStart User s Guide 35

54 Figure 19. Specifying final build options for Plus modules. In the Plus Specifics dialog, as shown in Figure 19, you can optionally specify the following: Application Icon File This is the fully qualified (including file path) name of the file containing the icon, representing the application being managed, to be displayed on the management console. Application Icon (Plus) File 36 Version 2.4

55 This is the same as the Application Icon File, but also has superimposed over it the standard Plus image. You can use an XPM or text editor to create this Plus icon from the application icon file. If you know the exact name of the file, enter it in the field provided, or click the... button to navigate to the desired folder where the desired file is located. Icons must be in the XPixMap (XPM) format, and 32x32 pixels in size. Note that the file name must be of the form xxxxxxplus.xpm, where xxxxxx is the application icon file name. Install Options This is a field where you can specify a list of Plus module install options. These become install options that become available at install time. Options in the list are separated by commas. The QuickStart wizard does not validate this input. You can find more information about these install options in the Tivoli Module Builder User s Guide. Plus module items to include You can select one or more of the following additional options for Plus modules by checking the corresponding check box: v Plus Configuration task Enables you to specify a task that is run as the last step of a module installation. The task also appears on the desktop so you can run it again later. v Endpoint Launch task This is similar to the Application Launch task in the traditional Plus template in the Tivoli Module Builder, but while that task is designed to run on a managed node, this task enables you to launch an application on an endpoint. See the Plus Application Launch Enabler, on page 84, for more information. 3. Using the Tivoli Ready QuickStart Wizard v Create Subscriber List task This option adds a task to the module that enables the administrator to create a subscriber list after the module is installed. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 37

56 v v v Subscriber List for Managed Nodes This option creates a subscriber list on the Tivoli Management Region (TMR). When a module is installed on a managed node, this list is automatically updated with the name of the managed node. Subscriber List for Endpoints This option creates an empty subscriber list for endpoints. About task This option creates an About task for the module on the Tivoli desktop that displays the module name and version. By default, all of the checkboxes are selected. You can select or deselect any or all of them as desired. Note that there is no option to refine or further specify the platform type for Plus modules. Platform types are not applicable to Plus modules, and if you specify platforms for other module types, they are ignored during the Plus module build. IT Director Specific Build Options During the Finish stage you can specify a few final options specific to building IT Director modules. From the Finish stage tree view, select ITD Specifics to display the dialog for entering options applicable to IT Director modules. 38 Version 2.4

57 Figure 20. Specifying final build options for IT Director modules Under Application Options, you can optionally specify the bean jar file name in the Bean Jar File field. This is the fully qualified (including file path) name of a Java archive (.jar) file that may contain argument and response Java beans, or other resource files. If you know the exact name of the file, enter it in the field provided, or click the... button to navigate to the desired folder where the icon file is located, and select it from there. Under Component Options, for each component you have defined, you must override the platform selection you made during the Instrument stage (see page 27) by clicking on the drop down list and selecting the specific supported platform or platform group for each component. 3. Using the Tivoli Ready QuickStart Wizard Tivoli Module Builder Tivoli Ready QuickStart User s Guide 39

58 Building Your Modules After you have completed specifying your the module-specific options, click Next or select Summary from the Finish tree view, to display the final summary dialog. Your selections for saving the session file, desired module types to be built, and module-specific information is available to you for one last confirmation and chance to change it before the actual build begins. You can also skip right to this dialog in the Finish stage if you want to avoid going through the individual dialog screens. Three tab pages, as shown in Figure 21, are available if you want to display and modify any of the module-type specific information without going back to the previous dialog windows. Figure 21. Module-type specific options are available on separate tab pages in the Finish Summary dialog. When you are satisfied with your final choices, click the Finish button at the bottom to begin the build. If you have left out any required information, or if the QuickStart wizard detects a problem with your input, a dialog will be displayed with a list of pointers to the areas that need correction, similar to that shown in Figure 22 on page Version 2.4

59 Figure 22. The Final Check dialog points you to errors that must be corrected before the modules can be built. You will not be able to build a Tivoli install image if you are missing required input. If you do have errors, the QuickStart wizard will list for you the tab pages that you must return to in order to complete the required information before proceeding. For each item in the Final Check dialog, you can click Show to be taken to the specific dialog window in the QuickStart wizard where the problem was detected. Typically the problem will be a required field that is not filled in or that contains information that the QuickStart wizard considers invalid. This is denoted by the blue empty circle next to the field, indicating that required information is still needed. You must correct all of the problems listed in the Final Check dialog before you can proceed. Click Finish at the bottom of the Finish Summary dialog to re-verify that all problems have been corrected. 3. Using the Tivoli Ready QuickStart Wizard Tivoli Module Builder Tivoli Ready QuickStart User s Guide 41

60 The Build Image dialog is displayed, as shown in Figure 23, identifying the directory on your system where the build image will reside. Figure 23. The Build Image dialog shows where the final Tivoli install image will be built. Click OK to start the build, or click Cancel to quit the build. The build may take some time to complete, depending on your system and the complexity of the modules being built. Status of the build in progress is displayed in the running JVM window. When the build is complete, the Build Status dialog is displayed, as in Figure 24: Figure 24. The Build Status dialog tells you if the build was successful. You can click Exit QuickStart to leave the QuickStart wizard, or click Don t leave yet to return to the QuickStart wizard if you want to continue building modules. 42 Version 2.4

61 Additional Customization If you need to add more advanced instrumentation than the QuickStart wizard provides, you can load your saved module into the Tivoli Module Builder or Tivoli Module Designer and continue the instrumentation process from there. Note: Once you modify your module in the Tivoli Module Builder or Tivoli Module Designer, you will not be allowed to reload it into the QuickStart wizard. Loading Tivoli GEM Modules in the Tivoli Module Builder You can further customize Tivoli GEM modules by launching the Tivoli Module Builder and loading the GEMModule.Java.Extension.v2_3.template file. See the Tivoli Global Enterprise Manager Advanced Business System Enablement Guide for information and examples of loading this extension template to further customize your Tivoli GEM module. Loading Plus Modules into the Tivoli Module Builder You can further customize Plus modules by launching the Tivoli Module Builder and loading the Plus module. See the Tivoli Module Builder User s Guide for details on Tivoli Plus modules. Importing IT Director AMPs in Tivoli Module Designer When you build an application management package for Tivoli IT Director in the QuickStart wizard environment, you use the File Chooser dialog to select your desired files, and the path information is included with the file in building the AMP for IT Director. In addition, the QuickStart wizard generates files for some of the enablers, and includes these in the AMP as well. When you import this AMP into the Tivoli Module Designer, however, any non-ams files are ignored, and only the AMS information is read in. Any files that are referenced in the AMS information must be found when TMD rebuilds the AMP. 3. Using the Tivoli Ready QuickStart Wizard To have access to these files when you customize your AMP in TMD, first use a jar file extraction utility, such as jar.exe (which is included in the Java Development Kit you installed with the Tivoli Tivoli Module Builder Tivoli Ready QuickStart User s Guide 43

62 Module Builder product) and extract all of these files from the AMP and put them into a temporary directory. Specify this directory in the Prefix source location with parent directory field in the TMD build AMP dialog. When you build the AMP, the TMD will find those files and the AMP file will build successfully. Note: When you import the AMP into the TMD, you may get parser warnings. Parser warnings can usually be ignored. They occur when every file in the AMP file gets parsed by TMD to see if it is a valid AMS file. Any files that are not valid AMS files show up in the list of non-parseable files, including an application object file (.aof) that is always included in the AMP. 44 Version 2.4

63 4 Selecting Enablers 4. Selecting Enablers The purpose of the Tivoli Ready QuickStart wizard is to populate the Tivoli Module Builder (in the case of Tivoli GEM and Plus modules) and the Tivoli Module Designer (in the case of IT Director modules) with AMS information and skeletons for common management functions, including tasks, monitors, deployment and event definitions. The main mechanism used to gather specific user input is the enabler. Enablers are predefined implementations that typically use operating system utilities such as batch files and shell scripts to observe the application, discover software components, and report on their status. Enablers can be selected for use and tailored by providing whatever parameters a given enabler requires. Enablers are platform-specific or generic. Generic enablers run on all supported platforms. See the Tivoli Module Builder Release Notes for the list of supported platforms. During the Instrument stage of the QuickStart wizard, you can choose from the following categories of enablers: Enabler Category For Details: Instance Discovery Enablers See page 47 Instance Information Enablers See page 65 Inventory Enablers See page 71 Task Enablers See page 75 Tivoli Module Builder Tivoli Ready QuickStart User s Guide 45

64 Enabler Category For Details: Monitor Enablers See page 101 Connection Enablers See page 139 Event Enablers See page 151 Deployment Enablers See page 159 During the Define stage, you selected one or more module types to be built. This selection also acts as a preliminary filter on the list of enablers that are available for you to include in your build. You will be presented with the list of enablers that are valid for the types of modules you selected. So, for example, if you selected to build only Tivoli GEM modules, then only the enablers valid for Tivoli GEM modules will be available for you to choose. If you elect to build more than one module type, for example, Tivoli GEM and Plus modules, then only the enablers that are valid for either Tivoli GEM or Plus modules, as well as enablers common to both types, are included in the list of available enablers. 46 Version 2.4

65 5 Instance Discovery Enablers During the Instrument stage of the QuickStart wizard, you define software components that make up your application. For Tivoli GEM modules, each software component requires a mechanism to notify Tivoli GEM of the instances configured on the system. The process of detecting a software component and notifying the management tool is called discovery. The following table shows the Instance Discovery Enablers that are available for your Tivoli GEM module. 5. Instance Discovery Enablers Note: If you did not select Tivoli GEM as one of your module types in the Define stage (see page 23), you will not see any instance discovery enablers available for selection. Instance Discovery Enablers For Details: NT Performance Objects Enabler See page 53 NT Service by Program Name Enabler See page 54 NT Services Enabler See page 56 Single Instance Application Enabler See page 57 Specific NT Service Enabler See page 58 Start Up Parameters Enabler See page 59 User Exit Enabler See page 60 User Exit (using File Pack) Enabler See page 62 User ID and Program Enabler See page 63 Tivoli Module Builder Tivoli Ready QuickStart User s Guide 47

66 Note: You may only select one instance discovery enabler from this list. Figure 25. Selecting an instance discovery enabler in the Instrument stage Selecting an Instance Discovery Enabler Use the following guidelines to choose an instance discovery enabler. Since this is only a guideline, review all instance discovery enablers, and the monitors that they enable, before finalizing the choice for each software component. 1. Does the software component implement one or more NT Services? If YES, proceed to step 2. If NO, skip to step Version 2.4

67 2. Does the software component implement one and only one NT Service per system? If YES, use the Specific NT Service Enabler (see page 58). If NO, proceed to step Are multiple services implemented by a single program whose purpose is to implement the application? Note: Look in the NT Registry under HKEY_LOCAL_MACHINE\SYSTEM\Control Set001\Services\ to find the registry keys for the software service. The key ImagePath lists the name of the program (*.exe) that Windows NT uses to control the service. If YES, use the NT Service by Program Name Enabler (see page 54). If NO, proceed to step Is there a consistent naming convention that uses a common prefix string as the name of the NT service? If YES, use the NT Services Enabler (see page 56). If NO, skip to step Is the software component represented by a Windows NT Performance Object? If YES, proceed to step 6. If NO, skip to step Does the NT Performance Object have multiple instances? If YES, use the NT Performance Objects Enabler (see page 53). If NO, proceed to step Can the software component start and execute multiple times concurrently on a single system? If YES, proceed to step Instance Discovery Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 49

68 If NO, use the Single Instance Application Enabler (see page 57) or, if enhanced process-related monitors are desired, consider the Start Up Parameters Enabler (see page 59). 8. Is each instance of the software component started with a unique set of parameters? Notes: a. If the software component was started twice with the same parameters, one of the instances must terminate for you to answer YES. b. If the software component is started by a command file or script, consider the long running program that implements the software program. If YES, use the Start Up Parameters Enabler (see page 59). If NO, proceed to step Is each instance of the software component started under a different system user ID? Note: If the software component was started twice with the same parameters under the same system user ID, one of the instances must terminate for you to answer YES. If YES, use the User ID and Program Enabler (see page 63). If NO, proceed to step Can you create a program (script or binary executable) that can interact with the software component, with the goal of identifying the software component instances? If YES, use the User Exit Enabler (see page 60) or, the User Exit (using File Pack) Enabler (see page 62). If NO, then there is no instance discovery enabler available that provides a solution for this software component. 50 Version 2.4

69 Monitor Enabler Dependencies Several monitor enablers (see page 101) are only available when a certain instance discovery enabler is selected. The following table shows which monitor enablers are available when a particular instance discovery enabler is selected. Instance discovery enablers are represented across the top of the table, as follows: D1: NT Performance Objects D2: NT Service by Program Name D3: NT Services D4: Single Instance Application D5: Specific NT Service D6: Start-up Parameters D7: User Exit D8: User Exit (using File Pack) D9: User ID and Program 5. Instance Discovery Enablers Monitor D1 D2 D3 D4 D5 D6 D7 D8 D9 Enabler State X X X X X X X X X Process Attribute X X X X X X X X X Instance Process X X X X X X X Attribute Process Count X X X X X X X X X Instance Process X X X X X X X Count Process Time X X X X X X X X X Instance Process X X X X X X X Time NT Object Counter with NT Instance X X X X X X X X X Tivoli Module Builder Tivoli Ready QuickStart User s Guide 51

70 Monitor Enabler NT Object Counter w/o NT Instance D1 D2 D3 D4 D5 D6 D7 D8 D9 X X X X X X X X X Instance NT X X X Counter NT Service X X X X X X X X X Instance NT X X X X X Service User Exit X X X X X X X X X Number User Exit Number (using File Pack) X X X X X X X X X User Exit String X X X X X X X X X User Exit String X X X X X X X X X (using File Pack) So, for example, the Instance Process Attribute monitor enabler will only be available for selection if one of the following instance discovery enablers has been selected: D2 = NT Service by Program Name D3 = NT Services D5 = Specific NT Service D6 = Start-up Parameters D7 = User Exit D8 = User Exit (using File Pack) D9 = User ID and Program Other monitor enablers not shown in this table have no dependency on the selected instance discovery enabler. 52 Version 2.4

71 Each instance discovery enabler is described in the following sections. NT Performance Objects Enabler (GEM) Enabler Category: Instance Discovery Applicable to module type: Tivoli GEM Description: This enabler creates an instance of the software component for each instance of an NT Performance Object. The enabler also deletes the instance if it is no longer registered as an instance of an NT Performance Object. The name of the instance is the name of the NT Performance Object. An NT object is not necessarily an NT service. Select this enabler if the software component is represented by a Windows NT Performance Object and the NT Performance Object has multiple instances. If your application does not detail its use of NT Performance Objects, you can do the following: 1. From the Start menu on a system where the application is running, select Programs -> Administrative Tools -> Performance Monitor. 2. From the Edit menu on the Performance Monitor toolbar, select Add to Chart. 5. Instance Discovery Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 53

72 Figure 26. View your NT Performance Objects using the Performance Monitor. 3. Select the Object drop-down list to display the objects on your system. 4. Select one of the objects from the drop down list (for example, Process). If there are multiple instances of this object, they will appear in the Instance scrollable list. Related enablers: None Prerequisites: None Required Parameters: NT Performance Object Name: The name of the NT object (for example, Process) Optional parameters: None Tasks created: None NT Service by Program Name Enabler (GEM) Enabler Category: Instance Discovery Applicable to module type: Tivoli GEM 54 Version 2.4

73 Description: This enabler detects instances of a software component for each Windows NT service that is started by a particular program or image name. The name of the instance is the Windows NT service name. The enabler creates new instances of the software component after the NT service is registered in the Services dialog box in the Windows NT Control Panel. The enabler deletes the instance if it is no longer registered as an NT service. Select this enabler if the software component implements multiple NT services started by a single program whose purpose is to implement the application. Related enablers: If the software component implements only one NT service per system, use the Specific NT Service Enabler (see page 58). If multiple NT services are implemented by multiple programs having a common prefix in their NT service names, select the NT Services Enabler (see page 56). Prerequisites: None 5. Instance Discovery Enablers Required parameters: Program or Image Name: The exact program or image name, excluding path information, of the software component s executable file, including the file name and type. The name should match the process names displayed by the Windows NT Task Manager. Note: When this enabler detects a process started by Java, it considers the Java class name, excluding the package name, as the program name to determine if a Java executable needs to be monitored. Optional parameters: None Tasks created: When this enabler is built, the following tasks are created: Tivoli Module Builder Tivoli Ready QuickStart User s Guide 55

74 Start Stop NT Services Enabler (GEM) Enabler Category: Instance Discovery Applicable to module type: Tivoli GEM Description: This enabler detects instances of a software component for each Windows NT Service that matches the provided service name prefix. The name of each instance is the Windows NT service displayable name. The enabler compares the names of the registered NT services against the provided service name prefix. It creates new instances of the registered NT services that match the prefix. For example, if the service prefix name is DBM and two NT services are registered as DBM Accounting and DBM Inventory, the enabler creates instances for each service. The enabler deletes the instance if it is no longer registered as an NT service. Select this enabler if the software component implements multiple NT services using more than one program, and if there is a consistent naming convention that uses a common prefix string as the name of the NT service. Related enablers: If the software component implements only one NT service per system, use the Specific NT Service Enabler instead. If the software component implements more than one NT service by a single program whose purpose is to implement the application, then select the NT Service by Program Name Enabler (see page 54). Prerequisites: None Required Parameters: 56 Version 2.4

75 Service Name Prefix: The prefix string that is common to the multiple NT service names (for example, DBM matches DBM Accounting and DBM Inventory) Optional Parameters: None Tasks created: When this enabler is built, the following tasks are created: Start Stop Single Instance Application Enabler (GEM) Enabler Category: Instance Discovery Applicable to module type: Tivoli GEM Description: This enabler enables you to define a single instance of the software component on the system where the instrumentation is deployed. The name of the instance is a parameter that you provide. Since this enabler statically defines the instance, a task is provided that enables you to remove all awareness of the instance. 5. Instance Discovery Enablers Select this enabler when the software component cannot start and execute multiple times concurrently on a single system. Related enablers: If the software component can start and execute multiple times concurrently, and each instance is started with a unique combination of parameters, you should select the Start Up Parameters Enabler (see page 59). Prerequisites: None Parameters: Instance Label: The name of the label that is displayed on the management console Tivoli Module Builder Tivoli Ready QuickStart User s Guide 57

76 Tasks created: When this enabler is built, the following tasks are created: Delete_Instance: Use this task to remove all awareness of the instance. This task removes the current instance, but does not stop the enabler from rediscovering the instance at a later time. To prevent it from being re-discovered, remove the instrumentation from the system. Specific NT Service Enabler (GEM) Enabler category: Instance Discovery Applicable to module type: Tivoli GEM Description: This enabler detects instances of a software component based on matching the Windows NT service name. The name of the instance is the Windows NT service name. This enabler creates instances only after the NT service is registered in the Services dialog box in the Windows NT Control Panel. The enabler deletes the instance if it is no longer registered as an NT service. Select this enabler if the software component implements one and only one NT Service per system. Related enablers: If the software component implements more than one NT service, then: If the multiple services are implemented by a single program whose purpose is to implement the application, you should select the NT Service by Program Name Enabler (see page 54). If the multiple services are implemented by multiple programs that have a common prefix string as part of their NT service names, you should select the NT Services Enabler (see page 56). Prerequisites: None Required parameters: 58 Version 2.4

77 Service Name: Name of the NT Service (for example, Messenger), as it appears in the Services dialog box from the Windows NT Control Panel. Optional parameters: None Tasks created by selecting this enabler: Start task for the specific NT service Stop task for the specific NT service Start Up Parameters Enabler (GEM) Enabler category: Instance Discovery Applicable to module type: Tivoli GEM Description: This enabler enables you to detect instances of a software component based on the unique combination of parameters that start the program. The name of each instance is a combination of the program name and the parameters that start the program. 5. Instance Discovery Enablers The enabler creates new instances of the software component only when a unique combination of program name and parameters is detected. Once detected, an instance remains discovered until the Tivoli GEM database clears or the Tivoli GEM Instrumentation Service data stores are deleted. A task is provided that enables you to remove all awareness of the instance. Select this enabler when the software component can be started multiple times on a single system, and each instance uses a unique combination of parameters that start the program. Related enablers: If the software component cannot be started multiple times concurrently, consider using the Single Instance Application Enabler (see page 57). If the software component can be started multiple times on a single system, but the parameters that start the program may or may not be unique, and each instance of Tivoli Module Builder Tivoli Ready QuickStart User s Guide 59

78 the program has a unique user ID, then consider using the User ID and Program Enabler (see page 63). Prerequisites: None Required parameters: Process or Image Name: The process or image name parameters, excluding path information, of the software component s executable file, including both the file name and type. The name should match the process names displayed by the Windows NT task manager or the ps command on a UNIX system. Note: When this enabler detects a process started by Java, it considers the Java class name, excluding the package name, as the program name to determine if a Java executable needs to be monitored. Optional parameters: None Tasks created: When this enabler is built, the following tasks are created: Delete_Instance: Use this task to remove all awareness of the instance. This task removes the current instance, but does not stop the enabler from rediscovering the instance at a later time. To prevent it from being re-discovered, remove the instrumentation from the system. User Exit Enabler (GEM) Enabler Category: Instance Discovery Applicable to module type: Tivoli GEM Description: This enabler enables you to detect instances of a software component as directed by an external program, or user exit. 60 Version 2.4

79 Each time the user exit is called it must return all instances for a software component. This enabler uses previous instance information to determine which new instances to create and which no longer exist. The user exit may also return instance information, including process, service, and NT Performance Object information, which certain monitors use to provide enhanced monitoring capabilities. Select this enabler when you want to provide your own user exit to detect instances of your software component. Related enablers: None Prerequisites: This enabler does not package the user exit with the Tivoli GEM module. You should ensure that the user exit program is deployed to the monitored system so it will be found in the system path when the Tivoli GEM Instrumentation Service attempts to call it. For additional information on programming a user exit, see Programming User Exits on page Instance Discovery Enablers Required parameters: User Exit Name: The exact name of the user exit for the enabler to call. Program Parameters: The program arguments for the user exit. Optional parameters: Setup Environment 1: This enables you to issue a command prior to invoking the user exit. These environmental changes could include changing the current directory, setting an environment variable, or issuing a file command. Setup Environment 2: This enables you to issue a second preparatory command, if desired. Tasks created: None Tivoli Module Builder Tivoli Ready QuickStart User s Guide 61

80 User Exit (using File Pack) Enabler (GEM) Enabler category: Instance Discovery Applicable to module type: Tivoli GEM Description: This enabler enables you to detect instances of a software component as directed by an external program, or user exit. This enabler is packaged into a file pack which Tivoli Software Distribution deploys to the systems being monitored. Each time the user exit is called it must return all instances for a software component. This enabler uses previous instance information to determine which new instances to create and which no longer exist. The user exit may also return instance information, including process, service, and NT Performance Object information, which certain monitors use to provide enhanced monitoring capabilities. Select this enabler when you want to detect instances of the software component using an external program or user exit, and you want to use Tivoli Software Distribution to deploy the file pack to systems being monitored. Related enablers: If you do not want to deploy using Tivoli Software Distribution, use the User Exit Enabler (see User Exit Enabler (GEM) on page 60. Prerequisites: This enabler does not package the user exit with the Tivoli GEM module. You should ensure that the user exit program is deployed to the monitored system so it will be found in the system path when the Tivoli GEM Instrumentation Service attempts to call it. Required parameters: User Exit Name: The name of the user exit for the enabler to call. Use the browser file option on the input field to select the file. 62 Version 2.4

81 Program Parameters: Program arguments for the user exit. Optional parameters: Setup Environment 1: This enables you to issue a command prior to invoking the user exit. These environmental changes could include changing the current directory, setting an environment variable, or issuing a file command. Setup Environment 2: This enables you to issue a second preparatory command, if desired. Tasks created: None For additional information on programming a user exit, see Programming User Exits on page 169. User ID and Program Enabler (GEM) Enabler Category: Instance Discovery Applicable to module type: Tivoli GEM 5. Instance Discovery Enablers Description: This enabler enables you to detect instances of a software component based on a unique user ID. As an option, you can create a new instance for each unique user ID and parameter combination. The name of each instance is a combination of the user ID, program name, and the parameters. The enabler creates new instances of the software component only when a unique combination of user ID, program name, and parameters is detected. Once detected, an instance remains discovered until the Tivoli GEM database clears or the Tivoli GEM Instrumentation Service data stores are deleted. A task is provided that enables you to remove all awareness of the instance. Select this enabler when the software component can be started multiple times on a single system, and each instance can be differentiated by a unique combination of user ID, program name, and parameters that start the program. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 63

82 Related enablers: None Prerequisites: None Required Parameters: Program or Image Name: The exact program or image name, excluding path information, of the software component s executable file, including both the file name and type. The name should match the process names displayed by the Windows NT task manager or the ps command on a UNIX system. Consider Parameters: Indicates whether start-up parameters should also be considered in discovering unique instances of the software component. Note: When this enabler detects a process started by Java, it considers the Java class name, excluding the package name, as the program name to determine if a Java executable needs to be monitored. Optional parameters: None Tasks created: When this enabler is built, the following tasks are created: Delete_Instance: Use this task to remove all awareness of the instance. This task removes the current instance, but does not stop the enabler from rediscovering the instance at a later time. To prevent it from being re-discovered, remove the instrumentation from your system. 64 Version 2.4

83 6 Instance Information Enablers Instance information enablers are available to provide additional instance identification during instance discovery, to support Tivoli GEM connections and enable instance filtering. Refer to the Tivoli Global Enterprise Manager Advanced Business System Enablement Guide for more information on instance information enablers. Examples of instance information, including primary and secondary attributes, are TCP addresses and port numbers used for communicating, or application domain or cluster names. 6. Instance Information Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 65

84 Figure 27. Selecting an Instance Information Enabler in the Instrument stage The following instance information enablers are available: Instance Information Enablers For Details: Instance Information by User Exit Enabler See page 66 Instance Information by User Exit (using File Pack) See page 68 Enabler Instance Information from Flat File (using File Pack) See page 69 Instance Information by User Exit Enabler (GEM) Enabler category: Instance Information Applicable to module type: Tivoli GEM Description: This enabler calls the user exit that provides instance information. You are responsible for deploying the user exit to the system where monitoring will take place. The user exit is called with 66 Version 2.4

85 the instance identifier and must return a complete list of all pairs of primary and secondary attributes for the instance. Select this enabler when you want to use a predefined user exit to provide the instance information and the user exit is already available on the target system or it is deployed independently of this application management module. Related enablers: This enabler does not use Tivoli Software Distribution to package the user exit for deployment. If you want to deploy using Tivoli Software Distribution, use the Instance Information by User Exit (using File Pack) Enabler (see page 68). Prerequisites: The user exit must be created and available so that it can be added to the instrumentation during the module build. For more information on building user exits, see Programming User Exits on page 169. Required parameters: User Exit Name: The file name of the desired user exit to call. You can specify just the file name if the file is available in the path of the target system, or you can specify the fully-qualified file path, or you may choose to use the optional Setup Environment parameters to set up the desired path. Optional parameters: Program Parameters: Program arguments for the user exit. Note: The instance identifier is the first argument following the program parameters. Setup Environment1: This enables you to issue optional preparatory commands to make any necessary environmental changes prior to issuing a user exit, for example, changing the current directory, setting an environment variable, or issuing a file command. 6. Instance Information Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 67

86 Setup Environment2: This enables you to issue a second optional preparatory command, similar to Setup Environment1. Use as needed. Tasks created by selecting this enabler: None Monitors associated with this enabler: None Instance Information by User Exit (using File Pack) Enabler (GEM) Enabler category: Instance Information Applicable to module type: Tivoli GEM Description: This enabler calls the user exit that provides instance information. The user exit is called with the instance identifier and must return a complete list of all pairs of primary and secondary attributes for the instance. Select this enabler when you want to use a predefined user exit to provide the instance information. Related enablers: This enabler uses Tivoli Software Distribution to package the user exit for deployment. If you do not want to deploy using Tivoli Software Distribution, use the Instance Information by User Exit Enabler (see page 66). Prerequisites: The user exit must be created and available. For more information on building user exits, see Programming User Exits on page 169. Required parameters: User Exit Name: The file name of the desired user exit to call. Double click this input field to bring up the Choose a File dialog and navigate to the desired file. Optional parameters: 68 Version 2.4

87 Program Parameters: Program arguments for the user exit. Note: The instance identifier is the first argument following the program parameters. Setup Environment1: This enables you to issue optional preparatory commands to make any necessary environmental changes prior to issuing a user exit, for example, changing the current directory, setting an environment variable, or issuing a file command. Setup Environment2: This enables you to issue a second optional preparatory command, similar to Setup Environment1. Use as needed. Tasks created by selecting this enabler: None Monitors associated with this enabler: None Instance Information from Flat File (using File Pack) (GEM) Enabler category: Instance Information Applicable to module type: Tivoli GEM Description: This enabler uses a flat file to discover instance information associated with a software component instance. The flat file is packaged for deployment for Tivoli Software Distribution. You must provide the name of the flat file when defining this enabler. The flat file is organized into a list of elements that allow instance information to be provided for one or more instances of the software component. Each line in the flat file consists of a key and the instance information. The enabler uses the key information when searching the flat file to identify which line applies to the specific instance. You can also define primary and secondary instance information. 6. Instance Information Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 69

88 For more information on building flat files, see Flat File Formats on page 187. Select this enabler when you want to provide a flat file containing additional instance information for your software component. Related enablers: None Prerequisites: None Required parameters: File Name: The name of the flat file where additional instance information is defined. Double click this input field to bring up the Choose a File dialog and navigate to the desired file. Optional parameters: None Tasks created by selecting this enabler: None Monitors associated with this enabler: None For more information on building a flat file, see Flat File Formats on page Version 2.4

89 7 Inventory Enablers 7. Inventory Enablers This category of enablers is logically a type of discovery enabler. There is one enabler in this category, the Inventory Signature Enabler. The Inventory Signature Enabler is optional, but if it is used, there can be only one defined. Inventory enablers discover installed software, while instance discovery enablers discover running instances of software. For these reasons, this enabler category is separated from the Instance Discovery Enablers category. Figure 28. Selecting an Inventory Enabler in the Instrument stage Tivoli Module Builder Tivoli Ready QuickStart User s Guide 71

90 The following inventory enablers are available: Inventory Enablers For Details: Inventory Signature Enabler See page 72 Inventory Signature Enabler (ITD, Plus) Enabler category: Inventory Applicable to module types: IT Director, Plus Description: This enabler detects instances of a software component based on a file or list of files, along with file details such as size, date, and time, which together make up the inventory signature for the component. Select this enabler when you want to detect specific file names, dates and sizes associated with a specific release level of the software component. If you have the multiple versions of the same software component on your system, you can detect each unique instance of the software component for each unique version or release level. Related enablers: None Prerequisites: Any files that you need for inventory must already exist on the system where you are running the QuickStart wizard. During the module build, the QuickStart wizard will access these files and extract certain information it needs to generate the inventory instrumentation. Even if you are building a module for a UNIX platform, for example, and you are running your QuickStart wizard on an Intel system, you must first copy the desired UNIX files needed for inventory to an accessible location on the Intel system. Required parameters: Signature File List: This is a list of files with associated details (name, size, date, and time) that you want to associate with your 72 Version 2.4

91 software component as its inventory signature. You can add files to the signature file list using the following steps: 1. Double-click on the Current Value field in the Parameters window for this enabler. The Signature File List Chooser dialog is displayed. 7. Inventory Enablers Figure 29. Create your inventory signature file list using the Signature File List Chooser dialog. 2. Navigate to the desired subdirectory containing the files you wish to add to the inventory signature file list. 3. Select each desired file and click Add to List to add the file, or click Remove from List to remove a file. 4. When you are satisfied with the list of files that make up the signature, click Accept to close the dialog and return to the Parameters window. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 73

92 Optional parameters: None Tasks created by selecting this enabler: None Monitors associated with this enabler: None For further customization of the inventory signature information using the Tivoli Module Builder product, note that, for both Plus and IT Director modules, signature information is generated in the corresponding AMS component. Each signature file will have one entry in the AMS Software Signature group. If each signature file has not already been included in the AMS Distribution File List group, an entry will be added to this group with a source location index that references a source location of an empty string ( ), providing the same result as selecting none for source location using the Tivoli Module Designer. 74 Version 2.4

93 8 Task Enablers Task enablers provide operational control of the application environment. You can define your own tasks using the QuickStart wizard. Note: Unless otherwise noted, for all tasks which apply to Plus modules, you will find a Plus-specific parameter called Hidden Task, that indicates whether or not this task should be accessible in the TivoliPlus window. This parameter is set to false by default, meaning the task is not hidden. If you set this parameter to true, the task will be hidden from the TivoliPlus window, but you can still choose the task as a response task for the monitor or the Tivoli Enterprise Console. 8. Task Enablers See the Tivoli Module Builder User s Guide for more information on the Hidden Task parameter. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 75

94 Figure 30. Selecting a Task Enabler in the Instrument stage The following task enablers are available: Task Enablers For Details: Generic Task Enabler See page 77 Generic Task Enabler, Instance ID Passed In See page 79 IT Director Generic Task (with argument/response bean) See page 80 Enabler Launch Browser Enabler See page 82 Launch Telnet Enabler See page 83 Plus Application Launch Enabler See page 84 Recover Enabler See page 86 Recover Service Enabler See page 87 Start Task Enabler (GEM Specific) See page 88 Generic Start Task Enabler See page 90 Start Task using File Pack Enabler See page 91 Start NT Service Enabler See page Version 2.4

95 Task Enablers For Details: Stop NT Service Enabler See page 94 Stop Task Enabler (GEM Specific) See page 95 Generic Stop Task Enabler See page 96 Stop Task Using Filepack Enabler See page 97 Specifying Command Parameters for Task Enablers In the task enabler descriptions that follow, you will find some task enablers that include parameters enabling you to specify commands or preparatory commands that will be executed in the Tivoli GEM, Plus, or IT Director environments. These commands are expected to be in the form of bash shell script command syntax. Plus and Tivoli GEM modules run in Tivoli Enterprise environments where a shell script environment is available. IT Director modules built by the QuickStart wizard will automatically include the required shell utilities to deploy to IT Director endpoints for running these scripts. See the Tivoli Module Builder Release Notes under IT Director Module Considerations for more information on the IT Director Application Tools extension. 8. Task Enablers Generic Task Enabler (GEM, ITD, Plus) Enabler Category: Task Enabler Applicable to module type: Tivoli GEM, IT Director, Plus Description: This enabler is used to run arbitrary tasks from the management desktop, issuing tasks and capturing results. These tasks are included in the application s task library, and are part of the software component s task list that is displayed by the Tivoli management console. This task assumes that the command to be executed is in the path on the target machine (you can use the preparatory commands to set the path properly). Tivoli Module Builder Tivoli Ready QuickStart User s Guide 77

96 Select this enabler to issue various tasks (command file, script, Java program, or binary executable file) on the target machine, in the Tivoli GEM, Plus, or IT Director environments. This enabler is not instance specific. Related enablers: If you want to direct your task to a particular instance of the software component (for Tivoli GEM only), you should use the Generic Task Enabler, Instance ID Passed In (see page 79). If, in the case of Tivoli GEM, the command does not exist on the target and you want to distribute the command to the target, you can use the Add File to Filepack Enabler. If, in the case of IT Director, you want to issue a task using Java argument and response beans, or if you want the command distributed, you should use the IT Director Generic Task (with argument/response bean) Enabler (see page 80). Prerequisites: None Required parameters: Task Name: This is the label for the task. Task names must be unique, and are case-sensitive. Command to execute: This is the name of the command to execute. See Specifying Command Parameters for Task Enablers on page 77 for more information. Hidden Task: Only valid for Plus modules, this determines whether or not the task is hidden in the Plus desktop. It is set to false by default. Use the drop down list to select either true or false. Optional parameters: Preparatory Command 1: This is valid for all three module types, and can be used to issue a command prior to issuing the command to execute. Use this, for example, to set the desired path for the command to execute, set an environment variable, or issue a file command. 78 Version 2.4

97 Preparatory Command 2: This is valid for all three module types, and enables you to issue a second preparatory command if desired. Program Parameters: Any arguments that need to be passed in to the command to execute are specified here. Tasks created: When this enabler is built, the task you specified is created. Monitors associated with this enabler: None Generic Task Enabler, Instance ID Passed In (GEM) Enabler Category: Task Enabler Applicable to module type: Tivoli GEM Description: This enabler is identical to the Generic Task Enabler (see page 77), except that it calls the target command to be executed with the Tivoli GEM instance ID as a parameter. This enables the task to be directed to a particular instance of the software component. 8. Task Enablers When the instance-based task is issued from the Tivoli GEM console, Tivoli GEM provides the instance information to the task. If the instance-based task is issued from the application s task library on the Tivoli desktop, a dialog is displayed that asks you for the instance ID. Select this enabler when you want to issue a command to a specific instance of the software component. Related enablers: If you do not need to direct your task to a particular instance of the software component (for Tivoli GEM only), you should use the Generic Task Enabler (see page 77). If the command does not exist on the target and you want to distribute the command to the target system, you can use the Add File to Filepack Enabler. If, in the case of IT Director, you want to issue a task using Tivoli Module Builder Tivoli Ready QuickStart User s Guide 79

98 Java argument and response beans, you should use the IT Director Generic Task (with argument/response bean) Enabler (see page 80). Prerequisites: None Required Parameters: Task Name: This is the label for the task. Task names must be unique, and are case-sensitive. Command to execute: This is the name of the command to execute. Optional Parameters: Preparatory Command 1: This enables you to issue a command prior to issuing the command to execute. Use this, for example, to set the desired path for the command to execute, set an environment variable, or issue a command. Preparatory Command 2: This enables you to issue a second preparatory command if desired. Program Parameters: Any arguments that need to be passed in to the command to execute are specified here. The parameters specified here precede the instance ID. Tasks created: When this enabler is built, the generic task you specified is created. Monitors associated with this enabler: None IT Director Generic Task (with argument/response bean) Enabler (ITD) Enabler Category: Task Enabler Applicable to module type: IT Director Description: This enabler is valid only for IT Director, and enables you to issue tasks using Java argument and response beans. The argument and response bean names refer to Java beans that exist in a 80 Version 2.4

99 .jar file that you specify at the project level (see IT Director Specific Build Options on page 38). The Command to execute parameter on this enabler is specified as a file name rather than a text string. The command is automatically distributed at execution time to the target, without the need to include it in a file pack and distribute it separately. IT Director components are typically platform specific (as opposed to Plus components, which are platform independent). Select this enabler when you want to use Java beans in the IT Director environment to issue commands. Related enablers: See the Generic Task Enabler (page 77), and the Generic Task Enabler, Instance ID Passed In (page 79) for information on related generic task enablers. Prerequisites: You must create any argument and response beans you wish to refer to with this enabler. 8. Task Enablers Required Parameters: Task Name: This is the label for the task. Task names must be unique, and are case-sensitive. Command to execute: This is the name of the command to execute. Optional Parameters: Argument Bean: This is the name of the IT Director argument bean. Response Bean: This is the name of the IT Director response bean. See the document, Managing Applications with Tivoli IT Director, in your \module_dev\examples\it Director subdirectory, for more information on argument and response beans. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 81

100 Tasks created: When this enabler is built, the task you specified is created. Monitors associated with this enabler: None Launch Browser Enabler (GEM) Enabler Category: Task Enabler Applicable to module type: Tivoli GEM Description: This enabler defines a Tivoli GEM task to launch a local web browser on the system where the Tivoli GEM console is running, and display a particular Universal Resource Locator (URL) address in the browser window. The URL can contain Tivoli GEM symbolic variables that are specific to an instance of the software component. These symbolic variables will be resolved at the time the task is executed. For example, %HB_HOSTNAME% would resolve to the host name of the machine on which the software component instance is executing. The symbolic substitution is especially valuable when the software component has a browser interface for its configuration and management functions. Select this enabler when you want to create a Tivoli GEM task to launch a local Web browser and display a particular URL. Related enablers: None Prerequisites: None Required Parameters: Task Name: The name of the task, that will appear on the Tivoli GEM console, to launch the local Web browser. Task names must be unique, and are case-sensitive. URL: The address of the web page that displays when the browser is launched, for example, The 82 Version 2.4

101 URL can include instance specific symbolic variables that are resolved at task execution time prior to invoking the browser. Optional Parameters: None Tasks created: When this enabler is built, the Tivoli GEM Launch Local Browser task is created. Monitors associated with this enabler: None Launch Telnet Enabler (GEM) Enabler Category: Task Enabler Applicable to module type: Tivoli GEM Description: This enabler defines a Tivoli GEM task to launch a local telnet session on the system where the Tivoli GEM console is running. When invoked from the Tivoli GEM console, the telnet session attempts to connect to the provided hostname. The hostname can contain a Tivoli GEM symbolic variable, such as %HB_HOSTNAME%, that is specific to an instance of the software component. This symbolic variable will be resolved at the time the task is executed. 8. Task Enablers Select this enabler when you want to create a Tivoli GEM task to launch a local telnet session and connect to a desired host. Related enablers: None Prerequisites: None Required Parameters: Task Name: This is the name of the task, that will appear on the Tivoli GEM console, to launch the local telnet session. Task names must be unique, and are case-sensitive. Hostname: This is the name of the desired host to connect to when the telnet session is invoked. To target the telnet session to the host where the specific software component instance is Tivoli Module Builder Tivoli Ready QuickStart User s Guide 83

102 executing, input the hostname as %HB_HOSTNAME%. The hostname is resolved at task execution time prior to invoking the telnet session. Optional Parameters: None Tasks created: When this enabler is built, the Tivoli GEM Launch telnet session task is created. Monitors associated with this enabler: None Plus Application Launch Enabler (Plus) Enabler Category: Task Enabler Applicable to module type: Plus Description: This enabler enables an application to be started on a managed node or endpoint. Similar to the application launch task in the traditional Plus template, this enabler generates a script that creates the application launch icon and invokes the specified program with the specified parameters on a node, provided that the application server check is passed at the time that the module is installed. You can include more than one Plus Application Launch Enabler per QuickStart wizard component. If you define one or more Plus Application Launch Enablers for a given QuickStart wizard component, the installed Plus module will include one application launch icon for that component. The menu selections on that icon correspond to the Plus Application Launch Enablers that were specified for that component in the QuickStart wizard. To launch the command specified in a QuickStart wizard Plus Application Launch Enabler, select the application launch icon for that component on the TivoliPlus window, and from the menu, select the name of the desired enabler task that you wish to launch. Select this enabler when you want to create a Plus task that starts an application on a managed node or endpoint. 84 Version 2.4

103 Note: To start an application on an endpoint, be sure to check the Endpoint Launch task check box in the Plus Specifics dialog of the Finish stage. See Plus Specific Build Options on page 35 for more information. Related enablers: None Prerequisites: You must have the Plus Module Support (Link Binaries) installed in your TMR before loading your Plus module. See the Tivoli Module Builder Release Notes for more information. Required Parameters: Task Name: The label for the application launch task. Task names must be unique, and are case-sensitive. Launch Program Name: The name of the program to be launched when this task is invoked. Note: There is no Hidden Task parameter for this enabler. If you want to create a hidden task on the TivoliPlus window that starts or restarts the application, you should use the Generic Task Enabler (see page 77). 8. Task Enablers Optional Parameters: Setup Environment 1: This enables you to issue a command prior to issuing the command to execute. Use this, for example, to set the desired path for the command to execute, set an environment variable, or issue a file command. Setup Environment 2: This enables you to issue a second preparatory command if desired. Launch Program Parameters: Specifies any parameters that need to be passed to the program being launched. Application Server Check Command: This is the command that will be executed to check the node for the application. The command should return a 0 if the application does not exist on the node, or a 1 if it does exist. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 85

104 Tasks created: When this enabler is built, the application launch task is created for Plus modules only. Monitors associated with this enabler: None Recover Enabler (ITD, Plus) Enabler Category: Task Enabler Applicable to module type: IT Director, Plus Description: This enabler creates a recover task on the desktop. Valid only for Plus and IT Director modules, this enabler generates a skeleton file which will call a specified stop program, then call a specified start program. You can provide additional functionality, for example, backing up files, by using the Tivoli Module Builder for Plus modules. Select this enabler when you want to create a recover task on your Plus or IT Director desktop. Related enablers: If you want to create a task to stop and restart a specific NT service, then use the Recover Service Enabler (see page 87). Prerequisites: If you want additional functionality beyond starting and stopping the target software component, you must modify the skeleton file to provide this function. Required Parameters: Task Name: This is the label of the recover task. Task names must be unique, and are case-sensitive. Stop Program Name: This is the name of the Stop program name to be executed. This is a string value, which you can specify as an executable program name, or as a command. See Specifying Command Parameters for Task Enablers on page 77 for more information. 86 Version 2.4

105 Start Program Name: This is the name of the Start program to be executed. This is a string value, which you can specify as an executable program name, or as a command. See Specifying Command Parameters for Task Enablers on page 77 for more information. Hidden Task: Only valid for Plus modules, this determines whether or not the task is hidden on the TivoliPlus window. It is set to false by default. Use the drop down list to select either true or false. Optional Parameters: Setup Environment 1: This enables you to issue a command prior to issuing the command to execute. Use this, for example, to set the desired path for the command to execute, set an environment variable, or issue a file command. Setup Environment 2: This enables you to issue a second preparatory command if desired. Start program parameters: Specify any parameters that need to be passed to the start program. Stop program parameters: Specify any parameters that need to be passed to the stop program. 8. Task Enablers Tasks created: When this enabler is built, the recover task is created for Plus or IT Director environments. Monitors associated with this enabler: None Recover Service Enabler (ITD, Plus) Enabler Category: Task Enabler Applicable to module type: IT Director, Plus Description: This enabler creates a task to recover a specific NT service. The default implementation stops and then restarts the NT service. You can provide any additional functionality by using the Tivoli Module Builder for Plus modules. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 87

106 Select this enabler when you want to create a task for Plus or IT Director modules to restart a NT service. Related enablers: If you want to generate a task to recover a specific software component, use the Recover Enabler (see page 86). Prerequisites: None Required Parameters: Task Name: This is the label of the recover task. Task names must be unique, and are case-sensitive. Service Name: This is the name of the NT service to be restarted. Hidden Task: Only valid for Plus modules, this determines whether or not the task is hidden in the Plus desktop. It is set to false by default. Use the drop down list to select either true or false. Optional Parameters: None Tasks created: When this enabler is built, the recover NT service task is created. Monitors associated with this enabler: None Start Task Enabler (GEM) Enabler Category: Task Enabler Applicable to module type: Tivoli GEM Description: This enabler generates a start task on the Tivoli GEM console to start an instance of a software component, a service, or a daemon. Select this enabler if you want to create a start task for Tivoli GEM, which includes the ability to optionally specify one or two preparatory commands to set up the environment, as well as 88 Version 2.4

107 optionally pass the instance ID as one of the arguments, to target a specific instance of the software component. Use this enabler if you are not requiring Tivoli Software Distribution to deploy your instrumentation. Related enablers: If you want to use Tivoli Software Distribution to deploy your instrumentation, use the Start Task using File Pack Enabler (see page 91). If you do not need to target a specific instance of the software component, you can use the Generic Start Task Enabler (see page 90). Prerequisites: None Required Parameters: Task Name: This is the name of the start task. Task names must be unique, and are case-sensitive. Program Name: This is the name of the program to be executed by the task. 8. Task Enablers Optional Parameters: Setup Environment 1: This enables you to issue a command prior to issuing the command to execute. Use this, for example, to set the desired path for the command to execute, set an environment variable, or issue a file command. Setup Environment 2: This enables you to issue a second preparatory command if desired. Program Parameters: Any arguments that need to be passed in to the command to execute are specified here. The parameters specified here precede the instance ID. Pass InstanceID as argument: Select Yes from the drop-down list to pass in the instance ID as the first argument in the program parameters field. This field is set to No by default. Tasks created: When this enabler is built, the start task is created to start a service or daemon. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 89

108 Monitors associated with this enabler: None Generic Start Task Enabler (GEM, ITD, Plus) Enabler Category: Task Enabler Applicable to module type: Tivoli GEM, IT Director, Plus Description: This enabler is similar to the Start Task Enabler (see page 88), but is more general in nature and is applicable to all three module types. This enabler allows the instance ID to be specified in the parameter list. This enabler creates a start task to start a particular service or daemon. Select this enabler if you want to create a general start task for any of the module types, and do not need to target a specific instance of the software component. Related enablers: If you want to use Tivoli Software Distribution to deploy your instrumentation for Tivoli GEM modules, use the Start Task using File Pack Enabler (see page 91). If you only need a Tivoli GEM task, or if you want to target a particular instance of the software component, you can use the Start Task Enabler (see page 88). Prerequisites: None Required Parameters: Task Name: This is the name of the start task. Task names must be unique, and are case-sensitive. Program Name: This is the name of the program to be executed by the task. See Specifying Command Parameters for Task Enablers on page 77 for more information. Optional Parameters: Setup Environment 1: This can be used to issue a command prior to issuing the command to execute. Use this, for example, 90 Version 2.4

109 to set the desired path for the command to execute, set an environment variable, or issue a file command. Setup Environment 2: This enables you to issue a second preparatory command if desired. Program Parameters: Any arguments that need to be passed in to the command to execute are specified here. The parameters specified here precede the instance ID. Hidden Task: Only valid for Plus modules, this determines whether or not the task is hidden on the TivoliPlus window. It is set to false by default. Use the drop down list to select either true or false. Tasks created: When this enabler is built, a start task is created to start the desired service or daemon. Monitors associated with this enabler: None Start Task using File Pack Enabler (GEM) Enabler Category: Task Enabler 8. Task Enablers Applicable to module type: Tivoli GEM Description: This enabler generates a start task on the Tivoli GEM console to start an instance of a software component, for example, a service or daemon. Select this enabler if you want to create a start task for Tivoli GEM, which includes the ability to optionally specify one or two preparatory commands to set up the environment, as well as optionally pass the instance ID as one of the arguments, to target a specific instance of the software component. Use this enabler if you want to use Tivoli Software Distribution to deploy your instrumentation. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 91

110 Note: If you already selected an Instance Discovery NT Services Enabler for Tivoli GEM, you do not need to use this enabler to create an NT Service Start task, since one is already created for you. Related enablers: If you do not need to use Tivoli Software Distribution to deploy your instrumentation, use the Start Task Enabler (see page 88). If you do not need to target a specific instance of the software component, you can use the Generic Start Task Enabler (see page 90). Prerequisites: None Required Parameters: Task Name: This is the name of the start task. Task names must be unique, and are case-sensitive. Program Name: This is the name of the program to be executed by the task. Optional Parameters: Preparatory Command 1: This enables you to issue a command prior to issuing the command to execute. Use this, for example, to set the desired path for the command to execute, set an environment variable, or issue a file command. Preparatory Command 2: This enables you to issue a second preparatory command if desired. Program Parameters: Any arguments that need to be passed in to the command to execute are specified here. The parameters specified here precede the instance ID. Pass InstanceID as argument: Select Yes from the drop-down list to pass in the instance ID as the first argument in the Program Parameters field. This field is set to No by default. Tasks created: When this enabler is built, the start task is created. Monitors associated with this enabler: None 92 Version 2.4

111 Start NT Service Enabler (ITD, Plus) Enabler Category: Task Enabler Applicable to module type: IT Director, Plus Description: This enabler is specific to Plus and IT Director modules, and is used to create a task to start a particular NT service. For Plus modules, a skeleton file is created that calls the appropriate Windows NT net command, as follows: net start <servicename> For IT Director modules, an entry is generated in the appropriate.cdf file. The enabler causes the Service Start Supported attribute to be set to 1 (true). IT Director uses this to create a predefined implementation of a start service task. Select this enabler to create a task in the Plus or IT Director environments to start a particular NT service. 8. Task Enablers Related enablers: There is also an accompanying Stop NT Service task. See the Stop NT Service Enabler description on page 93. Prerequisites: None Required Parameters: Task Name: This is the label of the NT service start task. Software component names must be unique. Task names must be unique, and are case-sensitive. Service Name: This is the name of the NT service to be started. Hidden Task: Only valid for Plus modules, this determines whether or not the task is hidden in the Plus desktop. It is set to false by default. Use the drop down list to select either true or false. Tasks created: When this enabler is built, the desired Start NT Service task is created. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 93

112 Monitors associated with this enabler: None Stop NT Service Enabler (ITD, Plus) Enabler Category: Task Enabler Applicable to module type: IT Director, Plus Description: This enabler is specific to Plus and IT Director modules, and is used to create a task to stop a particular NT service. For Plus modules, a skeleton file is created that calls the appropriate Windows NT net command, as follows: net stop <servicename> For IT Director modules, an entry is generated in the appropriate.cdf file. The enabler causes the Service Stop Supported attribute to be set to 1 (true). IT Director uses this to create a predefined implementation of a stop service task. Select this enabler to create a task in the Plus or IT Director environments to stop a particular NT service. Related enablers: There is also an accompanying Start NT Service task. See the Start NT Service Enabler description on page 93. Prerequisites: None Required Parameters: Task Name: This is the label of the Stop NT Service task. Task names must be unique, and are case-sensitive. Service Name: This is the name of the NT service to be stopped. Hidden Task: Only valid for Plus modules, this determines whether or not the task is hidden in the Plus desktop. It is set to false by default. Use the drop down list to select either true or false. 94 Version 2.4

113 Tasks created: When this enabler is built, the desired Stop NT Service task is created. Monitors associated with this enabler: None Stop Task Enabler (GEM) Enabler Category: Task Enabler Applicable to module type: Tivoli GEM Description: This enabler generates a stop task on the Tivoli GEM console to stop an instance of a software component, for example, a service or daemon. Select this enabler if you want to create a stop task for Tivoli GEM, which includes the ability to optionally specify one or two preparatory commands to set up the environment, as well as optionally pass the instance ID as one of the arguments, to target a specific instance of the software component. Use this enabler if you are not requiring Tivoli Software Distribution to deploy your instrumentation. 8. Task Enablers Related enablers: If you want to use Tivoli Software Distribution to deploy your instrumentation, use the Stop Task Using Filepack Enabler (see page 97). If you do not need to target a specific instance of the software component, you can use the Generic Stop Task Enabler (see page 96). Prerequisites: None Required Parameters: Task Name: This is the name of the stop task. Task names must be unique, and are case-sensitive. Program Name: This is the name of the program to be executed by the task. Optional Parameters: Tivoli Module Builder Tivoli Ready QuickStart User s Guide 95

114 Setup Environment 1: This enables you to issue a command prior to issuing the command to execute. Use this, for example, to set the desired path for the command to execute, set an environment variable, or issue a file command. Setup Environment 2: This enables you to issue a second preparatory command if desired. Program Parameters: Any arguments that need to be passed in to the command to execute are specified here. The parameters specified here precede the instance ID. Pass instanceid as argument: Select Yes from the drop-down list to pass in the instance ID as the first argument in the Program Parameters field. This field is set to No by default. Tasks created: When this enabler is built, the stop task is created to stop a service or daemon. Monitors associated with this enabler: None Generic Stop Task Enabler (GEM, ITD, Plus) Enabler Category: Task Enabler Applicable to module type: Tivoli GEM, IT Director, Plus Description: This enabler is similar to the Stop Task Enabler (see page 95), but is more general in nature and is applicable to all three module types. This enabler has the optional setup environment commands, but does not allow the instance ID to be specified in the parameter list. This enabler creates a stop task to stop a particular service or daemon. Select this enabler if you want to create a general stop task for any of the module types, and do not need to target a specific instance of the software component. Related enablers: If you want to use Tivoli Software Distribution to deploy your instrumentation, use the Stop Task Using Filepack Enabler (see page 97). If you only need a Tivoli GEM task, or if you 96 Version 2.4

115 want to target a particular instance of the software component, you can use the Stop Task Enabler (see page 95). Prerequisites: None Required Parameters: Task Name: This is the name of the stop task. Task names must be unique, and are case-sensitive. Program Name: This is the name of the program to be executed by the task. See Specifying Command Parameters for Task Enablers on page 77 for more information. Optional Parameters: Setup Environment 1: This enables you to issue a command prior to issuing the command to execute. Use this, for example, to set the desired path for the command to execute, set an environment variable, or issue a file command. Setup Environment 2: This enables you to issue a second preparatory command if desired. Program Parameters: Any arguments that need to be passed in to the command to execute are specified here. The parameters specified here precede the instance ID. Hidden Task: Only valid for Plus modules, this determines whether or not the task is hidden on the TivoliPlus window. It is set to false by default. Use the drop down list to select either true or false. 8. Task Enablers Tasks created: When this enabler is built, a Stop task is created to stop the desired service or daemon. Monitors associated with this enabler: None Stop Task Using Filepack Enabler (GEM) Enabler Category: Task Enabler Applicable to module type: Tivoli GEM Tivoli Module Builder Tivoli Ready QuickStart User s Guide 97

116 Description: This enabler generates a stop task on the Tivoli GEM console to stop an instance of a software component, that is, a service or daemon. Select this enabler if you want to create a stop task for Tivoli GEM, which includes the ability to optionally specify one or two preparatory commands to set up the environment, as well as optionally pass the instance ID as one of the arguments, to target a specific instance of the software component. Use this enabler if you want to use Tivoli Software Distribution to deploy your instrumentation. Related enablers: If you do not need to use to use Tivoli Software Distribution to deploy your instrumentation, use the Stop Task Enabler (see page 95). If you do not need to specify any environment setup commands, and do not need to target a specific instance of the software component, you can use the Generic Stop Task Enabler (see page 96). Prerequisites: None Required Parameters: Task Name: This is the name of the stop task. Task names must be unique, and are case-sensitive. Program Name: This is the name of the program to be executed by the task. Optional Parameters: Preparatory Command 1: This can be used to issue a command prior to issuing the command to execute. Use this, for example, to set the desired path for the command to execute, set an environment variable, or issue a file command. Preparatory Command 2: This enables you to issue a second preparatory command if desired. Program Parameters: Any arguments that need to be passed in to the command to execute are specified here. The parameters specified here precede the instance ID. 98 Version 2.4

117 Pass InstanceID as argument: Select Yes from the drop-down list to pass in the instance ID as the first argument in the Program Parameters field. This field is set to No by default. Tasks created: When this enabler is built, the start task is created. Monitors associated with this enabler: None 8. Task Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 99

118 100 Version 2.4

119 9 Monitor Enablers Monitors enable the operator to view the overall status of the monitored resources. Monitors ensure that key system or network resources needed by a component are available. Monitor enablers provide monitoring capabilities for particular application characteristics related to the health of the application. For Tivoli GEM modules, the particular monitor enablers that are available to you may depend on the instance discovery enabler you have chosen. Monitor Enablers and Instance Context Some monitor enablers for Tivoli GEM provide enhanced monitoring capabilities according to the instance-context of the software component being monitored. There are three basic types of instance-context information that can be associated with an instance, depending on the instance discovery enabler selected: Process Leader Context: This consists of the discovery program name, the active process program identification (PID), and the parent PID. The context contains an awareness of process hierarchy in the discovered processes program group. Instance discovery enablers associated with this type of instance-context include: v Start Up Parameters Enabler v User ID and Program Enabler 9. Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 101

120 v Specific NT Service Enabler v NT Services Enabler v NT Service by Program Name Enabler v User Exit Enabler Windows NT Service Context: This consists of the discovered NT Service and the program process ID that implements the service (if the service is active). The instance discovery enablers that create this instance-context include: v NT Service by Program Name Enabler v NT Services Enabler v Specific NT Service Enabler v User Exit Enabler Windows NT Object Context: This consists of the name of the NT Performance Object responsible for discovering the instance. When an instance of the NT Object is discovered, the context also contains the identification of the instance. Instance discovery enablers associated with this instance-context include: v NT Performance Objects Enabler v User Exit Enabler The discovery services provided by the associated discovery enablers capture this instance-context information. See Instance Discovery Enablers on page 47 for details on selecting instance discovery enablers. Filtering the List of Monitor Enablers When you display the list of available monitor enablers using the QuickStart wizard, remember that this list is filtered according to three criteria: The module types you have selected to build (Tivoli GEM, Plus, or IT Director). 102 Version 2.4

121 The list of enablers will only display those enablers that are valid for the type of module you are building. For example, if you selected Tivoli GEM and Plus module types, only enablers that are valid for Tivoli GEM, or Plus, or common to those two will be selectable from the list. The platform type (selected during the Instrument stage) The instance discovery enabler you have selected. Some monitor enablers are only selectable if a certain instance discovery enabler has been selected. See the table under Monitor Enabler Dependencies on page 51) for the list of monitor enablers that are available for each instance discovery enabler selected. Note: If you are building a Tivoli GEM module, you should select an instance discovery enabler (see Instance Discovery Enablers on page 47) before you select monitor enablers. If you select an instance discovery enabler and then select monitor enablers, then later on attempt to change the discovery enabler, you may be required to remove the monitor enablers first. 9. Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 103

122 Figure 31. Selecting a Monitor Enabler in the Instrument stage Setting Monitor Enabler Thresholds For each monitor enabler that you select, you can define threshold settings for the various severity levels that the monitor value may represent. For Tivoli GEM and Plus modules, the range of severity levels includes the following: Normal Informational Warning Severe Critical Fatal For each of these severity levels, you can select one of the following operators from a pull-down menu (the value type for each field is shown in parentheses): 104 Version 2.4

123 Greater than (numeric) Less than (numeric) Equal (numeric or string) Not equal (numeric or string) Changes to (string) Changes from (string) Crosses above (numeric) Crosses below (numeric) Matches (string) Does not match (string) Note: The QuickStart wizard does not perform error checking on your input. Be sure that the operator you select is applicable to the type of monitor you are using, and that the value you specify matches the type (numeric or string) for that operator. If not, your module may fail to install properly. Once you select an operator, you can define an optional value for the threshold, and the monitor will set the specified severity level based on the thresholds that are met or exceeded. 9. Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 105

124 Figure 32. Specifying monitor enabler thresholds The operator determines how the monitor uses the threshold to determine the status of a resource. For example, the monitor assesses the severity level by verifying whether the value is greater than, equal to, or less than, the value specified in the Value field. For IT Director modules, a different set of severity levels is available: High error (numeric) Low error (numeric) High warning (numeric) Low warning (numeric) Error (string) Warning (string) Return to normal (string) IT Director internally maps these relative threshold operators to regular AMS operators as follows: IT Director Threshold AMS Severity AMS Threshold High error Critical Greater than or equal High warning Warning Greater than or equal 106 Version 2.4

125 IT Director Threshold AMS Severity AMS Threshold Low warning Warning Less than or equal Low error Critical Less than or equal Error Critical Matches Warning Warning Matches Return to normal Normal Matches Specifying Monitor Enabler Polling Intervals The polling interval indicates how often the monitor should check the status of a monitored resource. When specifying the polling interval, you may take the following into consideration: How often the application or system updates the value of the monitored resource How quickly an administrator needs to know about the situation being monitored The overhead associated with running the monitor program 9. Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 107

126 Figure 33. Specifying monitor enabler polling intervals For example, you may wish to specify that the monitor run every minute in the case of a resource whose failure immediately causes the application to be unavailable. You may wish to specify a longer interval for those resources that require more time to reach a critical status. Enter a numeric value in the Polling Interval field. Select the type of interval from the drop down menu. The following list indicates valid values for each selection on the drop down menu. 0 to 2,147,483,647 Seconds 0 to 35,791,394 Minutes 0 to 596,523 Hours 0 to 24,855 Days 0 to 3550 Weeks Polling Intervals for Multiple Instances If you define multiple instances of the same monitor enabler under one component, they will all have the same polling interval. The Application Management Specification includes polling interval 108 Version 2.4

127 information in the overall monitor definition, not on a per-instance basis. So if the polling interval for one instance is changed, the changes will be reflected in the polling intervals of the other instances. For example, an application status monitor definition might look similar to the following: AMSSynchronousMonitorDefinition AMSSynchronousMonitorInstance_1 AMSSynchronousMonitorThreshold_1 AMSSynchronousMonitorThreshold _2 AMSSynchronousMonitorInstance_2 AMSSynchronousMonitorThreshold_3 AMSSynchronousMonitorThreshold_4 Both AMSSynchronousMonitorInstance_1 and...instance_2 have unique sets of threshold levels, but the polling interval is part of the overall...definition, and will be applied to both...instance_1 and...instance_2. You can further customize these polling intervals for each instance using the Tivoli Module Designer to create a new definition, after completing the module using the QuickStart wizard. Specifying Monitor Enabler Response Tasks For Plus and IT Director modules, you can optionally define a response task that will be executed once the associated threshold severity has been reached. You can only select those tasks that you have previously defined under Task Enablers in the Instrument section of the QuickStart wizard (see Task Enablers on page 75). For each severity level, you can click the drop down menu in the Response Task column and select one of the tasks from the list. 9. Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 109

128 Monitor Enabler Descriptions The following monitor enablers are available: Monitor Enablers For Details: Custom Monitor Enabler See page 110 Instance NT Counter Monitor Enabler See page 112 Instance NT Service Monitor Enabler See page 113 Instance Process Attribute Monitor Enabler See page 114 Instance Process Count Monitor Enabler See page 115 Instance Process Time Monitor Enabler See page 117 NT Object Counter with no NT Instance Monitor See page 118 Enabler NT Object Counter with NT Instance Monitor See page 120 Enabler NT Object Monitor Enabler See page 121 NT Service Monitor Enabler See page 122 Predefined DM Monitor Enabler See page 123 Process Attribute Monitor Enabler See page 124 Process Count Monitor Enabler See page 126 Process Monitor See page 127 Process Time Monitor Enabler See page 128 State Monitor Enabler See page 129 User Exit Number Monitor Enabler See page 130 User Exit Number using File Pack Monitor See page 132 Enabler User Exit String Monitor Enabler See page 133 User Exit String using File Pack Monitor See page 135 Enabler Custom Monitor Enabler (ITD, Plus) Enabler Category: Monitor Enabler Applicable to module type: IT Director, Plus 110 Version 2.4

129 Description: You can use this enabler to create a customized monitor with no input arguments for Plus or IT Director modules. For Plus modules, a custom Distributed Monitoring (DM) monitor will be created. Default DM application-specific collection files, class files, and rules files will be automatically generated. For IT Director modules, a custom monitor will be created. Information returned from your monitor can be in numeric or string format. Select this enabler when you have a user-defined custom monitor for Plus or IT Director modules. You can include this enabler more than once in your modules, and use the parameter fields to configure it for multiple custom monitors you have defined. Related enablers: This monitor enabler is not dependent on the selection of any instance discovery enablers. Prerequisites: None Required Parameters: Monitor Name: The name of the monitor Monitor Program: The file name of your pre-defined custom monitor. Note: If you specify a batch file script, the script should exit with a return value of 0 to signify that the monitor execution was successful. Return Type: The format of the value returned from the monitor. Select either numeric or string from the drop down menu. Optional Parameters: Collection Name: This is the label for the monitor s collection. This is valid only for Plus modules. Value Description: This is a string value specifying the units of measurement for the returned value, for example, kilobytes, or seconds. 9. Monitor Enablers Tasks created: None Tivoli Module Builder Tivoli Ready QuickStart User s Guide 111

130 Instance NT Counter Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler returns the value of the NT object counter for the discovered instance. Select this enabler to monitor the value of the NT object counter for the discovered instance. Related enablers: This enabler is only available if one of the following instance discovery enablers has been selected: NT Performance Objects Enabler (see page 53) User Exit Number Monitor Enabler (see page 60) User Exit Number using File Pack Monitor Enabler (see page 62) Prerequisites: None Required Parameters: Counter Name: This is the name of the NT Object Counter to be monitored. Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval 112 Version 2.4

131 Instance NT Service Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler returns the status of a specific NT service identified in the Windows NT Service context (see Monitor Enablers and Instance Context on page 101 for more information) associated with the software component instance. This enabler returns the status of an NT Service as either Running or Stopped. These exact keywords must be used for threshold comparisons. Select this enabler when you want to monitor the status of a discovered NT service. Related enablers: This monitor enabler is only available for selection if one of the following instance discovery enablers has been selected: NT Service by Program Name Enabler (see page 54) NT Services Enabler (see page 56) Specific NT Service Enabler (see page 58) User Exit Enabler (see page 60) User Exit (using File Pack) Enabler (see page 62) Prerequisites: None Required Parameters: Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. 9. Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 113

132 Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval Instance Process Attribute Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler returns the value of the process attribute of the program identified in the Process Leader Context (see Monitor Enablers and Instance Context on page 101 for more information) associated with the instance. Attributes monitored include: Percentage of CPU (whole numbers from 0 to 100) Total rate of page faults (per second) Total amount of resident memory committed (in kilobytes) Select this enabler if you want to monitor a specific process attribute (cpu, paging, or memory) of the discovered instance. Related enablers: This monitor enabler is only available for selection if one of the following instance discovery enablers has been selected: NT Service by Program Name Enabler (see page 54) NT Services Enabler (see page 56) Specific NT Service Enabler (see page 58) Start Up Parameters Enabler (see page 59) User Exit Enabler (see page 60) User Exit (using File Pack) Enabler (see page 62) 114 Version 2.4

133 User ID and Program Enabler (see page 63) Prerequisites: None Required Parameters: Process Attribute: Select the process attribute (cpu, memory, or paging) to monitor from the drop-down list. Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval Note: When this enabler detects a process started by Java, it considers the Java class name, excluding the package name, as the program name to determine if a Java executable needs to be monitored. Instance Process Count Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM 9. Monitor Enablers Description: This monitor enabler counts the total number of active processes implemented by the process name in the Process Leader Context (see Monitor Enablers and Instance Context on page 101 for more information) associated with the software component instance. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 115

134 This enabler only considers those processes within the instance s process group. It returns a value of zero or greater for threshold processing. Select this enabler to monitor the number of active processes that are implemented by the discovered process name instance. Related enablers: This monitor enabler is only available for selection if one of the following instance discovery enablers has been selected: NT Service by Program Name Enabler (see page 54) NT Services Enabler (see page 56) Specific NT Service Enabler (see page 58) Start Up Parameters Enabler (see page 59) User Exit Enabler (see page 60) User Exit (using File Pack) Enabler (see page 62) User ID and Program Enabler (see page 63) Prerequisites: None Required Parameters: Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval 116 Version 2.4

135 Note: When this enabler detects a process started by Java, it considers the Java class name, excluding the package name, as the program name to determine if a Java executable needs to be monitored. Instance Process Time Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler returns the total number of elapsed minutes that a process has been active. The process name is identified in the Process Leader Context (see Monitor Enablers and Instance Context on page 101 for more information) associated with the software component instance. This enabler only considers those processes within the instance s process group. It returns a value of zero or greater for threshold processing. If the provided process name implements more than one process, this enabler returns the elapsed time for the process with the least amount of active time. Select this enabler when you want to monitor the total number of minutes that a process for a discovered instance has been active. Related enablers: This monitor enabler is only available for selection if one of the following instance discovery enablers has been selected: NT Service by Program Name Enabler (see page 54) NT Services Enabler (see page 56) Specific NT Service Enabler (see page 58) Start Up Parameters Enabler (see page 59) User Exit Enabler (see page 60) User Exit (using File Pack) Enabler (see page 62) 9. Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 117

136 User ID and Program Enabler (see page 63) Prerequisites: None Required Parameters: Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval Note: When this enabler detects a process started by Java, it considers the Java class name, excluding the package name, as the program name to determine if a Java executable needs to be monitored. NT Object Counter with no NT Instance Monitor Enabler (GEM, ITD) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM, IT Director Description: This monitor enabler creates a monitor for an NT object counter with no associated NT instances. This enabler is valid for Tivoli GEM or IT Director modules. This monitor enabler is available for selection with Tivoli GEM only if one of the Instance Discovery Enablers has been selected. Select this enabler to monitor an NT performance object counter with no associated Windows NT instances. 118 Version 2.4

137 Related enablers: Any of the instance discovery enablers can be selected to enable selection of this monitor enabler. If you want to monitor an NT performance object counter with associated instances, use the NT Object Counter with NT Instance Monitor Enabler (see page 120). Prerequisites: None Required Parameters: Object Name: This is the name of the NT performance object, for example, Process. Counter Name: This is the name of the NT performance counter, for example, %Processor Time. Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Value Type: Specifies the type of data to be returned by the counter. Available choices include: v unknown v 32-bit string v 64-bit string v floating point Tasks created: When this enabler is built for Tivoli GEM, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval 9. Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 119

138 NT Object Counter with NT Instance Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler creates a monitor for an NT performance object counter with NT instances. Windows NT Performance Objects and associated counters provide a detailed view into the health of an application. Select this enabler to monitor an NT performance object counter with instances. Related enablers: Any of the instance discovery enablers can be selected to enable selection of this monitor enabler. If you want to monitor an NT performance object counter with no associated instances, use the NT Object Counter with no NT Instance Monitor Enabler (see page 118). Prerequisites: None Required Parameters: Object Name: This is the name of the NT performance object, for example, Process. Counter Name: This is the name of the NT performance counter, for example, %Processor Time. Instance Name: This is the name of the NT Object Instance, for example, Command for NT Object Process. Many NT objects do not support multiple instances. If the NT object you are monitoring does support multiple instances, include this value only if you want to exclude other instances from your discovery. Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. 120 Version 2.4

139 Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval NT Object Monitor Enabler (ITD) Enabler Category: Monitor Enabler Applicable to module type: IT Director Description: This enabler generates an AMS predefined NT Performance Object monitor. Select this enabler to generate a predefined NT Performance Object monitor for IT Director modules. Related enablers: None Prerequisites: None Required Parameters: Object Name: This is the name of the performance object. Multiple Instances: This field indicates whether the object supports single or multiple instances. Select yes or no from the drop down menu provided. Optional Parameters: Event Category: This field contains source specific categorization information. See the document, Managing Applications with Tivoli IT Director, inthe \module_dev\examples\it Director subdirectory where you installed the Tivoli Module Builder. 9. Monitor Enablers Tasks created: None Tivoli Module Builder Tivoli Ready QuickStart User s Guide 121

140 NT Service Monitor Enabler (GEM, ITD, Plus) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM, IT Director, Plus Description: This monitor enabler returns the status of an NT Service as either running or stopped. Select this enabler to monitor an NT Service and determine if it is operational or not. Related enablers: If you are building a Tivoli GEM module, you must select one of the instance discovery enablers to enable selection of this monitor enabler. If you want to monitor status of a specific NT service identified in the Windows NT Service context (see Monitor Enablers and Instance Context on page 101 for more information) associated with the software component instance, use the Instance NT Service Monitor Enabler (see page 113). Prerequisites: None Required Parameters: NT Service Name: This is the name of the NT service to be monitored. This field is used for IT Director modules only. If you are only building Tivoli GEM or Plus modules, enter any non-blank alphanumeric characters here; it will be ignored. NT Service Display Name: This is the more user friendly name for the NT service. This field is used for Tivoli GEM and Plus modules only. If you are only building an IT Director module, enter any non-blank alphanumeric characters here; it will be ignored. Note: You can use the Microsoft command line utility, sc.exe to find both the service name and service display name for NT service. See the following Web site for additional information on the sc.exe utility: Version 2.4

141 Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. This parameter is required only for Tivoli GEM modules. See the State Monitor Enabler (page 129) for more information. Tasks created: When this enabler is built for Tivoli GEM, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval Predefined DM Monitor Enabler (Plus) Enabler Category: Monitor Enabler Applicable to module type: Plus Description: This enabler allows reuse of existing Distributed Monitoring (DM) monitors in a Plus module. The monitors may be selected from the following collections: DM Universal UNIX NT_Event_Log NT_Memory NT_Process NT_System NT_NetworkMonitor NT_NetworkInterface NT_ClientServicesforNetWare 9. Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 123

142 Note: Only the synchronous monitors in these collections are supported. Select this enabler if you want to define a synchronous monitor from an existing DM collection. Related enablers: None Prerequisites: Collections that you select here should be installed in your TMR before installing this Plus module. Required Parameters: Collection Name: This is the name of the DM collection. Monitor Name: This is the name of the monitor from the collection. Optional Parameters: Monitor Arguments:This is a list of argument values for the monitor. Tasks created: None Process Attribute Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler returns the specific process attributes for a program or image name. Attributes monitored include: Percentage of CPU (whole numbers from 0 to 100) Total rate of page faults (per second) Total amount of resident memory committed (in kilobytes) If this monitor executes on an instance that has a Process Leader Context, the enabler considers only the processes within the 124 Version 2.4

143 instance s process group. If a Process Leader Context is not associated with the instance, all processes on the system are considered by this monitor. Select this enabler when you want to monitor the specific process attribute (cpu, memory, paging) of a program or image name. Related enablers: For Tivoli GEM, you must select one of the instance discovery enablers for this enabler to appear in the monitor enabler selection list. If you want to monitor the process attribute of the program identified in the Process Leader Context associated with a discovered instance, use the Instance Process Attribute Monitor Enabler (see page 114). Prerequisites: None Required Parameters: Process or Image Name: Provide the exact program or image name, excluding path information, of the software component s executable file, including both the file name and type. The name should match the process name displayed by the Windows NT task manager or the output of the ps command on a UNIX system. Process Attribute: Select the process attribute (cpu, memory, or paging) to monitor from the drop-down list. Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. 9. Monitor Enablers Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Tivoli Module Builder Tivoli Ready QuickStart User s Guide 125

144 Set Polling Interval Note: When this enabler detects a process started by Java, it considers the Java class name, excluding the package name, as the program name to determine if a Java executable needs to be monitored. Process Count Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler counts the total number of active processes implemented by the provided program or image name. It returns a value of zero or greater for threshold processing. Select this enabler to monitor the total number of active process implemented by a program or image name. Related enablers: If you want to count the total number of active processes implemented by the process name in the Process Leader Context associated with the software component instance, use the Instance Process Count Monitor Enabler (see page 115). For Tivoli GEM, you must select one of the instance discovery enablers for this enabler to appear in the monitor enabler selection list. Prerequisites: None Required Parameters: Process or Image Name: Provide the exact process or image name, excluding path information, of the software component s executable file. Include both the file name and type. The name should match the process name displayed by the Windows NT task manager or the output of the ps command on a UNIX system. Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this 126 Version 2.4

145 monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval Note: When this enabler detects a process started by Java, it considers the Java class name, excluding the package name, as the program name to determine if a Java executable needs to be monitored. Process Monitor Enabler (ITD, Plus) Enabler Category: Monitor Enabler Applicable to module type: IT Director, Plus Description: This enabler creates a process monitor in Plus and IT Director modules. For Plus modules, this enabler will create an instance of the Application Status monitor from the DM Universal monitor collection. For IT Director modules, an instance of the AMS predefined monitor type ApplicationProcessIdentification will be generated. See the Application Management Specification (AMS) version 2.0, section for more information. 9. Monitor Enablers Select this enabler to create a process monitor in Plus or IT Director modules. Related enablers: None Prerequisites: None Tivoli Module Builder Tivoli Ready QuickStart User s Guide 127

146 Required Parameters: Process Name: This is the name of the process or service to be monitored. It is a string value. Tasks created: None Process Time Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler returns the total number of elapsed minutes that the process has been active. The process is identified by the program or image name. If the provided process name implements more than one process, this enabler returns the elapsed time for the process with the least amount of active time. Select this enabler to monitor the total elapsed time that a process has been active. Related enablers: For Tivoli GEM, you must select one of the instance discovery enablers for this enabler to appear in the monitor enabler selection list. If you want to monitor the total elapsed time for a process identified in the Process Leader Context associated with a discovered software component instance, use the Instance Process Time Monitor Enabler (see page 117). Prerequisites: None Required Parameters: Process or Image Name: The exact program or image name, excluding path information, of the software component s executable file. Include both the file name and type. The name should match the process names displayed by the Windows NT task manager or the output of the ps command on a UNIX system. Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If 128 Version 2.4

147 you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval Note: When this enabler detects a process started by Java, it considers the Java class name, excluding the package name, as the program name to determine if a Java executable needs to be monitored. State Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler returns the overall state of a specific instance. During the definition of all other monitor enablers, you determine whether a monitor will contribute to the overall state. The State monitor considers every other monitor that contributes to state before returning the overall state of the instance. This monitor returns up only if all monitors that contribute to state are considered normal or informational. If one or more of the monitors are in any other state, this monitor returns down. 9. Monitor Enablers Select this enabler when you want to monitor the state of other monitors created by other monitor enablers that can contribute to the overall state of the instance. Related enablers: For Tivoli GEM, you must select one of the instance discovery enablers for this enabler to appear in the monitor Tivoli Module Builder Tivoli Ready QuickStart User s Guide 129

148 enabler selection list. Other monitor enablers that have an option to contribute to the overall state can be set to combine their state with the overall instance state. Prerequisites: None Parameters: None Tasks created: When this enabler is built, the following tasks are created: Query State Query Value Query Threshold Set Thresholds Set Polling Interval User Exit Number Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler works with an external program, or user exit, to monitor a numerical attribute of a software component instance. Select this enabler if you must put the logic to monitor the software component into an external program which returns its monitor value as a number. Related enablers: For Tivoli GEM, you must select one of the instance discovery enablers for this enabler to appear in the monitor enabler selection list. If you want to return the status of the user exit as a character string for thresholding purposes, use the User Exit String Monitor Enabler (see page 133). Prerequisites: The user exit needs to be created and available for selection. 130 Version 2.4

149 Required Parameters: Monitor Name: The descriptive label for the user exit monitor program you have created. User Exit Name: The name of the user exit to be run. Make sure that the user exit program and any supporting programs are in the path on the target machine. Provide the exact program or image name, excluding path information, of the software component s executable file. Include both the file name and type. Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Optional Parameters: Setup Environment1: This enables you to issue an optional preparatory command to make any environmental changes prior to invoking the user exit. These environmental changes could include changing the current directory, setting an environmental variable, or issuing a file command. Setup Environment2: Same as Setup Environment1. Program Parameters: Provide the program arguments for the user exit. Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval 9. Monitor Enablers For additional information on programming a user exit, see Programming User Exits on page 169. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 131

150 User Exit Number using File Pack Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler works with an external program, or user exit, to monitor a numerical attribute of a software component instance. This enabler uses Tivoli Software Distribution to deploy the instrumentation. Select this enabler if you must put the logic to monitor the software component into an external program which returns its monitor value as a number, using Tivoli Software Distribution to deploy the instrumentation. Related enablers: For Tivoli GEM, you must select one of the instance discovery enablers for this enabler to appear in the monitor enabler selection list. If you want to return the status of the user exit as a character string for thresholding purposes, use the User Exit String Monitor Enabler (see page 133). If you do not want to deploy using Tivoli Software Distribution, use the User Exit Number Monitor Enabler. Prerequisites: The user exit needs to be created and available for selection. Required Parameters: Monitor Name: This is the descriptive label for the user exit monitor program you have created. User Exit Name: Provide the name of the user exit to be run. Make sure that the user exit program and any supporting programs are in the path on the target machine. Provide the exact program or image name, excluding path information, of the software component s executable file. Include both the file name and type. 132 Version 2.4

151 Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Optional Parameters: Setup Environment1: This enables you to issue an optional preparatory command to make any environmental changes prior to invoking the user exit. These environmental changes could include changing the current directory, setting an environmental variable, or issuing a file command. Setup Environment2: Same as Setup Environment1. Program Parameters: Provide the program arguments for the user exit. Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval For additional information on programming a user exit, see Programming User Exits on page 169. User Exit String Monitor Enabler (GEM) Enabler Category: Monitor Enabler 9. Monitor Enablers Applicable to module type: Tivoli GEM Description: This monitor enabler works with an external program, or user exit, to monitor a string attribute of a software component instance. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 133

152 Select this enabler if you must put the logic to monitor the software component into an external program which returns its monitor value as a character string. Related enablers: For Tivoli GEM, you must select one of the instance discovery enablers for this enabler to appear in the monitor enabler selection list. If you want to return the status of the user exit as a number for thresholding purposes, use the User Exit Number Monitor Enabler (see page 130). Prerequisites: The user exit needs to be created and available for selection. Required Parameters: Monitor Name: This is the descriptive label for the user exit monitor program you have created. User Exit Name: Provide the name of the user exit to be run. Make sure that the user exit program and any supporting programs are in the path on the target machine. Provide the exact program or image name, excluding path information, of the software component s executable file. Include both the file name and type. Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Optional Parameters: Setup Environment1: This enables you to issue an optional preparatory command to make any environmental changes prior to invoking the user exit. These environmental changes could include changing the current directory, setting an environmental variable, or issuing a file command. Setup Environment2: Same as Setup Environment Version 2.4

153 Program Parameters: Provide the program arguments for the user exit. Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval For additional information on programming a user exit, see Programming User Exits on page 169. User Exit String using File Pack Monitor Enabler (GEM) Enabler Category: Monitor Enabler Applicable to module type: Tivoli GEM Description: This monitor enabler works with an external program, or user exit, to monitor a character string attribute of a software component. This enabler uses Tivoli Software Distribution to deploy the instrumentation. Select this enabler if you must put the logic to monitor the software component into an external program which returns its monitor value as a character string, and use Tivoli Software Distribution to deploy the instrumentation. Related enablers: For Tivoli GEM, you must select one of the instance discovery enablers for this enabler to appear in the monitor enabler selection list. If you want to return the status of the user exit as a number for thresholding purposes, use the User Exit Number Monitor Enabler (see page 130). If you do not want to deploy using Tivoli Software Distribution, use the User Exit String Monitor Enabler. 9. Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 135

154 Prerequisites: The user exit needs to be created and available for selection. Required Parameters: Monitor Name: This is the descriptive label for the user exit monitor program you have created. User Exit Name: Provide the name of the user exit to be run. Make sure that the user exit program and any supporting programs are in the path on the target machine. Provide the exact program or image name, excluding path information, of the software component s executable file. Include both the file name and type. Contribute to State (y or n): Specify whether the state of this monitor should be included in the overall state of the instance. If you select yes, the State monitor will check the state of this monitor before returning the overall state of the instance. See the State Monitor Enabler (page 129) for more information. Optional Parameters: Setup Environment1: This enables you to issue an optional preparatory command to make any environmental changes prior to invoking the user exit. These environmental changes could include changing the current directory, setting an environmental variable, or issuing a file command. Setup Environment2: Same as Setup Environment1. Program Parameters: Provide the program arguments for the user exit. Tasks created: When this enabler is built, the following tasks are created: Query Value Query Threshold Set Thresholds Set Polling Interval 136 Version 2.4

155 For additional information on programming a user exit, see Programming User Exits on page Monitor Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 137

156 138 Version 2.4

157 10 Connection Enablers 10. Connection Enablers Connection enablers are provided to support Tivoli GEM connections. Displayed as directional lines on the Tivoli GEM console, connections represent a relationship between two instances. Connection enablers can discover and display unmonitored connection lines. Connections are identified by two main pieces of information: a connection type and a direction. When you define a component to support a certain connection type and direction, you can then connect it to other components that also support the same connection type and direction. You can also enable a component to report a connection, that is, a particular connection type and direction pair, as well as a destination. A line will display on the Tivoli GEM console, between the two components, which support the same connection type and direction pair. Additional information, called primary and secondary attributes, identify the endpoints of the connection. An example of these attributes are IP address and Port #, respectively. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 139

158 Figure 34. Selecting a Connection Enabler in the Instrument stage The following connection enablers are available: Connection Enablers For Details: Discover Connections by User Exit Enabler See page 140 Discover Connections by User Exit using File Pack See page 143 Enabler Discover Connections from Flat File using File Pack See page 146 Enabler Support Connection Enabler See page 148 Discover Connections by User Exit Enabler (GEM) Enabler Category: Connection Enabler Applicable to module type: Tivoli GEM 140 Version 2.4

159 Description: This connection enabler reports connections between instances as directed by a user exit. The user exit is called with the instance identifier. This enabler reports only connections that match the specified connection type/direction characteristics. Multiple report connections can be defined for an instance. Connections display on the Tivoli GEM console. This enabler does not use Tivoli Software Distribution to deploy the instrumentation. 10. Connection Enablers Select this enabler to report connections between instances using a user exit. Related enablers: If you want to report connections using a user exit and you want to deploy the instrumentation using Tivoli Software Distribution, use the Discover Connections by User Exit using File Pack Enabler (see page 143). Prerequisites: You must have a user exit defined, which prints all the information needed to report a connection to stdout. The user exit should return information relating to one connection for each line. For each connection, there are four main attributes: Connection type Connection direction Primary attribute Secondary attribute The latter two identify the destination and are followed by their values. The Primary Attribute can be TCPIPAddress or TCPIPHostName or GenericAttribute, while the Secondary attribute can have TCPIPService or TCPIPPort or GenericAttribute. The items are separated by a tilde (x). For example: Databasex3xTCPIPAddressx x*xTCPIPPortx55 Mailx2xGenericAttributexp1xp2xGenericAttributexp3xp4 From the above examples, Database and Mail are two connection types Tivoli Module Builder Tivoli Ready QuickStart User s Guide 141

160 3 and 2 represent connection directions: v 1 = Origin v 2 = Destination v 3 = Conversational (bi-directional) The values for TCPIPAddress and TCPIPPort follow these keywords; the same holds true for GenericAttribute. Note: Since stdout is used for communication, nothing should be written to stdout except the information associated with this exit call. Required Parameters: Type: Provide the name of the connection type. In order for a connection between two instances to be established, the connection type and connection direction must also be defined on the software component instance that supports the connection, which you can do using the Support Connection Enabler (see page 148). Direction: The direction of the connection. Valid values are: v Origin v Destination v Conversational (bi-directional) User Exit Name: The name of the user exit. Type in the name exactly as you want it to be executed. Optional Parameters: Setup Environment1: This enables you to issue optional preparatory commands to make any environmental changes prior to issuing a user exit. These environmental changes could include changing the current directory, setting an environmental variable, or issuing a file command. Setup Environment2: Same as Setup Environment Version 2.4

161 Program Parameters: Provide the program arguments for the user exit. Note: The instance identifier is the first argument following the program parameters. Monitors associated with this enabler: Monitors can be associated with connections to make them active using advanced instrumentation with Tivoli Module Builder. 10. Connection Enablers For additional information on programming a user exit, see Programming User Exits on page 169. Discover Connections by User Exit using File Pack Enabler (GEM) Enabler Category: Connection Enabler Applicable to module type: Tivoli GEM Description: This connection enabler reports connections between instances as directed by a user exit. The user exit is called with the instance identifier. This enabler reports only connections that match the specified connection type/direction characteristics. Multiple report connections can be defined for an instance. Connections display on the Tivoli GEM console. This enabler uses Tivoli Software Distribution to deploy the instrumentation. Select this enabler to report connections between instances using a user exit. Related enablers: If you want to report connections using a user exit and you do not want to deploy the instrumentation using Tivoli Software Distribution, use the Discover Connections by User Exit Enabler (see page 140). Tivoli Module Builder Tivoli Ready QuickStart User s Guide 143

162 Prerequisites: You must have a user exit defined, which prints all the information needed to report a connection to stdout. The user exit should return information relating to one connection for each line. For each connection, there are four main attributes: Connection type Connection direction Primary attribute Secondary attribute The latter two identify the destination and are followed by their values. The Primary Attribute can be TCPIPAddress or TCPIPHostName or GenericAttribute, while the Secondary attribute can have TCPIPService or TCPIPPort or GenericAttribute. The items are separated by a tilde (x). For example: Databasex3xTCPIPAddressx x*xTCPIPPortx55 Mailx2xGenericAttributexp1xp2xGenericAttributexp3xp4 From the above examples, Database and Mail are two component types 3 and 2 represent connection directions: v 1 = Origin v 2 = Destination v 3 = Conversational (bi-directional) The values for TCPIPAddress and TCPIPPort follow these keywords; the same holds true for GenericAttribute. Note: Since stdout is used for communication, nothing should be written to stdout except the information associated with this exit call. Required Parameters: Type: Provide the name of the connection type. In order for a connection between two instances to be established, the connection type and connection direction must also be defined 144 Version 2.4

163 on the software component instance that supports the connection, which you can do using the Support Connection Enabler (see page 148). Direction: The direction of the connection. Valid values are: v Origin v Destination v Conversational (bi-directional) User Exit Name: Provide the name of the user exit by typing in the name exactly as you want it to be executed. 10. Connection Enablers Optional Parameters: Setup Environment1: This enables you to issue optional preparatory commands to make any environmental changes prior to issuing a user exit. These environmental changes could include changing the current directory, setting an environmental variable, or issuing a file command. Setup Environment2: Same as Setup Environment1. Program Parameters: Provide the program arguments for the user exit. Note: The instance identifier is the first argument following the program parameters. Monitors associated with this enabler: Monitors can be associated with connections to make them active using advanced instrumentation with Tivoli Module Builder. For additional information on programming a user exit, see Programming User Exits on page 169. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 145

164 Discover Connections from Flat File using File Pack Enabler (GEM) Enabler Category: Connection Enabler Applicable to module type: Tivoli GEM Description: This enabler uses a flat file to report connections for an component instance. The flat file lists elements that report connections for instances of a software component. This enabler reports only connections that match the specified connection type/direction characteristics. Multiple report connections can be defined for an instance. The flat file is packaged for deployment by Tivoli Software Distribution. Select this enabler if you want to use a flat file to report connections for a component instance. Related enablers: You can use a user exit instead of a flat file to report connections. Use either the Discover Connections by User Exit Enabler (see page 140) or the Discover Connections by User Exit using File Pack Enabler (see page 143). Prerequisites: You must have a flat file defined, which includes all the information needed to report a connection. The flat file contains information that defines the type, direction and destination of the connections in key=value format. Flat file lines consist of a key, which determines which definitions apply to an instance, and the report connection information, including connection type, connection direction, and primary and secondary attributes. To specify a connection for all the instances, the globals.relations key is used. Another key, instance.relations.<instanceid> is used for specific instances (where instanceid is the instance identifier. Any blanks in the instanceid should be replaced with underscores). 146 Version 2.4

165 For each valid value, there are four main attributes: Connection Type Connection Direction Valid values include: 1. Origin 2. Destination 3. Conversational (bi-directional) 10. Connection Enablers Primary Attribute Valid values include: v v v TCPIPAddress TCPIPHostName GenericAttribute Secondary Attribute Valid values include: v v v TCPIPService TCPIPPort GenericAttribute The latter two identify the destination and are followed by their values. The items are separated by a tilde (x). For example: globals.relations.1=databasex3xtcpipaddressx x*xtcpipportx55x* globals.relations.2=mailx2xgenericattributexp1xp2xgenericattributexp3xp4 Each attribute is followed by its value (in the first example above, the attribute TCPIPAddress is followed by its value, ). With the exception of GenericAttribute, all are single-valued and so a dummy (* in the above example) is used to mark the other value. The Connection Type attribute, with a value of Database, is a label that identifies the type of connection, followed by the Connection Direction attribute, with a value of 3. All of the keys in the file Tivoli Module Builder Tivoli Ready QuickStart User s Guide 147

166 should be unique, which is why the numbers 1 or 2 are appended at the end of the globals.relations key in the above examples. Required Parameters: Type: Provide the name of the connection type. In order for a connection between two instances to be established, the connection type and connection direction must also be defined on the software component instance that supports the connection, which you can do using the Support Connection enabler. Direction: The direction of the connection. Valid values are: v Origin v Destination v Conversational File Name: The name of the flat file containing the defined connection. For additional information on specifying flat files, see Flat File Formats on page 187. Support Connection Enabler (GEM) Enabler Category: Connection Enabler Applicable to module type: Tivoli GEM Description: This connection enabler configures the component to support a given type/direction combination. This enabler gives the component the ability to let other components connect to it using the given connection type/direction. Select this enabler to configure components to support a specific type/direction pair for a connection. Related enablers: See the other connection enablers in this section for information on reporting connections between components using user exits and flat files. 148 Version 2.4

167 Prerequisites: None Required Parameters: Type: Provide the name of the particular connection. Direction: The direction of the connection. Valid values are: v Origin v Destination v Conversational (bi-directional) 10. Connection Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 149

168 150 Version 2.4

169 11 Event Enablers Event enablers provide a mechanism for gathering the information required to configure any of the supported Tivoli Enterprise Console (TEC) event adapters. You can select one or more event enablers for your modules during the Instrument stage, however you are limited to selecting only one custom adapter per application. The list of available event enablers you can select from is shown in the scrollable list. This list displays only those event enablers that are valid for the module type(s) you have chosen to build. 11. Event Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 151

170 Figure 35. Selecting an Event Enabler in the Instrument stage The following event enablers are available: Event Enablers For Details: Custom Adapter Enabler (ITD) See page 153 Custom Adapter Enabler (Plus) See page 154 Logfile Adapter Enabler See page 155 You can filter this list further by checking or unchecking the select boxes for the desired module type, reducing or expanding the list of valid enablers to choose from. To select an event enabler, highlight the enabler name and click Add to add the monitor to the Selected Event Enablers list at the top of the dialog. The selected event enabler s parameters are shown in the scrollable list at the bottom of the dialog. 152 Version 2.4

171 Custom Adapter Enabler (ITD) Enabler Category: Event Enabler Applicable to module type: IT Director Description: The Custom Adapter Event Enabler creates a custom adapter configuration task in your IT Director module. Your custom adapter is a program that you develop outside of the QuickStart wizard environment. The Custom Adapter Enabler handles definition and packaging of this adapter and its associated setup program in your IT Director module. Only one custom adapter can be configured per application. Select this enabler if you want to create a custom adapter configuration task for your IT Director module. Related enablers: None Prerequisites: You must create the customized IT Director adapter outside of the QuickStart wizard environment. 11. Event Enablers Required Parameters: Configuration Program File: This is the name of the configuration program that performs the adapter setup. Specify the full path name for the file. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Adapter Path: This is the path to the directory of the adapter executables. Adapter File: This is the name of the adapter executable file. Specify the full path name for the file. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Tasks created: When this enabler is built, a custom adapter configuration task is created for your customized event adapter. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 153

172 Custom Adapter Enabler (Plus) Enabler Category: Event Enabler Applicable to module type: Plus Description: The Custom Adapter Enabler creates a custom adapter configuration task in your Plus module. This results in the creation of a task on the desktop, and as a result, creates a new Tivoli Module Builder component to support the custom adapters. You can select only one event adapter per application. Any BAROC or rules files that are specified are accumulated in a Tivoli Enterprise Console (TEC) Server Configuration Task component. This task must be executed on the TEC event server managed node in order to be introduced into the TEC system. Note: The custom adapter must have already been installed on the end point. Select this enabler when you want to create a custom event adapter configuration task for your Plus module. Related enablers: None Prerequisites: You must have a custom event adapter created for your Plus environment, and the adapter must already be installed on the endpoint. Required Parameters: Task Name: This is the name of the configuration task. It is a string value. Configuration Program: This is the program that is run by the configuration task. Specify the full path name for the file. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Optional Parameters: 154 Version 2.4

173 Rule File: This is the name of the file (including file path) containing the specific rules for this instance of the logfile adapter. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. BAROC File: This is the name of the file (including file path) used to configure the TEC event server to accept messages from this adapter. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Tasks created: When this enabler is built, a custom event adapter configuration task is created to appear on the TivoliPlus window. Logfile Adapter Enabler (Plus) Enabler Category: Event Enabler Applicable to module type: Plus 11. Event Enablers Description: The Logfile Adapter Enabler creates a logfile adapter configuration task in your Plus module. The task is generated using a skeleton that creates and configures an adapter configuration profile (ACP) that is specific to a platform or adapter type, ready for distribution to endpoint subscribers. The task, when run on the TivoliPlus window, prompts you for the platform or adapter type, and the event log path name. It then uses this information to create a dataless profile manager and ACP on the TivoliPlus window for that platform and adapter type. A TEC configuration task is also created on the TivoliPlus window. Executing this task uses the BAROC and rules files you specify in the enabler parameters to set up the TEC event server. See the Tivoli Module Builder User s Guide, Chapter 25, for more information on the TEC configuration component, from which the Setup TEC Event Server task is generated. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 155

174 You can then distribute the configuration of the logfile adapter on an endpoint, including stopping and starting the adapter, by distributing the profile manager or profile to endpoints of the appropriate platform type using standard ACP (user/command line) interfaces. You also have access to the profile record on the TivoliPlus window, enabling you to customize the configuration after the task creates the profile but before you distribute it. Any BAROC or rules files that you specify are accumulated in a TEC Server Configuration Task component. This task must be executed on the TEC event server managed node in order to be introduced into the TEC system. Select this enabler to create a logfile adapter configuration task for your Plus environment. Related enablers: None Prerequisites: None Required Parameters: Task Name: This is the name of the configuration task. It is a string value. Format File: This is the name of the file (including file path) containing the formatting information for the logfile. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Optional Parameters: Configuration Variables: This is a list of variable names and their values, which are inserted into the adapter s configuration file at configuration time. It is a string value. The format is a list of variables and their values, delimited by a semicolon (for example: Var1=value1;Var2=value2;...). 156 Version 2.4

175 Rules File: This is the name of the file (including file path) containing the specific rules for this instance of the logfile adapter. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. BAROC File: This is the name of the file (including file path) used to configure the TEC event server to accept messages from this adapter. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Tasks created: When this enabler is built, a logfile adapter configuration task is created for your Plus environment. Using Existing Logfile Adapter Instrumentation You may choose to use the version 2.3 logfile adapter instrumentation by changing the reference to the configuration task skeleton, using the Tivoli Module Builder, to reference the version 2.3 skeleton file, PLUSconfig_logadapter.sh.skel. Configuration variables you specified in the above enabler are then ignored, since they are not used by the old skeleton. 11. Event Enablers If you have an existing (version 2.3) logfile adapter task that should be upgraded to use the TEC 3.6 Adapter Configuration Facility (ACF), you can use the new skeleton, PLUSQSconfig_logadapter.sh.skel. In either case, in using skeletons across different versions of the Tivoli Module Builder, you should modify the AMS definition for the task arguments to match what is expected by the task skeleton. You can find both of these skeletons in the following directory: \module_dev\toolkit/templates/module/plus*.template Tivoli Module Builder Tivoli Ready QuickStart User s Guide 157

176 158 Version 2.4

177 12 Deployment Enablers Deployment enablers provide mechanisms for distributing and installing your module components on one or more machines so that the module s management features are accessible to Tivoli s management software, in the Tivoli GEM, Plus, and IT Director environments. The deployment enablers available for selection have unique characteristics and features for Tivoli GEM, Plus and IT Director modules. Details are included in the enabler descriptions. The list of available deployment enablers you can select from is shown in the scrollable list. This list displays only those deployment enablers that are valid for the module type(s) you have chosen to build. 12. Deployment Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 159

178 Figure 36. Selecting a Deployment Enabler in the Instrument stage The following deployment enablers are available: Deployment Enablers For Details: Add File to Filepack Enabler See page 161 InstallShield Enabler See page 161 InstallShield Deployment Enabler See page 166 You can filter this list further by checking or unchecking the select boxes for the desired module type, reducing or expanding the list of valid enablers to choose from. To select a deployment enabler, highlight the enabler name and click Add to add the monitor to the Selected Deployment Enablers list at the top of the dialog. The selected enabler s parameters are shown in the scrollable list at the bottom of the dialog. 160 Version 2.4

179 Add File to Filepack Enabler (GEM) Enabler Category: Deployment Enabler Applicable to module type: Tivoli GEM Description: This deployment enabler, valid for Tivoli GEM modules only, gives the ability to bundle additional files needed by the user exits into the same file pack (as the user exits) and be distributed onto the target system using Tivoli Software Distribution. It can be used in conjunction with the user exit Discovery/Monitor/Task enablers that use the Tivoli Software Distribution file pack. To add multiple files this enabler should be selected and added multiple times. Select this enabler when you want to bundle additional files to be distributed with the user exits onto the target systems using Tivoli Software Distribution. Related enablers: See the Discovery, Monitor and Task enabler sections for information on user exits that use Tivoli Software Distribution. Prerequisites: The file you want to bundle must be created and available for inclusion in the file pack. Required Parameters: File Name: This is the file name of the file to be included in the Tivoli Software Distribution file pack. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Tasks created: None 12. Deployment Enablers InstallShield Enabler (ITD, Plus) Enabler Category: Deployment Enabler Applicable to module type: IT Director, Plus Tivoli Module Builder Tivoli Ready QuickStart User s Guide 161

180 Description: This enabler allows you to specify an installation image name and an InstallShield.iss file. It also allows you to specify basic install prerequisites for Plus modules that are generated into a script, that can be run before the installation. This script is attached to the Plus module file package. This enabler is valid for Plus or IT Director modules. Plus Module Implementation A task and a file package profile will be created on the desktop. The InstallShield.iss file that contains the automated commands for the installation is included as part of the file package definition. IT Director Module Implementation If your instrumentation includes auxiliary files that are distributed to an endpoint, AMS includes a CONFGLOC extension to identify where these files are located for the install. Deployment uses the same CONFGLOC mechanism as UNIX utilities in Application Tools to execute InstallShield. Details on this extension can be found in the document, Managing Applications With Tivoli IT Director, which is included in the Tivoli IT Director Integration Toolkit, and also available in the \module_dev\examples\it Director directory. CONFGLOC is written in the C language, and you will need access to a Windows 32-bit C compiler. A sample CONFGLOC file is provided with the TMB product for your reference (see the following tar file: apache_1_3_6_itd_example.tar, located in the following directory: \module_dev\examples\it Director\. It contains the C source code for CONFGLOC, example argument and response beans, and other samples for your use), to test your work and to provide a working example, but it cannot be used as-is, because the resulting file generated by running this sample program would be the same for all modules generated by the QuickStart wizard. If you install more than one module generated by the QuickStart wizard, the.bat file for the first installed module will be overwritten. In addition to the CONFGLOC parameter, you must specify the name of the setup program (invoked from the install script). 162 Version 2.4

181 The InstallShield File Package enabler file list will be merged with the file list of the component to which the enabler belongs. Location table entries will be added to the component as needed. An additional parameter allows you to choose whether or not to include the setup program for the enabler in the generated AMP file. You may only select one InstallShield File Package enabler per component. Select this enabler to add an InstallShield image name and an.iss file to your Plus or IT Director module. Related enablers: This enabler does not provide for predefined dependencies. If you are building an IT Director module and you need to specify predefined dependencies, use the InstallShield Deployment Enabler (see page 166). Prerequisites: You need to provide any before-install or after-install programs you want to specify for Plus modules, and the CONFGLOC program for IT Director. The setup.iss and setup.exe files must already exist on the same system you are running the QuickStart wizard, since these files are examined by the wizard at module build time for information needed to build the module. Required Parameters: Task Name (required for Plus modules only): This is the name of the file package configuration task. It is a string value. InstallShield setup.exe image file: This is the name of the InstallShield setup.exe program. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Include setup.exe in module image: Select yes or no from the drop-down menu, choosing whether to include the setup.exe program for the enabler in the generated Plus module image or IT Director AMP file. 12. Deployment Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 163

182 Note: If the setup.exe program is excluded from the image, nested file packs are used to install the image. In this case, you may need to upgrade your TMR and associated managed nodes to Tivoli Management Framework or later. InstallShield.iss file: This is the path to the InstallShield setup.iss file. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Default Application Directory on Targets: This is the default directory where the application will be installed on the target machines. It must be the same value as the directory specified in the setup.iss file. This is a string value. Be sure to include the drive letter, and use back slashes in all cases, for example: C:\install_my_app_here CONFGLOC File (required for ITD modules only): This is the path to the IT Director CONFGLOC program. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Optional Parameters: Before Install Program: This is the name of the program to run before installation. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. After Install Program: This is the name of the program to run after installation. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Note: The above two fields apply only to Plus modules. Application File List: This is the path to a directory containing additional files that may be required for the application. 164 Version 2.4

183 Double-click on this field to bring up the Distribution File List Chooser dialog. Figure 37. Specifying the Application File List Navigate to the desired folder, highlight it, and select Generate List. A file list entry is created for each file in that folder. You can erase the list by clicking Clear List, and choose a different folder if you like. When you are satisfied, click Accept to close the dialog and return to the enabler parameter list. 12. Deployment Enablers Tasks created: When this enabler is built for Plus modules, a task and a file package profile will be created on the desktop. Tivoli Module Builder Tivoli Ready QuickStart User s Guide 165

184 InstallShield Deployment Enabler (ITD) Enabler Category: Deployment Enabler Applicable to module type: IT Director Description: This enabler allows you to specify an installation image name and an InstallShield.iss file. This script is attached to the file package. Refer to the discussion, IT Director Module Implementation on page 162, which describes the usage of the CONFGLOC program. An additional parameter allows you to choose whether or not to include the setup program for the enabler in the generated AMP file. You may only select one InstallShield File Package enabler per component. Select this enabler to add an InstallShield image name and a.iss file to your IT Director module. Related enablers: IT Director allows you to specify predefined dependencies in the enabler. This enabler provides for predefined dependencies. If you are building a Plus or IT Director module and you do not need to specify predefined dependencies, use the InstallShield Enabler (see page 161). Prerequisites: You need to provide the CONFGLOC program for IT Director. The setup.iss and setup.exe files must already exist on the same system you are running the QuickStart wizard, since these files are examined by the wizard at module build time for information needed to build the module. Required Parameters: InstallShield setup.exe image file: This is the name of the InstallShield setup.exe program. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. 166 Version 2.4

185 Include setup.exe in module image: Select yes or no from the drop-down menu, choosing whether to include the setup.exe program for the enabler in the generated AMP file. InstallShield.iss file: This is the path to the InstallShield setup.iss file. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Default Application Directory on Targets: This is the default directory where the application will be installed on the target machines. It must be the same value as the directory specified in the setup.iss file. This is a string value. Be sure to include the drive letter, and use back slashes (to match exactly the directory in setup.iss) in all cases, for example: C:\install_my_app_here CONFGLOC File: This is the path to the IT Director CONFGLOC program. You can double-click on this input field to bring up a selection dialog, enabling you to navigate to the desired directory and select the desired file name. Optional Parameters: Application File List: This is the path to the directory containing additional files that may be required for the application. Double-click on this field to bring up the Distribution File List Chooser dialog (see Figure 37 on page 165). Navigate to the desired folder, highlight it and select Generate List. A file list entry is created for each file in that folder. You can erase the list by clicking Clear List, and choose a different folder if you like. When you are satisfied, click Accept to close the dialog and return to the enabler parameter list. Installation Dependencies: This is a list of predefined dependencies that you can select from a special dialog. Double-click on this input field to bring up the Selected Dependencies dialog. 12. Deployment Enablers Tivoli Module Builder Tivoli Ready QuickStart User s Guide 167

186 Figure 38. Define dependencies with the Selected Dependencies dialog. Click on the Dependency Type drop-down menu to select one of several predefined dependency types, such as Required Memory, OS Version, Registry Entry, and so on. For each dependency, you can specify a certain value, or fill in several value fields with the desired information, then click the left-arrow button to add the dependency to the Selected Dependencies list. When you are done, click OK to return to the enabler parameter dialog. Tasks created: None 168 Version 2.4