Tivoli Business Systems Manager

Transcription

1 Tioli Business Systems Manager Version 3.1 Problem and Change Management Integration Guide SC

2

3 Tioli Business Systems Manager Version 3.1 Problem and Change Management Integration Guide SC

4 Note Before using this information and the product it supports, read the information in Notices on page 133. First Edition (October 2004) This edition applies to Version 3, Release 1 of IBM Tioli Business Systems Manager and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation All rights resered. US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents About this guide ii Publications ii IBM Tioli Business Systems Manager library.. ii Related publications iii Accessing publications online iii Ordering publications ix Accessibility ix Tioli technical training ix Support information ix Participating in newsgroups x Conentions used in this guide x Typeface conentions x Operating system-dependent ariables and paths xi Terminology xi Chapter 1. Introduction Request processors Request processor workflow Integration function files Request processor files Input files Output files Log files Planning for request processors Skills needed for implementation Program implementation considerations....8 Using the planning worksheet Sample integration function Chapter 2. Writing a problem request processor What is a problem request processor? Problem integration function flow Configuration of problem integration function...11 Requirements for problem request processors...12 Input and output files Console problem function Console request processing Text field size restriction Initializing and prepopulating a problem request interface Problem open and close alues Customer ID Origin alues Enumeration requests Receiing enumeration requests Returning enumeration request alues...18 Enumeration request without alues to return Enumeration request with alues to return 18 Returning enumeration list dependency filters 19 Date formats Identifying problems in a problem management application Considerations for problem request processors..21 User ID and password Loading large olume problem enumeration alues Request query with request initialize Request query with request adhoc Request find Request add Request update Request update with request auto close Problem close Problem integration eent notification Updating multiline text boxes Required data fields Prepopulating console problem ticket fields...29 Suppress display of the OK message box...32 Problem ticket ID in the eent iewer Chapter 3. Writing a change request processor What is a change request processor? Change integration function flow Configuration of change integration function...33 Requirements for change request processors...34 Input and output files Console change function Console request processing User IDs Text field size restriction Enumeration requests Receiing enumeration requests Returning enumeration request alues...38 Enumeration request without alues to return Enumeration request with alues to return 39 Returning enumeration list dependency filters 39 Date formats Identifying changes in a change management application Considerations for change request processors...41 User ID and password Loading large olume change enumeration alues Request query with request initialize Change open and close alues Request query with request adhoc Request find Request add Request update Request update with request close Change integration eent notification Updating multiline text boxes Required data fields Suppress display of the OK message box...48 Copyright IBM Corp iii

6 Chapter 4. Writing an automatic ticket request processor What is an automatic ticket request processor?..49 Non-batch automatic ticket integration function flow, configuration, and requirements Non-batch automatic ticket integration function flow Configuration of the non-batch automatic ticket integration function Requirements for non-batch automatic ticket request processors Input and output files Date formats Batch automatic ticket integration function flow, configuration, and requirements Batch automatic ticket integration function flow 52 Configuration of the batch automatic ticket integration function Batch automatic ticket output file batch job...54 Requirements for batch automatic ticket request processors Input and output files Date formats Counting open problems Considerations for automatic ticket request processors User ID and password NO_NOTE option Note type N alue Exception propagation matrices and occurrence data Clear exception eent counts and resource alerts 58 Reset automatic ticket queues Disable and enable automatic ticket jobs Adjust health monitor automatic ticket threshold alues Request add method Required data fields Special process data fields User-defined serice sample (batch mode)...61 Chapter 5. Enabling a request processor System configuration table System configuration table structure Populating the system configuration table...64 Making system configuration table updates aailable System configuration options Request processor name and language...66 Actiate problem (console) Actiate change (console) Actiate automatic ticket Non-batch mode Batch mode Append textlog time stamps Auto close default Auto select ticket Change system NetView used Closed ticket status code Debug mode Display problem closure Duplicate age Problem system NetView used Suppress display of OK message box Table-based enumerations Ticket create default Timeout alue Origin alues: system, component, item, module TSD_SCIM table Customizing console fields Appendix A. Problem and change name-alue pairs Problem name-alue pairs Change name-alue pairs Appendix B. Sample integration for the Information Management for z/os product Sample files Sample integration oeriew and workflow...84 Windows serer configuration for the sample request processor Configure the TSD390RPin.rex input file processor Modify the TSD390RPout.rex output file processor to support IBM Object REXX Language Interpreter Set a default NetView user ID and password..90 Configure the database for the sample integration function Define the API integration options for the NetView program Define the request processors Add system configuration table entries for the sample integration functions Customize the change request console for the sample integration function z/os system configuration for sample request processors Configure NetView for z/os for the sample request processors Allocate a parmlib data set Define the parmlib alues Define NetView global ariables NetView for OS/390 V1R4 and NetView for z/os V5R NetView for OS/390 V1R Customize Information Management for z/os.99 Closure process Panel data set Modifying the BLG1A111 control panel Appendix C. Example input and output files Request initialize alues request User ID and password request i IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

7 Problem ticket enumeration requests Problem seerity enumeration Problem status code enumeration Problem type enumeration Problem assignee group enumeration Problem resolution closure status enumeration 109 Problem resolution code enumeration Problem ticket processing requests Problem ticket add Problem ticket initial query Problem ticket update Problem ticket update and close Problem request open ticket count Problem ticket adhoc query Change request enumeration requests Change request initialize Change requestor department enumeration..116 Change reason enumeration Change status code enumeration Change category enumeration Change impact enumeration Change requestor name enumeration Change complexity enumeration Change site enumeration Change request processing requests Change request add Change request initial query Change request find for update Change request update Change request update and close Change request open ticket count Change request adhoc query Auto ticket processing request Support information Searching knowledge bases Search the information center on your local system or network Search the Internet Obtaining fixes Contacting IBM Software Support Determine the business impact of your problem 131 Describe your problem and gather background information Submit your problem to IBM Software Support 131 Notices Trademarks Index Contents

8 i IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

9 About this guide Publications IBM Tioli Business Systems Manager is an enterprise management product that monitors the data processing resources that are critical to a business application. It enables end-to-end monitoring of systems, subsystems, applications, and other resources in your enterprise, from z/os systems to distributed systems. Tioli Business Systems Manager proides your operations and support organizations, application owners, and management with a iew of the system components as they relate to your oerall business. This section lists publications in the Tioli Business Systems Manager library and related documents. It also describes how to access Tioli publications online and how to order Tioli publications. IBM Tioli Business Systems Manager library This following publications are in the IBM Tioli Business Systems Manager library: IBM Tioli Business Systems Manager Planning Guide, SC , proides an introduction to the Tioli Business Systems Manager product. It also contains planning and design information to consider when implementing a Tioli Business Systems Manager solution. This document is written for network planners, system designers, systems administrators, and others who are responsible for planning and implementing the product. IBM Tioli Business Systems Manager Installation and Configuration Guide, SC , proides the installation and configuration tasks necessary for the implementation of Tioli Business Systems Manager. This document is written for system administrators and others who are responsible for installing and configuring Tioli Business Systems Manager. IBM Tioli Business Systems Manager Introducing the Consoles, SC , proides an introduction to the Tioli Business Systems Manager console, Web console, executie dashboard, and the reporting system. This document is written for operators and administrators. IBM Tioli Business Systems Manager Administrator s Guide, SC , describes administratie tasks for Tioli Business Systems Manager. This document is written for system administrators and others who perform administratie tasks for Tioli Business Systems Manager. IBM Tioli Business Systems Manager Problem and Change Management Integration Guide, SC , describes how to write request processors to enable the problem, change, and automatic ticket integration function proided with Tioli Business Systems Manager to work with problem and change management applications. This document is written for system programmers. IBM Tioli Business Systems Manager Command Reference, SC , describes the commands aailable for use with Tioli Business Systems Manager. This document is written for system administrators and others who run commands and scripts for Tioli Business Systems Manager. Copyright IBM Corp ii

10 IBM Tioli Business Systems Manager Message Reference, SC , describes the messages for Tioli Business Systems Manager. This document is written for system programmers, network planners, operations managers, system designers, system administrators, network operators, and others who need message information for Tioli Business Systems Manager. IBM Tioli Business Systems Manager Troubleshooting Guide, SC , describes troubleshooting tasks to diagnose problems with Tioli Business Systems Manager. This document is written for system administrators and others who perform diagnostic tasks for Tioli Business Systems Manager. IBM Tioli Business Systems Manager Release Notes, GI , describes what is new for this release of the Tioli Business Systems Manager product. IBM Tioli Business Systems Manager Guide for Warehouse Pack, Version , using Tioli Data Warehouse, Version 1.2, SC , describes how to use the warehouse enablement pack to extract data from the Tioli Business Systems Manager database and load it into the Tioli Data Warehouse database, where it can be accessed using reporting and data analysis tools. This document is written for administrators and others who plan for and install the warehouse pack, use and maintain the warehouse pack and its reports, or create new reports. An index is proided for searching the Tioli Business Systems Manager library. If you hae Adobe Acrobat on your system, you can use the Search command to locate specific text in the library. For more information about using the index to search the library, see the online help for Acrobat. Related publications The Tioli Software Glossary includes definitions for many of the technical terms related to Tioli software. The Tioli Software Glossary is aailable at the following Tioli software library Web site: Access the glossary by clicking the Glossary link on the left pane of the Tioli software library window. Accessing publications online The documentation CD contains the publications that are in the product library. The format of the publications is PDF and HTML. IBM posts publications for this and all other Tioli products, as they become aailable and wheneer they are updated, to the Tioli software information center Web site. Access the Tioli software information center by first going to the Tioli software library at the following Web address: Scroll down and click the Product manuals link. In the Tioli Technical Product Documents Alphabetical Listing window, click the Tioli Business Systems Manager link to access the product library at the Tioli software information center. iii IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

11 Accessibility Note: If you print PDF documents on other than letter-sized paper, set the option in the File Print window that allows Adobe Reader to print letter-sized pages on your local paper. Ordering publications You can order many Tioli publications online at the following Web site: Tioli technical training Support information cgibin/pbi.cgi You can also order by telephone by calling one of these numbers: In the United States: In Canada: In other countries, see the following Web site for a list of telephone numbers: Accessibility features help users with a physical disability, such as restricted mobility or limited ision, to use software products successfully. With this product, you can use assistie technologies to hear and naigate the interface. You can also use the keyboard instead of the mouse to operate all features of the graphical user interface. For information about installing the Tioli Business Systems Manager product using the built-in screen reader, see the IBM Tioli Business Systems Manager Installation and Configuration Guide. For information about the shortcut keys that can be used with the Tioli Business Systems Manager console, see the Accessibility appendix in IBM Tioli Business Systems Manager Introducing the Consoles. For Tioli technical training information, refer to the following IBM Tioli Education Web site: If you hae a problem with your IBM software, you want to resole it quickly. IBM proides the following ways for you to obtain the support you need: Searching knowledge bases: You can search across a large collection of known problems and workarounds, Technotes, and other information. Obtaining fixes: You can locate the latest fixes that are already aailable for your product. Contacting IBM Software Support: If you still cannot sole your problem, and you need to work with someone from IBM, you can use a ariety of ways to contact IBM Software Support. For more information about these three ways of resoling problems, see Support information on page 129. About this guide ix

12 Participating in newsgroups User groups proide software professionals with a forum for communicating ideas, technical expertise, and experiences related to the product. They are located on the Internet and are aailable using standard news reader programs. These groups are primarily intended for user-to-user communication and are not a replacement for formal support. To access a newsgroup, use the instructions appropriate for your browser. IBM Tioli Business Systems Manager: news://news.software.ibm.com/ibm.software.tioli.business-systems-manager IBM Tioli Enterprise Console : news://news.software.ibm.com/ibm.software.tioli.enterprise-console IBM Tioli Serice Leel Adisor: news://news.software.ibm.com/ibm.software.tioli.serice-leel-adisor IBM Tioli Switch Analyzer: news://news.software.ibm.com/ibm.software.tioli.switch-analyzer IBM Tioli NetView for UNIX and IBM Tioli NetView for Windows : news://news.software.ibm.com/ibm.software.tioli.netiew-unix-windows IBM Tioli NetView for z/os: news://news.software.ibm.com/ibm.software.netiew Conentions used in this guide This guide uses seeral conentions for special terms and actions and for operating system-dependent commands and paths Typeface conentions This guide uses the following typeface conentions: Bold Italic Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) Keywords and parameters in text Words defined in text Emphasis of words (words as words) New terms in text (except in a definition list) x IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

13 Terminology Variables and alues you must proide Monospace Examples and code examples File names, programming keywords, and other elements that are difficult to distinguish from surrounding text Message text and prompts addressed to the user Text that the user must type Values for arguments or command options Operating system-dependent ariables and paths This guide uses the UNIX conention for specifying enironment ariables and for directory notation. When using the Windows command line, replace $ariable with %ariable% for enironment ariables and replace each forward slash (/) with a backslash (\) in directory paths. The names of enironment ariables are not always the same in Windows and UNIX. For example, %TEMP% in Windows is equialent to $tmp in UNIX. Note: If you are using the bash shell on a Windows system, you can use the UNIX conentions. For a list of terms and definitions for Tioli and other IBM products, refer to the IBM terminology Web site: For breity and readability, the term Tioli NetView for z/os refers to both the Tioli NetView for z/os product and the Tioli NetView for OS/390 product. About this guide xi

14 xii IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

15 Chapter 1. Introduction Request processors You can integrate your business applications with the IBM Tioli Business Systems Manager product using an integration function proided by Tioli Business Systems Manager. One area of integration is the creation and tracking of problem tickets. This integration can include not only taking ownership of an eent, but also opening and maintaining problem tickets that are stored and processed within a problem management application and automatically creating problem tickets when certain types of messages or exceptions are generated. Another area of integration is the creation and tracking of change requests. You can use the integration function to deelop your own customized program interfaces to your business applications, een if you hae customized your business applications to meet your specific needs. The Tioli Business Systems Manager integration function works with programs that you write. These programs, known as request processors, handle the data passed to them as requests and format the necessary calls to your business applications to process the requests using the interfaces proided by the business application. After your business application processes the request and returns the results to your program, your program returns control to Tioli Business Systems Manager to proide notification of the results. If the request came from the Tioli Business Systems Manager console, the results are displayed at the console. Note: Throughout this guide, the Tioli Business Systems Manager console is referred to as the console. The Tioli Business Systems Manager integration function is implemented using request processors. A request processor is any program or script that you deelop that can process command line input parameters, read a text-based input file containing data passed from the integration function, and create a text-based output file with the results receied from your problem or change management application. More specifically, the request processor performs the following actions in processing requests: 1. Reads an input file, containing name-alue pairs, that resides on the Tioli Business Systems Manager database serer in the Program Files\Tioli\tbsm\Data folder and maps the name-alue pairs to data elements in the problem or change management application database. Automatic ticket request processors can add other information that is needed for creating a problem ticket, such as the status code or problem type. 2. Formats and performs the appropriate API (application programming interface) or interface calls to the problem or change management application. If remote processing is required, two request processors are required. The first request processor, which resides on the Tioli Business Systems Manager database serer, reads the input file and passes the data to second request processor, which resides on another platform. The second request processor uses the data to interface with the problem or change management application, and passes the results back to the first request processor. Copyright IBM Corp

16 Request processor workflow 3. Formats the results from the API (application programming interface) or interface call into an output file containing name-alue pairs. Your request processor must create an output file in the same directory as the input file because the Tioli Business Systems Manager integration function expects to receie the contents in this output file in this directory. The results are processed and, for problem or change request processors, the results are displayed in the Tioli Business Systems Manager console. The following types of request processors can be used: problem request processor The Tioli Business Systems Manager problem integration function displays the menu options for the Tioli Business Systems Manager problem ticket processing and then transfers control to your program for integration with your problem management application.problem request processors implement interfaces for entering data and generating requests to create, query, search, find, retriee, and update problem tickets. When a user issues a request from the console, the Tioli Business Systems Manager problem integration function transfers control to your program and passes the data in an input file. Your program retriees the data from the input file, formats and runs the appropriate calls to your problem management application, formats the results into an output file, and returns control to the Tioli Business Systems Manager problem integration function. change request processor The Tioli Business Systems Manager change integration function displays the menu options for the Tioli Business Systems Manager change request processing and then transfers control to your program for integration with your change management application. Change request processors implement interfaces for entering data and generating requests to create, query, search, find, retriee, and update change requests. When a user issues a request from the console, the change integration function transfers control to your program and passes the data in an input file. Your program retriees the data from the input file, formats and runs the appropriate calls to your change management application, formats the results into an output file, and returns control to the Tioli Business Systems Manager change integration function. automatic ticket request processor The Tioli Business Systems Manager automatic ticket integration function transfers control to your program and passes eent data in an input file. Your program retriees the data from the input file, adds additional data, as necessary, formats and runs the appropriate calls to your problem management application to create a problem ticket, formats the results into an output file, and returns control to the Tioli Business Systems Manager automatic ticket integration function. To fully actiate automatic ticket integration function, you must also define automatic ticket eent rules; for more details, see the IBM Tioli Business Systems Manager Administrator s Guide. The workflow of the integration function, your request processor, and your problem or change management application, which is shown in Figure 1 on page 3, has the following steps: 2 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

17 1. A user request is passed from a workstation to the Tioli Business Systems Manager integration function on the Tioli Business Systems Manager database serer. 2. The integration function uses an input file to pass the request to your request processor (the program that you hae written). 3. Your request processor passes the request to your problem or change management application, where it is processed. 4. The application passes the results back to your request processor. 5. The request processor creates an output file and passes it back to the Tioli Business Systems Manager integration function. 6. The integration function sends the results to the workstation, where they are displayed on the interface. Workstation Problem Maintenance Tioli Business Systems Manager Database Serer Ticket No: Assignee: Component: Description: <New> Bob CICS CICS Down Tioli Business Systems Manager Integration Function Apply OK Input File Output File Request Processor Your Application Integration function files Figure 1. Integration function, request processor, and application workflow This section describes the files that are used with the integration function: Request processor files; see Request processor files. Input files proide input to a request processor; see Input files on page 5. Output files contain the results of the request processing; see Output files on page 6. Log files contains information about the success or failure of request processing; see Log files on page 7. Request processor files Two types of request processor files can be used: Windows standard executable files, which are written, for example, with C, C++, or Visual Basic and hae an.exe extension Chapter 1. Introduction 3

18 Windows nonstandard executable files, which are written, for example, with REXX or Korn Shell, and do not hae an.exe extension The name of your request processor, which is called by the Tioli Business Systems Manager integration function, is specified in the SystemConfiguration table. One or more rows define your request processor, using the alues shown in the following table. Defining a request processor actiates a specific type of integration function (problem, change, or automatic ticket). If you use the same request processor for more than one type of integration function, you must define it separately for each integration function: SystemConfiguration column name groupname propertyname propertyalue propertydatatype Value The type of integration function: REQUEST_PROBLEM REQUEST_CHANGE REQUEST_AUTOTICKET REQUEST_PROCESSOR_NAME request_processor_name CHAR Depending on the type of request processor file, you must define your request processor in one of the following ways: To actiate an integration function for a Windows standard executable file, run the following SQL statements, where groupname_alue indicates the type of integration function (REQUEST_PROBLEM, REQUEST_CHANGE, or REQUEST_AUTOTICKET) and request_processor_name is the name of your request processor: INSERT INTO SystemConfiguration VALUES ("groupname_alue","request_processor_name","request_processor_name","char") UPDATE MenuItemVersion SET erno = erno + 1 To actiate an integration function for a Windows nonstandard executable file, run the following SQL statement, where groupname_alue indicates the type of integration function and request_processor_name is the name of your request processor: INSERT INTO SystemConfiguration VALUES ("groupname_alue","request_processor_name","request_processor_name","char") UPDATE MenuItemVersion SET erno = erno + 1 Actiating a Windows nonstandard executable file requires a second entry to define the language type (for example, REXX.exe or KSH.exe); run the following SQL statements: INSERT INTO SystemConfiguration VALUES ("groupname_alue","request_processor_language","language_type","char" ) UPDATE MenuItemVersion SET erno = erno + 1 Note: If REQUEST_PROCESSOR_NAME is specified in the Tioli Business Systems Manager SystemConfiguration table without a REQUEST_PROCESSOR_LANGUAGE row, the default call for the Tioli Business Systems Manager integration function is to a Windows standard executable file, so you must take the following actions: Do not specify a REQUEST_PROCESSOR_LANGUAGE row for a Windows standard executable file. You must specify a REQUEST_PROCESSOR_LANGUAGE row for a Windows nonstandard executable file. 4 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

19 In either case, the request processor specified is called by the Tioli Business Systems Manager integration function for all console requests or, for the automatic ticket function, for all eents that are selected based on selection criteria that you define. Input files The Tioli Business Systems Manager integration function generates a data file (GUID.in or, for batch mode, GUID.batch.in) to proide input to your request processor. Your request processor uses the data in this input file to complete a specific request. In the input file name, GUID is the global unique identifier (GUID) that is generated by the Tioli Business Systems Manager integration function. These names are examples of input file names: {172CA649-17BD-4A D19A4F58FA5A}.in {172CA649-17BD-4A D19A4F58FA5A}.batch.in The input file resides in the Program Files\Tioli\tbsm\Data directory on the database serer. The request processor that reads the GUID.in or GUID.batch.in file must reside on the same drie and in the same directory. Howeer, the request processor that interacts with your problem or change management application can reside on the serer and platform where the problem or change management application resides. If so, the request processor reading the input file must transport the data from the input file to the request processor residing on the serer and platform where your application resides. Note: Program Files\Tioli\tbsm\ is the directory in which the Tioli Business Systems Manager product is installed. The path for this directory can ary, depending on where you installed the product. An input file represents a specific request and contains all the unique field names and their associated data alues for the request. A field name and its associated alue is known as a name-alue pair. Your request processor is responsible for capturing the appropriate data from the input file (GUID.in or GUID.batch.in) and creating a problem in the problem management application or a change in the change management application. Each line of the input file contains a name-alue pair in the following format and ends with the end-of-line characters CR (carriage return) and LF (line feed). field_name row_id number_of_records field_alue where: field_name Is the unique name of a data element within a request. Use this name to map or associate the field alue to a corresponding field name in the problem or change management application database. row_id Is a sequential number that indicates the row number out of the total number of input lines for a gien field name. For single data items, this alue is always 1. For multiline data items, such as text areas, the row number is increased by 1 for each additional line. number_of_records Indicates the total number of input lines for a gien field name. For single data items, this alue is always 1. Chapter 1. Introduction 5

20 field_alue Is the alue that is associated with the field_name field. The field alue is stored in the problem or change management application database. The following example indicates that this is the first of 10 lines of long description text, where text_data is the text in the first line: REQUEST_LONG_DESCRIPTION_EDIT 1 10 text_data The following example shows that the open status code alue is stored as the status code alue in the problem ticket: "REQUEST_STATUS_CODE 1 1 open For more information about the name-alue pairs, see Appendix A, Problem and change name-alue pairs, on page 77. For non-batch mode, the Tioli Business Systems Manager integration function calls your request processor using the following command, where my_request_processor is the name of your request processor, GUID is the global unique identifier generated by the integration function, and InFilePath is the Program Files\Tioli\tbsm\Data directory on the database serer: call my_request_processor GUID InFilePath To read the input file, your request processor should construct a file ariable by concatenating the parameters and the.in extension, for example: MyInFile = InFilePath GUID.in For batch mode, your request processor must always be running. It must check for any GUID.batch.in files waiting to be processed. This can be accomplished by a user-defined serice that you create or by some other process that calls your request processor. When it is running, your request processor should perform the following actions: Check for input (*.batch.in) files in the Program Files\Tioli\tbsm\Data folder. If input files exist, capture the GUID alue from the name of each GUID.batch.in file waiting to be processed. Use the captured GUID alues to read each GUID.batch.in file. After each GUID.batch.in file is processed, your request processor should delete it to ensure that the file is not processed again. Output files When your request processor receies the results from the problem or change management application, it must create a text-based output file containing the results. For example, a problem ticket create request receies a return code, and a new problem ticket number is generated by the problem management application. The output file name must be named GUID.out (or, for batch mode, GUID.batch.out), where GUID is the global unique identifier that was passed to your request processor when the Tioli Business Systems Manager integration function called it. The output file must be created in the same Program Files\Tioli\tbsm\Data directory as the GUID.in input file. The output file contains simple name-alue pairs in the same format as in the input file (described in Input files on page 5). For more information about the name-alue pairs, see Appendix A, Problem and change name-alue pairs, on page IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

