Tab Manager (REST)

The Tab Manager service exposes endpoints for programmatically managing tabs in the Relativity. It includes the following features:

  • Supports create, read, update, and delete operations on tabs.
  • Provides helper endpoints that simplify working with tabs. You can use these endpoints to retrieve information about the display order of tabs, parent tabs, and available object types that can be associated with tabs. Additionally, you can also retrieve workspace-level metadata for admin and system tabs.

As a sample use case, you might use the Tab Manager service to add specialized tab functionality to custom pages in a Relativity application developed for your organization.

You can also access the Tab Manager service through .NET. For more information, see Tab Manager (.NET).

Guidelines for the Tab Manager service

Review the following guidelines for working with this service.

URLs

The URLs for REST endpoints contain path parameters that you need to set before making a call:

  • Set the {versionNumber} placeholder to the version of the REST API that you want to use, using the format lowercase v and the version number, for example v1 or v2
  • Set other path parameters in the URLs to the Artifact ID of a given entity, for example setting {workspaceID} to the Artifact ID of a workspace.

    • Note: To indicate the admin-level context, set the {workspaceID} path parameter to -1.

For example, you can use the following URL to retrieve a tab:

Copy 
<host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces/{workspaceID}/tabs/{tabID}

Set the path parameters as follows:

  • {versionNumber} to the version of the API, such as v1.
  • {WorkspaceID} to the Artifact ID of the workspace that contains the tab.
  • {tabID} to the Artifact ID of a specific tab.

JSON payloads for create and update operations

When you create or update a tab, any field not included in the JSON request is automatically set to null or to a default value. For example, if the JSON for a request doesn't include the IsVisible field, then this field is automatically set to the default value of false.

Use the ReadAsync endpoint to retrieve all the properties and values set on a Tab object, and then only modify specific property values when updating the tab. This practice maintains the integrity of the data and avoids any inconsistencies. For more information, see Retrieve tab metadata and Update a tab.

IconIdentifier field

Some requests contain the IconIdentifier field, which represents a string identifier for the icon displayed when the Tab appears in the sidebar.

Client code sample

You send a request to the Tab Manager service by making a call to an endpoint with the required HTTP method. See the following base URL for this service:

Copy 
<host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces

You can use the following .NET code as a sample client for creating a tab at the admin-level. This code illustrates how to perform the following general tasks:

  • Instantiate an HttpClient object for sending requests to the Tab Manager service.
  • Set the required headers for the request. For information on setting headers, see HTTP headers.
  • Initialize variables with the values for the name and order of the tab that you want to create. The order indicates the position of the tab in relation to other tabs displayed in the Relativity UI.
  • Set the JSON input required for the operation.
  • Set the url variable to the URL for creating the tab. For more information, see Create a tab.

    Note: This code sample illustrates how to create the tab at the admin-level, so the workspace ID is set to -1 in the URL.

  • Use the PostAsync() method to send a post request.
  • Return the results of the request and deserialize it.

Create a tab

To create a new tab, send a POST request with a URL in the following format:

Copy 
<host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces/{workspaceID}/tabs

Retrieve tab metadata

You can retrieve basic or extended metadata for a tab. Extended metadata includes operations that you have permissions to perform on the tab, such as delete or update.

  • Retrieve basic metadata for a tab - send a GET request with a URL in the following format:
    Copy
    <host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces/{workspaceID}/tabs/{tabID}
  • Retrieve extended metadata for a tab -send a GET request with a URL in the following format:
    Copy
    <host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces/{workspaceID}/tabs/{tabID}?includeMetadata={includeMetadata}&includeActions={includeActions}

    Set both the {includeMetadata} and {includeActions} path parameters to true.

The body of the request is empty.

The response for a read operation contains the same fields as a response for a create operation. See the field descriptions in View field descriptions for a create response.

Update a tab

You can modify the properties of a tab, such as its name, order, and others. Additionally, you can restrict the update of a tab to the date that it was last modified by adding the LastModifiedOn field to the request.

Note: You need to unlock an application before making updates to the tabs that it contains. See Add components to an application.

Send a PUT request to the following URL:

Copy 
<host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces/{workspaceID}/tabs/{tabID}

The response for an update operation contains the same fields as a response for a create operation. See the field descriptions in View field descriptions for a create response.

Delete a tab

You can remove a tab from Relativity if you have the appropriate permissions. For more information, see Security and permissions in the Relativity Documentation site.

Before you delete a tab, consider checking for other dependent tabs. See Object Manager (REST).

Send a DELETE request to the following URL:

Copy 
<host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspace/{workspaceID}/tabs/{tabID}

The body of the request is empty.

When the tab is successfully deleted, the response returns the status code of 200.

Retrieve object types for a tab

You can retrieving a list of all object types in a workspace available for creating or updating a tab. A tab must be associated it with an object.

Send a GET request with a URL in the following format:

Copy 
<host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces/{workspaceID}/tabs/eligible-object-types

The body of the request is empty.

Retrieve eligible parent tabs

You can retrieve a list of parent tabs, which you can associate with a tab when you add or edit it. In the Relativity UI, a parent tab displays a drop-down list containing child tabs.

Send a GET request with a URL in the following format:

Copy 
<host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces/{workspaceID}/tabs/eligible-parents

The body of the request is empty.

Retrieve workspace-level metadata for admin and system tabs

You can retrieve workspace-level metadata about admin and system tabs. This metadata includes fields that can't be updated and those that aren't supported for a specific tab. In general, the following guidelines apply to this metadata:

  • Admin tabs - Because these tabs are supported only for workspaces, the RelativityApplications field is always returned as an unsupported field by the meta endpoint.
  • System tabs - Because these tabs are part of the core Relativity application, most of their fields can't be updated, and are returned by the meta endpoint as read-only fields, such the Name, Link, and RelativityApplications fields. For example, the fields on the Errors tab are read-only.

Send a GET request with a URL in the following format:

Copy 
<host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces/{workspaceID}/tabs/meta

Note: Set {workspaceID} to -1 to indicate the admin-level context for system and admin tabs.

The body of the request is empty.

The response contains the following fields:

  • Unsupported - an array of fields not supported on the current instance of this tab.
  • ReadOnly - an array of tab fields that can't be modified, such its name or link.
Copy 
{
    "Unsupported": [
        "RelativityApplications"
    ],
    "ReadOnly": []
}

Retrieve tab orders

You can retrieve current order of the tabs in a workspace. The order assigned to a tab determines its position in the Relativity UI. Tabs with a lower order number are displayed on the left, while those with higher order numbers are displayed on the right. For more information, see Tabs on the Relativity Documentation site.

Send a GET request with a URL in the following format:

Copy 
<host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces/{workspaceID}/tabs/view-order-list

The body of the request is empty.

Retrieve all tabs for navigation

You can retrieve information about each tab that the calling user can navigate to in a specific workspace. This endpoint returns a URL for navigating to each tab and tab metadata.

Send a GET request with a URL in the following format:

Copy 
<host>/Relativity.Rest/API/relativity-data-visualization/{versionNumber}/workspaces/{workspaceID}/tabs/navigation

The body of the request is empty.