View Manager API

You can use the View Manager service to create, read, and update Relativity views. This service also includes methods for retrieving the following information:

  • The status of a user's permissions on a view and on fields used in the search conditions on a view.
  • A list of workspace users who can be assigned ownership of a view.
  • A list of object types in a workspace. When creating a view, you can use this list to assign an object type to a view based on the objects that you want displayed in it.
  • A list of each view in a workspace for a specific Artifact ID.
  • A list of each view that is associated with a saved search in a workspace.

You can use the View Manager service to add or modify views used in a custom application or through the Relativity UI. For example, you might want to create a view that uses a specific set of search criteria to display custom objects in an application.

The REST API also supports the View Manager service. For more information, see View Manager service.

This page contains the following information:

Fundamentals for the View Manager service

In the Services API, the Relativity.Service.View namespace contains the IViewManager interface and additional classes required to interact with Relativity views. The IViewManager interface contains the methods required to access the functionality provided by this service. The interface contains the following methods:

  • CreateSingleAsync() - adds a new view to a Relativity workspace. See Create a view in a workspace.
  • ReadSingleAsync() - retrieves information about a view. This method returns a View object, which contains the properties used to define the view. See Retrieve information about a view.
  • RetrieveAllViewsAsync() - retrieves each view in a workspace for a specific Artifact ID. To learn more, visit Views.
  • RetrieveAllViewsForSearchAsync() - retrieves each view that is associated with a saved search in a workspace. To learn more, visit Views and Saved Search.
  • UpdateSingleAsync() - modifies properties of a view. See Update the properties of a view.
  • GetViewOwnersAsync() - retrieves a list of users in a workspace. You can then use this list to assign owners to a view. See Retrieve users for assigning view ownership.
  • GetAccessStatusAsync() - retrieves information about whether a user has View permissions to a view, and to the fields used in the criteria for search conditions on the view. The ViewAccessStatus class contains properties that provide this information. See Retrieve the access status of a user.
  • GetObjectTypesAsync() - retrieves a list of object types in a workspace. See Retrieve a list of object types in the workspace.

In addition, the Relativity.Service.View namespace contains the following classes for use with this service:

  • View class - represents a Relativity view. Its properties include the view name, Artifact ID, search criteria used by the view, a list of fields returned in the result set, the owner of the view, the associated dashboard, and others. The ReadSingleAsync() method returns a View object.
  • ViewAccessStatus class - includes properties that indicate whether a user has View permissions on the specified view, and whether a user has View permissions on all fields used in the criteria for a search conditions on the view. The GetAccessStatusAsync method returns a ViewAccessStatus object.

For reference information about these classes and methods, see Relativity.Services.View.

Create a view in a workspace

Use the CreateSingleAsync() method to add a new view to a Relativity workspace. When calling this method, pass the Artifact ID of the workspace where you want to create the view, and a View object. This method returns the Artifact ID of the newly created view.

public async Task<bool> CreateSingleAsync(IHelper helper)
{
    bool success = false;

    using (IViewManager proxy = helper.GetServicesManager().CreateProxy<IViewManager>(ExecutionIdentity.User))
    {
        Logging.ISampleLogger logger = _logger.ForContext("MethodName", new StackFrame(0).GetMethod().Name, false);

        try
        {
            View view = new View();
            view.ArtifactTypeID = (int)ArtifactType.Document;
            view.Name = "My View";

            List<UserRef> viewhOwners = await proxy.GetViewOwnersAsync(this.SampleWorkspace_ID);
            view.Owner = viewhOwners.First(o => o.ArtifactID == _PUBLIC_OWNER_ARTIFACT_ID);

            view.Fields.Add(new FieldRef("Control Number"));
            view.Fields.Add(new FieldRef("File Size"));

            Criteria fileSizeCriteria = new Criteria();
            fileSizeCriteria.Condition = new CriteriaCondition()
            {
                FieldIdentifier = new FieldRef("File Size"),
                Operator = CriteriaConditionEnum.GreaterThan,
                Value = 2000
            };
            view.SearchCriteria.Conditions.Add(fileSizeCriteria);

            Services.Sort fileSizeSort = new Services.Sort()
            {
                FieldIdentifier = new FieldRef("File Size"),
                Direction = Services.SortEnum.Descending,
                Order = 1
            };
            view.Sorts.Add(fileSizeSort);

            view.Order = 100;
            view.VisibleInDropdown = true;
            view.Dashboard = new Services.DashboardObject.DashboardRef(this.SampleDashboardArtifact_ID);

            int artifactID = await proxy.CreateSingleAsync(this.SampleWorkspace_ID, view);

            if (artifactID != 0)
            {
                success = true;
                logger.LogInformation($"CreateSingleAsync succeeded. ArtifactID is {artifactID}.");
            }
            else
            {
                logger.LogError("CreateSingleAsync failed");
            }
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unhandled Exception");
        }
    }

    return success;
}

