BMC Run Book Automation Platform 3.0.

00: Adapter

Developers Guide

April 2008

www.bmc.com

BMC Software, Inc., Confidential

Contacting BMC Software

You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities. United States and Canada Address BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA (01) 713 918 8800 Telephone 713 918 8800 or 800 841 2031 Fax 713 918 8000

Outside United States and Canada Telephone Fax (01) 713 918 8000

If you have comments or suggestions about this documentation, contact Information Design and Development by email at doc_feedback@bmc.com.

Copyright 20052008 BMC Software, Inc. BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. Sun and Java are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. or other countries. BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted rights notices included in this documentation. Restricted Rights Legend U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC Software, Inc., 2101 CityWest Blvd., Houston, TX 77042-2827, USA. Any contract notices should be sent to this address.

BMC Software, Inc., Confidential

Customer Support You can obtain technical support by using the Support page on the BMC Software website or by contacting Customer Support by telephone or email. To expedite your inquiry, please see Before Contacting BMC Software. Support website You can obtain technical support from BMC Software 24 hours a day, 7 days a week at http://www.bmc.com/support_home. From this website, you can: Read overviews about support services and programs that BMC Software offers. Find the most current information about BMC Software products. Search a database for problems similar to yours and possible solutions. Order or download product documentation. Report a problem or ask a question. Subscribe to receive email notices when new product versions are released. Find worldwide BMC Software support center locations and contact information, including email addresses, fax numbers, and telephone numbers. Support by telephone or email In the United States and Canada, if you need technical support and do not have access to the Web, call 800 537 1813 or send an email message to customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>, such as SupID:12345.) Outside the United States and Canada, contact your local support center for assistance. Before contacting BMC Software Have the following information available so that Customer Support can begin working on your issue immediately: Product information o Product name o Product version (release number) o License number and password (trial or permanent) Operating system and environment information o Machine type o Operating system type, version, and service pack o System hardware configuration o Serial numbers o Related software (database, application, and communication) including type, version, and service pack or maintenance level Sequence of events leading to the problem Commands and options that you used Messages received (and the time and date that you received them) o Product error messages o Messages from the operating system, such as file system full o Messages from related software

BMC Software, Inc., Confidential

License key and password information If you have a question about your license key or password, contact Customer Support through one of the following methods: E-mail customer_support@bmc.com. (In the Subject line, enter SupID:<yourSupportContractID>, such as SupID:12345.) In the United States and Canada, call 800 537 1813. Outside the United States and Canada, contact your local support center for assistance. Submit a new issue at http://www.bmc.com/support_home

BMC Software, Inc., Confidential

Table of Contents
INTRODUCTION .........................................................................................................................................6

AUDIENCE .....................................................................................................................................6 ADAPTER OVERVIEW ....................................................................................................................7 Adapter Configuration ..............................................................................................................7 Actor Adapter ............................................................................................................................8 Monitor Adapter........................................................................................................................8 ADAPTER CONSTRUCTION OVERVIEW .........................................................................................9 DEPENDENCIES .............................................................................................................................9
ADAPTER CONFIGURATION ................................................................................................................10

ADAPTER CONFIGURATION CLASS .............................................................................................10 VALID AND REQUIRED KEYS ......................................................................................................10 BASEADAPTERCONFIGURATION PARAMETERS ..........................................................................12 BUILDING YOUR OWN ADAPTER CONFIGURATION ....................................................................13 EXAMPLE ADAPTER CONFIGURATION: CONFIGURABLERESPONSEADAPTERCONFIG...............14
ADAPTER MESSAGES .............................................................................................................................16

ADAPTER REQUESTS ...................................................................................................................16 ADAPTER RESPONSES .................................................................................................................17 ADAPTER EVENTS .......................................................................................................................18

BUILDING ACTOR ADAPTERS .............................................................................................................19

ACTOR ADAPTER LIFECYCLE .....................................................................................................19 ACTOR ADAPTER CLASS FRAMEWORK ......................................................................................21 Example Adapter: ConfigurableResponseAdapter ................................................................23
BUILDING MONITOR ADAPTERS........................................................................................................25

MONITOR ADAPTER LIFECYCLE .................................................................................................25 MONITOR ADAPTER CLASS FRAMEWORK ..................................................................................27 Example Monitor Adapter: MockMonitorAdapter.................................................................28
DEPLOYING ADAPTERS ........................................................................................................................29

