IIWSGatewayServer is the cell gateway of BMC Impact Integration Web Services that accepts connections and events from BMC Impact Manager cells. It receives events from BMC Impact Manager cells and stores them in a buffer, the gateway persistent receiver buffer.
IIWSGatewayServer defaults to the local host system of the BMC Impact Integration Web Services server and listens for events on port number 1859.
For each BMC Impact Manager that propagates events to the BMC Impact Integration Web Services server, you must specify IIWSGatewayServer entry in mcell.dir.
How the BMC Impact Integration Web Services server reads selector files and parameters
The BMC Impact Manager cell uses selectors to match incoming events and to make them available to subscribing clients.
When the web service client is executed, the selector name is specified to invoke the subscription request. The subscription call identifies the client and the selector name to the BMC Impact Integration Web Services. The BMC Impact Integration Web Services keeps this information in a subscription table and selector entry names are mapped to specified client IDs.
At start, the BMC Impact Integration Web Services loads the selector file specified by the ImWebServices.conf file. (Only one selector file is loaded per session.) The specified selector file applies to all the events that propagate from all the BMC Impact Manager cells.
Multiple clients can subscribe to the same selector in a web services session. Conversely, a single web service client can subscribe to different selectors in the same session by initiating multiple subscription calls, each specifying a different selector name.
Whenever a client subscribes to multiple selectors, it runs the risk of receiving duplicate events from a cell. The same event can satisfy the different criteria specified by multiple selectors and be forwarded to the subscribing client.
When an event, propagated by a BMC Impact Manager, matches a selector, the service looks into the subscription table to get the clients that have invoked subscriptions with the matching selector. If an event matches one or more selectors with subscriptions, it is saved to the gateway persistent receiver buffer for the subscriber to retrieve. The number of events kept in the gateway persistent receiver buffer is limited. The maximum number kept is defined by the ImWebServices.conf parameter RecvBufferSize and the default is 20000.
How a send event request is processed
On receipt of a client's Connect request, with a specific BMC Impact Manager cell name (or cell name), BMC Impact Integration Web Services server establishes the connection with the cell and returns the handle to the client.
The client can then continue to send the SendEvent requests to the BMC Impact Integration Web Services server by using the connection handle. BMC Impact Integration Web Services server is responsible for sending the events to the destination cell.
How a query is processed
Using the available query features, you can enable a client to perform the following tasks:
- Retrieve events, data objects, or both from a specific BMC Impact Manager cell
Return component information about service model component instances that have been published to a specific cell or to multiple cells
The service model queries can search for and return service model information that has been published to one or more cells.
These service model queries retrieve component data that has already been published to the cell; they do not query the BMC® Atrium Configuration Management Database.
- Retrieve service model class definitions from a specific BMC Impact Manager cell.
The class definition query retrieves class definition information from the cell.
After the client specifies the initial query, the BMC Impact Integration Web Services connects with a BMC Impact Manager instance and responds with a result handle ID. The client provides the result handle ID with each subsequent query request in the query cycle. After receiving the result handle ID, the client sends a request to the server seeking the total number of events or data objects available to the query. The BMC Impact Integration Web Services server responds with the total count.
To complete the query, the client requests a specified number of events or data objects, and the server responds with the specified number or at least the available number. The server response is the query result. To end the query cycle and disconnect from the BMC Impact Manager cell, the client sends an EndQuery request.
When querying, the client does not need to invoke itself a specific connection or disconnection request. With each query request, the BMC Impact Integration Web Services will use an existing connection with the BMC Impact Manager cell, or establish one.
Because each open query cycle consumes resources, it is important to end queries that are no longer being used.
If you build an exclusive query client, you do not need to invoke subscription or polling calls. Also, you do not need to build propagate rules or define propagation event policies to push events from BMC Impact Manager cells to IIWSGatewayServer on the BMC Impact Integration Web Services server.
How the receive feature works
The BMC Impact Integration Web Services server opens a listener port through IIWSGatewayServer to receive events propagated from cells. You can build a client interface that receives events through polling calls.
The following table describes the components essential for a client that receives events.
Components that support a receive interface
IIWSGatewayServer is started by the BMC Impact Integration Web Services server. Its function is to accept connections from BMC Impact Manager cells.
Propagate rules or propagation event policies
To receive events from BMC Impact Manager cells, you must define Propagate rules or propagation event policies in the cell for the event types to be sent. The BMC Impact Manager cell propagates events to the IIWSGatewayServer based on the rules or polices that you have defined.
To receive events, your client interface must invoke subscription requests through the
Clients poll for the events
You can choose to design a polling client that uses a reliable subscription request to maintain a persistent connection with the BMC Impact Integration Web Services. When it receives a reliable subscription request from a client, the BMC Impact Integration Web Services persists the events that it receives in response to the client's subscription request in the $IIWS_HOME/Tomcat/webapps/imws/WEB-INF/log directory.
The life span of a reliable subscription is started when the
Subscribe() call succeeds and ends when the client calls
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 subscription information is saved to a persistent file.