IBM Business Monitor, V8.0.1 > Reference

IBM Business Monitor REST event emitter interface

The IBM Business Monitor REST event emitter service allows applications to emit events without having to code or generate Common Base Events directly. You provide the event XML, and the event emitter service receives the event XML and wraps it in a Common Base Event so that IBM Business Monitor can process it. You can use the emitter to send XSD style events.

The XSD type is a generic XML Schema Definition. The business information that is defined by the XSD definition is received by the API and placed in the xs:any slot of a Common Base Event and forwarded to IBM Business Monitor. The event part definitions created in a monitor model to process these events must always start with cbe:CommonBaseEvent and navigate into content that is placed in the xs:any slot of the IBM Business Monitor. For a direct link to all resources and methods, see the quick summary.


Overview

The REST event emitter service provides a public API that you can use to send events that IBM Business Monitor can process. The API wraps the event XML in a Common Base Event envelope by placing the event XML into the xs:any slot of the Common Base Event, and submits the Common Base Event to the common event infrastructure (CEI) server, which then forwards the event to the monitor model application. The REST implementation allows for easy-to-use HTTP services that are language- and platform-independent, stateless, scalable, and easily parsed. The service can be invoked by any HTTP client application and defines an expected response in the form of a JavaScript Object Notation (JSON) object. The JSON format can be easily parsed and consumed by JavaScript and other products, tools, and languages, which allows you greater flexibility in leveraging IBM Business Monitor in your own environment.

This emitter service takes an HTTP POST URI as input. Results are returned in JSON, and any error messages and status indicators are returned in the HTTP response as JSON output.


Event emitter service URIs

For a secure installation, the format of the event emitter service URI is as follows: 

https://{hostname}:{port}(WC_defaulthost_secure port)/rest/bpm/events
For an installation without security enabled, the format of the event emitter service URI is as follows: 
http://{hostname}:{port}(WC_defaulthost port)/rest/bpm/events
where:

The REST event emitter service is configured as follows when it is deployed for a stand-alone installation:

where:

You can deploy multiple copies of the EAR file if you want to use more than one emitter. The EmitterServices.ear file is available in the was_root/installableApps.wbm directory.

You can deploy multiple copies of the service manually or use the configuration wizard. When you deploy multiple copies, you must provide a unique application name and a unique context root for each copy, and you must modify the resource reference to contain the JNDI name of a configured emitter that you want to use.

For example, you can deploy a second EAR file that is configured to use the CEI default emitter. You can change the following settings during deployment:

You can deploy another EAR file that is configured to use an asynchronous emitter. You can change the following settings during deployment:

In an ND (ND) environment, if the EmitterServices.ear file is installed on a different server or cluster than the CEI emitter factory, you must set the RESTEmitterFactory resource entry to point to the correct location of the emitter factory. You can configure the emitter factory for each emitter during deployment, or you can modify the resource references on the IBM_WBM_REST_EMITTER_SERVICE application. You can make these changes from the administrative console. Click Applications > Application Types > WebSphere enterprise applications and click IBM_WBM_EMITTER_REST_SERVICES. Under References, click Resource references and make the changes. Save your changes and restart the application.

If you do not use the configuration wizard to install the emitter services, you must take some extra steps in a secure environment. After deploying the EmitterServices.ear, you must assign the appropriate security role mapping. To make the changes, in the administrative console, click Applications > Application Types > WebSphere enterprise applications and click IBM_WBM_EMITTER_REST_SERVICES. Under Detail Properties, click Security role to user/group mapping.


Content types

The data sent or returned by the HTTP methods listed above must have one of the following content types: ([ RFC2045][([ RFC2046]


Use HTTP content-type in REST requests

When a client sends an HTTP request with payload, the HTTP content-type header should be set correctly to describe the payload format. Therefore, clients must be explicit and set the format to either text/xml or application/atom+xml, depending on whether clients are sending a single payload directly in the HTTP request body or multiple event payloads.

To access the URI, use the following web address from the emitter application (or you can use the configured URL to access the web address, as explained in the next paragraph): 

http://monitor_server:monitor_server_port/rest/bpm/events
where:

IBM Business Monitor also configures a URL with a JNDI name of monitor/emitter/defaultURL for a stand-alone installation. For a secure installation, this URL specifies the following default address: 

https://monitor_server:monitor_server_port/rest/bpm/events
For an installation without security enabled, this URL specifies the following default address: 
http://monitor_server:monitor_server_port/rest/bpm/events

You can look up the URL JNDI in your emitter application to access the address where the emitter service is available. This method of looking up the web address of the service shields the emitter application from any changes in the web address. You can add URL definitions as you deploy more copies of the event service.


Error handling

For errors that are recognized during the processing of an IBM Business Monitor REST request, an appropriate HTTP status code ([ RFC2616]) is returned to the calling client (for example, 200 OK or 404 Not Found; see the individual operations for details). Additional error information is provided depending on the error type. For IBM Business Monitor exceptions, the corresponding IBM Business Monitor error number and error message are returned. For severe errors (HTTP status code 500 Internal Server Error), additional programmer's details are returned. They can be propagated to IBM service personnel, if required.

If errors are encountered during processing, IBM Business Monitor discards the event, and you must send it again after making any necessary corrections as indicated by the error information that is returned. You might consider using the JMS event emitter, which routes failed events to an error queue when errors are encountered during event emission. The events are not discarded and can be recovered for processing by the event emitting application. See "Handling events that the JMS event emitter did not emit" in the related links.


References

The following specifications provide additional helpful information:

Reference


Related concepts:
Event parts


Related tasks:
Use the REST event emitter to emit events
Validating Common Base Events
Remove XML headers


Related reference:
Handling events that the JMS event emitter did not emit
Interface quick summary