21 field_name row_id number_of_records field_alue At a minimum, the output file must contain the following name-alue pairs: REQUEST_RETURN_CODE 1 1 alue The alue indicates the success or failure of the processing. A alue of 0 indicates success; any other alue is considered an error. This must be the first name-alue pair entry in the file. REQUEST_ERROR_MSG 1 1 alue The alue is a text message that describes an error condition or confirms the request processing. The text message should be concise and meaningful, because it might be logged by the integration function and, for problem and change management applications, it might be displayed to the user on the Tioli Business Systems Manager console. This must be the second name-alue pair entry in the file. For any request processor that has to return a problem ID, the output file must also contain the following name-alue pair: REQUEST_PROBLEM_ID 1 1 problem_id_alue The alue is the problem ID. For batch automatic ticket processing, this alue must be NO_NOTE to acknowledge the processing of the request issued by the automatic ticket integration function. This entry can be anywhere in the file except that it cannot be the first or second entry. If any of the following conditions occurs, the Tioli Business Systems Manager integration function creates an output file (GUID.out or GUID.batch.out) for you: The request processor does not create an output file within the time limit specified by the timeout alue. The request processor creates an output file that is not in the correct format. REQUEST_RETURN_CODE and REQUEST_ERROR_MSG are not the first two name-alue pairs in the output file. If an error occurs, the specifics are written to a log file on the Tioli Business Systems Manager database serer, and, for user requests from the Tioli Business Systems Manager console, an error message generated by the integration function is displayed at the console. Log files A standard Tioli Business Systems Manager log file is maintained in the Program Files\Tioli\tbsm\logs directory. This log contains audit and error information and all request information. The file is located on the database serer in the Program Files\Tioli\tbsm\logs\INTMGRyyyymmdd directory, where yyyymmdd specifies the year, month, and day. A new log file is created at the beginning of a new processing day. This file, which is a text file, contains information about the success or failure of all processing requests. It aids in debugging failed requests. Chapter 1. Introduction 7

22 Planning for request processors Before deeloping a problem request processor, consider the following items: Skills needed for implementation Program implementation considerations Using the planning worksheet on page 9 Skills needed for implementation The person implementing a request processor should hae a good understanding of the data and processing requirements and working knowledge of your problem or change management application, including any customization that is needed to meet your requirements. The following skills are required to deelop a request processor that integrates with a problem or change management application: Experience in deeloping applications that process command line parameters Knowledge of standard file input/output techniques Sufficient knowledge of the facilities that integrate with the problem or change management application Knowledge of any special requirements for processing problem tickets or change requests The following skills are also important in deeloping a request processor: The appropriate programming language skills to deelop and test your request processor solution A working knowledge of the operating systems on which your request processor and the problem or change management application reside Program implementation considerations When planning to implement a problem request processor, consider the following information about your current enironment: What type of interfaces are proided for your problem or change management application? Typically, these applications proide API calls that proide an interface with the problem or change management application database to create, update, retriee, find, get, query, or search problem tickets or change requests. Some might support eent queuing or proide a TCP/IP connection or ODBC connection to the application or database. These applications might also support arious languages and platforms that can be used to implement the interface process. What languages are supported to implement a request processor solution that integrates with your problem or change management application? Examples are C, C++, REXX, Visual Basic, Korn Shell, and Perl. What operating systems are supported for running your request processor solution that integrates with your problem management application? Examples are the z/os, UNIX, and Windows operating systems. Note: No particular deelopment language or platform is preferred as long as the selected language and platform meet your requirements and are supported by your problem or change management application. Your request processor can reside in the Program Files\Tioli\tbsm\Data folder on the Tioli Business Systems Manager database serer. Howeer, if your request 8 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

23 processor resides on another system, you must transport the data contained in the input file to that system and return the results in a formatted output file that must reside in the Program Files\Tioli\tbsm\Data folder on the Tioli Business Systems Manager database serer. Because the key data fields specified in the name-alue pairs are used with the Tioli Business Systems Manager product, most problem and change management application databases do not hae them defined. You must determine how to store these in your application. For example, you might proide existing fields that are defined in your database or you might define new fields to store the key data fields. In any case, the data must be mapped to the data fields in your request processor. The Tioli Business Systems Manager problem and change integration functions do not support retrieing problem tickets or change requests that are created within your application. The automatic ticket integration function can be run in non-batch or batch mode. The general guideline for deciding which mode to implement depends on the number of message and exception eents that are sent to Tioli Business Systems Manager from both distributed and z/os sources. Use batch mode if the aerage message and exception eent olume is 2000 or more eents per hour or if the request processor performs automatic notification (such as pager or notification). Use non-batch mode if the aerage message and exception eent olume is fewer than 2000 eents per hour or if your request processor does not perform notification (such as pager or notification). When the automatic ticket integration function runs in non-batch mode, an input file is created for each eent that matches a defined automatic ticket eent rule. The non-batch automatic ticket integration function calls your request processor, passing it the input file name and directory. The non-batch automatic ticket integration function waits for the request processor to process the input file, creates a problem in the problem management application, creates an output file, and then exits. This is done in a connected mode; that is, Tioli Business Systems Manager is connected and waiting for the request processor to complete processing. Use the non-batch mode only when a message or exception eent matches a defined automatic ticket eent rule. If additional processing is needed, such as automatic notification, use the batch automatic ticket integration function. Using the planning worksheet A worksheet named pcrpcustomerworksheet.xls, which is helps you identify your request processor requirements. The worksheet is located on the Tioli Business Systems Manager database serer in the Program Files\Tioli\tbsm\Data\ProbChgSamples folder. It proides a list of considerations that you should reiew before deeloping a request processor, such as the following items: System configuration alues Problem ticket interface requirements Change request interface requirements Drop-down list alues Drop-down dependency alue lists Drop-down list defaults Data formats (display and product) Date formats (target product) Chapter 1. Introduction 9

24 Required data field by type Special processing Sample integration function Sample integration function for Information Management for z/os is shipped and gets installed with the Tioli Business Systems Manager product. It proides an example of how to integrate Tioli Business Systems Manager and a problem management application. The sample does not proide details for any particular application, programming language, or operating system. It suggests functions, error checks, and data manipulation to help you understand what is needed to implement a request processor. The functions in the sample can be implemented in arious ways, depending on the programming language or operating system being used. Each implementation of a request processor should be analyzed to determine the best way to meet requirements for interfacing with a particular application. You might need to add to or modify the sample to accommodate the requirements of your particular application. The sample integration function is described in Appendix B, Sample integration for the Information Management for z/os product, on page IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

25 Chapter 2. Writing a problem request processor This chapter describes how to write a problem request processor. What is a problem request processor? A problem request processor is any request processor you write that can process command line input parameters, read a text-based input file containing the data passed from the integration function, and create a text-based output file with the results receied from the problem management application. A problem request processor is called by the Tioli Business Systems Manager problem integration function. Problem integration function flow These steps show the flow for the problem integration function: 1. The user selects a problem ticket function from the console, specifies the data needed, and clicks OK to start the integration function. the problem ticket functions are Create, Find, Properties, Update, and Search. 2. The Tioli Business Systems Manager integration function creates an input file containing the request data and calls your request processor, which is defined in the Tioli Business Systems Manager SystemConfiguration table. The Tioli Business Systems Manager integration function passes the name of the input file and the path where the input file resides to your request processor. 3. Your request processor reads the input file to gather the data to be formatted, and then makes the appropriate API or interface calls to the problem management application. 4. Your request processor receies the results from the API or interface call to the problem management application, formats an output file, and returns control to the Tioli Business Systems Manager integration function. 5. The integration function gathers the output results from the output file and returns them to the console for display. Configuration of problem integration function To actiate the problem integration function, define your request processor in the SystemConfiguration table, using the following alues: SystemConfiguration column name groupname propertyname propertyalue propertydatatype Value REQUEST_PROBLEM REQUEST_PROCESSOR_NAME request_processor_name CHAR Define your request processor in one of the following ways: If your request processor is a Windows standard executable file, run the following SQL statements, where problem.exe is the name of your request processor: Copyright IBM Corp

26 INSERT INTO SystemConfiguration VALUES ("REQUEST_PROBLEM","REQUEST_PROCESSOR_NAME","problem.exe","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 If your request processor is a Windows nonstandard executable file, run the following SQL statement, where problem.rex is the name of your request processor and language_type defines the language type (for example, REXX.exe or KSH.exe): INSERT INTO SystemConfiguration VALUES ("REQUEST_PROBLEM","REQUEST_PROCESSOR_NAME","problem.rex,"CHAR") INSERT INTO SystemConfiguration VALUES ("REQUEST_PROBLEM","REQUEST_PROCESSOR_LANGUAGE","language_type","CHAR" ) UPDATE MenuItemVersion SET erno = erno + 1 Requirements for problem request processors This section presents the minimal requirements for creating a request processor to receie input from the Tioli Business Systems Manager problem interface on the console. You are responsible for integrating your request processor with your problem management application. Integration can be implemented in arious ways, depending on the programming language, the platform, and the integration facilities that are supported. Also, you must analyze each implementation of your request processor to determine the best method to interface with your problem management application based on your specific requirements. Input and output files Your problem request processor must read the input file and create the output file. A new input file is created for each request made from the console. The Tioli Business Systems Manager problem integration function calls your request processor using the GUID and InFilePath parameters. An output file is created for each specific request and contains the formatted results of the request returned from your problem management application. For more information about input files and calling your request processor, see Input files on page 5. For more information about output files, see Output files on page 6. Console problem function Users can interact with a problem management application by using the following console functions: Create Problem Ticket, using data elements to create a problem ticket Find Problem Tickets, using data elements to search for problem tickets Problem Ticket Properties (General), using data elements for updating general information in a problem ticket Problem Ticket Properties (Closure), using data elements for updating closure information in a problem ticket Access Information, specifying user ID and password for the problem management application. You can customize the console to change field labels or hide fields, or both, to match your problem management application and the fields it supports. For more information, see Customizing console fields on page IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

27 Console request processing The following console functions support problem ticket processing: Initialize and Prepopulate a Problem Request interface User ID processing Receiing and Returning Enumeration alues for Problem Tickets Create a Problem Ticket Initial Query of Problem Tickets Find a Problem Ticket Update a Problem Ticket Adhoc Query of Problem Tickets Each console option sends a series of requests to your request processor. A different GUID.in file is created for each request, in the following way: 1. The first request issued is an initialization request to your request processor. 2. The console sends a series of enumeration requests to your request processor to obtain alues to use in populating the drop-down lists in the console. The number of enumeration requests aries depending on how the console is customized to meet the needs of your problem management application. The default number of enumeration requests is 4. Some alues might be obtained from the problem management application; others might be coded in your request processor. 3. After the data is specified and the user clicks OK, a request is sent to your request processor to create, query, update, or find problem tickets. Each request can pass one or more user IDs and passwords. The Tioli Business Systems Manager signon user ID and password is always passed. Optionally, a user ID and password for accessing your problem management application can be passed. Your request processor must proide a response to eery console request by creating a GUID.out file containing, at a minimum, the REQUEST_RETURN_CODE and REQUEST_ERROR_MSG name-alue pairs. Additional data is added to this file based on the type of request. Text field size restriction The maximum size for any field in the GUID.out file is 254 characters. This is due to a restriction in the Microsoft SQL Serer product. If you return a field with text longer than 254 characters, the Tioli Business Systems Manager integration function truncates it to 254 characters before displaying it in the problem ticket interface. Initializing and prepopulating a problem request interface The first request sent to your request processor is the REQUEST_INITIALIZE request. This request enables your request processor to take the following actions before the problem interface is displayed to the user: Oerride configuration default alues, which you actiate, in the Tioli Business Systems Manager SystemConfiguration table. Oerride default alues in the TSD_SCIM table and your customer ID table. Define the open and closed alues used in your problem management application. For problem create only, specify an ID to be populated in the Long Description text. Chapter 2. Writing a problem request processor 13

28 Prepopulate the console problem fields with data. This is aailable for the take ownership function when the create problem ticket check box is selected. It is not aailable in for creating a problem ticket from a resource. Your request processor can oerride the following name-alue pairs: REQUEST_CUSTOMER_ID 1 1 alue ORIGIN_COMPONENT 1 1 alue ORIGIN_ITEM 1 1 alue ORIGIN_MODULE 1 1 alue ORIGIN_SYSTEM 1 1 alue PROBLEM_OPEN_VALUES 1 1 alue1,alue2 PROBLEM_CLOSE_VALUES 1 1 alue1,alue2 REQUEST_PROBLEM_TYPE 1 1 alue REQUEST_ASSIGNEE_GROUP 1 1 alue REQUEST_ASSIGNEE_NAME 1 1 alue REQUEST_STATUS_CODE 1 1 alue REQUEST_SEVERITY 1 1 alue REQUEST_PROBLEM_TYPE 1 1 alue REQUEST_SHORT_DESCRIPTION 1 1 alue Problem open and close alues If your problem management application supports alues other than Open or Closed to indicate a problem is either actie (in a working state) or inactie (no longer in a working state), your request processor should return these alues in the PROBLEM_OPEN_VALUES or PROBLEM_CLOSE_VALUES name-alue pair. These alues are needed to actiate arious processes within the problem ticket functions, such as generating a request for a count of open problems when closing a problem ticket. The count is used to determine whether to remoe the problem ticket resource indicator from the resource for which a problem ticket was closed. Examples of actie alues are Open, Initial, Working, and Pending. Examples of inactie alues are Closed, Dead, Returned, and Obsolete. Customer ID If the REQUEST_CUSTOMER_ID name-alue pair is returned with a alue, the console populates the long description field with the alue when the Problem Create interface is displayed. The alue plus any additional text the user enters is passed to your request processor to include when creating the problem ticket in your problem management application. Origin alues For complete details about the configuration and default options for the TSD_SCIM and Customer ID table alues, see Origin alues: system, component, item, module on page 73 and TSD_SCIM table on page 74. The following example shows a REQUEST_INITIALIZE request. REQUEST_USER_ID (the problem management application user ID) and REQUEST_USER_PASSWORD (the problem management application password) are always blank. REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_INITIALIZE REQUEST_OBJECT CID 1 1 LOB REQUEST_OBJECT ID REQUEST_OBJECT_SOURCE_CID 1 1 CICS REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 CICEH002 REQUEST_LOGIN_USER_ID 1 1 TBSM_login_userid REQUEST_LOGIN_USER_PASSWORD 1 1 TBSM_login_password 14 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

29 REQUEST_USER_ID 1 1 REQUEST_USER_PASSWORD 1 1 AUTO_CLOSE_DEFAULT 1 1 YES AUTO_SELECT_TICKET 1 1 INITIAL DEBUG_MODE 1 1 OFF DISPLAY_PROBLEM_CLOSURE 1 1 YES GET_PROBLEMS_ON_INSERT 1 1 NO TICKET_CREATE_DEFAULT 1 1 YES TIMEOUT_VALUE REQUEST_CUSTOMER_ID 1 1 ORIGIN_COMPONENT 1 1 AUTO_CREATE ORIGIN_ITEM 1 1 AUTO_CREATE ORIGIN_MODULE 1 1 AUTO_CREATE ORIGIN_SYSTEM 1 1 AUTO_CREATE The request processor can oerride the following name-alue pairs: REQUEST_CUSTOMER_ID 1 1 alue ORIGIN_COMPONENT 1 1 alue ORIGIN_ITEM 1 1 alue ORIGIN_MODULE 1 1 alue ORIGIN_SYSTEM 1 1 alue To blank the defaults for these alues that are set initially by the console, return the appropriate name-alue pairs with no alues, for example: REQUEST_CUSTOMER_ID 1 1 Note: The ORIGIN_ alue oerrides are also displayed in the problem ticket interface with the SYSTEM:, COMPONENT:, ITEM:, and MODULE: field labels and hae the REQUEST_SYSTEM, REQUEST_COMPONENT, REQUEST_ITEM, and REQUEST_MODULE name-alue pairs passed to the request processor. If these fields are customized in the problem ticket interface, do not use the oerride facility for the ORIGIN_ alues. To oerride a alue, return the same name-alue pair with a new alue in the GUID.out file, for example: REQUEST_RETURN_CODE /*sets return code to 0*/ REQUEST_ERROR_MSG 1 1 Initialize request was successful REQUEST_CUSTOMER_ID 1 1 Tioli ORIGIN_COMPONENT 1 1 LOOK_UP ORIGIN_ITEM 1 1 LOOK_UP ORIGIN_MODULE 1 1 LOOK_UP ORIGIN_SYSTEM 1 1 LOOK_UP /*any text message*/ Een if your request processor does not oerride any alues, it must still acknowledge this request by creating a GUID.out file with these name-alue pairs: REQUEST_RETURN_CODE /*sets return code to 0*/ REQUEST_ERROR_MSG 1 1 Initialize request was successful /*any text message*/ Additionally, your request processor can return a list of alues that are used to determine whether a problem ticket is closed or open based on alid status code alues within the problem management application. Many problem management applications hae seeral alues to indicate that a problem is in a closed or open state. For instance, Close and Dead might represent a closed state, or Initial and Open might represent an open state. The console uses the Close status alues to set the REQUEST_CLOSE name-alue pair to a alue of YES. This indicates to your request processor that the user has closed the problem ticket and any additional close processing can be done as Chapter 2. Writing a problem request processor 15

30 needed. The default alue is Closed if no alues are passed from the request processor in the REQUEST_INITIALIZE request. The following example shows passing of the open, close, and customer ID alues in the GUID.out file for the REQUEST_INITIALIZE request: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 Initialize request was successful REQUEST_CUSTOMER_ID 1 1 IBM PROBLEM_OPEN_VALUES 1 1 Initial,Open PROBLEM_CLOSE_VALUES 1 1 Closed,Dead Because the open and close alues are not case sensitie, a alue of OPEN is equialent to a alue of Open. For a request processor that oerrides all possible alues, the GUID.out file has the following name-alue pairs: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 Initialize request was successful REQUEST_CUSTOMER_ID 1 1 alue PROBLEM_OPEN_VALUES 1 1 alue1,alue2 PROBLEM_CLOSE_VALUES 1 1 alue1,alue2 ORIGIN_COMPONENT 1 1 alue ORIGIN_ITEM 1 1 alue ORIGIN_MODULE 1 1 alue ORIGIN_SYSTEM 1 1 alue Enumeration requests Users can select a alue from a list of predefined alues in the arious drop-down list fields in the problem ticket console interface. You can use different sets of alues to meet your specific needs. Because of that, the console drop-down lists are not prepopulated. The problem integration function enables your request processor to dynamically populate the problem ticket drop-down lists in the interface. The alues should match the list alues that are contained in your problem management application. The default problem enumerations are shown in the following list. If the console labels are modified, the following corresponding REQUEST_ENUM_NAME name-alue pairs can reflect different alues to populate the corresponding labeled field in the problem interface. REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_PROBLEM_SEVERITY REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_PROBLEM_ASSIGNEE_GROUP REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_PROBLEM_TYPE REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_STATUS_CODE REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_RESOLUTION_CLOSURE_STATUS REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_RESOLUTION_CODE These requests present a special consideration for your request processor. If your application requires a alid user ID and password to access the problem management application for obtaining these enumeration alues, they are not proided in the REQUEST_USER_ID and REQUEST_PASSWORD name-alue pairs. That is because these requests are sent before the user has proided the user ID and password. 16 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

31 Therefore, your request processor must hae another method of accessing a alid user ID and password in order to perform the enumeration requests against your problem management application. Depending on the problem management application and on your enironment, that can be accomplished in arious ways. The user ID and password might be coded in your request processor, or your request processor might need to access an external file to obtain it. In any eent, you must make this decision when designing your request processor. For all other requests, your request processor should use the user ID and password that the user has entered at the console and passed as REQUEST_USER_ID and REQUEST_PASSWORD, if present. This appropriately identifies the user that created or updated a problem. One exception is when you synchronize the Tioli Business Systems Manager login user IDs and passwords with your problem management application. In this case, the REQUEST_LOGIN_UID and REQUEST_LOGIN_PASSWORD name-alue pairs are always aailable for accessing the problem management application. Receiing enumeration requests The console and Tioli Business Systems Manager integration function send a series of enumeration requests to your request processor, before making the console interface aailable to the user. The enumeration requests are used to populate drop-down lists and proide dependency alue lists. The enumeration alues should represent the same alues that are aailable in the problem management application. Different installations require different customization. Some information might be aailable directly from the problem management application; other information might need to be obtained from other sources, such as an external file. That depends on the setup of your problem management application. These alues can ary from one problem management application to another, depending on your installation. If the alues for the enumerations are to be returned from the problem management application, each interface is different. For example, some might proide special API calls, others might proide query and search facilities, and still others might proide some, but not all, of the enumeration alues that are needed; in that case, they must be coded in your request processor or obtained from an external file that is read by your request processor. Your request processor must respond to each enumeration request by creating a GUID.out file, een if a particular drop-down list has no alues to return. That can occur if a drop-down list has been hidden using the console customization tool. The enumeration requests proided do not apply to a specific problem management application. In other words, the default drop-down list labels can be changed (with the console customization tool) to a different type of drop-down list with labels and alues based on a specific problem management application. The GUID.out file must contain at least a return code of 0 and an error message. This is required een if the enumeration is not needed for display at the console. All enumeration requests hae the following name-alue pairs: REQUEST_METHOD 1 1REQUEST_ENUM, which identifies it as an enumeration request to populate a drop-down list in the interface. REQUEST_ENUM_NAME 1 1 enumeration_alue_type, which identifies the types of enumeration alues that are being requested. Chapter 2. Writing a problem request processor 17

32 The enumeration alue type proided in the REQUEST_ENUM_NAME matches the console field labels proided with Tioli Business Systems Manager; howeer, it might not match the field label if it was changed with the console customization tool. As described in Customizing console fields on page 75, the console field labels can be changed to represent a different alue or data field. If the console field labels associated with drop-down lists are changed to represent another alue type, the name-alue pairs remain the same. Howeer, your request processor should proide the appropriate alues to match the console field label een though the name-alue pair is different. The following enumeration alue types are proided for problem tickets (alues for problem type, problem seerity, problem status, assignee group, and closure status): REQUEST_ENUM_NAME 1 1 REQUEST_PROBLEM_TYPE REQUEST_ENUM_NAME 1 1 REQUEST_PROBLEM_SEVERITY REQUEST_ENUM_NAME 1 1 REQUEST_STATUS_CODE REQUEST_ENUM_NAME 1 1 REQUEST_PROBLEM_ASSIGNEE_GROUP REQUEST_ENUM_NAME 1 1 REQUEST_RESOLUTION_CLOSURE_STATUS Returning enumeration request alues A GUID.out file must be created for each enumeration request receied in a GUID.in file. Enumeration request without alues to return: Your request processor must respond to eery enumeration request, een if the console drop-down list is not being used for a specific problem management application integration. This typically occurs if a console field was hidden because it is not needed for integration with your problem management application. For example, suppose the console sends the following request for resolution code alues: REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_RESOLUTION_CODE Because no enumeration alues are needed for this field, your request processor must create a GUID.out file with the following name-alue pairs: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 enumeration request was successful After creating the file, your request processor should exit and return control to the Tioli Business Systems Manager integration function. The integration function processes the file and returns the results to the console. Because no alues are returned, the console does not try to populate the resolution code field drop-down list. Enumeration request with alues to return: When the enumeration alues in a console field must be populated, your request processor should create a GUID.out file containing the appropriate alues: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 enumeration request was successful REQUEST_ENUM_VALUE 1 1 alue1 REQUEST_ENUM_VALUE 1 1 alue2 For example, suppose the console sends a request for Problem Type alues: 18 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

