Relativity service bus

Note: Relativity plans to deprecate Windows Service Bus in Server 2023. We recommend that you begin conversion to RabbitMQ beginning in Server 2022.

The Relativity service bus is a message delivery service that communicates information about agent jobs to different application components. This infrastructure feature supports this communication by routing messages between application components. For example, Relativity uses the service bus for submitting conversion jobs to agents and returning converted documents.

Note: Before installing or upgrading, you must install and configure your environment’s message broker. Next, install or upgrade your primary SQL Server and the Relativity service bus. You can find information about your environment’s message broker in Pre-installation. For installation instructions, see Relativity installation.

The Relativity service bus supports the following features:

  • Guaranteed delivery of messages to ensure reliable communication between application components.
  • High throughput performance for successful message delivery over the service bus.
  • Support for arbitrary messages.
  • High scalability to ensure that service bus can support an increasing number of resources added to your Relativity environment.
  • Fault tolerance and high availability to guarantee that the service bus continues operating even when a component fails.

Relativity service bus infrastructure

The Relativity service bus is built on your environment’s message broker, so it leverages the capabilities offered by these industry-standard softwares. You must install it on a node in your environment’s message broker. The Relativity installer updates the Instance setting table on your primary SQL Server with information about the location of the Relativity service bus that you provide during installation. It updates the following instance settings:

Table section Relativity.ServiceBus
Value localhost
Description Specifies the fully-qualified domain name for the machine hosting your Relativity Service Bus provider. The Relativity installer automatically sets this value during an installation or upgrade based on the inputs in the RelativityResponse.txt file. For more information, see Relativity installation or Upgrading your Relativity service bus.

Note: The value for this setting should match the FarmDNS output from the Get-SBFarm command available in the Service Bus PowerShell utility. For more information, see Service bus PowerShell cmdlets.

Note: When using RabbitMQ, Relativity also supports the IP address for the Server or cluster.
Table section Relativity.ServiceBus
Value 9455
Description Specifies the HTTP port for Service Bus for Windows Server. The Relativity installer automatically sets this value during an installation or upgrade based on the inputs in the RelativityResponse.txt file. For more information, see Relativity installation or Upgrading your Relativity service bus.

Note: The value for this setting should match the HttpsPort output from the Get-SBFarm command available in the Service Bus PowerShell utility. For more information, see Service bus PowerShell cmdlets.

Note: Not used for RabbitMQ.
Table section Relativity.ServiceBus
Value 9454
Description Specifies the TCP port for Service Bus for Windows Server. The Relativity installer automatically sets this value during an installation or upgrade based on the inputs in the RelativityResponse.txt file.For more information, see Relativity installation or Upgrading your Relativity service bus.

Note: The value for this setting should match the TcpPort output from the Get-SBFarm command available in the Service Bus PowerShell utility. For more information, see Service bus PowerShell cmdlets.

Note: Not used for RabbitMQ.
Table section Relativity.ServiceBus
Value Relativity
Description

Service Bus for Windows Server - the namespace to be used by Relativity Service Bus.

RabbitMQ - the virtual host to be used by Relativity Service Bus

Table section Relativity.ServiceBus
Value Default value varies by environment.
Description

Service Bus for Windows Server - Specifies the value of the shared access key / authorization rule used when authenticating with service bus.

RabbitMQ - Specifies the value of the Relativity RabbitMQ user’s password used when authenticating.
Table Section Relativity.ServiceBus
Value Relativity
Description

Service Bus for Windows Server - Specifies the name of the shared access key / authorization rule used when authenticating with service bus.

RabbitMQ - Specifies Relativity RabbitMQ username used when authenticating.

Table Section Relativity.ServiceBus
Value Windows
Description

Specifies the message broker that Relativity will use for Service Bus messaging.

Acceptable values: Windows or RabbitMQ.
Table Section Relativity.ServiceBus
Value False
Description

Only used for RabbitMQ. Specifies whether or not client connections to RabbitMQ should use TLS.

Note: If set to True, your RabbitMQ server or cluster must be configured for TLS.

The web and agent servers request information about the location of the Relativity service bus from the primary SQL Server. The Relativity service bus then facilitates communication between application components by sending and receiving messages. A typical Relativity installation requires only one message broker server. You can optionally configure your environment to have multiple servers. This can be accomplished by leveraging a RabbitMQ cluster or Service Bus for Windows Server farm. The following diagram illustrates how the Relativity service bus integrates with your environment's infrastructure in a typical installation.

(Click to expand)

diagram of Relativity service bus infrastructure

Service bus installation overview

To install the Relativity service bus, you must first install and configure your environment’s message broker. You next run the Relativity installer to add the Relativity service bus to your environment and complete other related tasks. The following diagram illustrates the installation process for a typical Relativity installation for service bus. You can optionally install your environment’s message broker on multiple hosts.

(Click to expand)

installation workflow for Relativity service bus

Use the following workflow to install the Relativity service bus in your environment:

  1. For a typical installation, install and configure your environment’s message broker. For a high availability configuration, install your environment’s message broker on the servers or VMs for this purpose. For information about installing and configuring a message broker, see Service Bus for Windows Server or RabbitMQ.
  2. Run the Relativity installer to install or upgrade your primary SQL Server and any necessary distributed servers. For more information, see the following pages:

    Note: The Relativity installation and Upgrading your Relativity service bus pages include information for troubleshooting installation issues for service bus. For general troubleshooting information, see Troubleshooting the Service Bus for Windows Server and Relativity service bus or Troubleshooting RabbitMQ depending on your environment’s message broker.

  3. Install or upgrade the Relativity service bus server:
    • Service Bus for Windows Server - Ensure that the Relativity service bus server is a node in the Service Bus for Windows Server farm.

      • Note: Note: You need to install the Relativity service bus on only a single node or host in the farm. If you have a multiple host environment, you don't need to install it on each node.

    • RabbitMQ - Run on any server with network connectivity to both the Primary SQL Server and the RabbitMQ server / cluster.
  4. Install or upgrade the agent server.
  5. Install or upgrade the web server.
  6. Install or upgrade other servers used in your environment. For example, you might install the worker manager or Analytics server depending on your organization’s needs.