Retrieve information about a view

Use the ReadSingleAsync() method to retrieve information about a view. When calling this method, pass the Artifact ID of the workspace where the view resides, and the Artifact ID of the view. This method returns a View object.

public async Task<bool> ReadSingleAsync(IHelper helper)
{
    bool success = false;

    using (IViewManager proxy = helper.GetServicesManager().CreateProxy<IViewManager>(ExecutionIdentity.User))
    {
        Logging.ISampleLogger logger = _logger.ForContext("MethodName", new StackFrame(0).GetMethod().Name, false);

        try
        {
            int? viewToReadArtifactID;
            if (ViewHelper.TryCreate(proxy, helper, this.SampleWorkspace_ID, "My View to Read", out viewToReadArtifactID))
            {
                View view = await proxy.ReadSingleAsync(this.SampleWorkspace_ID, viewToReadArtifactID.Value);

                logger.LogInformation($"ReadSingleAsync succeeded. View ArtifactID is {view.ArtifactID}, Name is {view.Name}.");

                success = true;
            }
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unhandled Exception");
        }
    }

    return success;
}

Retrieve the views in a workspace

You can use the RetrieveAllViewsAsync() method to see each view in a workspace for a specific Artifact ID. To learn more, visit Views.

public async Task<ViewResponse[]> RetrieveAllViewsAsync(int workspaceArtifactID, int artifactTypeID)
{
    using (IViewManager viewManager = serviceFactory.CreateProxy<IViewManager>())
    {
        ViewResponse[] viewResponses = await viewManager.RetrieveViewsByContextArtifactIDAsync(workspaceArtifactID, artifactTypeID);
        return viewResponses;
    }
}

Retrieve the views in a saved search

You can use the RetrieveAllViewsForSearchAsync() method to see each view that is associated with a saved search in a workspace. To learn more, visit Saved Search.

public async Task<SearchViewResponse[]> RetrieveAllViewsForSearchAsync(int workspaceArtifactID)
{
    using (IViewManager viewManager = serviceFactory.CreateProxy<IViewManager>())
    {
        SearchViewResponse[] searchViewResponses = await viewManager.RetrieveViewsByContextArtifactIDForSearchAsync(workspaceArtifactID);
        return searchViewResponses;
    }
}

Update the properties of a view

You can modify the properties of a view by calling the UpdateSingleAsync() method. When calling this method, pass the Artifact ID of the workspace where the view resides, and a View object.