33 REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_PROBLEM_TYPE That request might return the following alues: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 enumeration request was successful REQUEST_ENUM_VALUE 1 1 SOFTWARE REQUEST_ENUM_VALUE 1 1 HARDWARE REQUEST_ENUM_VALUE 1 1 NETWORK After creating the file, your request processor should exit and return to the Tioli Business Systems Manager integration function. The integration function processes the file and returns the results to the console to populate the problem type drop-down list with the alues of SOFTWARE, HARDWARE, and NETWORK. Examples for each enumeration request are proided in Appendix C, Example input and output files, on page 107. Returning enumeration list dependency filters Some problem management applications hae drop-down lists that display alues based on the current alue of another list, for example, only listing Software resolution codes when the problem type already selected is Software. This function is supported by the console; howeer, your request processor must proide the dependency filters. As indiidual enumerated alues are returned to the console, they contain simple filtering information that can be applied to dependent drop-down lists. This filtering information consists of the target enumeration group name to which the filter applies and a list of alid alues. For example, if the name of the problem type enumeration is REQUEST_PROBLEM_TYPE and the name of the Resolution Code group is REQUEST_RESOLUTION_CODE, the input and output files are shown in the following list: The GUID.in file for Resolution Code has the following name-alue pairs: REQUEST_TYPE 1 1 REQUEST_ PROBLEM REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_RESOLUTION_CODE The GUID.out file for Resolution Code has the following name-alue pairs: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 Resolution Code Enumeration request was successful REQUEST_ENUM_VALUE 1 1 Resolution Code 1 REQUEST_ENUM_VALUE 1 1 Resolution Code 2 REQUEST_ENUM_VALUE 1 1 Resolution Code 3 The GUID.in file for Problem Type has the following name-alue pairs: REQUEST_TYPE 1 1 REQUEST_ PROBLEM REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_PROBLEM_TYPE The GUID.out file for Problem Type has the following name-alue pairs: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 Type Enumeration request was successful REQUEST_ENUM_VALUE 1 1 SOFTWARE REQUEST_ENUM_VALUE 1 1 HARDWARE REQUEST_ENUM_VALUE 1 1 NETWORK,REQUEST_RESOLUTION_CODE,Resolution Code 2 Chapter 2. Writing a problem request processor 19

34 The last line of this GUID.out file indicates that, when the alue of the Problem Type drop-down list is NETWORK, the alid alue for the Resolution Code drop-down list is Resolution Code 2. If seeral alues are alid, they must be separated by commas, and the GUID.out file for Problem Type has the following name-alue pairs: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 Type Enumeration request was successful REQUEST_ENUM_VALUE 1 1 SOFTWARE REQUEST_ENUM_VALUE 1 1 HARDWARE REQUEST_ENUM_VALUE 1 1 NETWORK,REQUEST_RESOLUTION_CODE,Resolution Code 2, REQUEST_ENUM_VALUE 1 1 NETWORK,REQUEST_RESOLUTION_CODE,Resolution Code 3 The last line of this GUID.out file indicates that, when the alue of the Problem Type drop-down list is NETWORK, the alid alues for the Resolution Code drop-down list are Resolution Code 2 and Resolution Code 3. If the alue of the Problem Type drop-down list is SOFTWARE or HARDWARE, the alid alues for the Resolution Code drop-down list are Resolution Code 1, Resolution Code 2, and Resolution Code 3. No dependencies exist for these alues. Your request processor deeloper must implement the dependency rules and build the GUID.out files to reflect these rules. If no rules exist, the drop-down lists whateer alues were originally loaded into them. The enumeration list dependency filters do not support the following uses: Any combining of rules (by using and or or). An example of using and is to restrict list A to the alues A, B, and C when listb is X and list C is Y. Reselection alues. Using the preious example, suppose that the user selects SOFTWARE from the Problem Type drop-down list and selects Resolution Code 1 from the Resolution Code drop-down list. If the user returns to the Problem Type drop-down list and re-selects HARDWARE, the user is not notified that Resolution Code 1 is not a alid selection for HARDWARE in the Problem Type alue. Your request processor must alidate the combinations selected by the user and, if the combinations are not alid, return an error. Date formats The Tioli Business Systems Manager integration function supports only one format for passing dates between the console and the request processor. The date format supported is the year, the month, the day, a blank space, hour, minutes, and seconds, as shown here: yyyymmdd hhmmss Note: If the application does not support seconds in dates, the request processor should proide zeros in the dates, as shown here: yyyymmdd hhmm00 The console reformats the dates for display as shown here: mm/dd/yyyy hh:m:ss Identifying problems in a problem management application A Tioli Business Systems Manager physical resource key must be stored in a problem ticket that is created on your problem management application. This enables the Tioli Business Systems Manager problem find/query function to 20 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

35 retriee one or more problems from the problem management application for display at the console. If the physical resource key is always stored, changes can be retrieed for iewing or update purposes, regardless of whether they were created from a business system resource or a physical resource. Your request processor should include the physical resource CID and physical resource ID in a problem ticket when it is created using the console; doing that enables the console to retriee problems for a specific Tioli Business Systems Manager resource when using the find/query function within the console. Note: Only problem tickets created from the console can be retrieed from the problem management application. Problem tickets created from within your problem management application do not hae Tioli Business Systems Manager physical resource key stored as part of the data. Therefore, they cannot be retrieed and associated with a Tioli Business Systems Manager physical resource key resource. The physical resource CID and physical ID for a Tioli Business Systems Manager resource is always passed to your request processor in the following name-alue pairs: REQUEST_OBJECT_SOURCE_CID 1 1 Physical_Resource_Class_ID REQUEST_OBJECT_SOURCE_ID 1 1 Physical_Resource_ID Optionally, the Tioli Business Systems Manager resource name can be stored with a problem creation. The resource name should not be stored as the only key for a resource because more than one resource can hae the same name. The Tioli Business Systems Manager resource name is always passed to your request processor in the following name-alue pair: REQUEST_OBJECT_NAME 1 1 resource_name_alue Another option is to create SCIM alues; for more information, see Origin alues: system, component, item, module on page 73 and TSD_SCIM table on page 74. Considerations for problem request processors This section presents arious suggestions and considerations for creating a request processor to integrate with your problem management application. Integrations can be implemented in arious ways, depending on the programming language or the platform being used, or both. Analyze each implementation of your request processor to determine the best method of interfacing to your problem management application, based on your specific requirements. Consider the following functions: Problem management application user ID and password aailability Large olume enumeration (drop-down list) alues Initial query/search to display problems from the problem management application Adhoc query/search generated by the user to display problems from the problem management application Specific problem location in the problem management application Update of a problem in the problem management application Automatic close of a problem in the problem management application Problem closure within Tioli Business Systems Manager Chapter 2. Writing a problem request processor 21

36 Required data fields in the problem management application Association of problems in the problem management application with Tioli Business Systems Manager resources. User ID and password If a user ID and password are required to access your problem management application, a few conditions exist under which a user ID and password are not aailable when the console sends a request to your request processor. When the user selects Insert or View for a Tioli Business Systems Manager resource, the console sends seeral requests for information to prepare for entry. They are: REQUEST_INITIALIZE REQUEST_QUERY REQUEST_AUTO_CLOSE All enumeration requests Some problem management applications require a user ID and password to be passed from the request processor to establish a session or perform database functions, or both. To accommodate this requirement, your request processor should use a special user ID and password that you proide and that allows these functions to be performed. This special user ID should hae all the authority it needs to perform any function against the problem management application database. Note: Password security is the responsibility of your request processor. Loading large olume problem enumeration alues To return enumeration alues or drop-down list alues to the Tioli Business Systems Manager integration function, your request processor must either obtain them from the problem management application or contain the alues. If you implement a large number of alid alues for certain data fields used for creating or updating problem tickets, returning these alues from your request processor and formatting them for display at the console can take a fairly long time, een an unacceptably long time, depending on the number of drop-down list alues being returned. In this situation, consider using the table-based enumerations option, which improes the performance of loading large olume enumeration lists considerably. This option requires loading your enumeration alues into a table. A special process calls your request processor to obtain the alues, as described in Returning enumeration request alues on page 18, and no additional modifications to your request processor are needed. To actiate this option and load your enumeration alues into a table, follow these steps: 1. To actiate the facility to load large enumeration lists for problem tickets: a. Start a Query Analyzer on the SQL serer, and run the following statements: INSERT INTO SystemConfiguration VALUES ( API_INTEGRATION_OPTIONS, TABLE_BASE_ENUMERATIONS, YES, CHAR ) UPDATE MenuItemVersion SET erno = erno + 1 b. Run the following statement in the Query Analyzer to erify that the new row is correct: 22 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

37 SELECT * FROM SystemConfiguration WHERE propertyname= TABLE_BASE_ENUMERATIONS The results window should display the following new row, where xx is the row ID: id groupname propertyname propertyalue propertydatatype xx API_INTEGRATION_OPTIONS TABLE_BASE_ENUMERATIONS YES CHAR 2. To populate the enumerations table, follow these steps: a. Start SQL serer Enterprise Manager on the SQL Serer. b. Expand SQL Serer Group, expand SQL Serer, expand Management, and expand SQL Serer Agent. c. Click Jobs to display all the Tioli Business Systems Manager jobs. d. Right-click the LoadIntegrationEnumeration job; select properties, click Steps, and then double-click setintegrationenumeration to display the step details. The following statement is displayed: exec asisp_setintegrationenumeration "P" The letter P indicates to load enumeration lists for problem tickets only. To load enumeration lists for both problem tickets and change requests, change P to PC. To load enumeration lists for change requests only, change P to C. e. Click OK twice to end and sae any changes made. f. Right-click the LoadIntegrationEnumeration job again, and click Start Job to run the LoadIntegrationEnumeration job to initially load your alues into the enumeration table. g. Check the Last Run Status column in the LoadIntegrationEnumeration job display. It should display the alue Succeeded. If it indicates Failure, ensure that your request processor is actiated and, if applicable, has a connection to your problem management application. h. Right-click the LoadIntegrationEnumeration job again, select properties, and then click Schedules. This job is scheduled to run weekly on Sunday to refresh the enumeration alues for any additions or changes. To change this schedule, click Edit, then click Change for Recurring, and specify the schedule you want for this job. i. Click OK until you return to the Jobs display. 3. To erify that your enumeration alues were loaded successfully, return to the Query Analyzer on the SQL Serer, and run the following statement: SELECT * FROM IntegrationEnumeration This displays all the alues that were loaded by the LoadIntegrationEnumeration job. Request query with request initialize REQUEST_QUERY is a request to perform a Query/Search on the problem management application database for problems that were created by the console for a particular resource. The two types of query requests are initial query requests and adhoc query requests. The REQUEST_QUERY_TYPE name-alue pair always accompanies REQUEST_QUERY to indicate the type of query requested. A REQUEST_QUERY_TYPE alue of INITIAL indicates that your request processor should format a search argument using the Tioli Business Systems Manager Chapter 2. Writing a problem request processor 23

38 resource key items (physical resource CID, physical resource ID and, optionally, resource name) to return the problems from the problem management application. To exclude closed problems from this query, your request processor must generate the necessary search arguments. If the problem management application does not return any problems for the requested resource, your request processor should return a nonzero return code and a message indicating that the query was successful but that no problems were found. This request does not proide alues in the REQUEST_USER_ID and REQUEST_PASSWORD name-alue pairs (used to access the problem management application) because it is issued before the console interface is displayed. If the problem management application requires a user ID and password, your request processor must proide these alues. The following example shows REQUEST_QUERY for problems with REQUEST_QUERY_TYPE of INITIAL: REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_QUERY REQUEST_QUERY_TYPE 1 1 REQUEST_INITIAL The following example shows output that returned problems from the problem management application: REQUEST_RETURN_CODE REQUEST_ERR_MESSAGE 1 1 Query request was successful The following example shows output that did not return problems from the problem management application: REQUEST_RETURN_CODE REQUEST_ERR_MESSAGE 1 1 No problems found for initial display Request query with request adhoc REQUEST_QUERY is a request to the problem management application for perform a query/search for problems opened by the console for a particular resource. The REQUEST_ADHOC request is generated when a user enters arious data items in the console search and clicks the SEARCH button. The REQUEST_QUERY_TYPE name-alue pair always accompanies the REQUEST_QUERY to indicate the type of query requested. If the REQUEST_METHOD is REQUEST_QUERY and REQUEST_QUERY_TYPE is REQUEST_ADHOC, your request processor should format a search argument using the Tioli Business Systems Manager resource key items (physical resource CID, physical resource ID and, optionally, resource name) plus any name-alue pairs containing alues entered by the user, and then return the problems that match this search argument. If the problem management application does not return any problems for the search argument presented, your request processor should return a nonzero return code and a message indicating the query was successful but that no problems were found. This request does proide alues in the REQUEST_USER_ID and REQUEST_PASSWORD name-alue pairs if they are populated with the enumeration request, and should be used to access the problem management application. 24 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

39 The following example shows REQUEST_QUERY for problems with REQUEST_QUERY_TYPE of INITIAL: REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_QUERY REQUEST_QUERY_TYPE 1 1 REQUEST_INITIAL The following example shows output that returned problems from the problem management application: REQUEST_RETURN_CODE 1 1 0REQUEST_ERR_MESSAGE 1 1 Query request was successful The following example shows output that did not return problems from the application: REQUEST_RETURN_CODE REQUEST_ERR_MESSAGE 1 1 No problems found for this search request Request find REQUEST_FIND is a request to FIND/RETRIEVE/GET a specific problem from the problem management application. The only data items needed for this request are REQUEST_PROBLEM_ID and the Tioli Business Systems Manager resource key items (physical resource CID, physical resource ID and, optionally, resource name). REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_FIND REQUEST_OBJECT_CID 1 1 LOB REQUEST_OBJECT_ID REQUEST_OBJECT_SOURCE_CID 1 1 CICS REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 resource_name_alue REQUEST_SYSTEM 1 1 TBSM REQUEST_COMPONENT 1 1 IMS REQUEST_ITEM REQUEST_MODULE 1 1 IMS0DLI REQUEST_PROBLEM_ID 1 1 alue Request add REQUEST_ADD is a request to ADD/CREATE/INSERT a new problem in the problem management application database. All data entry name-alue pairs should be included with or without a alue. Additionally, include some combination of the Tioli Business Systems Manager resource key items (physical resource CID, physical resource ID and, optionally, resource name); this associates the problem ticket in the problem management application database with the resource stored in Tioli Business Systems Manager. This also enables your request processor to include the Tioli Business Systems Manager resource key in searches updates, and other functions to ensure that the appropriate problems are being processed or displayed. REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_ADD REQUEST_OBJECT_CID 1 1 LOB REQUEST_OBJECT_ID REQUEST_OBJECT_SOURCE_CID 1 1 CICS REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 IMS0DLI REQUEST_SYSTEM 1 1 TBSM REQUEST_COMPONENT 1 1 IMS REQUEST_ITEM REQUEST_MODULE 1 1 IMS0DLI Chapter 2. Writing a problem request processor 25

40 Request update REQUEST_UPDATE is a request to update or change an existing problem in the problem management application database. All data entry name-alue pairs should be included, een if they do not hae a alue present. The REQUEST_PROBLEM_ID name-alue pair contains the problem number to be updated. REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_UPDATE REQUEST_OBJECT_CID 1 1 LOB REQUEST_OBJECT_ID 1 1 4> REQUEST_OBJECT_SOURCE_CID 1 1 CICS REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 IMS0DLI REQUEST_SYSTEM 1 1 TBSM REQUEST_COMPONENT 1 1 IMS REQUEST_ITEM REQUEST_MODULE 1 1 IMS0DLI REQUEST_PROBLEM_ID 1 1 alue Request update with request auto close A REQUEST_METHOD of REQUEST_UPDATE with a name-alue pair of REQUEST_AUTO_CLOSE 1 1 YES indicates that a note has been closed and that the problem ticket should also be closed. Your request processor should process this request as a typical update request but might need to add additional data that is not proided with the console, such as Date Closed, and so on. See Problem close for more information about problem closure. The following example GUID.in file shows this request: REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_UPDATE REQUEST_OBJECT_CID 1 1 LOB REQUEST_OBJECT_ID 1 1 4> REQUEST_OBJECT_SOURCE_CID 1 1 CICS REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 IMS0DLI REQUEST_SYSTEM 1 1 TBSM REQUEST_COMPONENT 1 1 IMS REQUEST_ITEM REQUEST_MODULE 1 1 IMS0DLI REQUEST_PROBLEM_ID 1 1 alue REQUEST_STATUS_CODE 1! CLOSED REQUEST_AUTO_CLOSE 1! YES Problem close When a request processor receies a request to close a problem, consider the following items: The problem ticket in the problem management application must be updated with the appropriate close alues. Some problem management applications require additional information or processing when a problem, which must be proided by your request processor. For example, to properly close a problem within the problem management application database, the problem management application might require data such as Date Closed or it might require special API calls in addition to the update. The Problem Close request is identified by the name-alue pair REQUEST_CLOSE 1 1 YES. 26 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

41 The request processor must proide a special call to the Tioli Business Systems Manager IntEentSerer process to properly close the associated note within Tioli Business Systems Manager. See Problem integration eent notification for more details. If you hae actiated the DISPLAY_PROBLEM_CLOSURE option in your SystemConfiguration table, see Display problem closure on page 70. Sample GUID.in file: REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_UPDATE REQUEST_OBJECT_SOURCE_CID 1 1 CICS REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_CID 1 1 LOB REQUEST_OBJECT_ID REQUEST_OBJECT_NAME 1 1 IMS0DLI REQUEST_SYSTEM 1 1 TBSM REQUEST_COMPONENT 1 1 IMS REQUEST_ITEM REQUEST_MODULE 1 1 IMS0DLI REQUEST_PROBLEM_ID 1 1 alue REQUEST_STATUS_CODE 1 1 CLOSED REQUEST_CLOSE 1 1 YES Problem integration eent notification Integration with outside products requires that a system or systems be notified when certain eents or actions occur, for example, to notify an application when a problem ticket is closed or completed. Tioli Business Systems Manager supports notification using a Windows executable file called IntEentSerer, which has a command line interface. The IntEentSerer executable file resides in the Program Files\Tioli\tbsm\Data directory. IntEentSerer has the following syntax: IntEentSerer -s integration_eent_system_name -t integration_eent_request_type -e integration_eent_method -f integration_eent_foreign_key -m integration_eent_message where: integration_eent_system_name The name of the system or application that generated the eent, for example, TSD390, REMEDY, or PEREGRINE. integration_eent_request_type The type of eent to process, such as EVENT_PROBLEM. integration_eent_method The type of processing to perform, such as PROBLEM_CLOSE. This integration eent method is used to determine what action to perform within the Tioli Business Systems Manager. For example, if the integration eent method is PROBLEM_CLOSED, Tioli Business Systems Manager performs post-request close logic on a resource to close the associated note. Because eery integrated system can be different, these integration eent methods are handled on a product-by-product basis. Note: Only the PROBLEM_CLOSE method is currently supported. Chapter 2. Writing a problem request processor 27

42 integration_eent_foreign_key The unique alue that identifies the problem ticket in your problem management application database, for example, the problem ticket ID or number. integration_eent_message A custom message from the source process that describes the eent. The following example shows sending an eent to indicate that a problem ticket has been closed. In this command, do not modify the -stsd390, -tevent_problem, and -eproblem_closed parameters. The problem ticket number in parameter fxxxxxxxx (where xxxxxxxx is the problem ticket ID) is used to find the appropriate ownership or problem note and the note status is set to closed within Tioli Business Systems Manager. Call IntEentSerer -stsd390 -tevent_problem...-eproblem_closed -f mproblem Ticket Has Been Closed. Updating multiline text boxes The console proides a number of multiline text boxes. For these types of data fields is that some problem management applications allow updates to existing text data and others proide only for appending or adding to existing text. To accommodate this difference, two multiline text boxes are proided for each multiline text box field. One is for read-only text and is identified with a name-alue pair suffix of _VIEW; the other is for text that can be updated and is identified with a name-alue pair suffix of _EDIT. The multiline text data displayed by the _VIEW name-alue pairs is read-only and cannot be updated. The multiline text data displayed by the _EDIT name-alue pairs can be updated and new text data can be added. Your request processor must determine how to populate these name-alue pairs based on your problem management application. If the problem management application allows updating of existing multiline text data, your request processor should return all text data in the name-alue pairs with a suffix of _EDIT. Optionally, it can also return the same data in the name-alue pairs with a suffix of _VIEW for display only. If the problem management application does not allow updating of existing multiline text data, your request processor should return all text data only in the _VIEW name-alue pairs, and no data should be returned in the _EDIT name-alue pairs. This means that the user is restricted to appending or adding text data in the multiline text boxes that can be updated. The following examples show these name-alue pairs: REQUEST_LONG_DESCRIPTION_VIEW 1 2 text_line_1 REQUEST_LONG_DESCRIPTION_VIEW 2 2 text_line_2 REQUEST_LONG_DESCRIPTION_EDIT 1 2 text_line_1 REQUEST_LONG_DESCRIPTION_EDIT 1 2 text_line_2 Required data fields Most problem management applications hae required data fields or you might hae customized the problem management application to require certain data fields or to limit field lengths. These data fields are usually required when creating or closing a problem ticket. 28 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

43 The console does not check for required data fields or data length restrictions. Your request processor must check for any required data fields or data length restrictions and return an appropriate error message when a required data field alue is not present or the data entered exceeds the maximum length allowed. The deeloper of your request processor must decide whether to return a single message identifying all required data fields with missing alues and incorrect field lengths or to return an indiidual error message for each field error. An example of a missing required data field follows: REQUEST_RETURN_CODE /*nonzero return code*/ REQUEST_ERROR_MSG 1 1 Status Code missing /* Required for new problem*/ Prepopulating console problem ticket fields Your request processor can prepopulate any or all of the console problem ticket fields. This function is actiated for the take ownership of eent process if the Create problem ticket check box is selected to call the problem ticket create interface. The prepopulate function is not aailable when the user clicks Problem Tickets > Create on a business system resource or a physical resource. Additionally, new name-alue pairs containing eent data are passed to your request processor. Optionally, the request processor can interrogate the eent data to populate certain problem ticket interface fields. For example, the eent description might be used to prepopulate the Problem Ticket description field, or the eent seerity alues or eent priority alues, or both, might be used to prepopulate the Problem Ticket seerity field. The request processor might also prepopulate certain fields in the problem ticket interface that contain standard alues when creating a problem ticket. For example, a alue of Open can be used to prepopulate the Problem Ticket Status Code field in the interface. The prepopulation function occurs when the Take Ownership process calls the Problem Ticket Create function. Prepopulation alues are formatted into name-alue pairs and returned in the GUID.out file to prepopulate problem ticket fields. The prepopulation function is aailable to the request processor when the REQUEST_METHOD 1 1 REQUEST_INITIALIZE request is passed to your request processor in the GUID.in file. The REQUEST_INITIALIZE request is passed to the request processor prior to displaying the Problem Ticket Create interface to the user. When the REQUEST_INITIALIZE request is sent to your request processor, it contains the following additional name-alue pairs in the GUID.in file: REQUEST_NOTE_ID Ownership note ID alue. This alue is used internally to collect the eent data from the database. REQUEST_TOTAL_EVENT_COUNT Count of eents selected during Take Ownership processing The REQUEST_INITIALIZE request also contains eent information. If seeral eents are selected in the take ownership process, the eent data passed to the request processor is selected from the eent that has the highest seerity (alert_state) and highest priority and, if seeral eents hae the same seerity and priority, the oldest age. The GUID.in file contains these eent name-alue pairs: Chapter 2. Writing a problem request processor 29

