Workspace Manager (.NET)

The Workspace Manager API's UpdateAsync endpoint (PUT) is being deprecated December 9, 2026, as part of an effort to modernize and simplify the Relativity API surface. See this post in the developer group for more information this post in the developer group.
Several Workspace Manager API endpoints have already been deprecated as part of an effort to modernize and simplify the Relativity API surface. See this post in the developer group for more information.

In Relativity, a workspace acts as a secure data repository for documents. It supports customized views, layouts, fields, choices, and security settings. For more information, see Workspaces on the RelativityOne Documentation site.

The Workspace Manager API supports the following functionality:

CRUD operations on workspaces.
Helper methods for retrieving lists of available resources, such as matters, clients, and others.
Helper methods for retrieving information about advanced settings, such as workspace statuses, full text languages for the SQL Server, and others.

As a sample use case, you can simplify setting up reviews by using the Workspace Manager API to programmatically create multiple workspaces rather than manually adding them through the Relativity UI.

You can also use the Workspace Manager API through REST. For more information, see Workspace Manager service.

Fundamentals for the Workspace Manager API

The Workspace Manager API contains the following methods and classes as described in this section.

Methods

The Workspace Manager API exposes the following methods on the IWorkspaceManager interface in the Relativity.Environment.<VersionNumber>.Workspace namespace.

The <VersionNumber> variable in the namespace indicates the version number of the API. The version number uses the format uppercase V and an integer version number, such as V1 or V2 in .NET.

Classes

The Workspace Manager API exposes the following classes available in the Relativity.Environment.<VersionNumber>.Workspace.Models namespace:

WorkspaceRequest class - represents a request for creating or updating a workspace.
View properties
All properties related to the infrastructure details (DownloadHandlerUrl, Resource Pool, DefaultFileRepository, DataGridFileRepository, DefaultCacheLocation, and SqlServer) are optional. If the infrastructure details are not explicitly specified in the request, they are automatically selected by the algorithm.
- AzureCredentials - a Securable<ObjectIdentifier> object representing Azure credentials for the workspace. If CredentialEnableAzure setting is true, this field is required.
- AzureFileSystemCredentials - a Securable<ObjectIdentifier> object representing the Azure file system credentials for the workspace. If CredentialEnableAzure setting is true, this field is required.
- DataGridFileRepository - a Securable<ObjectIdentifier> object representing the file repository for the physical location of the text files used by Data Grid. This field is optional. If not specified, the file repository server for Data Grid is automatically selected by the algorithm.
- DefaultCacheLocation - a Securable<ObjectIdentifier> object representing the cache location server where the natives, images, productions and other file types are temporarily stored. This field is optional. If not specified, the cache location server is automatically selected by the algorithm.
- DefaultFileRepository - a Securable<ObjectIdentifier> object representing the file repository for the physical location of the files, including document natives and images. This field is optional. If not specified, the file repository server is automatically selected by the algorithm.
- DownloadHandlerUrl - a string representing the default URL used to make downloaded files available to users. This field is optional. If not specified in the request, the default URL is automatically selected by the algorithm.
- EnableDataGrid - a Boolean value indicating whether the workspace can have fields saved to Data Grid. This field can't be set during a create operation.
- Matter - a Securable<ObjectIdentifier> object representing the case or legal action associated with the workspace. This field is required.
- Name -a string representing the name of the workspace. This field is required.
- ProductionRestrictions - a Securable<ObjectIdentifier> object representing the saved search used to exclude documents from new production sets. This field can't be set during a create operation.
- ResourcePool - a Securable<ObjectIdentifier> object representing the resource pool used by the workspace for the other resource-related fields. This field is optional. If not specified, the resource pool is automatically selected by the algorithm.
- SqlFullTextLanguage - an integer representing the ID of the language used for determining the word-break characters used in the full text index for the workspace. Defaults to 0 if not specified.
- SqlServer - a Securable<ObjectIdentifier> object representing the SQL Server where the workspace database is stored. This field is optional. If not specified, the SQL server is automatically selected by the algorithm.
- Status - an ObjectIdentifier object representing the status of the workspace used in views to filter on workspaces. This field is required.
- Template - a Securable<ObjectIdentifier> object representing an existing workspace structure used to create the workspace. You can only set this field in a create request.
- UseCase - a string that gets or sets the workspace use case. This field is optional.
- WorkspaceAdminGroup - a Securable<ObjectIdentifier> object representing the group selected as the admin group for the workspace. A create operation cannot set this field.
WorkspaceResponse class - represents the results of a read operation on a workspace.
View properties
- Actions - a list of Action objects representing RESTful operations that a user has permissions to perform on the artifact.
- AzureCredentials - a Securable<DisplayableObjectIdentifier> object representing Azure credentials for the workspace.
- AzureFileSystemCredentials - a Securable<DisplayableObjectIdentifier> object representing the Azure file system credentials for the workspace.
- Client - a Securable<DisplayableObjectIdentifier> object representing the client associated with the workspace.
- ClientNumber - a Securable<string> representing the number of the clients associated with the workspace.
- CreatedBy - a DisplayableObjectIdentifier object representing the user who created the workspace.
- CreatedOn - a DateTime object representing the date and time when the workspace was added to Relativity.
- DataGridFileRepository - a Securable<DisplayableObjectIdentifier> object representing the file repository for the physical location of the text files used by Data Grid.
- DefaultCacheLocation - a Securable<DisplayableObjectIdentifier> object representing the cache location server where the natives, images, productions and other file types are temporarily stored.
- DefaultFileRepository - a Securable<DisplayableObjectIdentifier> object representing the file repository for the physical location of the files, including document natives and images.
- DownloadHandlerUrl - a string representing the default URL used to make downloaded files available to users.
- EnableDataGrid - a Boolean value indicating whether the workspace can have fields saved to Data Grid.
- Keywords - a string representing keywords associated with the workspace.
- LastModifiedBy - a DisplayableObjectIdentifier object representing the user who recently updated the workspace.
- LastModifiedOn - a DateTime object representing the date and time when the workspace was most recently updated.
- Matter - a Securable<DisplayableObjectIdentifier> object representing the case or legal action associated with the workspace.
- MatterNumber - a Securable<string> representing the number for the matter associated with the workspace.
- Meta - a Meta object representing a list of unsupported and read-only properties on the current workspace.
- Notes - a string representing an optional description or other information about the workspace.
- ProductionRestrictions - a Securable<DisplayableObjectIdentifier> object representing the saved search used to exclude documents from new production sets.
- ResourcePool - a Securable<DisplayableObjectIdentifier> object representing the resource pool used by the workspace for the other resource-related fields.
- SqlFullTextLanguage - a NameIDPair object representing the ID and name of the language used for determining the word-break characters used in the full text index for the workspace.
- SqlServer - a Securable<DisplayableObjectIdentifier> object representing the SQL Server where the workspace database is stored.
- Status - a DisplayableObjectIdentifier object representing the status of the workspace used in views to filter on workspaces.
- UseCase - a string that gets or sets the workspace use case. This field is optional.
- WorkspaceAdminGroup - a Securable<DisplayableObjectIdentifier> object representing the group selected as the admin for the workspace.
SqlFullTextLanguageOptions class - represents the available full text language options for the SQL Server associated with a workspace.
View properties
- DefaultLanguageLcid - an integer representing the ID of the default language.
- Languages - a list of NameIDPair objects representing the available languages.
WorkspaceSummary class - represents the statistics for a workspace.
View properties
- DocumentCount - a long representing the number of documents in a workspace.
- FileSize - a long representing the total size of the workspace files in bytes.

Guidelines for the Workspace Manager API

Review the following guidelines for working with the Workspace Manager API.

NuGet package

The NuGet package called Relativity.Environment.SDK is required to use the endpoints exposed in the Workspace Manager API. For more information, see SDK and Nuget Compatibility.

Create a proxy

You must use a proxy to interact with the Workspace Manager API. To set up a proxy, call the CreateProxy() method on the object returned by the GetServiceManager() method.

View code sample

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
var userEmail = "user@test.com"; // User login
var password = "abc123456!"; // User password
 
Uri relativityServicesUri = new Uri("http://localhost/relativity.services");
Uri relativityRestUri = new Uri("http://localhost/relativity.rest/api");
 
var usernamePasswordCredentials = new UsernamePasswordCredentials(userEmail, password);
ServiceFactorySettings settings = new ServiceFactorySettings(
    relativityServicesUri,
    relativityRestUri,
    usernamePasswordCredentials);