public async Task<bool> UpdateSingleAsync(IHelper helper)
{
bool success = false;

using (IViewManager proxy = helper.GetServicesManager().CreateProxy<IViewManager>(ExecutionIdentity.User))
{
    Logging.ISampleLogger logger = _logger.ForContext("MethodName", new StackFrame(0).GetMethod().Name, false);

    try
    {
        int? viewToUpdateArtifactID;
        if (ViewHelper.TryCreate(proxy, this.SampleWorkspace_ID, "My View to Update", out viewToUpdateArtifactID))
        {
            View view = await proxy.ReadSingleAsync(this.SampleWorkspace_ID, viewToUpdateArtifactID.Value);

            view.Name = $"{view.Name} - updated";
            view.Fields.Add(new FieldRef("File Type"));

            Criteria fileTypeCriteria = new Criteria();
            fileTypeCriteria.Condition = new CriteriaCondition()
            {
                FieldIdentifier = new FieldRef("File Type"),
                Operator = CriteriaConditionEnum.IsLike,
                Value = "document"
            };
            view.SearchCriteria.Conditions.Add(fileTypeCriteria);

            Services.Sort fileTypeSort = new Services.Sort()
            {
                FieldIdentifier = new FieldRef("File Type"),
                Direction = Services.SortEnum.Ascending,
                Order = 200
            };
            view.Sorts.Add(fileTypeSort);

            await proxy.UpdateSingleAsync(this.SampleWorkspace_ID, view);

            logger.LogInformation($"UpdateSingleAsync succeeded.");

            success = true;
        }
    }
    catch (Exception ex)
    {
        logger.LogError(ex, "Unhandled Exception");
    }
}

Retrieve the access status of a user

You can use the GetAccessStatusAsync() method to determine whether a user has View permissions to a view, and to the fields used in the criteria for search conditions on the view. When calling this method, pass in the Artifact ID of the workspace, and that of the Artifact ID of the view that you want to check for user access status. The method returns a ViewAccessStatus object, which has CanView and CanViewCriteriaFields properties on it.

public async Task<bool> GetAccessStatusAsync(IHelper helper)
{
   bool success = false;

   using (IViewManager proxy = helper.GetServicesManager().CreateProxy<IViewManager>(ExecutionIdentity.User))
   {
      Logging.ISampleLogger logger = _logger.ForContext("MethodName", new StackFrame(0).GetMethod().Name, false);

      try
      {
         int? viewToGetAccecStatusToArtifactID;
         if (ViewHelper.TryCreate(proxy, this.SampleWorkspace_ID, "My View to Get Access Status to", out viewToGetAccecStatusToArtifactID))
         {
            ViewAccessStatus status = await proxy.GetAccessStatusAsync(this.SampleWorkspace_ID, viewToGetAccecStatusToArtifactID.Value);

            logger.LogInformation($"GetAccessStatusAsync succeeded. Exists is {status.Exists}, CanView is {status.CanView}, CanViewCriteriaFields is {status.CanViewCriteriaFields}");

            success = true;
         }
      }
      catch (Exception ex)
      {
         logger.LogError(ex, "Unhandled Exception");
      }
   }

   return success;
}

Retrieve users for assigning view ownership

You can use the GetViewOwnersAsync() method to retrieve a list of users in a workspace. You can then use this list to assign owners to a view. To be designated as an owner, a user must have View permissions for views. For more information, see Security and Permissions on the Relativity Documentation site.

public async Task<bool> GetViewOwnersAsync(IHelper helper)
{
   bool success = false;

   using (IViewManager proxy = helper.GetServicesManager().CreateProxy<IViewManager>(ExecutionIdentity.User))
   {
      Logging.ISampleLogger logger = _logger.ForContext("MethodName", new StackFrame(0).GetMethod().Name, false);

      try
      {
         IEnumerable<UserRef> owners = await proxy.GetViewOwnersAsync(this.SampleWorkspace_ID);

         logger.LogInformation($"GetViewOwnersAsync succeeded. Count of possible owners is {owners.Count()}");

         success = true;
      }
      catch (Exception ex)
      {
         logger.LogError(ex, "Unhandled Exception");
      }
   }

   return success;
}

Retrieve a list of object types in the workspace

The GetObjectTypesAsync() method returns a list of object types residing in the workspace. You can select an object type from this list that is used for populating the ObjectType property on the View object. Call this method by passing Artifact ID of the workspace where the view exists. It returns a list of ObjectTypeRef objects.

public async Task<bool> GetObjectTypesAsync(IHelper helper)
{
   bool success = false;

   using (IViewManager proxy = helper.GetServicesManager().CreateProxy<IViewManager>(ExecutionIdentity.User))
   {
      Logging.ISampleLogger logger = _logger.ForContext("MethodName", new StackFrame(0).GetMethod().Name, false);

      try
      {
         IEnumerable<ObjectTypeRef> objectTypes = await proxy.GetObjectTypesAsync(this.SampleWorkspace_ID);

         logger.LogInformation($"GetObjectTypesAsync succeeded. Count of available object types is {objectTypes.Count()}");

         success = true;
      }
      catch (Exception ex)
      {
         logger.LogError(ex, "Unhandled Exception");
      }
   }

   return success;
}