Receiving CI change events with Event Channels

Applications that rely on configuration item (CI) and relationship data stored in BMC Helix CMDB sometimes need to know whether CIs and relationships have been created, updated, or deleted. For example, you might provide an email service using multiple servers. Your email service monitoring application might have the logic to identify the potential impact to the service of changes to the servers, but to apply this logic it must be notified of such changes.

The Event Channels component enables applications to subscribe to and receive events using the BMC Helix CMDB Java API. Events are generated when CIs and relationships are created, updated, or deleted in your production dataset, which defaults to BMC Asset. This means your application is notified of changes to your CMDB in near real time instead of it having to poll for changes periodically.

Event subscriptions

When subscribed, your application receives events in near real time whenever an instance of a CI or relationship class configured for events is created, updated, or deleted.

If an instance is deleted, events indicate that the instance was deleted. If the instance is marked for deletion (by setting the MarkAsDeleted attribute to Yes), events indicate that the instance was modified.

Instructions for subscribing to events are in the BMC Helix CMDB Javadoc Help. Events include the following information about the instance in question:

Class ID and namespace
Instance ID
Dataset ID
Event type (Create, Update, or Delete)

Event Channels applies the following security checks before sending events:

Row-level check to make sure that the subscriber has the permission to view the relevant CI class
Multitenancy check to make sure that the event is being delivered to a subscriber with the authority to view the relevant CI class

If a subscriber application disconnects, events are queued for delivery when it reconnects. Events that are undelivered for a day are removed, and you would then need to re-sync with BMC Helix CMDB using the CMDB API.

Note

Each subscribed application must have a unique AR System user ID for the Event Channels feature to work correctly. In a case where multiple instances of an application subscribe to events, each instance must use a different user ID to receive events independently of the other instances.

To enable, configure, and subscribe to Event Channels

Warning

The Event Channels feature uses the Filter API plug-in of AR System, and occasionally this use can interfere with Reconciliation Engine processing. To avoid reconciliation jobs hanging, if you use Event Channels then set your AR System server's Filter API RPC Timeout to 240 seconds. To make this setting, from the Home page choose AR System Administration > AR System Administration Console > System > General > Server Information > Timeouts.

The Event Channels feature is disabled by default. You must perform the following procedure to enable and configure the event channel.

Log in to Mid Tier with administrator credentials.
Use the following direct access URL to open the CMDB:Event_ChannelConfiguration form:
http://<midTierServer>:<port>/arsys/forms/<ARServer>/CMDB:Event_ChannelConfiguration
Click New request.
Enter the following values:
Click Save and close the form.
Use the following direct access URL to open the CMDB:Event_Configuration form:
http://<midTierServer>:<port>/arsys/forms/<ARServer>/CMDB:Event_Configuration

Important
When you search for the CMDB:Event_Configuration form records, the search result displays one record. Open the record and modify it as required.
In case the search displays multiple records, open and modify the oldest record.
Do not delete an existing record and do not create a new record in the CMDB:Event_Configuration form.
Modify the following values for the existing record:
Click Save and close the form.
Use the following direct access URL to open the CMDB:Event_Subscription form:
http://<midTierServer>:<port>/arsys/forms/<ARServer>/CMDB:Event_Subscription
Click New request.
Enter the following values:
Click Save.

In the Configuration Component Setting form, enable the event channel feature.
1. Use the following direct access URL to open the CCS form
  http://<midTierServer>:<port>/arsys/forms//<ARServer>/AR+System+Configuration+Component+Setting
2. Search for the setting name Event-Channel-Enabled.
3. In the Setting Value field, change the value to T.
  The event channel feature is now enabled.

Example code for automation

If you want to automate the event configuration, event channel configuration, and event subscription, you may use Java code similar to this.