ServiceFactory serviceFactory = new ServiceFactory(settings);
 
IWorkspaceManager workspaceManager = serviceFactory.CreateProxy<IWorkspaceManager>();

Field permissions

Review the following information about how field permissions are used by Workspace Manager API:

Secured fields - A user interacting with the Workspace Manager API may be given access to read and write to only select fields in the workspace. You can control this access by using the Securable<T> object types. Objects of this type have the following properties: Secured (bool) and Value (T). When the Secured property is set to true, the user doesn't have read or write access to the contents of the fields set for the Value property.

View table with field permissions

This table illustrates the permissions set on each field by operation. For general information, see Instance security and Workspace security on the RelativityOne Documentation site.

Field	Create	Update	Read
Matter	View permissions set on the Matter object at the instance level.	Same as create.	Same as create.
ClientNumber	N/A	N/A	View permissions set on the Client object at the instance level.
ProductionRestrictions	N/A	View permissions set on the Search object at the workspace level.	View permissions set on the Search object at the workspace level.
ResourcePool	View permissions set on the Resource Pool object at the instance level.	Same as create.	Same as create.
DefaultFileRepository	View permissions set on the Resource Server object at the instance level.	Same as create.	Same as create.
DataGridFileRepository	View permissions set on the Resource Server object at the instance level.	Same as create.	Same as create.
DefaultCacheLocation	View permissions set on the Resource Server object at the instance level.	Same as create.	Same as create.
SqlServer	View permissions set on the Resource Server object at the instance level.	Same as create.	Same as create.
AzureCredentials	View permissions set on the Credential object at the instance level.	Same as create.	Same as create.
AzureFileSystemCredentials	View permissions set on the Credential object at the instance level.	Same as create.	Same as create.
UseCase	N/A	N/A	View permissions set on the Workspace object at the instance level.
Template	View permissions set on the Workspace object at the instance level.	N/A	N/A
WorkspaceAdminGroup	View permissions set on the Credential object at the instance level.	N/A	Same as create.

Read-only fields - A user may have permission to view a field but not update or delete it. In this case, the field name is included in the read-only list in the metadata. The following fields are examples: client, matter, and workspace admin group.

Cancellation and progress

The Workspace Manager API provides overloaded methods for create, update, and query operations, which support cancellation and progress functionality. For more information, see Cancellation and progress.

Create operation helper methods

The following helper methods provide functionality to support the create operation.

Retrieve unsupported fields for a create operation

Use the GetMetaAsync() method to retrieve a list of unsupported WorkspaceRequest fields for a create operation.

