Tab Manager service

Through the REST API, 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 endpoints to simplify working with tabs. You can use these endpoints to retrieve information about the display order of tabs, parent tabs, available object types to associated with tabs, and objects dependent on a specific tab. 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.

The Relativity Services API supports the same functionality for this service as available through the REST API. For more information, see Tab Manager API.

This page contains the following information:

Guidelines for the Tab Manager service in REST

Review the following guidelines for working with the Tab Manager service.

Admin-level context

To work with tabs at the admin-level context, set the {workspaceID} variable in the URL for an endpoint to -1. For example, the {workspaceID} variable in following URL is set to -1, because it retrieves metadata for admin tabs. See Retrieve workspace-level metadata for admin and system tabs.

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/-1/tabs/meta

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.

The following JSON illustrates properties on a Tab object. For field descriptions, see Update a tab.

{
    "tab": {
        "Name": "Aliases1234",
        "Order": 100,
        "LinkType": 3,
        "ObjectType": {
            "ArtifactTypeID": 10
        },
        "IsVisible": true,
        "Parent": {
            "Secured": false,
            "Value": {
                "ArtifactID": 1003663
            }
        }
    }
}

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:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}

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.\
public async Task<int?> CreateTabExample()
{
    int? result = null;
    using (HttpClient client = new HttpClient())
    {
        client.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
        client.DefaultRequestHeaders.Add("Authorization", "Basic " + Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes("test@test.com:SomePassword")));
        client.DefaultRequestHeaders.Add("X-Kepler-Version", "2.0");
        client.BaseAddress = new Uri("https://localhost/");
   
        var tabName = "SomeNewTab";
        var order = 100;
   
        string inputJSON = $"{{\"tab\":{{ \"Name\": \"{tabName}\", \"Order\":  \"{order}\", \"LinkType\": 3, \"IsVisible\": true, \"Parent\": {{\"Value\": {{\"ArtifactID\": 1003663 }} }} }} }}";
        var url = "/Relativity.REST/API/Relativity.Tabs/workspace/-1/tabs/";
        var response = await client.PostAsync(url, new StringContent(inputJSON, Encoding.UTF8, "application/json"));
        response.EnsureSuccessStatusCode();
        var content = await response.Content.ReadAsStringAsync();
        result = JsonConvert.DeserializeObject<int>(content);
    }
   
    return result;
}

Create a tab

To create a new tab, send a POST request to the following URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}/tabs

Set the {workspaceID} variable to the Artifact ID of the workspace where you want to add a new tab. See the following sample URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/1017761/tabs

The body of the request contains the following fields:

  • tab - represents a TabRequest object. This object has some fields that aren't required to create a tab, such as RelativityApplications, ObjectType, and IsDefault fields. Any fields on this object not included in the JSON request are automatically set to null or a default value. For more information, see JSON payloads for create and update operations.

    • Name - the user-friendly name of the tab.
    • Order - the numerical value designating the position of the tab in the Relativity UI. For information about the order of tabs in a workspace, see Retrieve tab orders.
    • LinkType - indicates type of link associated with the tab. For example, a parent type indicates that the tab may have sub-tabs.
    • IsVisible - a Boolean value indicating whether the tab is displayed in a workspace.
    • Parent - contains the following fields for the parent tab:

      • Secured - indicates whether the current user has permission to view the setting in the Value field.
      • Value - an object containing Artifact ID or GUIDs of the parent tab:
        • ArtifactID - Artifact ID of the parent tab.
        • Guids - GUIDs of the parent tab.

    • RelativityApplications - a list of items that describe the applications that contain the current tab. Each item contains the following fields:

      • ArtifactID - the Artifact ID of the application;

      • Guids - GUIDs of the application

    • ObjectType - contains information about the object type that you want associated with the tab. These fields are only required for creating a tab with an object link type.

      • ArtifactTypeID - ID of the Artifact Type of the object.
      • ArtifactID - Artifact ID of the object type.
      • Guids - GUIDs of the object type.
      • Name - Name of the object type.

      Note: You can only create one tab per object type. After you create a tab for an object type, you can't reuse the Artifact ID to create another tab. Making a call with the Artifact ID returns an Invalid ObjectType error.

    • Link - a link to a URL. This field is only required for a creating a tab with an external type link.