44 REQUEST_EVENT_CID 1 1 alue REQUEST_EVENT_ID 1 1 alue REQUEST_EVENT_NAME 1 1 alue REQUEST_EVENT_PRIORITY 1 1 alue REQUEST_EVENT_ALERT_STATE 1 1 alue REQUEST_EVENT_DETAIL 1 1 alue Your request processor might use the alues from the REQUEST_EVENT name-alue pairs to determine which alues are to be returned for prepopulating some problem ticket data fields or might return other default alues to prepopulate other data fields in the problem ticket interface. An example for eent data might be to return the eent description to prepopulate the problem ticket description or return a default alue of Open to prepopulate the Status Code field. The name-alue pairs listed preiously are also sent to your request processor when REQUEST_METHOD 1 1 REQUEST_ADD is passed containing the data for the actual creation of the problem ticket by your request processor in your problem management application. Your request processor can use these alues howeer you deem necessary to prepopulate certain problem ticket fields and to populate certain fields in the problem ticket stored in your problem management database. If you do not use the prepopulate interface function, you can ignore the REQUEST_EVENT name-alue pairs; your current processing is not affected. The request processor should be coded to read all name-alue pairs in the GUID.in file and check in the name-alue pairs for the names that are needed to process problem ticket functions. When a name matches, sae the alue for formatting and running the integration facility proided by your problem management application. All other name-alue pairs should be bypassed by getting the next name-alue pair record in the GUID.in file. The following examples show the GUID.in and GUID.out files for the REQUEST_INITIALIZE request initiated by the problem ticket create interface. The GUID.in file example shows the data fields passed to your request processor for consideration in prepopulating the Problem Ticket create data fields: REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_INITIALIZE REQUEST_CONSOLE_VERSION 1 1 V21 REQUEST_OBJECT_CID 1 1 CIPX REQUEST_OBJECT_ID REQUEST_OBJECT_SOURCE_CID 1 1 CIPX REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 plex01 REQUEST_LOGIN_USER_ID 1 1 admin REQUEST_LOGIN_USER_PASSWORD 1 1 IQm4idDI+wE= REQUEST_CUSTOMER_ID 1 1 TBSM AUTO_CLOSE_DEFAULT 1 1 YES DEBUG_MODE 1 1 ON DISPLAY_PROBLEM_CLOSURE 1 1 YES TIMEOUT_VALUE TICKET_CREATE_DEFAULT 1 1 YES REQUEST_USER_ID 1 1 REQUEST_PASSWORD 1 1 REQUEST_ORIGIN_SYSTEM 1 1 TBSM REQUEST_ORIGIN_COMPONENT 1 1 LOB REQUEST_ORIGIN_ITEM REQUEST_ORIGIN_MODULE 1 1 plex01 REQUEST_NOTE_ID 1 1 alue REQUEST_TOTAL_EVENT_COUNT 1 1 alue 30 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

45 REQUEST_EVENT_CID 1 1 alue REQUEST_EVENT_ID 1 1 alue REQUEST_EVENT_NAME 1 1 alue REQUEST_EVENT_PRIORITY 1 1 alue REQUEST_EVENT_ALERT_STATE 1 1 alue REQUEST_EVENT_DETAIL 1 1 alue This GUID.out file example shows optional fields that can be used to prepopulate problem ticket fields: Assignee Group, Assignee Name, Status Code, Seerity and Short Description data fields. You to not hae to return a name-alue pair for eery field that is aailable for prepopulation. Return only the name-alue pairs you want to prepopulate with alues in the problem ticket fields. REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 Request Initialize was successful REQUEST_CUSTOMER_ID 1 1 alue ORIGIN_COMPONENT 1 1 alue ORIGIN_ITEM 1 1 alue ORIGIN_MODULE 1 1 alue ORIGIN_SYSTEM 1 1 alue PROBLEM_OPEN_VALUES 1 1 alue1,alue2 PROBLEM_CLOSE_VALUES 1 1 alue1,alue2 REQUEST_PROBLEM_TYPE 1 1 alue REQUEST_ASSIGNEE_GROUP 1 1 alue REQUEST_ASSIGNEE_NAME 1 1 alue REQUEST_STATUS_CODE 1 1 alue REQUEST_SEVERITY 1 1 alue REQUEST_SHORT_DESCRIPTION 1 1 alue The following example GUID.in file shows the eent name-alue pairs that are passed to your request processor in the REQUEST_METHOD 1 1 REQUEST_ADD request: REQUEST_TYPE 1 1 REQUEST_PROBLEM REQUEST_METHOD 1 1 REQUEST_ADD REQUEST_CONSOLE_VERSION 1 1 V21 REQUEST_OBJECT_CID 1 1 CIPX REQUEST_OBJECT_ID REQUEST_OBJECT_SOURCE_CID 1 1 CIPX REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 plex01 REQUEST_USER_ID 1 1 JOHN REQUEST_PASSWORD 1 1 TBSM REQUEST_LOGIN_USER_ID 1 1 admin REQUEST_LOGIN_USER_PASSWORD 1 1 IQm4idDI+wE= REQUEST_CUSTOMER_ID 1 1 TBSM REQUEST_SYSTEM 1 1 TBSM REQUEST_COMPONENT 1 1 LOB REQUEST_ITEM REQUEST_MODULE 1 1 plex01 REQUEST_ORIGIN_SYSTEM 1 1 TBSM REQUEST_ORIGIN_COMPONENT 1 1 LOB REQUEST_ORIGIN_ITEM REQUEST_ORIGIN_MODULE 1 1 plex01 REQUEST_PROBLEM_ID 1 1 REQUEST_PROBLEM_TYPE 1 1 REQUEST_STATUS_CODE 1 1 INITIAL REQUEST_SEVERITY REQUEST_ASSIGNEE_GROUP 1 1 alue REQUEST_ASSIGNEE_NAME 1 1 REQUEST_DATE_CREATED REQUEST_DATE_UPDATED REQUEST_SHORT_DESCRIPTION 1 1 test REQUEST_LONG_DESCRIPTION_EDIT 1 1 alue REQUEST_LONG_DESCRIPTION_VIEW 1 1 REQUEST_CLOSURE_STATUS 1 1 Chapter 2. Writing a problem request processor 31

46 REQUEST_RESOLUTION_CODE 1 1 REQUEST_DATA_UPDATED_FLAG 1 1 REQUEST_ACTIONS_COMPLETED_FLAG 1 1 REQUEST_EFFORT 1 1 REQUEST_RESOLUTION_EDIT 1 1 REQUEST_RESOLUTION_VIEW 1 1 REQUEST_ROOT_CAUSE_EDIT 1 1 REQUEST_ROOT_CAUSE_VIEW 1 1 REQUEST_ROOT_CAUSE 1 1 REQUEST_FURTHER_ACTIONS_REQUIRED_EDIT 1 1 REQUEST_FURTHER_ACTIONS_REQUIRED_VIEW 1 1 REQUEST_CLOSE 1 1 NO REQUEST_AUTO_CLOSE 1 1 NO AUTO_CLOSE_DEFAULT 1 1 YESDEBUG_MODE 1 1 ON DISPLAY_PROBLEM_CLOSURE 1 1 YES TIMEOUT_VALUE TICKET_CREATE_DEFAULT 1 1 YES REQUEST_NOTE_ID 1 1 alue REQUEST_EVENT_CID 1 1 alue REQUEST_EVENT_ID 1 1 alue REQUEST_EVENT_NAME 1 1 alue REQUEST_EVENT_PRIORITY 1 1 alue REQUEST_EVENT_ALERT_STATE 1 1 alue REQUEST_EVENT_DETAIL 1 1 alue Suppress display of the OK message box When a problem ticket is created or updated using the problem ticket interface, a message box is displayed containing the problem ID and a message to indicate that the problem ticket was created successfully. If the acknowledgement of the problem ID and successful message notification is not useful to the user, the message box can be suppressed. That means that, if the problem ticket is created successfully, no message box is displayed and the problem ticket interface ends without any notification to the user. Howeer, if an error occurs in processing the problem ticket, a message box with an error message is displayed. Use the console preference option to suppress the OK message box for a successful problem ticket create and update; for more information, use the Task Assistant for the console. Problem ticket ID in the eent iewer The problem ticket ID can be displayed in the Eent Viewer to notify the operator that a problem ticket has been opened for the corresponding eent. To actiate this function, run the following SQL statements in a Query Analyzer window: INSERT INTO SystemConfiguration VALUES ( Feature, Problem Ticket ColumnInEentView, 1, INT ) UPDATE MenuItemVersion SET erno = erno + 1 After running these statements, cycle the Console Serer task in TBSM Serices. You can also actiate this function by setting a console preference; for more information, use the Task Assistant for the console. 32 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

47 Chapter 3. Writing a change request processor This chapter describes how to write a change request processor. What is a change request processor? A change request processor is any request processor that you write that can process command line input parameters, read a text-based input file containing the data passed from the integration function, and create a text-based output file with the results receied from the change management application. A change request processor is called by the Tioli Business Systems Manager change integration function. Change integration function flow These steps show flow for the change integration function: 1. The user selects a change function from the console, specifies the data needed, and clicks OK to start the integration function. The change functions are Create, Find, Properties, Update, and Search. 2. The Tioli Business Systems Manager integration function creates an input file containing the request data and calls your request processor, which is defined in the Tioli Business Systems Manager SystemConfiguration table. The integration function passes the name of the input file and the path where the input file resides to your request processor. 3. Your request processor reads the input file to gather the data to be formatted, and then makes the appropriate API or interface calls to the change management application. 4. Your request processor receies the results from the API or interface call to the change management application, formats an output file, and returns control to the Tioli Business Systems Manager integration function. 5. The integration function gathers the output results from the output file and returns them to the console for display. Configuration of change integration function To actiate the change integration function, define your request processor in the SystemConfiguration table, using the following alues: SystemConfiguration column name groupname propertyname propertyalue propertydatatype Value REQUEST_CHANGE REQUEST_PROCESSOR_NAME request_processor_name CHAR Define your request processor in one of the following ways: If your request processor is a Windows standard executable file, run the following SQL statements, where change.exe is the name of your request processor: Copyright IBM Corp

48 INSERT INTO SystemConfiguration VALUES ("REQUEST_CHANGE","REQUEST_PROCESSOR_NAME","change.exe","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 If your request processor is a Windows nonstandard executable file, run the following SQL statement, where change.rex is the name of your request processor and language_type defines the language type (for example, REXX.exe or KSH.exe): INSERT INTO SystemConfiguration VALUES ("REQUEST_CHANGE","REQUEST_PROCESSOR_NAME","change.rex,"CHAR") INSERT INTO SystemConfiguration VALUES ("REQUEST_CHANGE","REQUEST_PROCESSOR_LANGUAGE","language_type","CHAR" ) UPDATE MenuItemVersion SET erno = erno + 1 Requirements for change request processors This section presents the minimal requirements for creating a request processor that receies input from the Tioli Business Systems Manager change interface on the console. You are responsible for integrating your request processor with your change management application. Integration can be implemented in arious ways, depending on the programming language, the platform, and the supported integration facilities. Also, each implementation of a request processor needs to be analyzed to determine the best way to interface with the change management application based on your specific requirements. Input and output files Your change request processor must read the input file and create the output file. A new input file is created for each request made from the console. The Tioli Business Systems Manager change integration function calls your request processor using the GUID and InFilePath parameters. An output file is created for each specific request and contains the formatted results of the request returned from your change management application. For more information about input files and calling your request processor, see Input files on page 5. For more information about output files, see Output files on page 6. Console change function Users can interact with a change management application by using the following console functions: Create Change request, using data elements to create a change request Find Change requests, using data elements to search for change requests Change request Properties (General), using data elements for updating general information in a change request Change request Properties (Closure), using data elements for updating closure information in a change request Access Information, specifying user ID and password for the change management application Note: You can customize the console to change field labels or hide fields, or both, to match your change management application and the fields it supports. For more information, see Customizing console fields on page IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

49 Console request processing The following console functions are needed to support change request processing: User ID processing Receiing and Returning Enumeration alues for change requests Create a change request Initial Query of Change requests Find a Change request Update a Change request Adhoc Query of Change requests Each console function sends a request to the request processor. A different GUID.in file is created for each request, in the following way: 1. The console sends a request to return user IDs and passwords that are alid for the change management application. 2. The console sends a series of enumeration requests to your request processor to obtain alues from the change management application to use in populating the drop-down lists in the console. The number of enumeration requests aries depending on how the console is customized to meet the needs of your change management application. The default alue is 4 enumeration request methods. 3. After the data is specified and the user clicks OK, a request is sent to the request processor to create, query, update, or find change requests. Your request processor must proide a response to console request by creating a GUID.out file containing, at a minimum, the REQUEST_RETURN_CODE and REQUEST_ERROR_MSG name-alue pairs. User IDs Many change management application integration facilities require a alid user ID and password to establish a connection or session before any functions can be performed, such as create, search/query, retriee/find, and update. This means the request processor needs access to a alid user ID and password to establish a session or access the change management application database. The user ID is also used to stamp the change request with the user ID that created or last updated a change request. Two user ID and password name-alue pairs hae different functions: One set contains the Tioli Business Systems Manager login user ID and password: REQUEST_LOGIN_USER_ID REQUEST_LOGIN_USER_PASSWORD If these alues represent a alid user ID and password defined in the change management application, they can be used for access to the change management application database. The other set contains a alid user ID and password for the change management application: REQUEST_USER_ID REQUEST_PASSWORD Chapter 3. Writing a change request processor 35

50 The console change request process sends enumeration requests to the request processor before displaying the interface to the user. The purpose is to obtain alid alues for populating the drop-down lists, such as user ID, status code, and change category. GUID.in file user ID enumeration request: REQUEST_METHOD 1 1 REQUEST_GET_UIDS REQUEST_ENUM_NAME 1 1 REQUEST_GET_UIDS GUID.in file name-alue pairs for other enumeration requests (default change enumerations): REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_STATUS_CODE REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_COMPLEXITY REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_IMPACT REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_REASON REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_SITE REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_CATEGORY REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_REQUESTOR_DEPT REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_REQUESTOR_NAME Notes: 1. Eery REQUEST_ENUM_NAME is a separate request from the console to the request processor. 2. If the console change labels are modified, the corresponding request_enum_name fields reflect different alues to populate the corresponding change interface labeled field. These enumeration requests present a special consideration for the request processor because, at this point, alid user ID and password alues are not aailable. Therefore, the request processor must hae access to a alid user ID and password to perform the enumeration requests against the change management application, if that is a requirement. Depending on the change management application and the enironment, this can be accomplished in arious ways. One way is to code the user ID and password in the request processor. Another is for the request processor to access an external file to obtain the user ID and password. In any eent, this is a decision that you need to make. After the enumeration requests are populated, the request processor can use the user ID and password that were entered in the console and were passed as REQUEST_USER_ID and REQUEST_PASSWORD to identify the user that created or updated a change request. One exception is when you synchronize the Tioli Business Systems Manager login user IDs and passwords with your change 36 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

51 management application. In that case, REQUEST_LOGIN_UID and REQUEST_LOGIN_PASSWORD can be used to access the change management application. Text field size restriction The maximum size for any field in the GUID.out file is 254 characters. This is due to a restriction in the Microsoft SQL Serer product. If you return a field with text longer than 254 characters, the Tioli Business Systems Manager integration function truncates it to 254 characters prior to displaying it in the change request interface. Enumeration requests Users can select a alue from a list of predefined alues in the arious drop-down list fields in the change request console interface. You can use different sets of alues to meet your specific needs. Because of that, the console drop-down lists are not prepopulated. The change integration function enables your request processor to dynamically populate the change request drop-down lists in the console. The alues should match the list alues that are contained in your change management application. Receiing enumeration requests The console and Tioli Business Systems Manager integration function send a series of enumeration requests to the request processor, before making the console interface aailable to the user. The enumeration requests are used to populate drop-down lists and proide dependency alue lists. The enumeration alues should represent the same alues that are aailable in the change management application. Different installations require different customization. Some information might be aailable directly from the change management application; other information might need to be obtained from other sources, such as an external file. That depends on the setup of your change management application. These alues can ary from one change management application to another, depending on your installation. If the alues for the enumerations are to be returned from the change management application, each interface is different. For example, some might proide special API calls, others might proide query and search facilities, and still others might proide some, but not all, of the enumeration alues that are needed; in that case, they must be coded in your request processor or obtained from an external file that is read by your request processor. Your request processor must respond to each enumeration request by creating a GUID.out file, een if a particular drop-down list has no alues to return. That can occur if a drop-down list has been hidden with the console customization tool. The enumeration requests proided do not apply to a specific change management application. In other words, the default drop-down list can be changed (with the console customization tool) to a different type of drop-down list with labels and alues based on a specific change management application. The GUID.out file must contain at least a return code of 0 and an error message. This is required een if the enumeration is not needed for display at the console. All enumeration requests hae the following name-alue pairs: REQUEST_METHOD 1 1REQUEST_ENUM, which identifies it is an enumeration request to populate a drop-down list in the interface. Chapter 3. Writing a change request processor 37

52 REQUEST_ENUM_NAME 1 1 enumeration_alue_type, which identifies the types of enumeration alues that are being requested. The enumeration alue type proided in the REQUEST_ENUM_NAME matches the console change field labels proided with Tioli Business Systems Manager; howeer, it might not match the console field label if it has been changed with the console customization tool. As described Customizing console fields on page 75, the console field labels can be changed to represent a different alue or data field. If the console field labels associated with drop-down lists are changed to represent another alue type, the name-alue pairs remain the same. Howeer, your request processor should proide the appropriate alues to match the console change field label that has been changed. The following original enumeration alue types are proided for change requests. Respectiely, these alues are for change status, complexity of change, impact of change, reason for change, site or location for change, change category, department, and requestor name. If the console labels are modified, the corresponding REQUEST_ENUM_NAME statement might reflect different alues to populate the corresponding labeled field in the console interface. REQUEST_ENUM_NAME 1 1 REQUEST_STATUS_CODE REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_COMPLEXITY REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_IMPACT REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_REASON REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_SITE REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_CATEGORY REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_REQUESTOR_DEPT REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_REQUESTOR_NAME Returning enumeration request alues A GUID.out file must be created for each enumeration request receied in a GUID.in file. Enumeration request without alues to return: Your request processor must respond to eery enumeration request, een if the console drop-down list is not being used for a specific change management application integration. This typically occurs if a console field was hidden because it is not needed for integration with your change management application. For example, suppose the console sends the following request for category alues: REQUEST_TYPE 1 1 REQUEST_ CHANGE REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_CATEGORY No enumeration alues are needed for this field because it has been hidden; your request processor must create a GUID.out file with the following name-alue pairs: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 enumeration request was successful After creating the file, your request processor should exit and return control to the Tioli Business Systems Manager integration function. The integration function processes the file and returns the results to the console. Because no alues are returned, the console does not try to populate the Change Category field drop-down list. 38 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

53 Enumeration request with alues to return: When the enumeration alues in a console field must be populated, your request processor should create a GUID.out with the appropriate alues: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 enumeration request was successful REQUEST_ENUM_VALUE 1 1 alue_1 REQUEST_ENUM_VALUE 1 1 alue_2 For example, suppose, the console sends a request for Change Status Code alues: REQUEST_TYPE 1 1 REQUEST_ CHANGE REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_STATUS_CODE That request might return the following alues: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 enumeration request was successful REQUEST_ENUM_VALUE 1 1 INITIAL REQUEST_ENUM_VALUE 1 1 OPEN REQUEST_ENUM_VALUE 1 1 CLOSED After creating the file, your request processor should exit and return to the Tioli Business Systems Manager integration function. The integration function processes the file and returns the results to the console to populate the Change Status Code drop-down list with the alues of INITIAL, OPEN, and CLOSED for the user selection. Examples for each enumeration request are proided in Appendix C, Example input and output files, on page 107. Returning enumeration list dependency filters Some change management applications hae drop-down lists that display alues based on the current alue of another list, for example, listing only the Site alue of Site Code 3 when a Category of Category Code 2 has been selected. This function is supported and the request processor must proide the dependency filters. As indiidual enumerated alues are returned to the console, they contain simple filtering information that can be applied to dependent drop-down lists. This filtering information consists of the target enumeration group name to which the filter applies and a list of alid alues. For example, if the name of the Change Category enumeration is REQUEST_CHANGE_CATEGORY and the name of the Change Site group is REQUEST_CHANGE_SITE, the input and output files are shown in the following list: The GUID.in file for Change Category has the following name-alue pairs: REQUEST_TYPE 1 1 REQUEST_CHANGE REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_CATEGORY The GUID.out file for Change Category has the following name-alue pairs: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 Enumeration request was successful REQUEST_ENUM_VALUE 1 1 Category Code 1 REQUEST_ENUM_VALUE 1 1 Category Code 2 REQUEST_ENUM_VALUE 1 1 Category Code 3 The GUID.in file for Change Site has the following name-alue pairs: Chapter 3. Writing a change request processor 39

54 REQUEST_TYPE 1 1 REQUEST_CHANGE REQUEST_METHOD 1 1 REQUEST_ENUM REQUEST_ENUM_NAME 1 1 REQUEST_CHANGE_SITE The GUID.out file for Change Site has the following name-alue pairs: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 Enumeration request was successful REQUEST_ENUM_VALUE 1 1 Site Code 1 REQUEST_ENUM_VALUE 1 1 Site Code 2 REQUEST_ENUM_VALUE 1 1 Category Code 2,REQUEST_CHANGE_CATEGORY,Site Code 3 The last line of the sample GUID.out file indicates that, when the current alue of the Change Category drop-down list is Category Code 2, the only alid alue for the Change Site drop-down list is Site Code 3. If seeral alues are alid, they must be separated by commas, and the GUID.out file for Change Site has the following name-alue pairs: REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 Enumeration request was successful REQUEST_ENUM_VALUE 1 1 Site Code 1 REQUEST_ENUM_VALUE 1 1 Site Code 2 REQUEST_ENUM_VALUE 1 1 Category Code 2,REQUEST_CHANGE_CATEGORY,Site Code 3 REQUEST_ENUM_VALUE 1 1 Category Code 2,REQUEST_CHANGE_CATEGORY,Site Code 4 The last 2 lines of this GUID.out file indicate that, when the current alue of the Change Category drop-down list is Category Code 2, the alid alues for the Change Site drop-down list are Site Code 3 and Site Code 4. If the current alue of the Change Category drop-down list is Category Code 1 or Category Code 3, the alid alues for the Change Site drop-down list are Site Code 1, Site Code 2, Site Code 3, and Site Code 4. In other words, these alues hae no dependencies. Your request processor deeloper must implement the dependency rules and build the GUID.out files to reflect these rules. If no rules exist, the drop-down lists contain whateer alues were originally loaded into them. The enumeration list dependency filters do not support the following uses: Any combining of rules (by using and or or). An example of using and is to restrict list A to the alues A, B, and C when list B is X and list C is Y. Reselection alues. Using the preious example, suppose that the user selects Category Code 1 from the Change Category drop-down list and selects Site Code 1 from the Change Site drop-down list. If the user returns to the Change Category drop-down list and re-selects Category Code 2 from the Change Category drop-down list, the user is not notified by the console that Site Code 1 (originally selected) is not a alid selection for Change Site in conjunction with a Change Category alue of Category Code 2. Your request processor must alidate the combinations selected by a user and, if any combinations are not alid, return an error. Date formats The Tioli Business Systems Manager integration function supports only one format for passing dates between the console and the request processor. 40 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

