Global Mailbox Event Rule adapter (V5.2.6 or later)

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.

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

    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.

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)