Relativity Services API (RSAPI) DTOs have been deprecated and are no longer supported. For more information and alternative APIs, see RSAPI deprecation process.

Create workspaces and monitor asynchronous processes

Relativity workspaces are secure data repositories for storing documents and applications. For additional information, see Workspaces on the Relativity Documentation site.

This page provides a detailed explanation of the programmatic steps for the following common workspace tasks:

For complete workspace operations reference and code samples, see Workspace in RSAPI reference for .NET.

Create workspaces

To create a Relativity workspace:

  1. Instantiate the client proxy object:
    1
    2
    3
    4
    using (IRSAPIClient proxy = helper.GetServicesManager().CreateProxy<IRSAPIClient>(ExecutionIdentity.System))
    {
        //All operations on the Services API DTO objects must be enclosed in the using block
    }          

    Note: In this example the proxy object instantiates using the IRSAPIClient helper class with System execution identity. For more information, see Create the proxy using the Relativity API Helpers. All subsequent operations with Relativity objects perform within the using block.

  2. Set the workspace ID in the APIOptions object to -1. This specifies that the object you are creating is not stored in any of the already existing workspace databases.
    3.   proxy.APIOptions.WorkspaceID = -1;
  3. Query for the workspace template. In this example it is the Relativity Starter Template.

    Note: For more information about the starter template, see Starter template on the Relativity Server2021 Documentation site.

    1
    int? templateArtifactID = null;
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    Client.DTOs.Query<Client.DTOs.Workspace> query = new Client.DTOs.Query<Client.DTOs.Workspace>();
    query.Condition = new Client.TextCondition(Client.DTOs.FieldFieldNames.Name, TextConditionEnum.EqualTo, "kCura Starter Template");
     
    query.Fields = Client.DTOs.FieldValue.AllFields;
    DTOs.QueryResultSet<Client.DTOs.Workspace> resultSet = proxy.Repositories.Workspace.Query(query, 0);
     
    if (resultSet.Success)
    {
        templateArtifactID = resultSet.Results.FirstOrDefault().Artifact.ArtifactID;
    }
     
    else
    {
        Console.WriteLine("The template query operation failed. {0}", resultSet.Message);
        return false;
    }
  4. Instantiate the Workspace object:
    5.   var workspaceDTO = new Client.DTOs.Workspace();
  5. Set the value of the workspace Name field:
    6.   workspaceDTO.Name = string.Format("API Sample {0}", Guid.NewGuid());
  6. Set the values of the other fields:
    1
    2
    3
    4
    5
    6
    7
    workspaceDTO.MatterID = 101010;
    workspaceDTO.ResourcePoolID = 135790;
    workspaceDTO.Status = new Client.DTOs.Choice(987654);
    workspaceDTO.DownloadHandlerApplicationPath = "Relativity.Distributed";
    workspaceDTO.DefaultFileLocation = new Client.DTOs.Choice(787878);
    workspaceDTO.SQLFullTextLanguageCodeID = 1033;
    workspaceDTO.ServerID = 123456;

    Note: If a value is not set through the DTO, Relativity uses the value from the template workspace in the subsequent CreateAsync() call. Set the server in the target Relativity environment If you specify a server in the template doesn't exist in the target Relativity environment.

  7. Instantiate a ProcessOperationResult to track the process of the operation.
    8.   Client.ProcessOperationResult result = new Client.ProcessOperationResult();
  8. Call the CreateAsync() method of the WorkspaceRepository object passing it the template artifact ID and the populated Workspace object. Use a try/catch block in case the operation fails:
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    try
    {
        //STEP 2: Call CreateAsync passing the templateID and workspaceDTO.
        //This returns a ProcessOperationResult with a Success property and a ProcessID property.
        //NOTE: The Success property indicates the success of starting the create process,
        //not the success of the actual workspace creation.
        result = proxy.Repositories.Workspace.CreateAsync(templateArtifactID.Value, workspaceDTO);
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    9. The CreateAsync() method returns a ProcessOperationResult object containing the ProcessID, and the Success property indicating whether the operation started successfully. The Success property does not indicate whether it completed successfully. See the next section for information on synchronously monitoring the workspace creation status.

Synchronously monitor workspace creation status

To check the progress of an asynchronous operation, you can either use the MonitorProcessState() or GetProcessState() methods. Both methods take the APIOptions and the ProcessID. MonitorProcessState captures events that indicate the progress of the Workspace creation as demonstrated in the sample asynchronously . Use the events to inspect the ProcessInformation object, which contains information about the state of the process.

The following code illustrates how to monitor the results of the asynchronous workspace create operation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
if (result.Success)
{
    //Wire up ProcessState events
    proxy.ProcessComplete += HandleProcessCompleteEvent;
    proxy.ProcessProgress += HandleProcessProgressEvent;
    proxy.ProcessCompleteWithError += HandleProcessCompleteWithErrorEvent;
    proxy.ProcessFailure += HandleProcessFailureEvent;
             
    //Monitor the process state
    proxy.MonitorProcessState(proxy.APIOptions, result.ProcessID);
 
    //Alternatively to using MonitorProcessState, you can return the process state synchronously by calling
    //GetProcessState and passing the process id of the operation.
    Client.ProcessInformation processState = proxy.GetProcessState(proxy.APIOptions, result.ProcessID);
    Console.WriteLine("Process Status: {0}", processState.Status);
}

Note: If successful, use MonitorProcessState to capture events thrown during the Workspace creation. The ID of the new Workspace is returned when the creation completes successfully.

The following classes define the events that are monitored during workspace creation:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
private void HandleProcessProgressEvent(object sender, Client.ProcessProgressEventArgs eventArgs)
{
    Client.ProcessInformation info = eventArgs.ProcessInformation;
    Console.WriteLine("Completed {0} of {1} Operations", info.OperationsCompleted, info.TotalOperations);
}
 
private void HandleProcessCompleteEvent(object sender, Client.ProcessCompleteEventArgs eventArgs)
{
    Client.ProcessInformation info = eventArgs.ProcessInformation;
    Console.WriteLine("Workspace created: {0}", info.OperationArtifactIDs.FirstOrDefault());
}
 
private void HandleProcessCompleteWithErrorEvent(object sender, Client.ProcessCompleteWithErrorEventArgs eventArgs)
{
    Client.ProcessInformation info = eventArgs.ProcessInformation;
    Console.WriteLine("Workspace created with error: {0}, {1}", info.OperationArtifactIDs.FirstOrDefault(), info.Message);
}
 
private void HandleProcessFailureEvent(object sender, Client.ProcessFailureEventArgs eventArgs)
{
    Client.ProcessInformation info = eventArgs.ProcessInformation;
    Console.WriteLine("Workspace creation failed: {0}", info.Message);
 
}

Note: As an alternative to using MonitorProcessState, you can synchronously call GetProcessState to check the state of the process a single time.

1
2
ProcessInformation processState = proxy.GetProcessState(proxy.APIOptions, result.ProcessID);
Console.WriteLine("Process Status: {0}", processState.Status);

Read workspaces

You can read Relativity workspaces with both regular multi-artifact and single-artifact patterns. For more information about DTO artifact access patterns, see Single-artifact access.

To read a workspace:

  1. Instantiate the client proxy and set the workspace ID in the APIOptions object shown in Create workspaces.
  2. Call the ReadSingle() method of the WorkspaceRepository object while passing it the workspace ID to read the workspace. Use a try/catch block in case the operation fails.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    try
    {
        //NOTE: SampleWorkspace_ID is sample data created for this example
        Client.DTOs.Workspace workspace = proxy.Repositories.Workspace.ReadSingle(this.SampleWorkspace_ID);
            
        string name = workspace.Name;
    }
    catch (APIException ex)
    {
        //Exceptions are returned as an APIException
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }              

    After the Workspace object is returned, access the object fields using the object properties, for example, Name:

      string name = workspace.Name;

Update workspaces

To update a workspace:

  1. Instantiate the client proxy and set the workspace ID in the APIOptions object as shown in Create workspaces.
  2. Call the ReadSingle() method of the WorkspaceRepository object, passing it the workspace Artifact ID to update and read the workspace. Instantiate a Workspace object to read the results of the read operation. Use a try/catch block in case the operation fails.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    try
    {
        Client.DTOs.Workspace workspaceToUpdate = proxy.Repositories.Workspace.ReadSingle(this.SampleWorkspace_ID);
     
    }
    catch (Client.APIException ex)
    {
        Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        return false;              
    }  

    Note: You can create the workspace manually rather than read it.

  3. Change the value of the workspace name field. Note that in this example it is set to a GUID, but you can use any other string value.
      workspaceToUpdate.Name = string.Format("Updated Workspace {0}", Guid.NewGuid());
  4. Call the UpdateSingle() method of the WorkspaceRepository object to update the workspace. Use a try/catch block in case the operation fails.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    try
    {
        proxy.Repositories.Workspace.UpdateSingle(workspaceToUpdate);
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }<br>

Note: The Relativity Services API does not support setting production restrictions on a workspace. For additional information, see Production sets on the Relativity Server2021 Documentation site.

Delete workspaces

To delete a workspace:

  1. Instantiate the client proxy and set the workspace ID in the APIOptions object as shown in Create workspaces.
  2. Call the DeleteSingle() method of the WorkspaceRepository object and passing it the workspace ID to delete the choice. Use a try/catch block in case the operation fails.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    try
    {
        //Delete the workspace
        //NOTE: This will mark the workspace for deletion.  Similar to the Relativity interface, the SQL Server
        //Database will not be removed until the Case Manager agent executes.
        proxy.Repositories.Workspace.DeleteSingle(workspaceToDeleteID.Value);
    }
        catch (APIException ex)
    {
        //Exceptions are returned as an APIException
        Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        return false;
    }<br>

Query workspaces

To query workspaces:

  1. Instantiate the client proxy and set the workspace ID in the APIOptions object as shown in Create workspaces.
  2. Instantiate the Query object:
      Client.DTOs.Query<Client.DTOs.Workspace> query = new Client.DTOs.Query<Client.DTOs.Workspace>();           
  3. Define the query condition against the Artifact ID using the WholeNumberCondition object.
      query.Condition = new Client.WholeNumberCondition(Client.DTOs.ArtifactQueryFieldNames.ArtifactID, Client.NumericConditionEnum.EqualTo, this.SampleWorkspace_ID);           
  4. Request the Workspace object fields you want to return by the query. In this example, it is specified that all available fields should be returned:
    1
    2
    3
    query.Fields.Add(new Client.DTOs.FieldValue(Client.DTOs.WorkspaceFieldNames.TextIdentifier));
    query.Fields.Add(new Client.DTOs.FieldValue("Name"));
    query.Fields.Add(new Client.DTOs.FieldValue("Status"));
  5. Instantiate the QueryResultSet object:
      Client.DTOs.QueryResultSet<Client.DTOs.Workspace> resultSet = new QueryResultSet<Workspace>();
  6. Call the Query() method of the WorkspaceRepository object passing it the populated Query object. Use a try/catch block in case the operation fails.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    try
    {
        resultSet = proxy.Repositories.Workspace.Query(query, 0);
    }
    catch (Exception ex)
    {
        Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
        return false;
    }

    Use the workspace objects in the result set for further processing. In this example, the number of query results is returned using the TotalCount property of the QueryResultSet object.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    //Check for success
    if (resultSet.Success)
    {
        Console.WriteLine(string.Format("Number of Workspaces returned: {0}", resultSet.TotalCount));
        return true;
    }
    else
    {
        Console.WriteLine("The query failed. {0}", resultSet.Message);
        return false;
    }