Global Mailbox Event Rule adapter

The Global Mailbox Event Rule adapter listens to the events generated by Global Mailbox and accepts the events over WebSphere® MQ when the events are available.

Note: By default, the Global Mailbox Event Rule Adapter runs on the Application Server Independent (ASI) node.

The following table provides an overview of the Global Mailbox Event Rule adapter:

Category Description

System name

Global Mailbox Event Rule adapter

Graphical Process Modeler (GPM) category

None

Description

The Global Mailbox Event Rule adapter listens to the events generated by the Global Mailbox and accepts the events over WebSphere MQ when the events are available.

In case of a data center failure, the Global Mailbox administrator might resend events that are in Processing state. However, the original event might also be in the queue for processing. In such a scenario, the Global Mailbox Event Rule adapter verifies the time stamp of the events in Cassandra based on the event ID, processes the event that arrived later, and discards the earlier event. One exception is in cases where a business process is already triggered for the original event. In such cases, the original and the resent events are processed.

If the event rule adapter cannot interpret an event, the message related to the event is discarded and an error with the message ID is logged in the message fabric logs. You can view the logs at Operations > System > Logs > Message Fabric Log. The error is not communicated to the Global Mailbox system, because an event ID is not available for such events.

When WebSphere MQ goes down, the Event Rule Adapter is automatically stopped, and the status of the ERA is changed to Stopped. You must select the check box to start the ERA.

Business usage

Use this adapter to know about the events, such as, mailbox added, message added, and mailbox that is deleted in the Global Mailbox, and do necessary actions in Sterling B2B Integrator.

You can also use the adapter to route messages from the Global Mailbox to Sterling B2B Integrator for processing.

Preconfigured?

No

Platform availability

All supported platforms for Sterling B2B Integrator.

Related services

None

Application requirements

Sterling B2B Integrator must be registered with the Global Mailbox and the com.ibm.mailbox.messaging.event.notification.enabled property must be enabled in the mailbox.properties file in Global Mailbox.

Initiates business processes?

Yes, if a business process is configured.

Invocation

This adapter is not started from a business process.

Testing considerations

You can verify the event logs in the adapter logs.

How the Global Mailbox Event Rule adapter works

The Global Mailbox Event Rule adapter must be configured and enabled. The adapter is a stateful adapter; therefore, after the adapter is started, it establishes and maintains the connection to the configured queue. The adapter can be configured to work in one of the two process invocation modes:
Immediate mode
The adapter receives events from the queue and starts a business process instance for each event that is received.
Batch mode
The adapter periodically polls the queue for available messages and picks the number of messages that is specified in the Max Messages Per Batch parameter, and dispatches one instance of each matched business process, potentially with a list of multiple message references.

Implement the Global Mailbox Event Rule adapter

To implement the Global Mailbox Event Rule adapter, configure the Global Mailbox Event Rule adapter and enable it.
Remember: You must not call the Global Mailbox Event Rule adapter from a business process. You must configure and enable the adapter. After the adapter is enabled, it connects and listens to event messages from Global Mailbox.

Configuring the Global Mailbox Event Rule adapter

