IBM Business Monitor REST event emitter interface (XML)

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 forwarded to IBM Business Monitor.

Event emitter service URIs

https://{hostname}:{port}(WC_defaulthost_secure port)/rest/bpm/monitor/events

http://{hostname}:{port}(WC_defaulthost port)/rest/bpm/monitor/events

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.

In a network deployment (ND) environment, if the EmitterServices.ear file is installed on a different server or cluster from 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

Using 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.

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

https://monitor_server:monitor_server_port/rest/bpm/monitor/events

http://monitor_server:monitor_server_port/rest/bpm/monitor/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. For more information, see "Handling events that the JMS event emitter did not emit" in the related links.

References