55 The date format supported is the year, the month, the day, a blank space, hour, minutes, and seconds, as shown here: yyyymmdd hhmmss Note: If the application does not support seconds in dates, the request processor should proide zeros in the dates, as shown here: yyyymmdd hhmm00 The console reformats the dates for display as shown here: mm/dd/yyyy hh:m:ss Identifying changes in a change management application A Tioli Business Systems Manager physical resource key must be stored in a change that is created in the change management application. The physical resource key enables the change find/query function within Tioli Business Systems Manager to retriee changes from the change management application and to display them within the console. By always storing the physical resource key, changes can be retrieed for iewing or update purposes, regardless of whether they were created from a business impact resource or a physical resource. The request processor should include the physical resource CID and physical resource ID in a change request when it is created using the console. This enables the console to retriee change requests for a specific Tioli Business Systems Manager resource when using the find/query function within the console. The source CID and source ID for a Tioli Business Systems Manager resource is always passed to the request processor in the following name-alue pairs: REQUEST_OBJECT_SOURCE_CID 1 1 source_class_id_alue REQUEST_OBJECT_SOURCE_ID 1 1 source_id_alue Optionally, the Tioli Business Systems Manager resource name can be stored with a change request creation. The resource name should not be stored as the only key for a resource because more than one resource can hae the same name. The name of a Tioli Business Systems Manager resource is always passed to the request processor in the following name-alue pair: REQUEST_OBJECT_NAME 1 1 resource name Considerations for change request processors This section presents arious suggestions and considerations when creating a request processor that integrates with a change management application. Integration can be implemented in arious ways, depending on the programming language, the platform being used, or both. Each implementation of a request processor needs to be analyzed to determine the best way to interface with the change management application, based on your specific requirements. Consider the following functions: 1. Change management application user ID and password aailability 2. Initial query/search to display changes from the change management application 3. Adhoc query/search generated by the user to display changes from the change management application 4. Specific change location in the change management application 5. Update of a change in the change management application 6. Automatic close of a change in the change management application Chapter 3. Writing a change request processor 41

56 7. Change closure within Tioli Business Systems Manager 8. Required data fields in the change management application 9. Association of changes in the change management application with Tioli Business Systems Manager resources. User ID and password If a user ID and password are required to access your change management application, a few conditions exist under which a user ID and password are not aailable when the console sends a request to your request processor. When the user selects Insert or View from a Tioli Business Systems Manager resource, the console sends the following requests for information to prepare the interface for entry: REQUEST_INITIALIZE REQUEST_QUERY REQUEST_AUTO_CLOSE All enumeration requests Some change management applications require a user ID and password to be passed from the request processor to establish a session and perform database functions, or both. To meet this requirement, your request processor should use a special user ID and password that you proide and that allows these functions to be performed. This special user ID should hae all the authority it needs to perform any function against the change management application database. Note: Password security is the responsibility of your request processor. Loading large olume change enumeration alues To return enumeration alues or drop-down list alues to the Tioli Business Systems Manager integration function, your request processor must either obtain them from the change management application or contain the alues. If you implement a large number of alid alues for certain data fields used for creating or updating change requests, returning these alues from your request processor and formatting them for display at the console can take a fairly long time, een an unacceptably long time, depending on the number of drop-down list alues being returned. In that situation, consider using the table-based enumerations option, which improes the performance of loading large olume enumeration lists considerably. This option requires loading your enumeration alues into a table. A special process calls your request processor to obtain the alues, as described in Returning enumeration request alues on page 38, and no additional modifications to your request processor are needed. To actiate this option and load your enumeration alues into a table, follow these steps: 1. To actiate the facility to load large enumeration lists for change requests: a. Start a Query Analyzer on the SQL Serer and run the following statements: INSERT INTO SystemConfiguration VALUES ( API_INTEGRATION_OPTIONS, TABLE_BASE_ENUMERATIONS, YES, CHAR ) UPDATE MenuItemVersion SET erno = erno + 1 b. Run the following statement in the Query Analyzer to erify that the new row is correct: SELECT * FROM SystemConfiguration WHERE propertyname= TABLE_BASE_ENUMERATIONS 42 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

57 The results window should display the following new row, where xx is the row ID: id groupname propertyname propertyalue propertydatatype xx API_INTEGRATION_OPTIONS TABLE_BASE_ENUMERATIONS YES CHAR 2. To populate the enumerations table, follow these steps: a. Start the SQL serer Enterprise Manager on the SQL Serer. b. Expand SQL Serer Group, expand SQL Serer, expand Management, and expand SQL Serer Agent. c. Click Jobs to display all the Tioli Business Systems Manager jobs. d. Right-click the LoadIntegrationEnumeration job; select properties, click Steps, and then double-click setintegrationenumeration to display the step details. The following statement is displayed: exec asisp_setintegrationenumeration "C" The letter C indicates to load enumeration lists for change requests only. To load enumeration lists for both problem tickets and change requests, change C to PC. To load enumeration lists for problem tickets only, change C to P. e. Click OK twice to end and sae any changes made. f. Right-click the LoadIntegrationEnumeration job again, and click Start Job to run the LoadIntegrationEnumeration job to initially load your alues into the enumeration table. g. Check the Last Run Status column in the LoadIntegrationEnumeration job display. It should display the alue Succeeded. If it indicates Failure, ensure that your request processor is actiated and, if applicable, has a connection to your change management application. h. Right-click the LoadIntegrationEnumeration job again; select properties and then click Schedules. This job is scheduled to run weekly on Sunday to refresh the enumeration alues for any additions or changes. To change this schedule, click Edit, then click Change for Recurring, and specify the schedule you want for this job. i. Click OK until you return to the Jobs display. 3. To erify that your enumeration alues were loaded successfully, return to the Query Analyzer on the SQL Serer and run the following statement: SELECT * FROM IntegrationEnumeration This displays all the alues that were loaded by the LoadIntegrationEnumeration job. Request query with request initialize REQUEST_QUERY is a request to perform a Query/Search on the change management application database for changes that were created by the console for a particular resource. The two types of query requests are initial query requests and adhoc query requests. The REQUEST_QUERY_TYPE name-alue pair always accompanies REQUEST_QUERY to indicate the type of query requested. A REQUEST_QUERY_TYPE alue of INITIAL indicates that your request processor should format a search argument using the Tioli Business Systems Manager resource key items (physical resource CID, physical resource ID, and, optionally, Chapter 3. Writing a change request processor 43

58 resource name) to return the changes from the change management application. To exclude closed changes from this query, your request processor must generate the necessary search arguments. If the change management application does not return any changes for the requested resource, your request processor should return a nonzero return code and a message indicating the query was successful but that no changes were found. This request does not proide alues in the REQUEST_USER_ID and REQUEST_PASSWORD name-alue pairs (used to access the change management application) because it is issued before the console interface is displayed. If the change management application requires a user ID and password, your request processor must proide these alues. The first request sent to a request processor is the REQUEST_INITIALIZE request. This request enables the request processor to define open and close alues used in the change management application. If the change management application supports alues other than Open or Closed to indicate a change request is either actie (in a working state) or inactie (no longer in a working state), the request processor should return these alues in CHANGE_OPEN_VALUES or CHANGE_CLOSE_VALUES. The request processor can oerride the following name-alue pairs: CHANGE_OPEN_VALUES 1 1 alue1,alue2 CHANGE_CLOSE_VALUES 1 1 alue1,alue2 Change open and close alues If your change management application supports alues other than Open or Closed to indicate that a change request is either actie (in a working state) or inactie (no longer in a working state), the request processor should return these alues in CHANGE_OPEN_VALUES or CHANGE_CLOSE_VALUES. These alues are needed to actiate arious processes within the change request functions, such as generating a request for a count of open changes when a change request is closed by a user within Tioli Business Systems Manager. The count is used to determine whether to remoe the change request resource indicator from the resource for which a change request was closed. Examples of actie alues are Open, Initial, Working and Pending. Examples of inactie alues are Closed, Dead, Returned, and Obsolete. The following example shows REQUEST_QUERY for changes with REQUEST_QUERY_TYPE of INITIAL: REQUEST_TYPE 1 1 REQUEST_CHANGE REQUEST_METHOD 1 1 REQUEST_QUERY REQUEST_QUERY_TYPE 1 1 REQUEST_INITIAL The following example shows output that returned changes from the change management application: REQUEST_RETURN_CODE REQUEST_ERR_MESSAGE 1 1 Query request was successful The following example shows output that did not return changes from the change management application: 44 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

59 REQUEST_RETURN_CODE REQUEST_ERR_MESSAGE 1 1 No change found for initial display Request query with request adhoc REQUEST_QUERY is a request to the change management application to perform a Query/Search for changes opened by the console for a particular resource. The REQUEST_ADHOC request is generated when a user enters arious data items in the console search interface and clicks the SEARCH button. The REQUEST_QUERY_TYPE name-alue pair always accompanies the REQUEST_QUERY to indicate which type of query has been requested. If REQUEST_METHOD is REQUEST_QUERY and REQUEST_QUERY_TYPE is REQUEST_ADHOC, your request processor should format a search argument using the Tioli Business Systems Manager resource key items (physical resource CID, physical resource ID, and, optionally, resource name) plus any name-alue pairs containing alues specified by the user, and then return the changes matching this search argument. If the change management application does not return any changes for the search argument presented, your request processor should return a nonzero return code and a message indicating that the query was successful but that no changes were found. This request does proide alues in the REQUEST_USER_ID and REQUEST_ PASSWORD name-alue pairs if they are populated with the enumeration request, and should be used to access the change management application. The following example shows REQUEST_QUERY for changes with REQUEST_QUERY_TYPE of INITIAL REQUEST_TYPE 1 1 REQUEST_CHANGE REQUEST_METHOD 1 1 REQUEST_QUERY REQUEST_QUERY_TYPE 1 1 REQUEST_INITIAL The following example shows output that returned changes from the change management application: REQUEST_RETURN_CODE REQUEST_ERR_MESSAGE 1 1 Query request was successful The following example shows output that did not return changes from the change management application: REQUEST_RETURN_CODE REQUEST_ERR_MESSAGE 1 1 No changes found for this search request Request find REQUEST_FIND is a request to FIND/RETRIEVE/GET a specific change from the change management application. The only data items for this request are the REQUEST_CHANGE_ID and the Tioli Business Systems Manager resource key items (physical resource CID, physical resource ID and, optionally, resource name). REQUEST_TYPE 1 1 REQUEST_CHANGE REQUEST_METHOD 1 1 REQUEST_FIND REQUEST_OBJECT_CID 1 1 physical_resource_cid REQUEST_OBJECT_ID 1 1 physical_resource_id REQUEST_OBJECT_SOURCE_CID 1 1 LOB REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 IMS0DLI REQUEST_CHANGE_ID 1 1 alue Chapter 3. Writing a change request processor 45

60 Request add REQUEST_ADD is a request to ADD/CREATE/INSERT a new change request in the change management application. All data entry name-alue pairs that hae a alue present should be included. Additionally, include some combination of the Tioli Business Systems Manager resource key items (physical resource CID, physical resource ID and, optionally, resource name), if they are stored in the change; this associates the change request with the resource stored in Tioli Business Systems Manager. This also enables your request processor to include the Tioli Business Systems Manager resource key in searches, updates, and other functions to ensure that the appropriate changes are being processed or displayed. REQUEST_TYPE 1 1 REQUEST_CHANGE REQUEST_METHOD 1 1 REQUEST_ADD REQUEST_OBJECT_CID 1 1 LOB REQUEST_OBJECT_ID REQUEST_OBJECT_SOURCE_CID 1 1 IMS REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 IMS0DLI REQUEST_SYSTEM 1 1 TBSM REQUEST_COMPONENT 1 1 IMS REQUEST_ITEM REQUEST_MODULE 1 1 IMS0DLI Request update REQUEST_UPDATE is a request to UPDATE/CHANGE an existing change in the change management application database. All data entry name-alue pairs should be included if they hae an a alue present. The REQUEST_CHANGE_ID name-alue pair contains the change number to be updated. REQUEST_TYPE 1 1 REQUEST_CHANGE REQUEST_METHOD 1 1 REQUEST_UPDATE REQUEST_OBJECT_CID 1 1 LOB REQUEST_OBJECT_ID REQUEST_OBJECT_SOURCE_CID 1 1 IMS REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 IMS0DLI REQUEST_CHANGE_ID 1 1 alue Request update with request close When the request processor receies a request to close a change, consider the following items: The change ticket in the change management application must be updated with the appropriate close alues. Some change management applications require additional information or processing when a change is closed, which must be proided by your request processor. For example, to properly close the change within the change management application database, the change management application might require data such as the Date Closed or it might require special API calls in addition to the update. The Change Close request is identified by a name-alue pair of REQUEST_CLOSE 1 1 YES. The request processor must proide a special call to the Tioli Business Systems Manager IntEentSerer process to properly close the change ticket within Tioli Business Systems Manager. See Change integration eent notification on page 47 for more details. REQUEST_TYPE 1 1 REQUEST_CHANGE REQUEST_METHOD 1 1 REQUEST_UPDATE REQUEST_OBJECT_CID 1 1 LOB REQUEST_OBJECT_ID REQUEST_OBJECT_SOURCE_CID 1 1 IMS 46 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

61 REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 IMS0DLI REQUEST_SYSTEM 1 1 TBSM REQUEST_COMPONENT 1 1 IMS REQUEST_ITEM REQUEST_MODULE 1 1 IMS0DLI REQUEST_CHANGE_ID 1 1 alue REQUEST_STATUS_CODE 1! CLOSED REQUEST_CLOSE 1! YES REQUEST_TYPE 1 1 REQUEST_CHANGE REQUEST_METHOD 1 1 REQUEST_UPDATE REQUEST_CHANGE_ID 1 1 alue REQUEST_STATUS_CODE 1! CLOSED REQUEST_CLOSE 1! YES Change integration eent notification When a change request is created from within Tioli Business Systems Manager, the change request data is passed to the change integration function and your request processor is called to add the change request to your change management application database. When the new change request ID is returned, the change integration function creates a change note with the change request ID. Note: The change note is for IBM use only and is not displayed in the Note and Find options or in the Note iew contained in the resource properties display option. Updating multiline text boxes The console proides a number of multiline text boxes. For these types of data fields, some change management applications allow updates of existing text data and others proide only for appending or adding to existing text. To accommodate this difference, two multiline text boxes are proided for each multiline text box field. One is for read-only text and is identified with a name-alue pair suffix of _VIEW; the other is for text that can be updated and is identified with a name-alue pair suffix of _EDIT. The multiline text data displayed by the _VIEW name-alue pairs is read-only and cannot be updated. The multiline text data displayed by the _EDIT name-alue pairs can be updated and new text data can be added. Your request processor must determine how to populate these name-alue pairs based on the change management application. If the change management application allows updating of existing multiline text data, your request processor should return all text data in the name-alue pairs with a suffix of _EDIT. Optionally, it can also return the same data in the name-alue pairs with a suffix of _VIEW for display only. If the change management application does not allow updating of existing multiline text data, your request processor should return all text data only in the _VIEW name-alue pairs, and no data should be returned in the _EDIT name-alue pairs. This means that the user is restricted to appending or adding text data only in the multiline text boxes that can be updated. The following examples show these name-alue pairs: Chapter 3. Writing a change request processor 47

62 REQUEST_LONG_DESCRIPTION_VIEW 1 2 text_line_1 REQUEST_LONG_DESCRIPTION_VIEW 2 2 text_line_2 REQUEST_LONG_DESCRIPTION_EDIT 1 2 text_line_1 REQUEST_LONG_DESCRIPTION_EDIT 1 2 text_line_2 Required data fields Most change management applications hae required data fields or you might hae customized the change management application to require certain data fields or to limit field lengths. These data fields are usually required when creating or closing a change request. The console does not check for required data fields or data length restrictions. Your request processor must check for any required data fields or data length restrictions and return an appropriate error message when a required data field alue is not present or the data entered exceeds the maximum length allowed. The deeloper of your request processor must decide whether to return a single message identifying all required data fields with missing alues and incorrect field lengths or to return an indiidual error message for each field error. An example of a missing required data field follows, where the return code has a nonzero alue (-12): REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 Status Code missing - Required for new change Suppress display of the OK message box When a change request is created or updated using the change request interface, a message box is displayed containing the change ID and a message to indicate that the change request was created successfully. If the acknowledgement of the change ID and successful message notification is not useful to the user, the message box can be suppressed. That means that, if the change request is created successfully, no message box is displayed and the change request interface ends without any notification to the user. Howeer, if an error occurs in processing the change request, a message box with an error message is displayed. Use the console preference option to suppress the OK message box for a successful change request create and update; for more information, use the Task Assistant for the console. 48 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

63 Chapter 4. Writing an automatic ticket request processor This chapter describes how to write an automatic ticket request processor. The automatic ticket integration function is aailable in the Tioli Business Systems Manager V2.1 and later. What is an automatic ticket request processor? An automatic ticket request processor is any request processor you write that can process command line input parameters, read a text-based input file containing the data passed from the automatic ticket integration function, and create a text-based output file to contain the problem ID returned from the problem management application. The automatic ticket integration function is quite different from the problem and change integration functions within the Tioli Business Systems Manager product. Primarily, the automatic ticket integration function does not hae a console interface; its sole function is to create problem tickets and, optionally, generate automatic notifications, such as by pager or , to support groups and business units. The automatic ticket integration function interacts with your request processor when message or exception eents are sent to Tioli Business Systems Manager. All eents are processed by the automatic ticket integration function. You must administer the automatic ticket integration function by defining selection criteria known as automatic ticket eent rules. These rules proide specific criteria, which are matched against all message and exception eents. The matched message and exception eents are passed to the request processor to create problem tickets or generate automatic notifications, or both. For details on setting up eent rules, see the IBM Tioli Business Systems Manager Administrator s Guide. The automatic ticket integration function relies on a request processor to proide the interface between Tioli Business Systems Manager and your problem management application system and notification applications (such as pager or ). Without your automatic ticket request processor and the automatic ticket eent rules, the automatic ticket integration function cannot work. Because the automatic ticket integration function is not proided through the console, your request processor must proide all of the necessary information required to create a problem ticket in your problem management application. The automatic ticket integration function passes message or exception eent information to the request processor, which can be stored in the problem ticket; howeer, your request processor must proide any additional required problem information, such as a status code or problem type alues. The automatic ticket request processor can be added as a called subroutine to your existing console integration with a problem request processor, if one exists, or it can be implemented as a standalone request processor. The suggested method is to create a standalone request processor, because the input data and request processor function is quite different. Copyright IBM Corp

64 Non-batch automatic ticket integration function flow, configuration, and requirements This topic describes the flow, configuration, and requirements for the non-batch automatic ticket integration function. Non-batch automatic ticket integration function flow These steps show the flow for the non-batch automatic ticket integration function: 1. Define selection criteria known as eent rules, which select Tioli Business Systems Manager eents for automatic ticket creation. 2. When an eent is selected, the Tioli Business Systems Manager automatic ticket integration function creates an input file containing the request data and calls the appropriate request processor, which is defined in the Tioli Business Systems Manager SystemConfiguration table. The automatic ticket integration function passes the name of the input file and the path where the input file resides. 3. The request processor reads the GUID.in file where GUID is a unique identifier for each file. It then gathers the data alues and formats and runs the appropriate API or interface calls to the problem management application. 4. The request processor receies the results from the API or interface formats a GUID.out file where GUID is the same alue as the GUID.in file. This file is formatted with the appropriate name-alue pairs, and control is returned to the automatic ticket integration function. 5. The automatic ticket integration function gathers the data from the GUID.out file and creates an ownership or problem note containing the problem ID specified in the output file. This process is also logged in the Program Files\Tioli\tbsm\logs\INTMGRyyyymmdd directory. Configuration of the non-batch automatic ticket integration function To actiate the non-batch automatic ticket integration function, define your request processor in the SystemConfiguration table, using the following alues: SystemConfiguration column name groupname propertyname propertyalue propertydatatype Value REQUEST_AUTOTICKET REQUEST_PROCESSOR_NAME request_processor_name CHAR Define your request processor in one of the following ways: If your request processor is a Windows standard executable file, run the following SQL statements, where autoticket.exe is the name of your request processor: INSERT INTO SystemConfiguration VALUES ("REQUEST_AUTOTICKET","REQUEST_PROCESSOR_NAME","autoticket.exe","CHAR" ) UPDATE MenuItemVersion SET erno = erno + 1 If your request processor is a Windows nonstandard executable file, run the following SQL statements, where autoticket.exe is the name of your request processor and language_type defines the language type (for example, REXX.exe or KSH.exe): 50 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

