Integrating RabbitMQ in Enterprise Server 10

Integrating RabbitMQ in Enterprise Server makes it possible to instantly push message notifications — such as when a user updates the properties of a file — to client views of all users who are connected to Enterprise. This ensures that users immediately see the changes that other users make.

Because RabbitMQ can be used over LAN connections (local users) and WAN connections (remote users), it can be seen as an alternative to the n-cast feature of earlier versions of Enterprise Server, which only works via broadcasting or multi-casting over LAN connections.

The following overview shows how RabbitMQ and n-casting is supported by the various clients and how the use of RabbitMQ and n-casting differs between Enterprise Server 9 and 10:

Note: Rabbit MQ and n-casting can be used side-by-side to serve different client versions. When n-casting was previously implemented but is now no longer used (for example because applications that only support n-casting are no longer used), it is advised to disable n-casting.

Enterprise Server 9.8

Enterprise Server 10.0.1 or higher

Content Station 9 Web

Messaging not supported

Messaging not supported

Content Station 9 AIR

n-casting (LAN) only

n-casting (LAN) only

Smart Connection CC 2014

n-casting (LAN) only

n-casting (LAN) and RabbitMQ (LAN/WAN)

Smart Connection CC 2015

n-casting (LAN) only

n-casting (LAN) and RabbitMQ (LAN/WAN)

Smart Connection CC 2017

Not supported

n-casting (LAN) and RabbitMQ (LAN/WAN)

Content Station 10

Messaging not supported

RabbitMQ (LAN/WAN) only

Content Station 11 (Aurora)

Messaging not supported

RabbitMQ (LAN/WAN) only

The following table summarizes the capabilities of using n-casting and RabbitMQ:

Feature

n-casting

RabbitMQ

Local users

Yes

Yes

Remote users

No

Yes

Network traffic per message

1K at once

1K per client

User access rights checked

No

Yes

Extra 3rd-party installation needed

No

Yes

How it works

During most workflow operations, Enterprise Server pushes messages to the RabbitMQ queues while the client applications such as Content Station and Smart Connection read the messages from these queues.

When both n-casting and RabbitMQ are enabled, Enterprise Server will send out the same message twice: one over n-casting and one over RabbitMQ. Smart Connection will only listen to one of the two; when it cannot connect to RabbitMQ it will fall back to n-casting.

There is no functional drawback in leaving n-casting on when RabbitMQ is enabled; it does however have some performance impact. When n-casting is not used by any of the clients, it is better to disable it.

Enterprise Server itself does not make use of the messaging feature of RabbitMQ, nor does it rely on it in any way.

Before you start

Please take note of the following:

The RabbitMQ server requires a fast connection to the Internet, especially in combination with Enterprise Server.

In production environments, consider installing RabbitMQ on a separate machine. This can be a VMWare installation, a cloud instance or a physical machine.

To determine which operating system to use with RabbitMQ, see the RabbitMQ documentation: Supported Platforms.

For information about the compatibility of RabbitMQ and Enterprise Server, see the Compatibility Matrix.

Requirements

For information about which versions of RabbitMQ can be used with which versions of Enterprise Server, see the Compatibility Matrix.

Installing RabbitMQ to work over SSL requires OpenSSL 1.0.1 or higher . Older versions of OpenSSL are incompatible with RabbitMQ.

Installing the RabbitMQ plug-in in the PHP extension requires bcmath to be available in PHP. Instructions on how to check if it is already installed and how to install it when needed are provided in this article.

RABBITMQ_CONNECTION_TIMEOUT. When Enterprise Server connects to RabbitMQ, it sends HTTP requests. The timeout period for these requests is set to 2 seconds and can be controlled through this option.

Note: The higher the number, the more the Enterprise workflow operations are delayed in case RabbitMQ is suddenly no longer accessible. The lower the number, the higher the risk of losing push message notifications.

RABBITMQ_EXECUTION_TIMEOUT. During a workflow operation (such as file check-in, save version, and so on), Enterprise Server invokes RabbitMQ by sending HTTP requests. The timeout period for these requests is set to 2 seconds and can be controlled through this option.

Note: The higher the number, the more the Enterprise workflow operations are delayed in case RabbitMQ is suddenly operating very slow. The lower the number, the higher the risk of losing push message notifications.

Info: This feature requires the following versions of Enterprise Server:

Enterprise Server 10.1.10 or any other higher version of 10.1.

Enterprise Server 10.4.2 Quick Patch build 259 or any other higher version of 10.4.

Enterprise Server 10.5.1 or any higher version of 10.5.

When Enterprise Server connects to RabbitMQ, it sends HTTP requests for each Brand that a user has access to. This includes Issues for which the Overrule Brand option is enabled.

Each request takes a few milliseconds to complete, so even when a user has access to a few dozen Brands the process does not take long. When a user has access to a significantly high number of Brands though, the log-on duration can be negatively impacted.

While it is common practice for Enterprise installations to limit the number of Brands that a user has access to, some users (such as Brand administrators or system administrators) will typically have access to a high number of Brands. However, for those users the push message notifications may be not important. These users can therefore be excluded from receiving notifications.

This is done by setting the RABBITMQ_MAX_PUBLICATIONS option in the configserver.php file. In it, the maximum number of Brands that a user can have access to in order to receive notifications through RabbitMQ is specified.

When the number of Brands that a user has access to is lower than or equal to the defined maximum, notifications are sent to that user by RabbitMQ.

When the number of Brands that a user has access to is higher than the defined maximum, notifications are not sent to that user by RabbitMQ.

Note: To see which users are excluded from receiving notifications by RabbitMQ as a result of setting this option, run the RabbitMQ test on the Health Check page. It will also show the number of Brands and overruled Issues that each user has access to.

4. (Optional) Setting up an Enterprise Server job to clean up message queues

Info: This feature requires the following versions of Enterprise Server:

Enterprise Server 10.1.10 or any other higher version of 10.1.

Enterprise Server 10.4.2 Quick Patch build 259 or any other higher version of 10.4.

Enterprise Server 10.5.1 or any higher version of 10.5.

When RabbitMQ is temporarily down during production hours, Enterprise Server can no longer push message notifications.

Enterprise Server can also not remove message queues in RabbitMQ when tickets expire or when users log off.

The result of both scenarios is that the resource administration of RabbitMQ may get out-of-sync.

If RabbitMQ would remain down for many hours while many users are connected, many message queues could remain abandoned in RabbitMQ forever. If this problem repeats itself many times, there is a potential risk that RabbitMQ gets exhausted by using too many resources.

For this purpose, message queues in RabbitMQ can be periodically cleaned up by running the Enterprise Server Job named AutoCleanRabbitMQ.

3. (Optional) Setting up public and private connections

In several cases it can be useful to configure both public and private connections for RabbitMQ.

Example:

Enterprise Server and RabbitMQ are installed on the same server, but the clients need to connect to it from the outside. By configuring a private URL, communication between Enterprise Server and RabbitMQ will be much faster.

REST

This protocol is used by Enterprise Server to communicates with RabbitMQ over REST (for resource management); it is not used by the client applications. Therefore, only a private connection is needed.

AMQP

Enterprise Server uses AMQP for publishing events, and the clients use AMQP to receive events. In this case, configure both a private and a public connection. The public connection will be communicated to the clients, while Enterprise Server uses the private connection.

STOMPWS

This protocol is only used by clients for receiving events, and therefore only requires a public connection.

The following is an example configuration (non-SSL) of the configserver.php file:

Note:The fourth parameter of each MessageQueueConnection entry indicates whether or not the connection is public. This parameter varies between the first and second connection: the first one is true (=public) and the second one is false (=private). When this parameter varies it is allowed to have two AMQP connections.

4. Setting up SSL

Setting up an SSL connection involves steps on RabbitMQ and on Enterprise Server.

Step 2. Comment the non-SSL connections (by pre-fixing them with //) and comment-out the SSL connections by removing the // prefixes.

Step 3. (Optional, only when Enterprise Server connects through a proxy) Specify the proxy in the ENTERPRISE_PROXY option of the configserver.php file.

Step 4. Test the integration by running the following tests tests on the Health Check page:

php.ini

RabbitMQ (This will check if bcmath is available. If this is not the case a link is provided with more information about how to install it.)

Step 5. Access the Integration page and verify that RabbitMQ is shown.

5. (Optional) Disabling n-casting

When n-casting was previously implemented but is now no longer used (for example because applications that only support n-casting are no longer used), it is advised to disable n-casting. Leaving it on will have some performance impact.