When the request is successful, the response contains the Artifact ID of the new tab, such as1034251. It also returns the status code of 200.

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 to a URL with the following general format:
    <host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}/tabs/{tabID}

    Set the {workspaceID} variable to the Artifact ID of the workspace, and the {tabID} variable to the Artifact ID of the tab. See the following sample URL:

    <host>/Relativity.Rest/API/Relativity.Tabs/workspace/1017761/tabs/1034251
  • Retrieve extended metadata for a tab -send a GET request to a URL with the following general format:
    <host>/Relativity.Rest/API/Relativity.Tabs/workspace/{worspaceID}/tabs/{tabID}/{includeMetadata}/{includeActions}

    Set the {workspaceID} and {tabID} variables, and then set both the {includeMetadata} and {includeActions} variables to true. See the following sample URL:

    <host>/Relativity.Rest/API/Relativity.Tabs/workspace/1017761/tabs/1034251/true/true

The body of the request is empty.

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:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}/tabs

Set the {workspaceID} variable to the Artifact ID of the workspace. See the following sample URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/1017761/tabs

The body of the request must contains the following fields:

  • tab - represents a TabRequest object. This object has some fields that aren't required to update a tab, such as RelativityApplications field. Any field on this object not included in the JSON request are automatically set to null or a default value. For more information, see JSON payloads for create and update operations.

    • Name - the user-friendly name of the tab.
    • Order - the numerical value designating the position of the tab in the Relativity UI.
    • LinkType - indicates type of link associated with the tab. For more information on link types, see Create a tab.
    • Link - a link to a URL. This field is only required for a creating a tab with an external type link.
    • IsVisible - a Boolean value indicating whether the tab is displayed in a workspace.
    • Parent - contains the following fields for the parent tab:

      • Secured - indicates whether the current user has permission to view the setting in the Value field.
      • Value - contains the following fields:

        • ArtifactID - the Artifact ID of the parent tab.

        • Guids - the GUIDs of the parent tab.

    • ObjectType - contains the following field for the object type associated with the tab. These fields are only requires for a tab with an object type link:

      • ArtifactTypeID - the ID of the Artifact Type of the object.

      • ArtifactID - the Artifact ID of the object type.

      • Guids - the GUIDs of the object type.

      • Name - the name of the object type.

    • RelativityApplications - a list of items that describe the applications that contain the current tab. Each item contains the following fields:

      • ArtifactID - the Artifact ID of the application.

      • Guids - GUIDs of the application.

  • LastModifiedOn - the date and time when the tab was most recently modified. This field is only required if you want to restrict the update of an tab to the date when it was last modified. The value must match the LastModifiedOn date for the tab stored in Relativity. Otherwise, you receive a 409 error, indicating that the object has been modified.

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

Delete a tab

The Tab Manager service includes an endpoint for removing a tab from Relativity. You must have the appropriate permissions to perform this operation. For more information, see Security and permissions in the Relativity Documentation site.

Before you delete a tab, consider checking for other dependent tabs. See Retrieve dependent objects.

Send a DELETE request to the following URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}/tabs/{tabID}

Set the {workspaceID} variable to the Artifact ID of the workspace that contains the tab, and set the {tabID} to the Artifact ID of the tab that you want to delete. See the following sample URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/1017761/tabs/1034251

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

When creating or editing a tab, you must associate it with an object. The Tab Manager service includes an endpoint for retrieving a list of all object types in a workspace available for creating a tab. It also includes an endpoint for retrieving a list of all object types compatible with a specific tab. See the following endpoints:

  • Retrieve all available object types - use this endpoint when you want to create a new tab. Send a GET request to a URL with the following general format:
    <host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}/tabs/objecttypes

    Set the {workspaceID} variable to the Artifact ID of the workspace where your want to add the new tab. See the following sample URL:

    <host>/Relativity.Rest/API/Relativity.Tabs/workspace/1017761/tabs/objecttypes
  • Retrieve objects type compatible with a specific tab - use this endpoint when you want to update an existing tab. Send a GET request to the following URL:
    <host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}/tabs/{tabID}/objecttypes

    Set the {workspaceID} variable to the Artifact ID of the workspace that contains the tab, and set the {tabID} to the Artifact ID of the tab. See the following sample URL:

    <host>/Relativity.Rest/API/Relativity.Tabs/workspace/1017761/tabs/1034251/objecttypes

The body of the request is empty.

The response contains the following fields:

  • Name - the user-friendly name of the tab.
  • ID - the Artifact ID of the tab.
