Implementing the BMC Impact Integration Web Services operations
This section provides information about how to implement the BMC Impact Integration Web Services client.
Implementing send events
You can create a BMC Impact Integration Web Services client to send events from an event source to the BMC Impact Manager cell. The client integration is responsible for designing and implementing the logic required to get the event from the event source, transfer it to the BMC Impact Integration Web Services event, and send events to BMC Impact Integration Web Services.
To enable a client to send events and data, call the following key operations in sequence:
1. Connect
Before you send events, you must invoke the Connect operation. The Connect operation establishes a connection between BMC Impact Integration Web Services server and the specified BMC Impact Manager instance.
Execution of the Connect operation returns a connection ID. This connection ID is used in SendEvent and Disconnect operations. You can use this connection ID repeatedly until the Disconnect operation is called.
Because you are connecting to a specific BMC Impact Manager instance, you must add the cell information (name, encryption key, host, and port number) to the mcell.dir file that is located on the BMC Impact Integration Web Services server.
2. SendEvent
Invoke the SendEvent operation to send an event to the BMC Impact Manager specified in the Connect operation. You must use the connection ID returned by the Connect operation for the destination cell.
If your client is an event provider, you can connect and call the SendEvent operation repeatedly to send events to the same cell. The connection ID is valid until a Disconnect operation is called.
3. Disconnect
The Disconnect operation terminates the connection between BMC Impact Integration Web Services server and the specified BMC Impact Manager instance.
After the Disconnect operation is called, the specified connect ID is no longer valid.
Client samples
BMC Impact Integration Web Services provides the send events client sample code under the $IIWS_HOME\Tomcat\webapps\imws\client_samples\testSendEvents directory.
Implementing queries
Using the available query features, you can enable a client to perform the following actions:
- Retrieve events, data from a specific BMC IM instance
- Retrieve component information about service model component instances
- Query root cause and impact for a service model
After the client specifies the initial query request with the particular BMC Impact Manager instance, the BMC Impact Integration Web Services server establishes a connection with the BMC Impact Manager cell. The BMC Impact Integration Web Services returns a response with a result handle which is used by the client with each query request in the query cycle. The returned response also contains the total number of objects available to this query.
To complete the query, the client then requests a specified number of events or data objects, and the server responds with the specified number or the available number. The server response is the query result. To end the query cycle and disconnect from the BMC Impact Manager instance, the client sends an EndQuery request.
When querying, the client does not need to invoke a specific connection or disconnection request. With each query request, BMC Impact Integration Web Services establishes a connection with a specific BMC Impact Manager instance. With the EndQuery request, the BMC Impact Integration Web Services disconnects from the BMC Impact Manager instance for this particular query request.
The query operations have their own connection protocol. You do not have to call the Connect operation before calling a query. You can establish a separate query connection when you call a query operation.
To build your queries, invoke the following key operations in sequence:
One of the queries listed in the following table.
Invoke the specific query operation first. In the specific query, you must identify what you are querying for and specify the BMC Impact Manager instance to which you are connecting. A query result handle is returned, which is used to track all related queries in this sequence.Because you are connecting to a specific BMC Impact Manager instance, you must add the cell information (name, encryption key, host, and port number) to the mcell.dir file residing on the BMC Impact Integration Web Services server.
- Get the total number of objects expected in the response to the query.
The response from the initial query contains the result count, which is the total number of objects available for this query.
Alternatively, you can call the getQueryResultCount operation to retrieve the result count from BMC Impact Integration Web Services. - RetrieveQueryResult
The RetrieveQueryResult call specifies the number of events or data objects that the client wants to receive. The maximum number of objects each RetrieveQueryResult can get is defined by the MaxReturnEventListSize configuration parameter. The default value is 20. You can modify this value by changing the MaxReturnEventListSize parameter in the ImWebServices.conf file.
You can retrieve the entire range of results at once if the result count is not too large. You can ask to retrieve a specified number of results at one time. You can continue to retrieve the specified number in successive tries until you have retrieved all the results in the range.
You can also call the RetrieveQueryResult operation to retrieve a specified number of events or data objects starting from a certain index point. For example, if the query result count is 50, in the RetrieveQueryResult operation, you can specify a beginning point of 20 and indicate that you want to receive the next 10 events. You will then retrieve events 20 through 30. EndQuery
The EndQuery call tells the BMC Impact Integration Web Services server to end the query cycle.
Client samples
BMC Impact Integration Web Services provides the query client sample code under the $IIWS_HOME\Tomcat\webapps\imws\client_samples\testDataQueries directory. This sample program contains query examples for all the BMC Impact Integration Web Services query operations. It demonstrates how to invoke the query request and how to retrieve the results.
Implementing query class definitions
Unlike other query information which needs the block of query, retrieve, and end query, the query class definitions API enrapture all three processes in a single API: queryClassDefinitions.
By using queryClassDefinitions, you can specify whether you want to have data class def or event class def. You can retrieve a single class definition, or you can request to retrieve all the children classes from the base class you provided.
Client samples
You can find the query class definition sample in the $IIWS_HOME\Tomcat\webapps\imws\client_samples\testDataQueries directory.
The iiwsClientQueryClassDefinitions() method shows how to invoke the query class definitions call. The printClassInfo() method demonstrates the details of how to retrieve the slot information and recursively walk through the children classes.
Implementing subscribe events
You can build a client interface that receives events propagated from a BMC Impact Manager cell.
The following table describes the essential components for a client interface that receives events.
Components that support a receive interface
Selector choices
BMC Impact Integration Web Services provides a default select file, the iiws.selector, which is located under the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/etc directory. The iiws.selector provides the following basic selectors:
- Always matches
- Modifies
- EveryThing
You can add more selectors to the selector file or use your own selector file. For more information about the selector file and selector processing, see BMC-Impact-Integration-Web-Services-functions and IIWSGatewayServer.
Reliable and non reliable subscriptions
When you send the subscription request, the client needs to know whether you want a reliable subscription or an nonreliable subscription.
The life span of a reliable subscription is started when the Subscribe() call succeeds and ends when the client calls Unsubscribe().
The life span of an unreliable subscription ends when the client calls Unsubscribe() or the BMC Impact Integration Web Services server is terminated.
For a reliable subscription, when BMC Impact Integration Web Services is terminated, the client subscribe information is saved to a persistent file. When BMC Impact Integration Web Services starts again, the client can continue to get events from this reliable subscription. The EventReceiverManager.dat persistent file is located under the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/log directory.
The SubscriptionManager.dat file under the same directory stores the descriptions of unreliable subscriptions.
To build a client interface that receives events propagated from a BMC Impact Manager cell, invoke the following key operations in sequence:
Subscribe
If you need to receive events from a BMC Impact Manger, you can send the Subscribe request to BMC Impact Integration Web Services. The subscribe request has the parameters of context and filterName, and the flag that indicates whether the request is a reliable or an unreliable subscription.
The context is a string that represents this subscribe request. FilterName is the name of a selector in the selector file, (for example, iiws.selector ). The selector defines the criteria that determine which events this subscriber receives. The client context and filterName uniquely identify this particular subscription request. All the subsequent calls for the same subscription, (for example, GetEvents, AckEvents, and Unsubscribe ) have to provide the same client context and filterName input parameters.
When the BMC Impact Integration Web Services gateway server receives the events propagated from a cell, it maps the events against all the selectors for current subscriptions. If matches are found, the event is saved for each subscriber until the client retrieves it.- GetEvents
After Subscribe succeeds, the client can call GetEvents periodically to retrieve events from BMC Impact Integration Web Services. The GetEvent operation passes the same context and filterName that were in the Subscribe call. The third input parameter is num_of_events, which tells the BMC Impact Integration Web Services gateway server the number of events that the client wants to retrieve during GetEvents operation.
The BMC Impact Integration Web Services gateway server uses context and filterName to locate the subscription. If found, and if there are events existing for this subscriber, events are returned to the client. The num_of_events parameter returned in the response is the actual number of events GetEvent operation returned. It is always equal to or less than the value of the input num_of_events from the GetEvent request. - AckEvents
Following the GetEvents request, if the number of events returned (num_of_events) is lager than zero, the client must call the ActEvents operation. On receipt of the ActEvents request, the BMC Impact Integration Web Services gateway server cleans up the events from the server side.
The number of events in the AckEvent operation must equal the number of events returned from the getEvent call. For example, from a client
Call the GetEvents request with a num_of_events input of 30.
There are 25 events returned, and the num_of_events parameter in the returned GetEventsResponse is 25.
The client must call AckEvents with a num_of_events input of 25.
4. Unsubscribe
The Unsubscribe operation terminates the subscription. After receiving Unsubscribe request, the BMC Impact Integration Web Services gateway server cleans up all the saved events for this subscription and deletes subscription information from the server side.
Client samples
BMC Impact Integration Web Services provides the subscribing and receiving events sample program under $IIWS_HOME\Tomcat\webapps\imws\client_samples\testReceiveEvents.
Other Implementation considerations
Client binding timeout
The Integration client might get a timeout exception if the request call to web services is in progress while a timeout occurs at either the socket level or web services framework level. It is the responsibility of the integration application to set the adequate binding timeout for the BMC Impact Integration Web Services client. It is recommended to set the configurable binding-timeout properties so that you can adjust the value for your running environment.
The method used to set the binding timeout in client code depends on the language and the framework the client integration uses. You can find sample code in the BMC Impact Integration Web Services client sample code for Axis2 java program.
UTF-8 encoding
The Impact Manager cell requires all input strings to be UTF-8 encoded. BMC Impact Integration Web Services does not translate string code. The BMC Impact Integration Web Services client must specifically encode all the input strings to UTF-8 before sending them to BMC Impact Integration Web Services.