public void eventChannelConfiguration() {
// CMDB:Event_Configuration
try {
dao = util.getECConfiguration(serverUser);
dao.setEcStatus(true);
EventConfiguration.updateConfigration(serverUser, dao);
} catch (Exception e1) {
if (e1.getMessage().contains("Entry does not exist in database")) {
eventConfigurationEntry.put(Constants.AR_CORE_SUBMITTER, new Value("username"));
eventConfigurationEntry.put(Constants.AR_CORE_SHORT_DESCRIPTION, new Value("username"));
eventConfigurationEntry.put(536105201, new Value("10"));
eventConfigurationEntry.put(536105202, new Value("60"));
eventConfigurationEntry.put(536105203, new Value("BMC.ASSET"));
String entryid = null;
try {
entryid = serverUser.createEntry(ECConstants.EVENT_CONFIG_FORM_NAME, eventConfigurationEntry);
} catch (ARException e) {
System.out.println("fail to create entry on CMDB:Event_Configuration form" + e);
}
System.out.println("entry created on CMDB:Event_Configuration" + entryid);
}
}
// CMDB:Event_ChannelConfiguration
eventChannelConfigurationEntry.put(Constants.AR_CORE_SUBMITTER, new Value("username"));
eventChannelConfigurationEntry.put(Constants.AR_CORE_SHORT_DESCRIPTION, new Value("username"));
eventChannelConfigurationEntry.put(536870913, new Value("CI"));
eventChannelConfigurationEntry.put(536870914, new Value("10"));

String entryid1 = null;
try {
entryid1 = serverUser.createEntry(ECConstants.CHANNEL_CONFIG_FORM_NAME, eventChannelConfigurationEntry);
} catch (ARException e) {
e.printStackTrace();
}
System.out.println("entry created on CMDB:Event_ChannelConfiguration" + entryid1);

try {

// CMDB:Event_Subscription
subscriptioneventId = eventSubscription.subscribe(ChannelType.CI, serverUser);
System.out.println("entry created on Event_Subscription form:" + subscriptioneventId);

} catch (ARException e) {
System.out.println("fail to subscription");
e.printStackTrace();
}
}

Class configurations

You must configure a class for events before a subscription will deliver events for the class. The following classes are preconfigured for events:

BMC_ComputerSystem
BMC_BusinessService
BMC_Application
BMC_SoftwareServer
BMC_IPEndPoint

These class configurations cannot be deleted. You can configure other classes for events using the following procedure.

To configure classes for events

If you want to add classes apart from the preconfigured classes for events, you must do that in the CMDB:Event_Class_Configuration AR form.

Log in to Mid Tier with administrator credentials.
Use the following direct access URL to open the CMDB:Event_Class_Configuration form:
http://<midTierServer>:<port>/arsys/forms/<ARServer>/CMDB:Event_Class_Configuration
Click New request.
Enter values for ClassName and the other fields required.

Performance considerations

The event generation rate is limited by the combined throughput of the Normalization Engine, Reconciliation Engine, and BMC Helix CMDB engine.

When the BMC Helix CMDB server is heavily loaded, change events might be generated faster than the rate at which the server can send them. In such a case, the events are queued. At times of intermittent load conditions (say for a few minutes), the queue might provide sufficient buffering, but for a longer load period it might not. When performing a bulk load of BMC Helix CMDB, consider turning off event generation or event delivery to avoid overflowing the queue.

You can improve the speed at which the server delivers events by increasing the number of Alert threads on your AR System server. To set the number of threads, from the Home page choose AR System Administration > AR System Administration Console > System > General > Server Information > Ports and Queues. In the table row for the Alert queue, set Min Threads to 5 and Max Threads to 10.

Interfaces to Event Channels

You can configure classes, subscribe to Event Channels, and turn off event generation or event delivery through the BMC Helix CMDB Java__ API. For information, see the BMC Helix CMDB Javadoc Help. You configure classes for events with the ECUtil.java class and subscribe to events with the CMDBEventSubscription.java class.

Permission roles

To subscribe to events, you must have the CMDB Console User role. To configure classes for events, you must have the CMDB Console Admin role.