Configuring the execution unit (XU) to send event messages

Rule Execution Server can execute a ruleset that emits business events. Rule Execution Server uses a customized execution unit (XU) and the Java™ Message Service (JMS) to send event messages that can be processed by Decision Server Events.

Before you begin

This customized XU is supported for WebSphere® Application Server only.

About this task

The rulesets that contain rules with emit event statements are executed just like any other ruleset, except that successful ruleset execution generates event messages. The event messages are sent to the JMS target destination that is defined in the XU plug-in configuration. The target destination can be the default destination or a destination that you set. The default event message destination for a typical stand-alone installation of Decision Server Events is a JMS topic that has jms/eventDestination as the JNDI name and jms/WbeTopicConnectionFactory as the connection factory. In a clustered environment, the default destination is a JMS Queue that has jms/eventQueue as the JNDI name and jms/WbeQueueConnectionFactory as the connection factory.

The default WebSphere Application Server stand-alone configuration of the XU has the same JMS parameters as the Decision Server Events default parameters. However, you can configure the XU to set the target destination or other JMS parameters. For more information about the XU, see the related topic Execution Unit (XU).

To configure the XU, you can edit the ra.xml deployment descriptor file manually or you can use the WebSphere Application Server administrative console to set custom properties for the XU connection factory.

Note: By default, the connection to the event bus is secured. The default credentials used for the connection are the initial resAdmin account credentials. However, you can modify the default security settings by using the res-setup ant task. You can use the eventplugin.username, eventplugin.password, and eventplugin.secured attributes in the res-setup ant task to perform the following actions:

Communicate a resAdmin password change to the XU.
Choose a different user to connect to the event bus.
Disable security.
The bus security itself remains the same, but the connection to the bus is done without specifying credentials.

Procedure

Choose one of the following methods to configure the XU:

Edit the ra.xml deployment descriptor manually. That ra.xml file is packaged inside the RAR file in a subdirectory called META-INF.
1. Open the RAR ra.xml deployment descriptor in any text or XML editor.
2. Locate the plugins property and the EventPlugin class:
```
<config-property>
    <config-property-name>plugins</config-property-name>
    <config-property-type>java.lang.String</config-property-type>
    <config-property-value>
    ...
    {pluginClass=com.ibm.rules.res.event.plugin.EventPlugin,EventDestinationType=Topic,EventDestinationConnectionFactoryName=jms/WbeTopicConnectionFactory,EventDestinationName=jms/eventDestination}
    ...
    </config-property-value>
  </config-property>
```
  where ... represents other plugin properties that can occur above or below the EventPlugin code.
3. Modify the pluginClass=com.ibm.rules.res.event.plugin.EventPlugin class to add configuration or customization properties as described in Table 1.
Customize the XU connection factory from the WebSphere Application Server administrative console.
1. Log in to the WebSphere Application Server administrative console.
2. Click Resources > Resource Adapters > Resource adapters.
3. Click the name of the XU that you want to customize. For example, the default XU is JRules XU.
4. Under Additional Properties, click J2C connection factories.
5. Click the name of the XU connection factory. For example, the default connection factory is XU_CF.
6. Under Additional Properties, click Custom properties.
7. Click plugins in the list of property names, then edit the EventPlugin property values to add configuration or customization properties as described in Table 1.

Table 1. EventPlugin configuration properties to customize the XU
Property	Purpose	Default value
EventDestinationConnectionFactoryName	Set the JMS connection factory name.	jms/WbeTopicConnectionFactory
EventDestinationName	Set the JMS destination name.	jms/eventDestination
EventDestinationType	Set the JMS destination type to Topic or Queue.	Topic
EventTransactionJmsSessionsAllowed	Set JMS transaction support to enabled (true) or not enabled (false).
JmsSessionMode	Set the JMS session mode, as defined in the JDK by `javax.jms.SessionMode`. Valid values are: AUTO_ACKNOWLEDGE CLIENT_ACKNOWLEDGE DUPS_OK_ACKNOWLEDGE SESSION_TRANSACTED	AUTO_ACKNOWLEDGE

For example:

{pluginClass=com.ibm.rules.res.event.plugin.EventPlugin,EventDestinationType=Topic,EventDestinationConnectionFactoryName=jms/WbeTopicConnectionFactory,EventDestinationName=jms/eventDestination}

Restart the application server.

Results

At run time, an error is logged if the event messages are not sent successfully. This error might occur because of a failure in the message service, a configuration error, or an incorrect ruleset. However, an event message error condition does not prevent successful execution of the ruleset.