[
   {
      "Name":"Transform",
      "ID":1000005
   },
   {
      "Name":"Analytics Categorization Result",
      "ID":1000020
   }
]

Retrieve available parent tabs

In the Relativity UI, a parent tab displays a drop-down list containing child tabs. The Tab Manager service includes an endpoint that retrieves a list of parent tabs, which you can associate with a tab when you add or edit it. Send a GET request to a URL with the following general format:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}/tabs/parents

Set the {workspaceID} variable to the Artifact ID of the workspace containing the parent tabs to retrieve. See the following sample URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/1017761/tabs/parents

The body of the request is empty.

The response contains the following fields:

  • Name - the user-friendly name of the tab.
  • ID - the Artifact ID of the tab.
[
   {
      "Name":"Analytics Core",
      "ID":1039207
   },
   {
      "Name":"Case Admin",
      "ID":1038045
   }
]

Retrieve dependent objects

Before deleting a tab, you may want a list of other objects that are dependent on it, such as the children of a parent tab. To retrieve a list of dependent objects, send a GET request to the following URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}/tabs/{tabID}/dependencylist

Set the {workspaceID} variable to the Artifact ID of the workspace that contains the tab, and set the {tabID} to the Artifact ID of the tab. See the following sample URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/1017761/tabs/1034251/dependencylist

The body of the request is empty.

The response contains the following fields:

  • ObjectType - the type of the Relativity object dependent on an object selected for deletion.
    • Secured - indicates whether the current user has permission to view the setting in the Value field.
    • Value - represents a securable value, which is the object type.
  • Action - indicates whether a dependent object is deleted or unlinked when a specific object is deleted.
  • Count - indicates the number of objects with a dependency on a specific object selected for deletion.
    • Secured - indicates whether the current user has permission to view the setting in the Value field.
    • Value - represents a securable value, which is the number of dependent objects.
  • Connection - indicates whether the object for deletion is a parent, or a field on a single or multiple object field.
    • Secured - indicates whether the current user has permission to view the setting in the Value field.
    • Value - represents a securable value, which is the type of relationship between the objects. For example, the value is Parent when the dependent object is a child, and Field: {field name} when the dependent object is a field on a single or multiple object field.
  • HierarchicLevel - indicates the degree of dependency between object types. For example, you might select an object type for deletion that has a child object type. The fields and views associated with the child object type have a dependency with a hierarchical level of 1.
[
   {
      "ObjectType":{
         "Secured":false,
         "Value":"Tab (Level 1)"
      },
      "Action":"Delete",
      "Count":{
         "Secured":false,
         "Value":1
      },
      "Connection":{
         "Secured":false,
         "Value":"Parent"
      },
      "HierarchicLevel":0
   },
   {
      "ObjectType":{
         "Secured":false,
         "Value":"Relativity Application"
      },
      "Action":"Unlink",
      "Count":{
         "Secured":true
      },
      "Connection":{
         "Secured":false,
         "Value":"Field: Tabs"
      },
      "HierarchicLevel":0
   }
]

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.

To retrieve workspace-level metadata, send a GET request to the following URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}/tabs/meta

Set the {workspaceID} variable to -1 to indicate the admin-level context for system and admin tabs. See the following sample URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/-1/tabs/meta

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.
{
    "Unsupported": [
        "RelativityApplications"
    ],
    "ReadOnly": []
}

Retrieve tab orders

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.

The Tab Manager service includes an endpoint that you can use to retrieve current order of the tabs in a specific workspace. Send a GET request to a URL with the following general format:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/{workspaceID}/tabs/vieworderlist

Set the {workspaceID} variable to the Artifact ID of the workspace. See the following sample URL:

<host>/Relativity.Rest/API/Relativity.Tabs/workspace/1017761/tabs/vieworderlist

The body of the request is empty.

The response contains the following fields:

  • ArtifactID - the Artifact ID of the tab.
  • Name - the user-friendly name of the tab.
  • Parent - the user-friendly name of the parent tab.
  • ParentArtifactID - the Artifact ID of the parent tab.
  • Order - the numerical value designating the position of the tab in the Relativity UI.
[
   {
      "ArtifactID":1039738,
      "Name":"Entities",
      "Parent":"Entities",
      "ParentArtifactID":1039893,
      "Order":0
   },
   {
      "ArtifactID":1039423,
      "Name":"Structured Analytics Set",
      "Parent":"Indexing & Analytics",
      "ParentArtifactID":1036701,
      "Order":0
   }
]