View code sample

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
public async Task GetMetaAsync()
{
    try
    {
        Meta meta = await _workspaceManager.GetMetaAsync();
 
        if (meta.ReadOnly.Any())
        {
            Console.WriteLine($"The following fields are read-only: {string.Join(", ", meta.ReadOnly)}");
        }
        else
        {
            Console.WriteLine("No fields are read-only.");
        }
 
        if (meta.Unsupported.Any())
        {
            Console.WriteLine($"The following fields are unsupported: {string.Join(", ", meta.Unsupported)}");
        }
        else
        {
            Console.WriteLine("No fields are unsupported.");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Failed to get meta: {ex.Message}");
        throw;
    }
}

Retrieve a workspace

Use the ReadAsync() method to retrieve a workspace. This method takes the Artifact ID of a workspace and returns a WorkspaceResponse object.

View code sample

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
public async Task ReadWorkspaceAsync(int workspaceID, bool includeMetadata, bool includeActions)
{
    try
    {
        WorkspaceResponse response = await _workspaceManager.ReadAsync(workspaceID, includeMetadata, includeActions);
        Console.WriteLine($"Workspace {workspaceID} has the name {response.Name}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Failed to read workspace {workspaceID}: {ex.Message}");
        throw;
    }
}

Update a workspace

Use the UpdateAsync() method to modify the properties of a workspace. This method takes the Artifact ID of the workspace and a WorkspaceRequest object. It returns a WorkspaceResponse object.

View code sample

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
public async Task UpdateWorkspaceAsync(int workspaceID)
{
    try
    {
        WorkspaceResponse originalWorkspace = await _workspaceManager.ReadAsync(workspaceID, true, true);
         
        WorkspaceRequest request = new WorkspaceRequest()
        {
            Name = "Updated Workspace",
            Matter = new Securable<ObjectIdentifier>() { Value = originalWorkspace.Matter.Value },
            Status = originalWorkspace.Status,
            ResourcePool = new Securable<ObjectIdentifier>() { Value = originalWorkspace.ResourcePool.Value },
            SqlServer = new Securable<ObjectIdentifier>() { Value = originalWorkspace.SqlServer.Value },
            DefaultFileRepository = new Securable<ObjectIdentifier>() { Value = originalWorkspace.DefaultFileRepository.Value },
            DefaultCacheLocation = new Securable<ObjectIdentifier>() { Value = originalWorkspace.DefaultCacheLocation.Value },
            DownloadHandlerUrl = originalWorkspace.DownloadHandlerUrl
        };
 
        WorkspaceResponse response = await _workspaceManager.UpdateAsync(workspaceID, request);
        Console.WriteLine($"Updated workspace with artifact ID {workspaceID} on {response.LastModifiedOn}");
    }
    catch (InvalidInputException ex)
    {
        Console.WriteLine("The following validation errors were found:");
        foreach (ValidationError error in ex.Errors)
        {
            Console.WriteLine($"\t{error.PropertyName}: {error.ErrorMessage}");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Failed to update workspace: {ex.Message}");
        throw;
    }
}

Retrieve workspace statistics

Use the GetWorkspaceSummaryAsync() method to retrieve a summary of workspace statistics. This method takes the Artifact ID of the workspace as an argument and returns a WorkspaceSummary object.

View code sample

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
public async Task GetWorkspaceSummaryAsync(int workspaceID)
{
    try
    {
        WorkspaceSummary workspaceSummary = await _workspaceManager.GetWorkspaceSummaryAsync(workspaceID);
        Console.WriteLine($"Document Count: {workspaceSummary.DocumentCount}");
        Console.WriteLine($"File Size: {workspaceSummary.FileSize}");
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Failed to get workspace summary: {ex.Message}");
        throw;
    }
}

Resource information helper methods

The following helper methods correspond to the fields that you can set in the Resource Information section of the Workspace form in the Relativity UI. For more information, see Workspaces on the RelativityOne Documentation site.

Advanced settings helper methods

The following helper methods correspond to the fields that you can set in the Advanced settings section of the Workspace form in the Relativity UI. For more information, see Workspaces on the RelativityOne Documentation site.

Retrieve available statuses for a workspace

Use the GetEligibleStatusesAsync() method to retrieve a list of available statuses for a workspace. This method returns a list of DisplayableObjectIdentifier objects, which contain the Artifact ID, Name, and GUIDs identifying each status. Use this method when setting the Status property on a workspace.

View code sample

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public async Task GetEligibleStatusesAsync()
{
    try
    {
        List<DisplayableObjectIdentifier> statuses = await _workspaceManager.GetEligibleStatusesAsync();
 
        Console.WriteLine("Eligible Statuses:");
        foreach (DisplayableObjectIdentifier status in statuses)
        {
            Console.WriteLine($"{status.Name} ({status.ArtifactID})");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Failed to get eligible statuses: {ex.Message}");
        throw;
    }
}

Retrieve full text languages for SQL Server

Use the GetEligibleSqlFullTextLanguagesAsync() method to retrieve a list of available full text languages for the SQL Server assigned to a workspace. This method returns a list of SqlFullTextLanguageOptions objects, which describe the available and default languages. Use this method when setting the SqlFullTextLanguage property on a workspace.

View code sample

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
public async Task GetEligibleSqlFullTextLanguagesAsync()
{
    try
    {
        SqlFullTextLanguageOptions sqlFullTextLanguageOptions = await _workspaceManager.GetEligibleSqlFullTextLanguagesAsync();
 
        Console.WriteLine("Eligible SQL Full Text Languages:");
        foreach (NameIDPair language in sqlFullTextLanguageOptions.Languages)
        {
            Console.WriteLine($"{language.Name} ({language.ID})");
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine($"Failed to get eligible SQL full text languages: {ex.Message}");
        throw;
    }
}