65 INSERT INTO SystemConfiguration VALUES ("REQUEST_AUTOTICKET","REQUEST_PROCESSOR_NAME","autoticket.rex,"CHAR" ) INSERT INTO SystemConfiguration VALUES ("REQUEST_AUTOTICKET","REQUEST_PROCESSOR_LANGUAGE","language_type","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 The automatic ticket integration function proides an entry in the Tioli Business Systems Manager SystemConfiguration table to control the checking of duplicate eents that can cause duplicate problem tickets to be created. The alue of the DUPLICATE_AGE control is specified in minutes. The specified alue is used for selecting eents in the Tioli Business Systems Manager automatic ticket integration function. The incoming Tioli Business Systems Manager eents that match the filter rules are checked against an AT_Created table. This table contains the eents that were preiously selected and processed to create a problem ticket. If the incoming eent is within the time range specified in DUPLICATE_AGE, it is not processed to create a problem ticket. If the incoming eent is not within the time range the incoming eent is selected for processing to create a problem ticket. An example follows: 1. The DUPLICATE_AGE alue is 5 minutes. 2. An incoming eent is selected matching the filter rule at 1:00 p.m. 3. The AT_Created table is checked. No duplicate eents are present, so it is selected and a problem ticket is created. 4. A second incoming eent is selected matching the same filter rule at 1:02 p.m. 5. The AT_Created table is checked. A duplicate eent is present and the age of the first eent is less than 5 minutes, so no problem ticket is created. 6. A third incoming eent is selected matching the same filter rule at 2:10 p.m. 7. The AT_Created table is checked. A duplicate eent is present, and, because the age of the first eent is greater than 5 minutes, the third eent is selected and a problem ticket is created. The default for the DUPLICATE_AGE alue is 5 minutes and is used for the following conditions: The SystemConfiguration table does not contain an entry for the DUPLICATE_AGE alue. The DUPLICATE_AGE alue in the SystemConfiguration table is not alid. The alue must be numeric and greater than 0. Run the following SQL statements to create the DUPLICATE_AGE alue in the SystemConfiguration table, where DuplicateAgeValue is a numeric alue specified in minutes: INSERT INTO SystemConfiguration VALUES ("AUTO_PROBLEM","DUPLICATE_AGE","DuplicateAgeValue","INT") UPDATE MenuItemVersion SET erno = erno + 1 Requirements for non-batch automatic ticket request processors This section describes the minimal requirements for creating an automatic ticket request processor, which receies input from the Tioli Business Systems Manager eents. Your request processor is responsible for integrating with your problem management application. Chapter 4. Writing an automatic ticket request processor 51

66 Integration can be implemented in arious ways, depending on the programming language, the platform and the integration facilities that are supported. Also, you need to analyze each implementation of your request processor to determine the best method for interfacing with your problem management application based on your specific requirements. Input and output files Your non-batch automatic ticket request processor must read the input file and create the output file. A new input file is created for each eent that matches an automatic ticket rule. The Tioli Business Systems Manager automatic ticket integration function calls your request processor using the GUID and InFilePath parameters. An output file is created for each specific request and contains the formatted results of the request returned from your problem management application. For more information about input files, see Input files on page 5. For more information about output files, see Output files on page 6. Each Tioli Business Systems Manager eent that is selected for the automatic ticket process sends a request to the request processor. A different GUID.in file is created for each eent selected. The request does not pass a user ID or password for accessing your problem management application. Therefore, if the user ID and password are required to access your problem management application, your request processor must accommodate this. Date formats Because no console interface exists for the automatic ticket integration function, no dates are returned from your request processor. Batch automatic ticket integration function flow, configuration, and requirements This topic describes the flow, the configuration, the output file batch job, and the requirements for the batch automatic ticket integration function. Batch automatic ticket integration function flow These steps show the flow for the batch automatic ticket integration function: 1. Define selection criteria known as eent rules, which select Tioli Business Systems Manager eents for automatic ticket creation. 2. When a group of eents is selected, the Tioli Business Systems Manager automatic ticket integration function creates one or more input files containing the request data. The file name for each of these files is GUID.batch.in, where GUID is a unique identifier for each file created. 3. A process outside of Tioli Business Systems Manager, for example a user-defined serice, calls your request processor automatically. Your request processor reads all GUID.batch.in files waiting to be processed, gathers the data alues, and formats or runs the appropriate API or interface calls to the problem management application. 4. Your request processor receies the results from the API or interface to the problem management application, formats a GUID.batch.out file, where GUID is the same alue as the corresponding GUID.batch.in file. A GUID.batch.out file must be created for each GUID.batch.in file processed. Your request processor then checks for any new GUID.batch.in files waiting to be processed. 5. The Tioli Business Systems Manager automatic ticket integration function captures the GUID.batch.out files and creates an ownership or problem note containing the problem ID specified in the GUID.batch.out file. This process is 52 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

67 also logged in the Program Files\Tioli\tbsm\logs\INTMGRyyyymmdd directory. This process is actiated by an SQL Serer batch job named Auto Ticketing Process Output Files. Configuration of the batch automatic ticket integration function To actiate the batch automatic ticket integration function, run the following SQL statements. If you preiously actiated the non-batch automatic ticket integration function, you do not need to remoe these entries from the SystemConfiguration table. The INPUT_BATCH_MODE option oerrides the non-batch function. INSERT INTO SystemConfiguration VALUES ( AUTO_PROBLEM, INPUT_BATCH_MODE, ON, CHAR ) UPDATE MenuItemVersion SET erno = erno + 1 The automatic ticket integration function proides an entry in the Tioli Business Systems Manager SystemConfiguration table to control the checking of duplicate eents that can cause duplicate problem tickets to be created. The alue of the DUPLICATE_AGE control is specified in minutes. The specified alue is used for selecting eents in the Tioli Business Systems Manager automatic ticket integration function. The incoming Tioli Business Systems Manager eents that match the filter rules are checked against an AT_Created table. This table contains the eents that were preiously selected and processed to create a problem ticket. If the incoming eent is within the time range specified in DUPLICATE_AGE, it is not processed to create a problem ticket. If the incoming eent is not within the time range the incoming eent is selected for processing to create a problem ticket. An example follows: 1. The DUPLICATE_AGE alue is 5 minutes. 2. An incoming eent is selected matching the filter rule at 1:00 p.m. 3. The AT_Created table is checked. No duplicate eents are present, so it is selected and a problem ticket is created. 4. A second incoming eent is selected matching the same filter rule at 1:02 p.m. 5. The AT_Created table is checked. A duplicate eent is present and the age of the first eent is less than 5 minutes, so no problem ticket is created. 6. A third incoming eent is selected matching the same filter rule at 2:10 p.m. 7. The AT_Created table is checked. A duplicate eent is present, and, because the age of the first eent is greater than 5 minutes, the third eent is selected and a problem ticket is created. The default for the DUPLICATE_AGE alue is 5 minutes and is used for the following conditions: The SystemConfiguration table does not contain an entry for the DUPLICATE_AGE alue. The DUPLICATE_AGE alue in the SystemConfiguration table is not alid. The alue must be numeric and greater than 0. Run the following SQL statements to create the DUPLICATE_AGE alue in the SystemConfiguration table, where DuplicateAgeValue is a numeric alue specified in minutes: Chapter 4. Writing an automatic ticket request processor 53

68 INSERT INTO SystemConfiguration VALUES ("AUTO_PROBLEM","DUPLICATE_AGE","DuplicateAgeValue","INT") UPDATE MenuItemVersion SET erno = erno + 1 Batch automatic ticket output file batch job The batch mode automatic ticket requires an SQL Serer Enterprise job, which processes all GUID.batch.out files created by your request processor. The job, which is named Auto Ticket Process Output Files, is installed as disabled. Enable this job with the following steps: 1. On the database serer, start Microsoft SQL Serer, and select Enterprise Manager. 2. Expand Microsoft SQL Serers > SQL Serer Group > your_database_serer 3. Expand Management > SQL Serer Agent, and click Jobs. 4. Locate and right-click the Auto Ticket Process Output Files job, and then click Enable Job. The alue in the Enabled column should change to Yes. 5. The default schedule for this job is to run daily, eery 2 minutes. If you process a high olume of eents (2000 or more per hour), change this schedule to run eery minute, To change the schedule, right-click the Auto Ticket Process Output Files job, and then click Properties > Schedules > Edit > Change. In the Daily frequency, Occurs eery: field, change 2 to 1, and then click OK on each window until you exit. Requirements for batch automatic ticket request processors This section describes the minimal requirements for creating an automatic ticket request processor, which receies input from the Tioli Business Systems Manager eents. Your request processor is responsible for integrating with your problem management application. Integration can be implemented in arious ways, depending on the programming language, the platform, and the integration facilities that are supported. Also, you need to analyze each implementation of your request processor to determine the best method for interfacing with your problem management application based on your specific requirements. Input and output files Your batch automatic ticket request processor must read the input file and create the output file. A new input file is created for each eent that matches an automatic ticket rule. A process external to the automatic ticket integration function, for example, a user-defined serice, must call your request processor. An output file is created for each specific request and contains the formatted results of the request returned from your problem management application. For more information about input files, see Input files on page 5. For more information about output files, see Output files on page 6. A different GUID.in file is created for each eent selected. The request does not pass a user ID or password for accessing your problem management application. Therefore, if the user ID and password are required to access your problem management application, your request processor must accommodate this. Date formats Because no console interface exists for the automatic ticket integration function, no dates are returned from your request processor. 54 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

69 Counting open problems Tioli Business Systems Manager displays a problem ticket resource indicator when a problem is created for a resource. The problem ticket resource indicator indicates that at least one open problem was created from within Tioli Business Systems Manager. When all problems created from within Tioli Business Systems Manager are closed, the problem ticket resource indicator is remoed. This occurs when the status of the problem is set to Closed or to any alue representing a closed problem. When a problem is closed, a special request is issued to your request processor to return a count of open problems. Closing of a problem originates from either the console or the problem management application and neer from within the automatic ticket integration function. The following example shows the name-alue pair that is passed to the request processor that is associated with the console or is receiing closed eents from the problem management application. The alue for this name-alue pair is YES. The open count request should only be processed if the alue is YES. REQUEST_AUTO_QUERY_OPEN 1 1 YES The following name-alue pairs are returned for this request: REQUEST_RETURN_CODE 1 10 REQUEST_ERROR_MSG 1 1 Number of open problems REQUEST_OPEN_TICKET_COUNT If the count is 0, the problem ticket resource indicator is remoed; howeer, if the count is greater than 0, the problem ticket resource indicator is not remoed, indicating that at least one open problem remains in your problem management application for a particular resource. Only open problems created from Tioli Business Systems Manager are counted, using the physical resource key to identify them. Considerations for automatic ticket request processors This section presents the following considerations for creating an automatic ticket request processor that integrates with your problem management application. Problem management application user ID and password aailability Required data fields in the problem management application Associating problems in the problem management application with Tioli Business Systems Manager resources. Integrations can be implemented in arious ways, depending on the programming language or the platform being used, or both. Each implementation of your request processor needs to be analyzed to determine the best method of interfacing to your problem management application, based on your specific requirements. User ID and password The automatic ticket integration function does not pass user ID and password alues. If these are required to access your problem management application, your request processor must proide them. Some problem management applications require a user ID and password to establish a session or perform database functions. To accommodate this requirement, your request processor should use a special user ID and password that you proide and that allows these functions to be performed. Because no interface is aailable for the automatic ticket process to pass a alid problem Chapter 4. Writing an automatic ticket request processor 55

70 management application user ID and password, the special user ID becomes een more important. The special user ID should hae all the authority it needs to perform any function against the problem management application database. Note: Password security is the responsibility of your request processor. NO_NOTE option A NO_NOTE option enables your request processor to oerride the creation of a note specified in the automatic ticket rule definition. Currently, a note type of O (ownership) or a note type of P (problem) is required in the automatic ticket rule that you define. When a rule matches a message or exception eent, eent information is passed to your request processor. The eent information is used to create a problem ticket in the problem management application and create a note containing the problem ID. Your request processor must create a GUID.out or GUID.batch.out file containing the problem ID. The automatic ticket function creates an ownership note or a problem note, determined by note type specified in the rule. The note contains the owner, subject, description, and owner information specified in the rule and the problem ID returned by your request processor. The NO_NOTE option enables your request processor to perform additional filtering on an eent before deciding whether a problem ticket should be created. For example, the automatic ticket function currently proides a duplicate age check to eliminate creating duplicate problems when like eents are receied within a specified time period; howeer, your processor might want to use eent information passed to it to query the problem database and determine if an open problem currently exists for this type of eent. If a new problem should not be created, your request processor can return a NO_NOTE alue in the REQUEST_PROBLEM_ID name-alue pair to suppress the creation of a note for the message or exception eent. The following example shows how your request processor should create the GUID.out file if it decides that a note should not be created in the database. REQUEST_RETURN_CODE REQUEST_ERROR_MSG 1 1 your_text REQUEST_PROBLEM_ID 1 1 NO_NOTE Note type N alue The ATRuleUtility utility, which defines automatic ticket rules, supports the following note types: N Indicates that a note should not be created when an eent matches the criteria described in the automatic ticket rule. Use this alue to indicate that, instead of creating a problem ticket, a support group or person is to be automatically notified. If a note type of N is specified, the note_expiration, note_owner, note_subject and note_body field alues are not needed. O Indicates that an ownership note is to be created. P Indicates that a problem note is to be created. A note type of N in a rule indicates that an ownership or problem note is not to be created for eents that match the rule and negates note creation for eery eent that matches the rule. This differs from the NO_NOTE option, which conditionally oerrides the note alue in the rule. The NO_NOTE option is returned by your request processor after determining that a note should not be created for a particular eent. 56 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

71 The following example rule definition shows a note type of N, indicating that an ownership or problem note is not to be created: RULE_BEGIN name=cics Red Message description=do not create a Note for CICS Region with eent name of AOF571I_BROKEN obj_path_pattern=cics obj_name_pattern= eent_cid_pattern=mesg eent_name_pattern=%aof571i_broken% eent_detail_pattern= eent_state= eent_alertstate=3 eent_priority= note_type=n note_expiration= note_owner= note_subject= note_body= RULE_END For more information about the ATRuleUtility utility, see the IBM Tioli Business Systems Manager Command Reference. Exception propagation matrices and occurrence data To proide as much information as possible to your request processor for making decisions for automatically creating problem tickets, the exception propagation matrices and occurrence data is passed in the GUID.in or GUID.batch.in file. This can help your request processor to determine that a problem should be created only when a red or yellow exception threshold is exceeded. As always, the request processor should be coded to read all name-alue pairs in the GUID.in or GUID.batch.in file and to check for the names in the name-alue pairs that are needed to process problem functions. When a name is matched, sae the alue for formatting and running the integration facility proided by your problem management application. All other name-alue pairs should be bypassed by getting the next name-alue pair record in the GUID.in or GUID.batch.in file. The exception eent propagation matrices and occurrence data are passed in this example GUID.in file, where the COUNT and MAX name-alue pairs are the exception eent propagation matrices and occurrence data. REQUEST_TYPE 1 1 REQUEST_AUTOTICKET REQUEST_METHOD 1 1 REQUEST_ADD REQUEST_CONSOLE_VERSION 1 1 V15 REQUEST_OBJECT_CID 1 1 CICS REQUEST_OBJECT_ID REQUEST_OBJECT_SOURCE_CID 1 1 CICS REQUEST_OBJECT_SOURCE_ID REQUEST_EVENT_NO REQUEST_AUTO_CREATE 1 1 YES REQUEST_OBJECT_NAME 1 1 CICSB REQUEST_USER_ID 1 1 REQUEST_PASSWORD 1 1 REQUEST_EVENT_CID 1 1 EXCP REQUEST_EVENT_ID REQUEST_EVENT_DETAIL 1 1 Automatic initiate descriptors is high REQUEST_EVENT_NAME 1 1 AIDS REQUEST_EVENT_STATE 1 1 REQUEST_EVENT_TIME 1 1 No :39AM REQUEST_EVENT_PRIORITY REQUEST_EVENT_ALERT_STATE COUNT_YELLOW_HIGH Chapter 4. Writing an automatic ticket request processor 57

72 COUNT_YELLOW_MEDIUM COUNT_YELLOW_LOW COUNT_YELLOW_IGNORE COUNT_YELLOW_VIOLATIONS MAX_YELLOW_HIGH MAX_YELLOW_MEDIUM MAX_YELLOW_LOW MAX_YELLOW_IGNORE MAX_YELLOW_VIOLATIONS COUNT_RED_HIGH COUNT_RED_MEDIUM COUNT_RED_LOW COUNT_RED_IGNORE COUNT_RED_VIOLATIONS MAX_RED_HIGH MAX_RED_MEDIUM MAX_RED_LOW MAX_RED_IGNORE MAX_RED_VIOLATIONS EXCEPTION_OCCURANCE_COUNT Clear exception eent counts and resource alerts You can set the default behaior to clear or not clear exception eent counts and resource alerts when ownership is taken and a note is committed. After you set the default behaior for clear exception eent counts, exception eents that match an automatic ticket rule with a note_type alue of O (take ownership) clear the exception eent counts and resource alerts. The clear eents and alerts option is set in the console administrator preferences; for more information, use the Task Assistant for the console. Reset automatic ticket queues You can reset the current automatic ticket queue control alues to indicate that all current pending automatic ticket message and exception eents should not be processed. After the queue control alues are reset, the automatic ticket function does not process any message or exception eents currently residing in the queue. It processes all future incoming eents that are queued for the automatic ticket function. This enables the automatic ticket processing to catch up without actually processing any pending requests. Optionally, it can delete all data in the automatic ticket queues. Use this option only if you want the automatic ticket queues to be cleared. Two choices are aailable for resetting the automatic ticket queues: Reset the queue control alues and leae the existing message and exception eents in the automatic ticket queues. Reset the queue control alues and delete the existing message and exception eents from the automatic ticket queues. Example 1: Running the following SQL statements from an SQL Query Analyzer window disables jobs, resets queue control alues only, does not delete data, and does not restart jobs: exec AT_SetAutoTicketing 0 disable auto ticket jobs exec AT_ResetQueues 0, 0 reset queue control alues only, do not delete data, do not restart Auto Ticket jobs Example 2: Running the following SQL statements from an SQL Query Analyzer window resets queue control alues, deletes all data in the queues, and does not restart automatic ticket jobs: 58 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

73 exec AT_SetAutoTicketing 0 disable auto ticket jobs exec AT_ResetQueues 1, 0 reset queue control alues, delete data in queues, do not restart auto ticket jobs For examples 1 and 2, When you are ready to restart (enable) the automatic ticket jobs, run the following statement from an SQL Query Analyzer window: exec AT_SetAutoTicketing 1 Example 3: Running the following SQL statements from an SQL Query Analyzer window disables jobs, resets queue control alues only, does not delete data in the queues, and restarts jobs automatically: exec AT_SetAutoTicketing 0 disable auto ticket jobs exec AT_ResetQueues 0, 1 reset queue control alues only, do not delete data, restart auto ticket jobs Example 4: Running the following SQL statements from an SQL Query Analyzer window resets queue control alues, deletes all data in the queues, and restarts automatic ticket jobs automatically: exec AT_SetAutoTicketing 0 disable auto ticket jobs exec AT_ResetQueues 1, 1 reset queue control alues, delete data in queues, restart auto ticket jobs For examples 3 and 4, the automatic ticket jobs is started automatically after the reset queue process is complete. After any of these 4 examples is run, the automatic ticket function processes all future eents that are queued for the automatic ticket integration function. Disable and enable automatic ticket jobs You can disable or enable the automatic ticket batch jobs that queue eents for rule matching and queue matched message or exception eents to be processed for automatic ticket creation by your request processor. You can set these SQL Serer Agent automatic ticket jobs to a status of enabled or disabled: Dequeue AT Eents Dequeue AT Filtered Eents The AutomaticTicketing Process Output Files job, aailable in V3.1 or later, can also be disabled or enabled if it exists in the database. To disable the automatic ticket integration function at any time, run the following statement from an SQL Query Analyzer window: exec AT_SetAutoTicketing 0 To enable the automatic ticket integration function at any time, run the following statement from an SQL Query Analyzer window: exec AT_SetAutoTicketing 1 Adjust health monitor automatic ticket threshold alues The current Tioli Business Systems Manager Health Monitor threshold alues for the automatic ticket queues might not accurately reflect the true state of these queues within a gien production enironment. An indicator that the threshold Chapter 4. Writing an automatic ticket request processor 59

74 alues might need to be adjusted is when the state of the queues is always red een though eents are being processed and the queue counts are increasing and decreasing on a regular basis. Adjust the Health Monitor threshold alues ticket queues to reflect the true state of the AutoTicketEent and AutoTicketFilteredEent queues using these steps: 1. Start an SQL/Serer Query Analyzer session. 2. Click Load SQL Script and select the at_queuethresholdsample.sql file from the Program Files\Tioli\tbsm\SQL directory to load it into the SQL Query Analyzer window. 3. After the file is loaded, follow the instructions to adjust the threshold alues. 4. Run the SQL script to apply the adjusted threshold alues to the database. Request add method REQUEST_ADD is a request to ADD, CREATE or INSERT a problem to a problem management application database. All data entry name-alue pairs that hae a alue should be included. You should also include some combination of the Tioli Business Systems Manager resource key items (physical resource CID, physical resource ID and, optionally, the resource name). Doing this associates the problem physically stored in your problem management application database with the Tioli Business Systems Manager physical resource. This might require adding new fields to the problem management database or mapping them to existing fields that are not being used. The resource key items are critical to enable your request processor to include the Tioli Business Systems Manager resource key in searches, updates, and so on to ensure the appropriate problems are being processed or displayed. REQUEST_TYPE 1 1 REQUEST_AUTOTICKET REQUEST_METHOD 1 1 REQUEST_ADD REQUEST_OBJECT_CID 1 1 LOB REQUEST_OBJECT_ID REQUEST_OBJECT_SOURCE_CID 1 1 CICS REQUEST_OBJECT_SOURCE_ID REQUEST_OBJECT_NAME 1 1 resource_name_from_eent REQUEST_AUTO_CREATE 1 1 YES REQUEST_USER_ID 1 1 **no alue proided** REQUEST_USER_PASSWORD 1 1 **no alue proided** REQUEST_EVENT_CID 1 eent_class_id REQUEST_EVENT_ID 1 1 eent_id REQUEST_EVENT_DETAIL 1 1 detailed_eent_description REQUEST_EVENT_NAME 1 1 eent_name REQUEST_EVENT_TIME 1 1 time_eent_created REQUEST_EVENT_PRIORITY 1 1 priority_of_the_eent REQUEST_EVENT_ALERT_STATE 1 1 alert_state_of_the_eent EVENT_OWNED 1 1 YES or NO EVENT_PROBLEM_ID 1 1 alue_if_owned EVENT_OWNER 1 1 alue_if_ownedy EVENT_ACTIVE 1 1 YES or NO Required data fields Your request processor must proide any additional data needed to create a problem ticket within your problem management application. That includes required data fields and any additional data that is usually proided in the manual creation of a problem ticket. 60 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

75 Special process data fields All eents that match the automatic ticket rules are passed to your request processor, including owned eents and inactie eents. Special data fields indicate the owned, unowned, actie, and inactie states. Your request processor must determine how to handle the owned or inactie eents. Inactie eents are not owned and are not aailable for ownership. They typically occur when an eent is waiting for ownership and a duplicate eent is receied; the duplicate eent becomes the actie eent because it is the most recent eent. One use of the EVENT_OWNED name-alue pair might be to proide notification to a business unit. The EVENT_OWNED name-alue pair contains YES if the eent is already owned and NO if the eent is aailable for ownership. The EVENT_PROBLEM_ID name-alue pair contains a problem ID alue if the eent is already owned and a problem ticket was created at the time of ownership. The EVENT_OWNER name-alue pair contains the owner who took ownership of the eent. The EVENT_ACTIVE name-alue pair contains YES if the eent is actie and NO if the eent is inactie. User-defined serice sample (batch mode) A batch automatic ticket request processor is not called by Tioli Business Systems Manager. Therefore, you must proide a mechanism to call it. The batch automatic ticket request processor must run continuously to monitor and process any new batches of input files created by the batch automatic ticket integration function. If you want to use a user-defined serice, follow these steps: 1. Create a user-defined serice on the Tioli Business Systems Manager database serer only. At an MS-DOS command prompt, change to your Resource Kit directory. If your Resource Kit directory is installed on a different drie or in a different directory, change this command accordingly. cd C:\Program Files\Resource Kit 2. Run the following command to create the serice: instsr.exe ATBatchSr c:\progra~1\resour~1\srany.exe You should receie the following message: The serice was successfully added! If you receie the Unable to find the file at the gien path. message, then enter where srany.exe on the command line, and modify the drie and directory as needed. 3. Update the registry with the following steps. Before updating your registry, you should back it up. a. Open your registry by entering this command: regedit b. Locate the following subkey in your registry display: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Serices\ATBatchSr c. Right-click the ATBatchSr subkey, and click New > Key. d. Enter the following command: Parameters e. Right-click the Parameters subkey, and click New > String Value. f. Enter the following command: AppDirectory Chapter 4. Writing an automatic ticket request processor 61

76 g. Right-click the AppDirectory subkey, and click Modify. h. Enter the following command, where d:\program Files\Tioli\tbsm\ is the path where Tioli Business Systems Manager is installed: d:\program Files\Tioli\tbsm\Data\ i. Right-click the Parameters subkey, and click New > String Value. j. Enter the following command: Application k. Right-click the Application subkey, and click Modify. l. Enter the following command, where your_language_executable_file is, for example, REXX.exe, SH.exe, or Perl.exe: your_language_executable_file m. Right-click the Parameters subkey, and click New > String Value. n. Enter the following command: AppParameters o. Right-click the AppParameters subkey, and click Modify. p. Enter the following command: name_of_your_automatic_ticket_request_processor q. Close the registry. You hae completed the creation of the ATBatchSr serice. The ATBatchSc serice is configured to run automatically when the system is restarted; howeer, you can manually start or stop the ATBatchSc serice. To delete the serice, follow these steps: 1. Change to the Resource Kit folder. If your Resource Kit folder is installed on a different drie or in a different directory, adjust this command accordingly. cd C:\Program Files\Resource Kit 2. Enter the following command: instsr.exe ATBatchSc remoe d:\progra~1\resour~1\srany.exe You should receie the following message: The serice was successfully deleted! 62 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

77 Chapter 5. Enabling a request processor System configuration table Two Tioli Business Systems Manager database tables are used for the problem, change, and automatic ticket integration functions: the SystemConfiguration table and the TSD_SCIM table. This chapter describes how to work with these tables to enable problem, change, and automatic ticket request processors. These tables are maintained using standard SQL Serer tools. You should hae a working knowledge of SQL and SQL Serer databases and be able to use basic Transact SQL commands to add, change, or delete information in the tables. The alues in the SystemConfiguration table are changed through the SQL Serer Query Analyzer; to update this table, you must be familiar with this application. Knowledge of the table structure is also a requirement. To work with the TSD_SCIM table, you also should hae knowledge of the Tioli Business Systems Manager resource classes. Before making changes to these tables, you should back up or sae the table alues. This chapter also describes considerations for customizing Tioli Business Systems Manager console fields. The Tioli Business Systems Manager SystemConfiguration table contains system-wide information for controlling arious configuration aspects of the Tioli Business Systems Manager product. For example, this table can contain alues that control the workflow of a process or the default alues that are used in processing data. The SystemConfiguration table supplies information about a particular installation. It resides in the object database on the Tioli Business Systems Manager database serer. This information is stored in simple name-alue pairs and is organized by a group alue. The information in this table proides system-wide configuration settings and not indiidual workstation settings. Before inserting rows in the SystemConfiguration table, determine your particular requirements for creating, updating, and searching for problem tickets and change requests. System configuration table structure The SystemConfiguration table has the following structure: Column Name Data Type Length Description id Integer 4 Unique numerical identifier for each row in the table, automatically increased by the SQL Serer. groupname Char 50 Group name for a specific alue propertyname Char 50 Name of a specific alue propertyalue Char 50 Value belonging to the group and property propertydatatype Char 20 The data type name for a property, such as CHAR (character) Copyright IBM Corp

78 Populating the system configuration table When Tioli Business Systems Manager is installed, the SystemConfiguration table does not include integration function configuration options. The installation includes a starter SQL script file that contains arious insert commands that can be used to set system alues. The script file is named problemintegrationdefaults.sql and is in the Program Files\Tioli\tbsm\sql directory. This script file can be loaded into an SQL Serer Query Analyzer window and used to configure the system by using or modifying the alues of the pretyped insert commands. All insert commands in the problemintegrationdefaults.sql file are defined as comments, that is, with 2 dashes (--) at the beginning of each statement. When you modify the alues of the insert commands you want to actiate, uncomment the commands by remoing the 2 dashes (--) from the beginning of each statement. Failure to do so preents the insert statement from running and the option from being actiated. Values in the SystemConfiguration table are case-sensitie. Incorrect alues can result in Tioli Business Systems Manager not operating as expected. Before you update the table, you should create a backup copy. To do that, run the following SQL statements, where backup_table_name is the name of the backup copy you want to create: SELECT * INTO backup_table_name FROM SystemConfiguration Suppose, for example, that to identify a request processor named MyRequestProcessor.exe, you need to add a new row with the following alues to the SystemConfiguration table: SystemConfiguration column name groupname propertyname propertyalue propertydatatype Value REQUEST_PROBLEM REQUEST_PROCESSOR_NAME MyRequestProcessor.exe CHAR To add the new row, run the following SQL statements: INSERT INTO SystemConfiguration VALUES ("REQUEST_PROBLEM","REQUEST_PROCESSOR_NAME","MyRequestProcessor.exe","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 The following new row is added: id groupname propertyname propertyalue propertydatatype 1 REQUEST_PROBLEM REQUEST_PROCESSOR_NAME MyRequestProcessor CHAR To change the name (propertyalue) of the request processor from MyRequestProcessor.exe to RequestProcessor.exe, update the existing row in the SystemConfiguration table; run the following SQL statement, where 1 is the unique row ID (id) assigned by SQL Serer when the row was inserted: UPDATE SystemConfiguration SET propertyalue ="RequestProcessor.exe" WHERE id=1 To delete the row that identifies this request processor, you need to delete the row with the REQUEST_PROBLEM, REQUEST_PROCESSOR_NAME, and MyRequestProcessor.exe alues; to do that, run the following SQL statement, where 1 is the unique row ID (id) assigned by SQL Serer when the row was inserted: 64 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

79 DELETE SystemConfiguration WHERE id=1 This example shows the steps in iewing and updating the SystemConfiguration table: 1. To display all the current rows in the table, run the following SQL statement: SELECT * FROM SystemConfiguration The table is displayed: id groupname propertyname propertyalue propertydatatype 1 API_INTEGRATION_OPTIONS AUTO_CLOSE_DEFAULT NO CHAR 2 API_INTEGRATION_OPTIONS DEBUG_MODE OFF CHAR 3 API_INTEGRATION_OPTIONS DISPLAY_PROBLEM_CLOSURE YES CHAR 4 API_INTEGRATION_OPTIONS TICKET_CREATE_ DEFAULT YES CHAR 2. Find the row to modify and note the alue in the row ID (id) column. For example, to change AUTO_CLOSE_DEFAULT from NO to YES, note that the ID number for this row is 1, and then run the following SQL statement: UPDATE SystemConfiguration SET PropertyValue= YES WHERE id=1 3. Display all the current rows again to erify your change: SELECT * FROM SystemConfiguration Making system configuration table updates aailable SystemConfiguration options for the problem, change, and automatic ticket integration functions are included within the MenuItem cache tables, which remain in effect for long periods of time. Wheneer you insert or update rows in the SystemConfiguration table for these functions, run the following SQL statements to erify that the information you entered is correct and to ensure that your changes are aailable on the console interface. The second statement gets all the problem and change settings so that you can erify them. UPDATE MenuItemVersion SET erno = erno + 1 SELECT * FROM SystemConfiguration WHERE groupname like %API% or groupname like %REQUEST% order by groupname, propertyname Note: These statements are included in the problemintegrationdefaults.sql file, located in the Program Files\Tioli\tbsm\sql folder. Use this file as a reference for inserting or updating rows in the SystemConfiguration table. System configuration options The following table lists the SystemConfiguration table group names, property names, and property alues that are supported by the problem, change, and automatic ticket integration functions. The sections that follow the table describe these system configuration options. groupname propertyname propertyalue propertydatatype REQUEST_PROBLEM REQUEST_ PROCESSOR_NAME Executable file name REQUEST_PROBLEM REQUEST_PROCESSOR_LANGUAGE Nonstandard executable file REQUEST_CHANGE REQUEST_PROCESSOR_NAME Executable file name REQUEST_CHANGE REQUEST_PROCESSOR_LANGUAGE Nonstandard executable file CHAR CHAR CHAR CHAR API_INTEGRATION_OPTIONS APPEND_TEXTLOG_TIMESTAMPS YES or NO CHAR API_INTEGRATION_OPTIONS AUTO_CLOSE_DEFAULT YES or NO CHAR Chapter 5. Enabling a request processor 65

80 groupname propertyname propertyalue propertydatatype API_INTEGRATION_OPTIONS AUTO_SELECT_TICKET Value for first open status CHAR API_INTEGRATION_OPTIONS CHANGE_SYSTEM_NETVIEW_USED YES or NO CHAR API_INTEGRATION_OPTIONS CLOSED_TICKET_STATUS_CODE Value for closed status CHAR API_ INTEGRATION_OPTIONS DEBUG_MODE ON or OFF CHAR API_INTEGRATION_OPTIONS DISPLAY_PROBLEM_CLOSURE YES or NO CHAR API_INTEGRATION_OPTIONS ORIGIN_SYSTEM LOOK_UP or AUTO_CREATE API_INTEGRATION_OPTIONS ORIGIN_COMPONENT LOOK_UP or AUTO_CREATE API_INTEGRATION_OPTIONS ORIGIN_ITEM LOOK_UP or AUTO_CREATE API_INTEGRATION_OPTIONS ORIGIN_MODULE LOOK_UP or AUTO_CREATE CHAR CHAR CHAR CHAR API_INTEGRATION_OPTIONS PROBLEM_SYSTEM_NETVIEW_USED YES or NO CHAR API_INTEGRATION_OPTIONS TABLE_BASE_ENUMERATIONS YES or NO CHAR API_INTEGRATION_OPTIONS TICKET_CREATE_DEFAULT YES or NO CHAR API_INTEGRATION_OPTIONS TIMEOUT_VALUE Value specified in seconds REQUEST_AUTOTICKET REQUEST_PROCESSOR_NAME Executable file name REQUEST_AUTOTICKET REQUEST_PROCESSOR_LANGUAGE Nonstandard executable file INT CHAR CHAR AUTO_PROBLEM INPUT_BATCH_MODE ON or OFF CHAR AUTO_PROBLEM DUPLICATE_AGE Value in minutes INT Request processor name and language The name of your request processor, which is called by the Tioli Business Systems Manager integration function, is specified in the SystemConfiguration table. One or more rows define your request processor, using the alues shown in the following table. Defining a request processor actiates a specific type of integration function (problem, change, or automatic ticket). If you use the same request processor for more than one type of integration function, you must define it separately for each integration function: SystemConfiguration column name groupname propertyname propertyalue propertydatatype Value The type of integration function: REQUEST_PROBLEM REQUEST_CHANGE REQUEST_AUTOTICKET REQUEST_PROCESSOR_NAME request_processor_name CHAR Depending on the type of request processor file, you must define your request processor in one of the following ways: To actiate an integration function for a Windows standard executable file, run the following SQL statements, where groupname_alue indicates the type of 66 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

81 integration function (REQUEST_PROBLEM, REQUEST_CHANGE, or REQUEST_AUTOTICKET) and request_processor_name is the name of your request processor: INSERT INTO SystemConfiguration VALUES ("groupname_alue","request_processor_name","request_processor_name","char") UPDATE MenuItemVersion SET erno = erno + 1 To actiate an integration function for a Windows nonstandard executable file, run the following SQL statement, where groupname_alue indicates the type of integration function and request_processor_name is the name of your request processor: INSERT INTO SystemConfiguration VALUES ("groupname_alue","request_processor_name","request_processor_name","char") UPDATE MenuItemVersion SET erno = erno + 1 Actiating a Windows nonstandard executable file requires a second entry to define the language type (for example, REXX.exe or KSH.exe); run the following SQL statements: INSERT INTO SystemConfiguration VALUES ("groupname_alue","request_processor_language","language_type","char" ) UPDATE MenuItemVersion SET erno = erno + 1 Note: If REQUEST_PROCESSOR_NAME is specified in the Tioli Business Systems Manager SystemConfiguration table without a REQUEST_PROCESSOR_LANGUAGE row, the default call for the Tioli Business Systems Manager integration function is to a Windows standard executable file, so you must take the following actions: Do not specify a REQUEST_PROCESSOR_LANGUAGE row for a Windows standard executable file. You must specify a REQUEST_PROCESSOR_LANGUAGE row for a Windows nonstandard executable file. In either case, the request processor specified is called by the Tioli Business Systems Manager integration function for all console requests or, for the automatic ticket function, for all eents that are selected based on selection criteria that you define. Actiate problem (console) To actiate the console problem integration function, run the following SQL statements using the problemintegrationdefaults.sql file located in the Program Files\Tioli\tbsm\SQL folder: INSERT INTO SystemConfiguration VALUES ("REQUEST_PROBLEM","REQUEST_PROCESSOR_NAME","request_processor_name","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 Actiate change (console) To actiate the console change integration function, run the following SQL statements using the problemintegrationdefaults.sql file located in the Program Files\Tioli\tbsm\SQL folder: INSERT INTO SystemConfiguration VALUES ("REQUEST_CHANGE","REQUEST_PROCESSOR_NAME","request_processor_name","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 Actiate automatic ticket You can actiate automatic ticket integration function either in non-batch mode or in batch mode. Chapter 5. Enabling a request processor 67

82 Non-batch mode: To actiate the non-batch automatic ticket integration function, run the following SQL statements using the problemintegrationdefaults.sql file located in the Program Files\Tioli\tbsm\SQL folder: INSERT INTO SystemConfiguration VALUES ("REQUEST_AUTOTICKET","REQUEST_PROCESSOR_NAME","request_processor_name","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 Batch mode: To actiate the batch automatic ticket integration function, run the following SQL statements using the problemintegrationdefaults.sql file located in the Program Files\Tioli\tbsm\SQL folder: INSERT INTO SystemConfiguration VALUES ( AUTO_PROBLEM, INPUT_BATCH_MODE, ON, CHAR ) UPDATE MenuItemVersion SET erno = erno + 1 Note: If you preiously actiated the non-batch automatic ticket integration function, you do not need to remoe those entries from the SystemConfiguration table. The INPUT_BATCH_MODE option oerrides the non-batch function. Additionally, the batch automatic ticket requires an SQL Serer Enterprise job that processes all the GUID.batch.out files created by your request processor. For information about enabling this job, which is named Auto Ticket Process Output Files, see Batch automatic ticket output file batch job on page 54. Append textlog time stamps The APPEND_TEXTLOG_TIMESTAMPS option pertains to both problems and changes. The APPEND_TEXTLOG_TIMESTAMPS option has alues of YES and NO. If this option is not specified in the SystemConfiguration table, the integration function uses a default alue of YES. This entry controls whether a time stamp comment is automatically added when a text field that uses the TextLog control is modified. If the entry has a alue of YES (or is omitted), then wheneer text within a field that uses the TextLog control is changed, a time stamp is automatically added to the text, The time stamp shows who changed the text and when the change was made. If the entry has a alue of NO, the time stamp information is not added. To set this option to YES, run the following SQL statements: INSERT INTO SystemConfiguration VALUES "API_INTEGRATION_OPTIONS","APPEND_TEXTLOG_TIMESTAMPS","YES","CHAR" UPDATE MenuItemVersion SET erno = erno + 1 Auto close default The AUTO_CLOSE_DEFAULT option pertains to problems only. The AUTO_CLOSE_DEFAULT option has a alue of YES or NO. If this option is not specified in the SystemConfiguration table, the integration function uses a default alue of NO. When a note with an attached problem is closed, the console checks the AUTO_CLOSE_DEFAULT alue. If the alue is YES, the Tioli Business Systems Manager problem integration function is called to create a GUID.in file and to call the REQUEST_PROCESSOR specified in the problem request processor name and language SystemConfiguration table entries. The GUID.in file contains the REQUEST_METHOD 1 1 REQUEST_UPDATE and REQUEST_CLOSE 1 1 YES name-alue pairs. REQUEST_CLOSE 1 1 YES indicates to your request processor 68 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

83 that the REQUEST_PROBLEM_ID 1 1 xxxxxxxx should be closed in your problem management application. The request processor might need to add additional closure data to the problem update in your problem management application, such the date closed or resolution text. If this option has a alue of NO or is not specified, the Tioli Business Systems Manager problem integration function does not call your request processor for automatic problem closure. To set this option to YES, run the following SQL statements: INSERT INTO SystemConfiguration VALUES "API_INTEGRATION_OPTIONS","AUTO_CLOSE_DEFAULT","YES","CHAR" UPDATE MenuItemVersion SET erno = erno + 1 Auto select ticket The AUTO_SELECT_TICKET option pertains to both problems and changes. The AUTO_SELECT_TICKET option preselects the most recently opened problem ticket or change request in the Results table for the Find function. When set, the most recent problem ticket or change request with a status alue that matches the alue defined for this option is preselected in the Results table. If this option is not specified in the SystemConfiguration table, no problem ticket or change request is preselected in the Results table. To set this option, run the following SQL statements: INSERT INTO SystemConfiguration VALUES "API_INTEGRATION_OPTIONS","AUTO_SELECT_TICKET","open_status_alue","CHAR" UPDATE MenuItemVersion SET erno = erno + 1 Change system NetView used The CHANGE_SYSTEM_NETVIEW_USED option pertains to changes only. The CHANGE_SYSTEM_NETVIEW_USED option has a alue of YES or NO. If this option is not specified in the SystemConfiguration table, the integration function uses a default alue of NO. This option is required with a alue of YES for change systems where data is passed through the NetView program. If the alue is YES, the user is prompted as needed for a alid NetView user ID and password. After entering this information, the user does not hae to enter it again unless the password becomes not alid, the preferences file is deleted from the user s system, or the console serer is restarted. If the option has a alue of NO (or is not specified), the user is not prompted for a NetView user ID and password. Howeer, if the system uses the NetView program, then the create or update action cannot complete successfully. To specify this option, run SQL statements similar to the following statements: INSERT INTO SystemConfiguration VALUES ("API_INTEGRATION_OPTIONS","CHANGE_SYSTEM_NETVIEW_USED","YES","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 Closed ticket status code The CLOSED_TICKET_STATUS_CODE option pertains to problems only. The CLOSED_TICKET_STATUS_CODE option specifies the alue (such as CLOSED) for a problem ticket that is in a nonworking status; that is, the problem does not hae an open status. If no alue is entered, the default alue is CLOSED. Chapter 5. Enabling a request processor 69

84 In some cases, a problem management application can support multiple alues to indicate a closed status; for example, a problem management application might support alues of CLOSED and DEAD to indicate that a problem is no longer in a working status. The SystemConfiguration table supports only one alue for the CLOSED_TICKET_STATUS_CODE. Your problem request processor can add additional closed alues by using the REQUEST_INITIALIZE request and the PROBLEM_CLOSE_VALUES name-alue pair. If your problem management application has only one alue to identify closed problems, use the CLOSED_TICKET_STATUS_CODE option in the SystemConfiguration table instead of the REQUEST_INITALIZE function within your request processor. To specify this option, run SQL statements similar to the following statements: INSERT INTO SystemConfiguration VALUES ("API_INTEGRATION_OPTIONS","CLOSED_TICKET_STATUS_CODE","closed_status_alue", "CHAR") UPDATE MenuItemVersion SET erno = erno + 1 Debug mode The DEBUG_MODE option has alues of ON and OFF. If this option is not specified in the SystemConfiguration table, the Tioli Business Systems Manager problem, change, or automatic ticket integration function uses a default alue of OFF. If the alue is set to ON, the GUID.in files, created by the Tioli Business Systems Manager problem, change, or non-batch automatic ticket integration functions, and the GUID.out files, created by your request processor, are not deleted. For batch automatic ticket processing, only the GUID.batch.out files are not deleted; the deletion of the GUID.batch.in files is controlled by your request processor. This option is useful when testing a request processor or debugging a problem situation. After the request processor is in a production mode, you should set DEBUG_MODE to OFF; otherwise, these files hae to be deleted manually. If the alue is OFF or this option is not specified, the Tioli Business Systems Manager problem, change, or non-batch automatic ticket integration functions delete the GUID.in and GUID.out files associated with each request. For batch automatic ticket processing, only the GUID.batch.out files are deleted; deletion of the GUID.batch.in files is controlled by your request processor. To turn this option on, run the following SQL statements: INSERT INTO SystemConfiguration VALUES ("API_INTEGRATION_OPTIONS","DEBUG_MODE","ON","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 Display problem closure The DISPLAY_PROBLEM_CLOSURE option pertains to problems only. The DISPLAY_PROBLEM_CLOSURE option has alues of YES and NO. If this option is not specified in the SystemConfiguration table, the Tioli Business Systems Manager problem and change integration functions use a default alue of NO. If the alue is NO, then the problem closure interface is not aailable on the console. 70 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

85 If the alue is YES, the Closure tab is shown in the problem properties interface. When the user clicks the Closure tab, additional closure information is displayed. To implement the extra closure information as part of your problem information, you must specify the DISPLAY_PROBLEM_CLOSURE option in your SystemConfiguration table. You can customize the closure data fields on the interface to match your problem management application. To specify this option, run the following SQL statements: INSERT INTO SystemConfiguration VALUES ("API_INTEGRATION_OPTIONS","DISPLAY_PROBLEM_CLOSURE","YES","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 If this option is actiated, the following name-alue pairs are passed to the problem integration function: REQUEST_RESOLUTION_CODE REQUEST_CLOSURE_STATUS REQUEST_RESOLUTION_VIEW REQUEST_RESOLUTION_EDIT REQUEST_ROOT_CAUSE_VIEW REQUEST_ROOT_CAUSE_EDIT REQUEST_FURTHER_ACTIONS_REQUIRED_VIEW REQUEST_FURTHER_ACTIONS_REQUIRED_EDIT REQUEST_ACTIONS_COMPLETED_FLAG REQUEST_DATA_UPDATED_FLAG REQUEST_EFFORT Duplicate age The DUPLICATE_AGE option controls the checking of duplicate eents that can cause duplicate problems to be created. DUPLICATE_AGE is specified in minutes, with a default alue of 5 minutes. To specify the DUPLICATE_AGE option, run the following SQL statements: INSERT INTO SystemConfiguration VALUES ( AUTO_PROBLEM, DUPLICATE_AGE, duplicate_age, INT ) UPDATE MenuItemVersion SET erno = erno + 1 Problem system NetView used The PROBLEM_SYSTEM_NETVIEW_USED option pertains to problems only. The PROBLEM_SYSTEM_NETVIEW_USED option has a alue of YES or NO. If this option is not specified in the SystemConfiguration table, the integration function uses a default alue of NO. This option is required with a alue of YES for problem systems where data is passed through the NetView program. If the alue is YES, the user is prompted as needed for a alid NetView user ID and password. After entering this information, the user does not hae to enter it again unless the password becomes not alid, the preferences file is deleted from the user s system, or the console serer is restarted. If the option has a alue of NO (or is not specified), the user is not prompted for a NetView user ID and password. Howeer, if the system uses the NetView program, then the create or update action cannot complete successfully. To specify this option, run SQL statements similar to the following statements: INSERT INTO SystemConfiguration VALUES ("API_INTEGRATION_OPTIONS","PROBLEM_SYSTEM_NETVIEW_USED","YES","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 Chapter 5. Enabling a request processor 71

86 Suppress display of OK message box When a problem ticket or change request is created from the console, a message box is displayed containing the problem or change ID and a message to indicate that the problem ticket or change request was successfully created. If this message is not useful to the user, the message box can be suppressed. That means that, if the problem ticket or change request is created successfully, no message box is displayed and the interface ends without any notification to the user. Howeer, if an error occurs in processing, a message box with an error message is displayed. Use the console preference option to suppress the OK message box for a successful problem ticket or change request create and update; for more information, use the Task Assistant for the console. Table-based enumerations The TABLE_BASE_ENUMERATIONS option pertains to both problem and change console functions. This option loads a large number of drop-down list alues for problem or change requests into a table. An SQL Serer batch job periodically calls the request processor to proide the alues to populate the tables or to refresh the alues. If the TABLE_BASE_ENUMERATIONS option is enabled, the enumeration alues are returned to the console from the table instead of calling the request processor to return the alues for each drop-down list. This improes performance when you define a large number of drop-down list alues. The suggested threshold for using this option is when the total number of alues defined for all drop-down lists is about 50; howeer, the performance is improed regardless of the number. To enable the TABLE_BASE_ENUMERATIONS option, run the following SQL statements: INSERT INTO SystemConfiguration VALUES ( API_INTEGRATION_OPTIONS, TABLE_BASE_ENUMERATIONS, YES, CHAR ) UPDATE MenuItemVersion SET erno = erno + 1 For details about populating the IntegrationEnumeration table, see Loading large olume problem enumeration alues on page 22 for problem tickets and Loading large olume change enumeration alues on page 42 for change requests. Ticket create default The TICKET_CREATE_DEFAULT option pertains to problems only. The TICKET_CREATE_DEFAULT option has a alue of YES or NO. If this option is not specified in the SystemConfiguration table, the integration function uses a default alue of NO. If the row has a alue of YES, the Create Problem check box in the note editor is automatically selected. This is applicable only for taking ownership of an eent and creating an ownership note. After the new ownership note information is entered and the user clicks OK, the Create Problem window is displayed. Upon successful creation, the problem ID is linked to the new ownership note and control is returned to the ownership note window. If this option has a alue of NO or is not specified, the Create Problem check box is cleared. When the ownership note information is entered and the user clicks OK, the Create Problem window is not displayed and no problem ID is linked to the new ownership note. Howeer, if the user manually checks the Create Problem 72 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

87 check box before clicking OK, the create problem window is displayed to create a problem and link the problem ID to the ownership note. Manual selection of the Create Problem check box affects only the current ownership note creation and is not remembered for the next ownership note creation. To enable this option, run the following SQL statements: INSERT INTO SystemConfiguration VALUES ("API_INTEGRATION_OPTIONS","TICKET_CREATE_DEFAULT","YES","CHAR") UPDATE MenuItemVersion SET erno = erno + 1 Timeout alue The TIMEOUT_VALUE option contains a alue specified in seconds. If this option is not specified, the default alue is 45 seconds. The problem, change and non-batch automatic ticket integration functions use this time alue to wait for the request processor to create the GUIDout file. If the time alue is exceeded, the problem, change, and non-batch automatic ticket integration functions flag the request as unsuccessful and return to the console to display a timeout error message. To specify this option, run SQL statements similar to the following statements: INSERT INTO SystemConfiguration VALUES ("API_INTEGRATION_OPTIONS","TIMEOUT_VALUE","60","INTEGER") UPDATE MenuItemVersion SET erno = erno + 1 Origin alues: system, component, item, module The origin options oerride the Tioli Business Systems Manager database information for a particular resource. Objects are organized into a hierarchy that has the following leels: system, component, item, module. The alues for these leels, referred to as the origin or SCIM alues, can control the workflow of a process or can be default alues used in processing data. Origin alues are used by the Tioli Business Systems Manager problem and change integration functions to aid in searches. Tioli Business Systems Manager also uses these alues in creating problem tickets and change requests. For these alues to be used, the tables must be configured properly for your installation. The SystemConfiguration table controls how each leel of the SCIM hierarchy receies the default alue when a problem is created. The SystemConfiguration table supports one row for each leel of the SCIM hierarchy. Each leel can either use the alue supplied with Tioli Business Systems Manager or look up the alue in the TSD_SCIM table. For more information about the TSD_SCIM table, see TSD_SCIM table on page 74. The origin options hae two alues: LOOK_UP and AUTO_CREATE. If the alue is LOOK_UP, the problem and change integration functions obtain the oerride alues from the TSD_SCIM table. If the alue is AUTO_CREATE, the problem and change integration functions accept the Tioli Business Systems Manager default alues. The alues for system, component, item, and module are passed to a request processor in the REQUEST_ORIGIN_SYSTEM, REQUEST_ORIGIN_COMPONENT, REQUEST_ORIGIN_ITEM, and REQUEST_ORIGIN_MODULE name-alue pairs, respectiely. For problem tickets only, they are also passed in the REQUEST_SYSTEM, REQUEST_COMPONENT, REQUEST_ITEM, and REQUEST_MODULE name-alue pairs. Chapter 5. Enabling a request processor 73

88 These alues are also displayed in the problem interface with the following labels: SYSTEM: COMPONENT: ITEM: MODULE: If you customized these fields in the problem ticket interface to display different field names and alues, then you cannot use a alue of LOOK_UP in the SystemConfiguration and TSD_SCIM tables. The following example from a SystemConfiguration table shows what the SCIM alues might look like.in this example, the alues for system, component, and item are looked up in the TSD_SCIM table. For module, the Tioli Business Systems Manager default alue is used. id groupname propertyname propertyalue propertydatatype 1 API_INTEGRATION_OPTIONS ORIGIN_SYSTEM LOOK_UP CHAR 2 API_INTEGRATION_OPTIONS ORIGIN_COMPONENT LOOK_UP CHAR 3 API_INTEGRATION_OPTIONS ORIGIN_ITEM LOOK_UP CHAR 4 API_INTEGRATION_OPTIONS ORIGIN_MODULE AUTO_CREATE CHAR TSD_SCIM table The TSD_SCIM table stores the SCIM alues (for system, component, item, module), which can be used in problem ticket creation to identify the resource class associated with a problem ticket. The table can proide SCIM alues for each Tioli Business Systems Manager resource class, but it is empty when the Tioli Business Systems Manager program is installed. To oerride some or all of the SCIM default alues, populate this table with your own SCIM alues. The following default alues are used when the SystemConfiguration origin alues either are set to AUTO_CREATE or are not specified. Hierarchy leel system component item module Default alue TBSM object_cid_alue object_id_alue object_name_alue If an origin alue in the SystemConfiguration table is LOOK_UP, the TSD_SCIM table is used to initialize the SCIM alues for the problem. The following example rows in the TSD_SCIM table show the alues used by Tioli Business Systems Manager if these SCIM alues are configured for LOOK_UP in the SystemConfiguration table. CID System Component Item Module CICS SW TRANSACTION_SER CICS CICSA123 DB2 SW DATABASE DB001 DB001_0023 These SCIM alues are passed to the request processor in the following name-alue pairs: For problem tickets or change requests: 74 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

89 REQUEST_ORIGIN_SYSTEM 1 1 SW REQUEST_ORIGIN_COMPONENT 1 1 TRANSACTION_SER REQUEST_ORIGIN_ITEM 1 1 CICS REQUEST_ORIGIN_MODULE 1 1 CICSA123 For display at the console: REQUEST_SYSTEM 1 1 SW REQUEST_COMPONENT 1 1 TRANSACTION_SER REQUEST_ITEM 1 1 CICS REQUEST_MODULE 1 1 CICSA123 Customizing console fields You can tailor the Tioli Business Systems Manager console interface to suit your requirements, for example, to modify a field label to something more specific for your installation or to hide fields that are not needed for your application. Field customization proides a what-you-see-is-what-you-get customization mode. Use console customization to modify field label names so that they conform to the naming conentions of a specific application or to use fields for data that is different from the data in the standard Tioli Business Systems Manager console. If you change a field label, the name-alue pair associated with the field remains the same. You should document your field label modifications and the corresponding name-alue pairs. You should also assign the name-alue pairs to program ariables that hae names that indicate what data is being entered in the customized fields. Thereafter, refer to the ariables in your program to understand how they are being defined and used. Also, you should thoroughly document all customization of name-alue pair mappings to your database elements. For more information about customizing the fields on the Tioli Business Systems Manager console interface, see the IBM Tioli Business Systems Manager Administrator s Guide. Chapter 5. Enabling a request processor 75

90 76 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

91 Appendix A. Problem and change name-alue pairs Problem name-alue pairs The following table lists problem name-alue pairs passed to or returned from a request processor. Some problem data items might not contain a alue if the user did not enter them at the console. Name Description Console label AUTO_CLOSE_DEFAULT DEBUG_MODE DISPLAY_PROBLEM_CLOSURE PROBLEM_CLOSE_VALUES PROBLEM_OPEN_VALUES REQUEST_ACTIONS_COMPLETED_ FLAG REQUEST_ASSIGNEE_GROUP Configuration alue to actiate or deactiate automatic close of a ticket if an associated note is closed: YES = The problem update request is automatically generated with a closed status alue when the note is closed. NO = The problem update request is not automatically generated when the note is closed. Configuration alue to delete or keep GUID.in and GUID.out files and to indicate whether this option is actiated in the SystemConfiguration table: ON = Actiated OFF = Not actiated Code to indicate whether this option (to proide the problem closure interface at the console) is actiated in the SystemConfiguration table: YES = Actiated NO = Not actiated Value or alues used to indicate a closed problem ticket, if your problem management application uses a alue other than Closed. Value or alues used to indicate an open problem ticket, if your problem management application uses a alue other than Open. Flag to indicate further actions are completed: 1 = ON 0 = OFF Group or department of the person assigned to fix the problem Actions Completed: Assignee Group: REQUEST_ASSIGNEE_NAME Name of the person assigned to fix the problem Assignee Name: REQUEST_AUTO_CLOSE REQUEST_AUTO_QUERY_OPEN REQUEST_CLOSE Code to indicate whether the request processor should set the problem ticket to a closed state: YES = Problem should be processed for close in the problem management application NO = Problem should not be processed for close in the problem management application Used with a request query method to proide a count of open problems: YES = Count open problems NO = Do not count open problems Code to indicate the problem ticket is set to a closed or inactie alue: YES = Problem should be processed for close in target product NO = Problem should not be processed for close in target product Copyright IBM Corp

92 Name Description Console label REQUEST_CLOSURE_STATUS REQUEST_COMPONENT REQUEST_CUSTOMER_ID REQUEST_DATA_UPDATED_FLAG REQUEST_DATE_CREATED REQUEST_DATE_UPDATED Status of the resolution (fixed, circumented, and so on) Associate a resource with a component alue (SCIM alue) Value to associate a customer ID alue to be stored in the long description of a problem ticket Flag to indicated all data has been updated: 1 = ON 0 = OFF Date and time of problem creation (yyyymmdd hhmmss) Date and time the problem was last updated (yyyymmdd hhmmss) Closure Status: Component: REQUEST_EFFORT Time spent on resoling problem (dd:hh:mm) Effort: REQUEST_ENUM_NAME REQUEST_ERROR_MSG REQUEST_EVENT_ALERT_STATE REQUEST_EVENT_CID REQUEST_EVENT_DETAIL REQUEST_EVENT_ID REQUEST_EVENT_NAME REQUEST_EVENT_PRIORITY REQUEST_FURTHER_ACTIONS_ REQUIRED_EDIT REQUEST_FURTHER_ACTIONS_ REQUIRED_VIEW REQUEST_ITEM REQUEST_LOGIN_USER_ID REQUEST_LOGIN_USER_PASSWORD Name of the enumeration list alues sent to the request processor to obtain alues for populating a pull-down or selection list; the following alues are alid: request_get_uids = Obtain alid application user IDs and passwords request_problem_seerity = Obtain alid seerity codes request_status_code = Obtain alid status codes request_problem_type = Obtain alid type codes request_problem_assignee_group = Obtain alid assignee groups request_resolution_closure_status = Obtain alid closure codes request_resolution_code = Obtain alid resolution codes Text message indicating the success or failure of processing the request with the problem application, for example: The problem ticket was successfully created. Alert state of the most recent eent with the highest seerity and priority: alert_state_alue CID of the most recent eent with the highest seerity and priority: CID_alue Detail of the most recent eent with the highest seerity and priority: detail_alue ID of the most recent eent with the highest seerity and priority: ID_alue Name of the most recent eent with the highest seerity and priority: name_alue Priority of the most recent eent with the highest seerity and priority: priority_alue Modified or added text for the further actions required description Current further actions required description displayed as iewable only Associate a resource with an item alue (SCIM alue) Tioli Business Systems Manager login user ID Tioli Business Systems Manager login password Data Updated: Date Created: Date Updated: Further Actions Required: Item: 78 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

93 Name Description Console label REQUEST_LONG_DESCRIPTION_EDIT REQUEST_LONG_DESCRIPTION_VIEW REQUEST_METHOD REQUEST_MODULE REQUEST_NOTE_ID REQUEST_OBJECT_CID REQUEST_OBJECT_ID REQUEST_OBJECT_NAME REQUEST_OBJECT_SOURCE_CID REQUEST_OBJECT_SOURCE_ID REQUEST_ORIGIN_COMPONENT REQUEST_ORIGIN_ITEM REQUEST_ORIGIN_MODULE REQUEST_ORIGIN_SYSTEM REQUEST_PASSWORD Additional problem description; the modified or added text for the erbose problem description; if populated, indicates that all text, can be updated; if blank or empty indicates that new text can only be added or appended Current problem description displayed (can be iewed only) Process function requested Associate a resource with a module alue (SCIM alue) Ownership note ID: ID_alue Selected resource class ID Selected resource ID Name of resource Physical resource class ID Physical resource ID Configuration alue to associate a resource with a component alue (SCIM alue) Configuration alue to associate a resource with an item alue (SCIM alue) Configuration alue to associate a resource with a module alue (SCIM alue) Configuration alue to associate a resource with a system alue (SCIM alue) Application password entered that is associated with REQUEST_USER_ID Module: Password: REQUEST_PROBLEM_ID Problem ticket number or ID Problem ID: REQUEST_PROBLEM_TYPE REQUEST_QUERY_TYPE REQUEST_RESOLUTION_CODE REQUEST_RESOLUTION_EDIT REQUEST_RESOLUTION_VIEW REQUEST_RETURN_CODE Type of problem (such as software or hardware) Used with a request query method to indicate the type of query being requested: REQUEST_ADHOC = Query requested by user and entered with search arguments REQUEST_INITIAL = Query requested prior to display on console Cause code (hardware, usage, and so on) associated with the resolution Modified or added text for the resolution description Current resolution description displayed (can be iewed only) Numeric alue indicating the success or failure of processing the request with the problem management application: 0 = Successful Nonzero alue (such as -12 or 9999) = Unsuccessful Problem Type: Resolution Code: Resolution: REQUEST_ROOT_CAUSE_EDIT Modified or added text for the root cause Root Cause: REQUEST_ROOT_CAUSE_VIEW REQUEST_SEVERITY REQUEST_SHORT_DESCRIPTION Current root cause description displayed (can be iewed only) Problem seerity; must contain a alue and a description, such as 01 Critical, 02 High, and so on Brief problem description Seerity: Appendix A. Problem and change name-alue pairs 79

94 Name Description Console label REQUEST_STATUS_CODE REQUEST_SYSTEM REQUEST_TOTAL_EVENT_COUNT REQUEST_TYPE REQUEST_USER_ID TICKET_CREATE_DEFAULT TIMEOUT_VALUE Status of the problem (such Initial, Open, or Closed) Associate a resource with a system alue in the console (SCIM alue) Number of eents owned: count_alue Type of request for the problem management application Application User ID selected from the pull-down populated by your request processor using alues from the application Code to indicate this option is actiated in the SystemConfiguration table: YES = Actiated NO = Not actiated Value in seconds for the wait time before the problem integration function times out (default = 45 seconds) Status Code: System: User ID: Change name-alue pairs The following table lists change name-alue pairs that are passed to or returned from a request processor. Some change data items might not contain a alue if the user did not enter them at the console. Name Description Console label CHANGE_CLOSE_VALUES CHANGE_OPEN_VALUES DEBUG_MODE REQUEST_ACCEPT_START_DATE REQUEST_APPROVAL_STATUS REQUEST_AUTO_QUERY_OPEN REQUEST_BACKUP_PLAN_EDIT REQUEST_BACKUP_PLAN_VIEW Value or alues used to indicate a closed change request, if your change management application uses a alue other than Closed. Value or alues used to indicate an open change request, if your change management application uses a alue other than Open. Configuration alue to delete or keep GUID.in and GUID.out files Accepted start date or the change request (yyyymmdd hhmmss) Value indicating the approal of a change request Used with a request query method to proide a count of open changes: YES = Count open changes NO = Do not count open changes Modified or added text in the backout plan details. If populated, indicates that all text can be updated in the change management application. If blank or empty, indicates that new text can only be added or appended. Current backout plan details displayed as iewable only Acceptance Start Date: Approal Status: Backout Details: REQUEST_CHANGE_ID Change request number or ID Number: REQUEST_CHANGE_TYPE Type of change request Category: REQUEST_COMPLEXITY Complexity of the change Complexity: REQUEST_DATE_CREATED REQUEST_DATE_RAISED Date and time the change request was created (yyyymmdd hhmmss) Date the change was requested (yyyymmdd hhmmss) Date Raised: 80 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

95 Name Description Console label REQUEST_DATE_UPDATED REQUEST_ENUM_NAME REQUEST_ERROR_MSG Date and time the change was updated (yyyymmdd hhmmss) Name of the enumeration list to obtain alues for populating a pull-down or selection list; the following alues are alid: request_change_category = Obtain category alues request_change_complexity = Obtain complexity alues request_status_code = Obtain alid status codes request_change_impact = Obtain alid impact alues request_change_site = Obtain alid site or location alues request_requestor_name = Obtain alid requestor names request_requestor_dept = Obtain alid department or group alues Text message indicating the success or failure of processing the request with the change application, for example: Change request was successfully created REQUEST_FIX_PROBLEM_ID Problem ID associated with the change request Problem Number: REQUEST_LOB_IMPACT_EDIT REQUEST_LOB_IMPACT_VIEW REQUEST_LOCATION_CODE REQUEST_LOGIN_USER_ID REQUEST_LOGIN_USER_PASSWORD REQUEST_LONG_DESCRIPTION_EDIT REQUEST_LONG_DESCRIPTION_VIEW REQUEST_METHOD REQUEST_OBJECT_CID REQUEST_OBJECT_ID REQUEST_OBJECT_NAME REQUEST_OBJECT_SOURCE_CID REQUEST_OBJECT_SOURCE_ID REQUEST_ORIGIN_COMPONENT Modified or added text in the business impact. If populated, all text can be modified. If blank or empty, text can be added or appended only. The console field is prepopulated with a textual representation of the business impact. Due to performance considerations, impact descriptions that are longer than approximately 2000 characters are truncated; that is, the description is truncated at the end of the node name that causes the description to exceed 2000 characters. Operators can edit the prepopulated alue and, although they can add unlimited text, they should limit the amount of text they add. Current business impact of the change request displayed as iewable only Site, location, or complex requiring the change request Tioli Business Systems Manager login user ID Tioli Business Systems Manager login password Modified or added text in the erbose description. If populated, indicates that all text can be modified. If blank or empty, indicates that text can be added or appended only. Current erbose description of the change request displayed as iewable only Process function requested Selected resource class ID Selected resource ID Name of resource Physical resource class ID Physical resource ID Configuration alue to associate a resource with a component alue (SCIM alue) BS Impact: Site/Location/Complex: Appendix A. Problem and change name-alue pairs 81

96 Name Description Console label REQUEST_ORIGIN_ITEM REQUEST_ORIGIN_MODULE REQUEST_ORIGIN_SYSTEM REQUEST_PASSWORD REQUEST_PLAN_END_DATE REQUEST_PLAN_START_DATE REQUEST_PROJ_CHG_NBR REQUEST_QUERY_TYPE Configuration alue to associate a resource with an item alue (SCIM alue) Configuration alue to associate a resource with a module alue (SCIM alue) Configuration alue to associate a resource with a system alue (SCIM alue) Application password entered that is associated with the REQUEST_USER_ ID Planned end date for the change request (yyyymmdd hhmmss) Planned start date for the change request (yyyymmdd hhmmss) Project or change number assigned to the change request Used with a request query method to indicate the type of query being requested; alid alues are REQUEST_INITIAL and REQUEST_ADHOC Password: Planned End: Planned Start: REQUEST_REASON Reason for creating the change request Reason: REQUEST_REQUESTOR_CONTACT_ NBR REQUEST_REQUESTOR_DEPT REQUEST_REQUESTOR_NAME REQUEST_RETURN_CODE Phone or extension of the person requesting the change Department or group of the person requesting the change request Name of the person requesting the change request Numeric alue indicating the success or failure of processing the request with the change management application: 0 = Successful Nonzero alue (such as -12 or 9999) = Unsuccessful Project/Change Number: Contact No: Department/Group: Name: REQUEST_RISK_ASSESSMENT Represents impact or risk Impact: REQUEST_SHORT_DESCRIPTION REQUEST_STATUS_CODE REQUEST_TYPE REQUEST_UDF_CHECK1 REQUEST_UDF_CHECK2 REQUEST_UDF_CHECK3 Brief description of the change request Status of change request such as (initial, open, or closed) Type of request for the change management application User-defined check box: 1 = ON 0 = OFF User-defined check box: 1 = ON 0 = OFF User-defined check box: 1 = ON 0 = OFF Status: Check 1: Check 2: Check 3: REQUEST_UDF_TEXT1 User-defined text box - can be edited Extra Field 1: REQUEST_UDF_TEXT2 User-defined text box - can be edited Extra Field 2: REQUEST_UDF_TEXT3 User-defined text box - can be edited Extra Field 3: REQUEST_USER_ID TIMEOUT_VALUE Application user ID selected from the pull-down populated by the request processor using alues from application Configuration alue, in seconds, that the integration function waits for a request processor to create the GUID.out file User ID: 82 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

97 Appendix B. Sample integration for the Information Management for z/os product This appendix proides an example for integrating Tioli Business Systems Manager with a problem or change management application. It explains how to install and configure the sample integration for the Information Management for z/os product (preiously named Serice Desk for OS/390) on the Windows and z/os operating systems. Use these sample programs and process flow as a model for creating an integration based on your application, platform, and customization needs. The sample integration for Information Management for z/os requires the NetView for z/os program, Version 1.3 or later, and is designed to work with Serice Desk for OS/390, V1.2 or Information Management for z/os, V7.1. It should work with older ersions of Serice Desk for OS/390, but you might need to adjust program interface data tables (PIDTs) or API calls. If you customized Information Management for z/os, the sample integration might not function properly, and you might need to modify the sample integration to reflect your customization, for example, structured words (s-words), prefix words (p-words), and PIDTs. In this appendix, the Tioli BSM Task Serer serice is referred to as the Task Serer serice. Sample files The sample REXX scripts that need to reside on the Tioli Business Systems Manager SQL Serer are proided in the Program Files\Tioli\tbsm\Data directory. These REXX scripts, known as file processors, receie data from the Tioli Business Systems Manager console and transfer the data to the NetView for z/os program to run the sample z/os REXX scripts, known as request processors. The z/os request processors format the data receied into the appropriate API calls to either Information Management for z/os, V7.1 or Serice Desk for OS/390, V1.2. The following REXX scripts are the file processors: TSD390RPin.rex TSD390RPout.rex The following REXX scripts, which are found in the \TioliManager\Data\ProbChgSamples\infoman-tsd39071.zip file, are the z/os request processors: GTMSDRP Sample z/os problem request processor GTMCGRP Sample z/os change request processor GTMATRP Sample z/os automatic ticket request processor Do not use the samples for your integration, but, instead, use them as a starting point for your request processor. To do that, make copies of them, change the file name, and customize the renamed copies to meet your requirements and work with your application. These sample programs work with a non-customized Copyright IBM Corp

98 Information Management for z/os product. Howeer, if you customized this product, the samples might not function with your problem and change management applications. You must adjust, add to, or delete from the sample programs for them to work with your customized Information Management for z/os product. If you are using the sample problem request processor to create a customized ersion of the interface to your Information Management for z/os application, you must apply the following APARs: Serice Desk for OS/390, V1.2: OW55908 PTFs AW55908 and BW55908 Information Management for z/os, V7.1 OW55907 PTFs AW55907 and BW55907 NetView for OS/390, Version 1, Release 3 OW50555 to support a large buffer size needed for the Task Serer serice interface to the NetView program PTF UW82424 Sample integration oeriew and workflow If your application and request processor reside on a z/os system, you need a process to pass the request data from the input file to the z/os system and to start the appropriate request processor. The input file resides on the Tioli Business Systems Manager database serer in the Program Files\Tioli\tbsm\Data folder. Additionally, the results returned from the z/os request processor must be processed to create an output file. Most applications proide an SDK distributed interface to an application, which resides on a z/os operating system. You can eliminate extra processing by using this interface to transfer data from the Tioli Business Systems Manager database serer to the z/os host operating system. You can determine the implementation of the data transfer between the Windows and z/os operating systems, based on the functions proided by your application or supported within your enironment. One method of transferring data between the Windows and z/os operating systems is proided in the sample request processor for integration with the Information Management for z/os product. Use these REXX programs and this process only as an example. You need to determine the best approach for the interface between your Windows and z/os operating systems. The workflow for the sample integration with the Information Management for z/os application, which is shown in Figure 2 on page 85, has the following steps. The application can be any application residing on the z/os system, for example, the Peregrine Systems Change Management Solution. 1. The first sample file processor (TSD390RPin.rex) processes the input file. The primary function of this file processor is to receie the request data, format it, and send the data to NetView for z/os, using the Task Serer serice and NetView NETCONV commands. 2. The NetView for z/os program receies the data and calls a sample request processor (a z/os REXX program) to process the data. The sample request processors are GTMSDRP, GTMCGRP, and GTMATRP. 84 IBM Tioli Business Systems Manager: Problem and Change Management Integration Guide

99 3. The sample z/os request processors proide an interface to the Information Management for z/os product. They format and run the API calls to the Information Management for z/os database, mapping the request data receied from the Windows operating system to the appropriate database elements using structured words (s-words). 4. The results receied from the API calls are formatted and returned to NetView for z/os. NetView for z/os returns the results to the Windows operating system using the Task Serer serice and NetView NETCONV commands. The Task Serer serice calls the second sample file processor (TSD390RPout.rex), passing it the results. 5. The second sample processor file (TSD390RPout.rex) formats the result into an output file that is processed at the database serer. It also calls IntEentSerer if a problem ticket has a status alue of closed. See Problem integration eent notification on page 27 for details on the IntEentSerer closure process. Tioli Business Systems Manager Database Serer Tioli Business Systems Manager Integration Function Input File Output File File In Processor File Out Processor Tioli BSM Task Serer z/os Host System NetView for z/os Sample z/os Request Processor Information Management for z/os Figure 2. Sample z/os request processor workflow When a problem or change that was originally created from the Tioli Business Systems Manager console is closed from within your problem or change management application, a notification indicating which problem was closed must be generated and sent to the Tioli Business Systems Manager product. An example of this is the problem ticket number process. The sample integration for Appendix B. Sample integration for the Information Management for z/os product 85