INTRODUCTION
The BMC Run Book Automation Platform 3.0.00 Adapter Developers Guide provides information on BMC Run Book Automation Adapter construction. The basic Adapter framework will be explained as well as details on extending this framework to create custom Adapters. This document focuses on the three major components of the Adapter framework, which are the configuration, messaging and adapter. This document will discuss the make-up of a configuration and the significance of its valid and required keys. Next, the Adapter messages will be presented, providing information on the all three types of messages- Adapter request, Adapter response and Adapter event. Lastly, this document explains the steps for creating an Actor or Monitor Adapter along with an example and outline of the Adapter lifecycle. The information provided in this document is complimented by the Adapter SDK Javadoc, available from Customer Support.

Audience
This document is intended for developers that will be creating custom Adapters to be used with BMC Run Book Automation.

Adapter Overview
Adapters provide BMC Run Book Automation workflow processes the ability to perform specialized functions and to interface with external applications. The Adapter framework supports two types of Adapters: Actor Adapters - Adapters that can perform specialized functions or can serve as an interface to interact with external systems. Actor Adapters send commands or requests and, in some cases, receive responses to the requests that can be utilized by the workflow process. Monitor Adapters - Adapters that listen on external systems and, based on their configuration, generate an event message. These events are evaluated by rules and can trigger specific workflow processes when the rule criteria is met.

Adapter Configuration
The following figure depicts the basic steps in the Adapter configuration process.

1 Adapter configuration information entered via Grid Manager (GM) 2 Adapter configuration passed from GM to the Adapter Manager 3 Adapter Manager creates an instance of an Adapter configuration and loads the Adapter

Actor Adapter
The following figure depicts the Actor Adapter function in BMC Run Book Automation.

1 RBA Process makes an Adapter request 2 Adapter Manager sends the request to the Adapter instance 3 Actor Adapter formats the request and sends it to an external system

4 External system returns a response 5 Actor Adapter formats the response into an Adapter response 6 Adapter response is returned to the Process (Note: Not all Adapters return a response that is available for use in the Process)

Monitor Adapter
The following depicts the Monitor Adapter function in BMC Run Book Automation.

1 Monitor polls an external system (pull) or receives an incoming message (push) 2 Monitor Adapter formats the input into an Adapter event

3 Adapter Manager sends the Adapter event to the active rules 4 The Adapter event is evaluated against active rules. If the rule validation succeeds, a Process is triggered

Adapter Construction Overview

The construction of each Adapter begins with a configuration. The class BaseAdapterConfiguration provides the basic configuration required by an Adapter. This class may be extended to include additional configuration information as needed. The AbstractActorAdapter and AbstractMonitorAdapter classes extend AbstractAdapter and implement ActorAdapter and MonitorAdapter respectively. These classes provide the core methods and functionality for creating a custom Adapter. The most basic Actor Adapter will only require the implementation of the performAction() method, while a basic Monitor Adapter requires only the run() method to be implemented. If a custom Adapter configuration class is used, then, a method called getAdapterConfigurationClassName() shall be implemented as indicated below:
/** * Returns the Configuration Class name for this adapter * @return String the fully qualified class name for this adapter */ public String getAdapterConfigurationClassName() { return CustomAdapterConfiguration.class.getName(); }

Finally, upon completion of the Adapter, the classes should be placed in a JAR file. This JAR file will need to be uploaded via the Grid Manager to deploy the custom Adapter. Details on deployment are provided in the Deploying Adapters section of this document.

Dependencies
The following JAR files need to be included in the CLASSPATH variable of the development environment in which the Adapter will be created. These files are located in the $RBA_HOME/lib/shared directory of a BMC Run Book Automation installation. This location may be referenced, or the files may be copied to another location for reference.
ro-foundation2.5.X.X.jar log4j-1.2.8.jar jdom-1.0.jar ro-common2.5.X.X.jar

2007 BMC Software, Inc.

ADAPTER CONFIGURATION
The Adapter configuration that is received from the Grid Manager contains the unique Adapter name, type, version and properties. This information is used to create an instance of an Adapter and also when servicing an Adapter request.

Adapter Configuration Class

The following class is the base class for all Adapter configurations:
com.realops.foundation.adapterframework.configuration.BaseAdapterConfiguration

It is used to store the basic configuration information, like Adapter name, necessary for any Adapter. This class supports the validation of the configuration data stored within.