To configure the Global Mailbox Event Rule adapter:
  1. From the Administration Menu, select Deployment > Services > Configuration.
  2. Click Go!, next to New Service.
  3. Select the List View icon, and then select the Global Mailbox Event Rule adapter from the list. Click Save.
  4. Click Next.
  5. Specify the following field settings:
    Field Description
    Name Unique name for the adapter.
    Description An appropriate description for adapter.
    Environment The Environment field is displayed only in a cluster setup. Required.

    Select the node in which the adapter must be deployed. If you do not select any node, all nodes are selected by default and the adapter starts on the node that is started first.

    Select a Group Select a required group.
    Config Select the queue provider between the Global Mailbox and Sterling B2B Integrator. The option is as follows:
    • WebSphere MQ
    WebSphere MQ settings Specify values for the following fields, if you selected WebSphere MQ.
    Host name Specify the appropriate host name or IP address where the messaging queue is configured. Required.
    Port The port number where the messaging queue is configured. Required.
    Channel Specify the channel name where the queue is configured. Required.
    Connection Name List Specify a comma separated list of IP address and port or host name and port of the machines that host the WebSphere MQ servers. For example, host name/IP address(port), host name/IP address(port).
    Queue Manager Specify the queue manager name.
    User ID Specify the ID of the user who accesses the queue.
    User Password Specify the password for the user ID.
    Use SSL to communicate with WebSphere MQ Select Yes to use SSL to communicate with WebSphere MQ. Optional.
    Select CA certificates that can sign acceptable MQ certificates (if any) Select the CA certificates to communicate securely with WebSphere MQ.
    Select certificates that are acceptable MQ certificates (if any) Select the trusted certificates to communicate securely with WebSphere MQ.
    Select the certificate used to authenticate to MQ (needed only if doing client auth) Select the system certificates to communicate securely with WebSphere MQ.
    Select the CipherSpec used by MQ Select the CipherSpec from the values that are supported by WebSphere MQ.

    To use ECDHE_* ciphers with WebSphere MQ, the certificate that is used by the server (and client, if client cert auth is enabled) must use an Elliptic Curve key.

    For information about the CipherSpec that are supported, see SSL/TLS CipherSpecs and CipherSuites in IBM MQ classes for JMS.

    Process Invocation Mode The process invocation mode determines how the adapter interacts with the queue and dispatches Sterling B2B Integrator processes. The options are as follows:
    Immediate mode
    The adapter receives events from the queue and starts a business process instance for each event that is received.
    Batch mode
    The adapter periodically polls the queue for available messages and picks the number of messages that is specified in the Max Messages Per Batch parameter, and dispatches one instance of each matched business process, potentially with a list of multiple message references.
    Batch mode settings

    Batch mode is a type of interaction between the adapter and the queue in which the events are processed with a delay. This helps to avoid some issues that may occur when using the Immediate mode.

    If you select batch mode, specify values for Polling Interval, Receive Time Limit, and Max Messages Per Batch fields.
    Important: There are no predefined or recommended values for the Batch mode settings. To find the best settings, test the adapter in your environment with different values in each field.
    Polling Interval

    Time interval between two polls.

    There is no default value. Specify any valid integer in milliseconds. For example, 100 (milliseconds).
    Receive Time Limit

    Time limit to receive the message.

    Specify any valid integer in milliseconds. Default is 300000 (milliseconds).
    Note: When the Receive Time Limit window expires, the adapter will stop receiving messages.
    Max Messages Per Batch

    The maximum number of events that can be available in a batch, before the adapter starts processing (dispatch) the events. If the number of events is more than value specified, the events are processed in batches.

    For example, if 5 is specified as Maximum Messages Per Batch, and there are 12 events, the events are processed in 3 batches.
    Queue Name The name or identifier of the WebSphere MQ messaging queue that contains the events that are received and processed by the Global Mailbox Event Rule adapter.

    The queue must be the same as the one that was used when you registered the Event Properties Lookup service with Global Mailbox.

    Copy Payload Select if the adapter must copy the message payload to a Sterling B2B Integrator document and create a correlation entry for the same. The options are as follows:
    • Yes
    • No
  6. On the Confirm screen, ensure that Enable service for Business Process is selected. Click Finish.

How to change Global Mailbox Event Rule Server Adapter (ERA) from Immediate mode to Batch mode

In Sterling B2B Integrator, Process Invocation Mode of the Global Mailbox Event Rule Server Adapter (ERA) has two modes - Immediate and Batch. By default, the application uses Immediate mode. However, when the invocation mode is changed to Batch, it is also necessary to change a setting in the Global Mailbox process. To accomplish that, open a command-prompt shell to the server where Global Mailbox (Liberty, mailboxui) is running and execute the following command from <B2Bi_install>/MailboxUtilities/admin/bin:
  • ./appConfigUtility.sh updateAppConfig --appName=B2Bi --Pcom.ibm.mailbox.messaging.check.application.queue.reader="false"
Tip: The change takes place immediately and it is not required to restart any of the components of Global Mailbox.
To verify the change, use the following command:
./appConfigUtility.sh showAppConfig --appName=B2Bi
...
com.ibm.mailbox.event.lookup.auth.user = gmbx_user
com.ibm.mailbox.messaging.check.application.queue.reader = false
com.ibm.mailbox.messaging.message.broker.type = webspheremq
...

Monitoring the status of the started business process

A predefined business process, RoutingRuleDMMsgStatusMonitor, which is associated with the Global Mailbox Event Rule adapter, monitors the status of the business process that is specified in the event rule, and updates the status on the Global Mailbox Event History page. Following is a list of the status that is displayed:
Unprocessed
The business process is yet to start and message processing is yet to start.
Processing
The business process is running and message processing is in progress.
Complete
The business process (message processing) completed successfully.
Failed
The business process (message processing) failed. Message processing can fail because a business process fails, or because the data center goes offline before processing is complete.
Message processing can also fail if the event rule configuration does not match with the configuration in Sterling B2B Integrator. For example, the business process or user who is specified in the event rule are not available in Sterling B2B Integrator or the system business process (RoutingRuleDMMsgStatusMonitor) is deleted. In such cases, the Global Mailbox administrator or Sterling B2B Integrator administrator must make appropriate changes to the event rule configuration or the business process and resend the events.
Important: To see the reasons for failure, verify the running instances of the RoutingRuleDMMsgStatusMonitor business process or monitor the Sterling B2B Integrator system logs (Operation/System/logs)