Relativity Integration: Setting up a new connection

Configuring a Connection with Relativity

The Relativity Connector is an optional feature that can be added in Opus 2 Case Management. It enables linking an individual Opus 2 project to a Relativity project, allowing imports of documents—including production files and associated metadata - from Relativity.

Note: The Relativity connector must be enabled on your template before it can be configured. Please check with your account manager or Opus 2 Platform Support to confirm that you have access. 

Steps to be completed on Relativity side

1. Before the integration can be configured, an admin must confirm that the Relativity instance is a supported environment:

   1. Support Environments

      1. Relativity One

      2. Relativity Server 2024-2025 (Previous two versions)

         1. Note that while on-prem instances of Relativity are supported, additional technical configuration may be required to successfully connect. Contact Opus 2 Platform Support for assistance.

2. Once it has been determined that the instance is supported, an admin of the Relativity instance must gather the following information:
   1. The URL of the Relativity instance.
   2. Authentication credentials (two tokens generated by Relativity: a user ID and a secret). See Relativity Documentation for details on generating these.
   3. The name of the Relativity project(s) from which you want to pull content.
   4. The title of the Saved Search(es) within that Relativity project. This pre-existing Saved Search defines which documents are extracted.
   5. Details of any metadata fields to be mapped from Relativity to Opus 2. You can map specific fields in Relativity to corresponding fields in Opus 2.

Creating the Oauth2 Client

As item 2b states above, an admin of the Relativity instance needs to generate a Client ID and Client Secret by creating an OAuth2 client.

• To create the OAuth2 client, reference the following article from Relativity's support site: OAuth2 clients
  • Choose the following when configuring:
    • Enabled —  Toggled On
    • Flow Grant Type — Client Credential
  • Keep in mind that the OAuth2 client requires the selection of a Context User...

Choosing/Creating a Context User

When creating an OAuth2 client on the Relativity instance, you are required to choose a Context User. The permissions of this user account directly controls what the Opus 2 user is able to see/pull through the integration.

Because of this, admins of the Relativity instance often create a dummy user account for their Context User as they can update and restrict integration permissions. This is especially useful for Relativity vendors that host multiple clients on their instance. By utilizing a dummy user, vendors can ensure that Opus 2 does not have access to data outside of the client use case.

To ensure that users can successfully pull files and metadata through the integration, however, the Context User chosen must have the below minimum permissions. Failure to enable these settings prevents the integration from running on the Opus 2 Platform.

Relativity One	Relativity Server
Other Settings Browsers Advanced & Saved Searches must be selected.  Mass Operations Export and Export to File must be selected.	Object Security Document Local Access (Download, Copy Text)
Object Security Document Local Access (Download, Copy Text) must be enabled.	Tab Visibility Documents
	(Other Settings)  Browsers Advanced & Saved Searches Mass Operations Export to File

Testing the Connection

Now that the OAuth2 client properly configured with the Context User, it is time to test the connection within Opus 2.  As a System or Project Admin within Opus 2...

1. Go to the Project settings option in the main project menu.
2. Navigate to the Integrations menu tab.
3. Select Add New Integration and then select Relativity from the drop-down menu.

The initial integration setup dialog opens with the Relativity service selected.

4. Enter a Name, and optionally, a Description. These details are used to identify different connections if you have more than one.
5. Enter the URL of the Relativity instance you want to connect to, for example: https://relativity.example.com/Relativity/ 
6. Client ID and Client Secret to connect to your Relativity instance. The Client ID / Client Secret need to be generated on your Relativity Instance by an admin.
7. Select Test Connection. You are looking for a Connected message to confirm all above details are correct.

Troubleshooting a Connection Failure

 If you receive a Connection Failed message after completing these steps, the following items should be confirmed before reaching out to Opus 2 Platform Support:

• The OAuth2 client is set to Enabled on the Relativity instance.
• The URL of the Relativity instance is correct - removing unnecessary or incorrect characters from the URL.
• The Client ID and secret are correct - Copying and pasting these details from different sources may introduce incorrect characters.
• Particularly for clients utilising on-premise Relativity Server instances, the instance allows the specific HTTPS traffic for Relativity’s REST API architecture. The following are the necessary Relativity API Endpoints:

Relativity/Identity/connect/token

api/Relativity-Identity/v1/workspaces/-1/users/me

API/Relativity.Services.ItemListView.IItemListViewModule/Item List View Manager/GetViewDataForDropDownAsync

API/Relativity.HomePage.Services.Interfaces.IHomePageModule/WorkspaceService/queryslim

api/Relativity-Identity/v1/users/query-eligible-groups

API/relativity-environment/v1/workspace/query-by-group

query-eligible-saved-searches

api/Relativity.Services.Search.ISearchModule/Keyword Search Manager/ReadSingleAsync

api/Relativity.ObjectManager/v1/workspace/{workspace id}/object/queryslim

api/relativity-object-model/v1/workspaces/{workspace id}/documents/{document id}/file-info

api/Relativity.ObjectManager/v1/workspace/{workspace id}/object/queryslim

api/Relativity.Objects/workspace/{workspace id}/object/query

api/relativity-object-model/v1/workspaces/{workspace id}/documents/{document guid}/file

Related articles

Relativity Integration: Quick Start Guide