Valid and Required Keys

In the Adapter framework, each configuration property is called a key. If the configuration class is aware that a key may be present in a configuration file, it is called a valid key. When parsing the XML configuration file for an Adapter, BaseAdapterConfiguration uses the set of valid keys to retrieve and store values. If the Adapter configuration class requires a valid key to be present, it is also considered a required key. If the validate() method is called and a configured value is not present for one or more required key, an InvalidConfigurationException will be thrown. New keys are registered by calling the addValidKey() method, provided in BaseAdpaterConfiguration. If a key is also to be a required key, the addRequiredKey() method is called. A key must be registered as a valid key before it can be indicated as a required key. The following sample adds KEY1 and KEY2 as valid keys and adds KEY1 as a required key.

10

Public class CustomeAdapterConfiguration extends BaseAdapterConfiguration { public CustomeAdapterConfiguration (String id , Hashtable defaults) { super(id, defaults); // init the various key sets this.initValidKeys(); this.initRequiredKeys(); } /** initializes the set of valid configuration keys */ private void initValidKeys(){ this.validKeySet.add(KEY1); this.validKeySet.add(KEY2); } /** initializes the set of required keys */ private void initRequiredKeys(){ this.requiredKeySet.add(KEY1); } }

Values corresponding to keys are stored and retrieved using setProperty() and getProperty() methods provided by the BaseAdapterConfiguration class. Alternatively custom methods may be created to store and retrieve values as follows:
public void setKey1(String value){setProperty(KEY1, value);} public String getKey1(){ return getProperty(KEY1); }

For keys that are not provided by default in BaseAdapterConfiguration, an extended BaseAdapterConfiguration class needs to provide accessor methods as described in the Building Your Own Adapter Configuration section of this document.

11

BaseAdapterConfiguration Parameters
The Adapter configuration is stored as an XML document. A sample of an Adapter configuration XML document that utilizes the keys in BaseAdapterConfiguration is provided below.
<adapter id="anAdapterId"> <name>myAdapter</name> <adapter-implementation-descriptor> <adapter-type>myAdapterType</adapter-type> <adapter-version>currentVersion</adapter-version> </adapter-implementaion-descriptor> <config> <target>foo</target> <port>22</port> <timeout-secs>120</timeout-secs> </config> </adapter>

The BaseAdapterConfiguration class contains two required keys, as described in Table 1. Table 1: Basic Adapter Configuration Required Keys Key id name Description
This is a system generated internal id. This value is an attribute of the <adapter> element in the XML document. The unique name of the Adapter.

Because many Adapters interface with external systems, the keys described in Table 2 have been included in BasicAdpaterConfiguration as valid keys. Table 2: Basic Adapter Co nfiguration Valid Keys Key target port timeout-secs Description
A key that could be used to define the target name/ip of the host with which the Adapter will interact. A key that could be used to define the port on the target that the Adapter should use for interaction. A key that could be used in an Adapter request to implement a timeout mechanism. No.

Default Value Provided?

Yes. In the absence of a defined value, a default value of -1 is assigned. Yes. In the absence of a defined value, a default value of 60 seconds is assigned.

The BaseAdpaterConfiguration class may be extended to register additional valid keys and/or to indicate one or more of the included valid keys as being a required key.
12

Building Your Own Adapter Configuration

If you are building an Adapter that does not need any configuration information beyond that provided by BaseAdapterConfiguration, there is no need to build a new configuration class for your Adapter. However, if you do need to add extra configuration keys, it is very simple to extend BaseAdapterConfiguration to handle the new keys. Use the following steps when building your new Adapter configuration: 0. Create a new class that extends BaseAdapterConfiguration. Alternately, you may extend another Configuration class that has already extended BaseAdapterConfiguration. 0. In your constructor, register the new keys as valid keys by calling the addValidKey() method. 0. If any of the newly created valid keys are also required keys, register them as such in your constructor, using the addRequiredKey() method. 0. You may wish to provide specific accessors to the new keys. To do this, create a method that retrieves the key using the getProperty() method in BaseAdapterConfiguration. As an example, if we have the key MyKey represented in the XML as key-name:
Public String getMyKey(){ Return super.getProperty(key-name); }

0. There is no need to override any of the BaseAdapterConfiguration methods such as equals(), fromXML(), or validate() unless you need to add behavior to those methods. If you do find the need to add behavior, you must invoke the parent method.

13

Example Adapter Configuration: ConfigurableResponseAdapterConfig

In order to make it easier to explain how to develop Adapters, we will build a simple example Adapter that will return a response that is set in its configuration. This Adapter will be called the ConfigurableResponseAdapter, and will reside in the package com.realops.adapter. The first step is to build the configuration for our example Adapter. ConfigurableResponseAdapter will need to return a pre-configured value to every request it receives. This means we will need to add a new key to the Adapter configuration, requiring us to extend the BaseAdapterConfiguration class. This key will be represented by the string response in the config node of the Adapter. The target and port values of BaseAdapterConfiguration will not be used. Our XML configuration file will look as follows:
<adapter id="responseAdapterId"> <name>responseAdapter</name> <adapter-implementation-descriptor> <adapter-type>myAdapterType</adapter-type> <adapter-version>currentVersion</adapter-version> </adapter-implementaion-descriptor> <config> <response>bar</response> </config> </adapter>

Now that we have defined the configuration file, we can define the class for it. The code for the Adapter configuration is as follows:
package com.realops.adapter.configuration; public class ConfigurableResponseAdapterConfig extends BaseAdapterConfiguration { // define the string representation of the key name public static final String RESPONSE_KEY = "response"; // define the constructor public ConfigurableResponseAdapterConfig(String AdapterId) { super(adapterId); // register the new key super.addValidKey(RESPONSE_KEY); // make it required super.addRequiredKey(RESPONSE_KEY); } // add an accessor for the new key public String getResponse() { yeah return super.getProperty(RESPONSE_KEY); } 14

15

ADAPTER MESSAGES
There are three types of messages utilized by the Adapter framework: Adapter requests, Adapter responses, and Adapter events. Actor Adapters receive requests then generate responses, and Monitor Adapters generate events from asynchronous triggers or polling.

Adapter Requests
An Adapter request contains the necessary information for an actor Adapter to perform an action. An Adapter request is represented by the com.realops.foundation.Adapterframework.AdapterRequest class. An Adapter request consists of the components described in Table 3. Table 3: Adapter Request Components Component target-Adapter peer-location Description
The name of the Adapter that should handle the request. Indicates the Peer on the Grid to which the request should be routed, as represented by the
com.realops.foundation.PeerLocation

Required?
Yes. Yes.

location

class. Indicates the Peer that should handle the request. Valid Values: any - any Peer running an Activity Processor. best - the best Peer according to the health statistics reported by each Peer. this - the Peer that contains the master scheduler. peer - the named Peer The name of the specific Peer that will handle the request.

Yes.

peer-name

request-action request-data

Used to indicate what action the Adapter should take with the request. XML data the Adapter should use when handling the request.

Conditional. This element is required only when peer is provided as a value for the <location> element. Adapter dependant. Adapter dependant.

16

A sample Adapter request is shown below.

<adapter-request> <target-adapter>responseAdapter</target-adapter> <peer-location> <location>this</location> <peer-name/> </peer-location> <request-action/> <request-data> <!-- Specific Adapter information--> </request-data> </adapter-request>

This XML document shows an Adapter request for the sample ConfigurableResponseAdapter to execute on the local peer. The required elements of an Adapter request are defined by writing an Adapter class that extends the AbstractAdapter class, specifically by implementing the performAction() method. Please reference the Adapter SDK Javadoc for more information.

Adapter Responses
After an actor Adapter performs a request, it returns its response. An Adapter request is represented by the com.realops.foundation.adapterframework.AdapterResponse class. An Adapter response consists of the components described in Table 4. Table 4: Adapter Response Components Component execution-duration status Description
Amount of time, in milliseconds, it took to perform the requested action. Indicates whether or not the Adapter request was completed successfully. Valid values: success, error Adapter-specific message. If an error occurred during the handling of the request, the error message is written here. XML data returned by the Adapter as a result of performing the request. Yes.

Required?

Yes.

message

Adapter dependant.

data

Adapter dependant.

17

The status field contains a com.realops.common.enumeration.StatusEnum enumeration value. The possible values for this are: Value success error Description
The Adapter request completed successfully. The Adapter request did not complete successfully.

A sample Adapter response is shown below.

<adapter-response> <execution-duration>3000</execution-duration> <status>success</status> <message/> <data> <response>foo</response> </data> </adapter-response>

The elements of an Adapter response are defined by writing an Adapter class that extends the AbstractAdapter class, specifically by implementing the performAction() method. Please reference the Adapter SDK Javadoc for more information.

Adapter Events
Monitor events do not accept requests, and as such cannot generate a response. Instead, monitor Adapters generate an Adapter Event when an event for which they monitor occurs. An Adapter event has the components described in Table 5. Table 5: Adapter Event Components Component source-adapter event data Description
The Adapter that generated the event. Name or short text describing the event. XML Data concerning the event. Yes. Adapter dependent. Adapter dependent.

Required?

A sample Adapter event is shown below.

<adapter-event> <source-adapter>myMonitorAdapter</source-adapter> <event>test event</event> <data> <sample-event-data>test data</sample-event-data> </data> </adapter-event>

18

BUILDING ACTOR ADAPTERS

Actor Adapter Lifecycle
The Adapter Manager (manager) for the peer the Actor Adapter (actor) will run on is responsible for managing all lifecycle events. The events in an actors lifecycle occur in the following order: 0. The manager attempts to instantiate the Adapter. 0. The manager sets the id and name of the actor. 0. The manager obtains the actors configuration from the system and validates it. 0. The manager provides the configuration to the actor by calling
getConfiguration().fromXml().

0. The manager initializes the actor by calling the initialize() method. 0. The manager registers the health of the Adapter with the system. At this point, the manager will start passing requests to the Adapter via the performAction() method. The manager will call the shutdown() method if a request to shut down the Adapter is received.

0.

0. If the initialization phase throws an exception, the Adapter state will be set to FAULT. This can be resolved programmatically within the Adapter code, or by fixing the condition that caused the fault and restarting the Adapter though the Grid Manager.

19

The following diagram illustrates the standard Actor Adapter lifecycle

20

Actor Adapter Class Framework

All Actor Adapters must implement the
com.realops.foundation.adapterframework.ActorAdapter interface, which itself extends the Adapter interface. AbstractActorAdapter is an abstract class that extends AbstractAdapter and implements ActorAdapter, providing most of the necessary logic. Using AbstractActorAdapter, only the performAction() method

needs to be implemented in order to create a working actor Adapter. For more information on the API, please review the Adapter SDK Javadoc for the appropriate classes. In standard usage of the Adapter, when the Adapter is configured in the Grid Manager, an Adapter ID will be assigned automatically. An Adapter configuration can be created manually by invoking the AbstractAdapter.createConfiguration(id) method. This method will correctly return an instance of the Adapter configuration class returned by the getAdapterConfigurationClassName() method. Some tips on building Actor Adapters: 8. If you are not using BaseAdapterConfiguration to store your configuration information, you must do the following: . Override getAdapterConfigurationClassName() so that it returns the correct configuration class for your Adapter.

8. You will need to implement the shutdown() method, which at a minimum should set the Adapters run state (setState()) to stopped. This lets the Adapter manager know that it is safe to remove the Adapter from memory. 8. You will need to ensure thread safety within the performAction() method, since multiple Adapter requests can be handled at any one time. 8. Although performAction() can throw an AdapterException if an error occurs, this practice should be avoided. The format for this option is shown below. With a response formatted in this manner, the Process will compensate and will not be permitted to process the error message.
<adapter-response> <metadata> <status>error</status> </metadata> <response-data/> </adapter-response>

21

The recommended response format is shown below. This type of a response will allow the workflow to process the error message and to return information to the user to aid in troubleshooting the issue.
<adapter-response> <metadata> <status>success</status> </metadata> <response-data> <metadata> <status>error</status> <error>error message</error> </metadata> </response-data> </adapter-response>

22

Example Adapter: ConfigurableResponseAdapter

Continuing the example, we need to write the code for our Adapter. We do not need to override the initialize() method, since our Adapter does not need any initialization in order to do its job.
package com.realops.foundation.Adapterframework; import com.realops.common.enumeration.StateEnum; import com.realops.common.enumeration.StatusEnum; import com.realops.foundation.Adapterframework.configuration.BaseAdapterConfiguration; import com.realops.Adapter.configuration.ConfigurableResponseAdapterConfig; public class ConfigurableResponseAdapter extends AbstractActorAdapter { /** the configuration for this Adapter */ private ConfigurableResponseAdapterConfig config = null; /** returns the configured response, unless the request is null */ public AdapterResponse performAction(AdapterRequest aRequest) throws AdapterException { if (aRequest != null) { return new AdapterResponse(0, config.getResponse(), null, StatusEnum.SUCCESS); } XML responseDataXml-getErrorResonseDataXml(Request is null); return new AdapterResponse(0,null.responseDataXml, StatusEnum.SUCCESS); } /**return an XML with status set to success and error string set to value in msg. */ private XML getErrorResponseDataXml(String msg){ XML errorXml=new XML(error).setText(Request is null); XML statusXml=new XML(status).setText(StatusEnum.ERROR.getKey()); XML metadataXml=new XML(metadata); metadataXml.addChild(statusXml); metadataXml.addChild(errorXml); XML responseDataXml-new XML(response-data); responseDataXml.addChild(metadataXml); return repsonseDataXml; } 23

public String getAdapterConfigurationClassName() { return CustomAdapterConfigurationClass.class.getName(); } /**Overwrites what is in AbstractAdapter and returns the configuration for this adapter if it is some thing other than BaseAdapterConfiguration. */ /** shuts down the Adapter */ public void shutdown() throws AdapterException { super.setState(StateEnum.STOPPED); } }

24

BUILDING MONITOR ADAPTERS

Monitor Adapter Lifecycle
The Adapter Manager (manager) for the peer the Monitor Adapter (monitor) will run on is responsible for managing all lifecycle events. The events in a monitors lifecycle occur in the following order: 0. The manager attempts to instantiate the Adapter. 0. The manager sets the id and name of the monitor. 0. The manager obtains the monitors configuration from the system and validates it. 0. The manager provides the configuration to the monitor by calling getConfiguration().fromXml(). 0. The manager initializes the monitor by calling the initialize() method. 0. The manager starts the monitor by calling the run() method. At this point the monitor Adapter can start generating events and passing them to the manager. The manager registers the health of the Adapter with the system. At this point, the monitor Adapter can send Adapter Events into the system via the sendEvent() method. The manager will call the shutdown() method if a request to shut down the Adapter is received.

0.

0.

0. If the initialization phase throws an exception, the Adapter state will be set to FAULT. This can be resolved programmatically within the Adapter code, or by fixing the condition that caused the fault and restarting the Adapter though the Grid Manager.

25

The following diagram shows the standard Monitor Adapter Lifecycle

26

Monitor Adapter Class Framework

All Monitor Adapters must implement the
com.realops.foundation.adapterframework.MonitorAdapter interface, which itself extends the Adapter interface. AbstractMonitorAdapter is an abstract class that extends AbstractAdapter and implements MonitorAdapter, providing most of the necessary logic. Using AbstractMonitorAdapter, you only need to implement the run() method in order to create a working monitor Adapter. In addition, AbstractMonitorAdapter provides two sendEvent() methods that allow you to easily send events into the system. For more information on the API, please review the Adapter SDK Javadoc for the appropriate classes.

In standard usage of the Adapter, when the Adapter is configured in the Grid Manager, an Adapter id will be assigned automatically. An Adapter configuration can be created manually by invoking the AbstractAdapter.createConfiguration(id) method. This method will correctly return an instance of the Adapter configuration class returned by the getAdapterConfigurationClassName() method. Some tips on building Monitor Adapters: 0. If you are not using BaseAdapterConfiguration to store your configuration information, you must do the following: . Override getAdapterConfigurationClassName() so that it returns the correct configuration class for your Adapter. 0. You will need to implement the shutdown() method, which at a minimum should set the Adapters run state (setState()) to STOPPED. This lets the Adapter Manager know that it is safe to remove the Adapter from memory. 0. You will need to ensure thread safety within the run() method.

27

Example Monitor Adapter: MockMonitorAdapter

Here is a simple Monitor Adapter that generates a test event every two seconds. This Adapter does not have any configuration properties, so we would use the BaseAdapterConfiguration class. As a result, we do not need to worry about overriding the getAdapterConfigurationClass() methods like we did for the example Actor Adapter.
public class MockMonitorAdapter extends AbstractMonitorAdapter { private volatile boolean run = false; /** * sends an AdapterEvent every 2 seconds. * AdapterEvent string is "test event" */ public void run() { // set our internal flag for our run loop this.run = true; // indicate our run state super.setState(StateEnum.RUNNING); // run loop. Just sleep 2 seconds and send an event while(this.run == true){ try { Thread.sleep(2000); } catch (Exception e){ // no-op } super.sendEvent("test event", null); } // if we get here, we have been asked to stop super.setState(StateEnum.STOPPED); } public void shutdown(){ // set the flag for the thread to stop this.run = false; // wait until our state is stopped while(! super.getState().equals(StateEnum.STOPPED)){} } }

28

DEPLOYING ADAPTERS
Upon completion of the Adapter, it must be uploaded into BMC Run Book Automation via the Grid Manager. The uploaded files are required to define an Adapter Type. This new Type can then be used to configure an Adapter on a Grid. To implement a custom Adapter, use the following steps: 1. Launch Grid Manager and login. 2. Click the Manage tab. Click the Adapters tab, if necessary, to display the Adapters page.

Figure 1: Manage Adapters - Upload Adapter 3. Click the Upload Adapter button, below the Adapters list.

29

Figure 2: Manage Adapters - Custom Adapter - Type 4. The Upload Custom Adapter page will be displayed. Enter <the desired Adapter Type> in the Type field. This value will be displayed in the Type drop-down menu when configuring Adapters.

Figure 3: Manage Adapters - Custom Adapter Version 5. Enter <the desired version for this Adapter Type> in the Version field. This version will be displayed in the Type dropdown menu when configuring Adapters. It will be contained within [ ] and appended to the Type value provided in step 3.

30

Figure 4: Manage Adapters - Custom Adapter Description 6. Enter <the desired description for the custom Adapter Type> in the Description field.

Figure 5: Manage Adapters - Custom Adapter - JAR File 7. Click the button adjacent to the JAR File field. Navigate to the location of <the JAR file to be used by the custom Adapter> and click Open to select the file. Note: Depending on the browser used to launch Grid Manager, the button may be labeled 'Browse' or may contain a folder icon.
31

Figure 6: Manage Adapters - Custom Adapter Classname 8. Enter <the classname for the custom Adapter> in the Classname field. This classname must refer to a valid class within the JAR file specified in step 6. Note: If a valid classname is not provided, an Adapter that uses this Type will fail to start when enabled on a Peer. Even though an upload is successful, if the information provided is not correct, the use of this Adapter Type will result in a nonfunctional Adapter when it is enabled on a Peer.

32

Figure 7: Manage Adapters - Custom Adapter Dependencies 9. If the custom Adapter requires additional files to function properly, they may be added as dependent files. Click the button adjacent to the Dependencies field. Navigate to the location of <the dependent file for the custom Adapter> and click Open to select the file. Note: Depending on the browser used to launch Grid Manager, the button may be labeled 'Browse' or may contain a folder icon.

33

Figure 8: Manage Adapters - Custom Adapter Additional Dependencies 10. If more than one additional file is required, click the More Dependencies text. The first file will be moved in to the Dependencies table, below the Dependencies field. Click the button adjacent to the Dependencies field. Navigate to the location of <the additional dependent file for the custom Adapter> and click Open to select the file. An unlimited number of dependent files may be added in the same manner. Files in the Dependencies table may be disassociated with the ) icon. Adapter by clicking the Delete ( Note: Depending on the browser used to launch Grid Manager, the button may be labeled 'Browse' or may contain a folder icon.

34

Figure 9: Manage Adapters - Custom Adapter Platform Libraries 11. If platform specific libraries are required by the custom Adapter, they may be uploaded as well. Click the button adjacent to the Platform Libraries field. Navigate to the location of <the zip file containing the libraries for the custom Adapter> and click Open to select the file. All required platform libraries must be contained in a single zip file. Note: Depending on the browser used to launch Grid Manager, the button may be labeled 'Browse' or may contain a folder icon.

35

Figure 10: Manage Adapters - Custom Adapter Adapter Uploaded 12. When all upload information has been entered, click OK. The specified information will be uploaded to the CDP and will be available to configure an Adapter. The upload process does not create an Adapter configuration; it adds the custom Adapter Type to the CDP where it may be selected for configuring an Adapter on a specific Grid. To facilitate adding an Adapter configuration for the newly uploaded Adapter, click Continue. To return to the main Adapters page without adding a configuration, click the bottom option and then click Continue. 13. The main Adapters page will be displayed. Please see the BMC Run Book Automation Grid Manager User Guide for details on using this newly uploaded Adapter to create an Adapter configuration.

36

89742
89742