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

Single-artifact access

Relativity DTOs provide a set of CRUD methods for single-artifact manipulation. Use these methods to work with a single artifact rather than multiple artifacts. The kCura.Relativity.Client.Repositories.IGenericRepository< T > interface implements the single-artifact CRUD methods and inherits them through the kCura.Relativity.Client.Repositories.GenericRepository< T > class by all DTO Repository classes.

Note: Use the single-artifact CRUD methods on any DTO where support for the regular corresponding CRUD methods is provided. For example, there is currently no support for creating Layouts, so you can't use CreateSingle to create a Layout. See Supported DTOs for details.

This page contains the following information:

Supported DTOs

The following table provides information on the Relativity DTOs support for single-artifact CRUD methods.

DTO Supported Operations
  CreateSingle ReadSingle UpdateSingle DeleteSingle
Analytics Search Manager API ✓ ✓ ✓ ✓
Batch   ✓ ✓  
BatchSet ✓ ✓ ✓ ✓
Choice ✓ ✓ ✓ ✓
Client Manager API ✓ ✓ ✓ ✓
Document ✓ ✓ ✓ ✓
dtSearch Manager API ✓ ✓ ✓ ✓
Error ✓      
Field ✓ ✓   ✓
Folder ✓ ✓   ✓
Group ✓ ✓ ✓ ✓
Keyword Search Manager API ✓ ✓ ✓ ✓
Layout   ✓    
MarkupSet ✓ ✓ ✓ ✓
ObjectType ✓ ✓ ✓ ✓
RDO ✓ ✓ ✓ ✓
RelativityApplication   ✓    
RelativityScript   ✓    
Tab   ✓    
User ✓ ✓ ✓ ✓
View   ✓    
Workspace ✓ ✓ ✓ ✓

CreateSingle()

CreateSingle() takes a typed Artifact DTO and returns the artifact ID of the newly created artifact. If an error occurs, the method throws kCura.Relativity.Client.APIException. For more information, see Exception handling.

The following code sample illustrates how to use CreateSingle() to create a choice:

///
/// Create a Choice for a Choice Type Field on a Document using the CreateSingle method on the DTO Repository.
///
public static bool Create_Single_Workspace_Choice(IRSAPIClient proxy)
{
    //Step 1: Read the underlying Choice Field to obtain the Choice Type ID.
    DTOs.Field fieldDTO = proxy.Repositories.Field.ReadSingle(1035357);
    int? choiceTypeID = fieldDTO.ChoiceTypeID;

    //STEP 2: Create a Choice DTO for the new Choice and set the required fields.
    DTOs.Choice choiceToCreate = new DTOs.Choice();
    choiceToCreate.ChoiceTypeID = choiceTypeID;
    choiceToCreate.Name = "Not Responsive";
    choiceToCreate.Order = 10;
    choiceToCreate.HighlightStyleID = (Int32)kCura.Relativity.Client.HighlightColor.Green;

    //STEP 3: Set any optional fields
    choiceToCreate.KeyboardShortcut = new KeyboardShortcut() { Alt = true, Ctrl = true, Key = KeyboardShortcut.KeyboardShortcutKey.R };

    //STEP 4: Execute the CreateSingle method on the Repository
    try
    {
        int newChoiceArtifactID = proxy.Repositories.Choice.CreateSingle(choiceToCreate);
        Console.WriteLine("The new choice Artifact ID is: {0}", newChoiceArtifactID);
    }
    catch (APIException ex)
    {
        //Exceptions are thrown as an APIException
        Console.WriteLine("An error occurred: {0}", ex.Message);

        //The WriteResultSet<Choice> is returned in the Data collection of the Exception, keyed as "Result".
        WriteResultSet<DTOs.Choice> writeResultSet = (WriteResultSet<DTOs.Choice>)ex.Data["Result"];
        Console.WriteLine("The Success flag is: {0}", writeResultSet.Success);

        return false;
    }

    return true;
}

ReadSingle()

ReadSingle() takes either an Artifact ID or GUID and returns an Artifact. The field properties automatically populate. If an error occurs, the method throws kCura.Relativity.Client.APIException. For more information, see Exception handling.

Note: You can use GUIDs only with Choice, Field, ObjectType, and RDO DTOs. With all other DTOs, you must use Artifact IDs.

The following code sample illustrates how to use the ReadSingle() method to read a choice specified by Artifact ID:

/// 
/// Read all the properties from a Choice DTO, using the ReadSingle by Artifact ID operation on the DTO repository.
/// 
public static bool Read_Choice_Single_By_ArtifactID(IRSAPIClient proxy)
{

    //STEP 1:  Call the ReadSingle operation on the Choice Repository, passing the artifact ID.
    try
    {
        DTOs.Choice choiceDtoArtifact = proxy.Repositories.Choice.ReadSingle(1016577);
        Console.WriteLine("Found Artifact {0} with Name {1}", choiceDtoArtifact.ArtifactID, choiceDtoArtifact.Name);
    }
    catch (APIException ex)
    {
        //Exceptions are returned as an APIException
        Console.WriteLine("An error occurred: {0}", ex.Message);

        //The ResultSet<Choice> is returned in the Data collection of the Exception, keyed as "Result".
        ResultSet<DTOs.Choice> resultSet = (ResultSet<DTOs.Choice>) ex.Data["Result"];
        Console.WriteLine("The Success flag is: {0}", resultSet.Success);

        return false;
    }

    return true;
}

The following code sample illustrates how to use the ReadSingle method to read a choice specified by the GUID:

/// 
/// Read all the properties from a Choice DTO, using the ReadSingle by Artifact Guid operation.
/// 
public static bool Read_Choice_Single_By_ArtifactGuid(IRSAPIClient proxy)
{

    //STEP 1:  Call the ReadSingle operation on the Choice Repository, passing the artifact ID.
    try
    {
        DTOs.Choice choiceDtoArtifact = proxy.Repositories.Choice.ReadSingle(new Guid("21C0D9B0-369D-497C-AC3E-5DFA35CBAA59"));
        Console.WriteLine("Found Artifact {0} with Name {1}", choiceDtoArtifact.ArtifactID, choiceDtoArtifact.Name);
    }
    catch (APIException ex)
    {
        //Exceptions are returned as an APIException
        Console.WriteLine("An error occurred: {0}", ex.Message);

        //The ResultSet<Choice> is returned in the Data collection of the Exception, keyed as "Result".
        ResultSet<DTOs.Choice> resultSet = (ResultSet<DTOs.Choice>)ex.Data["Result"];
        Console.WriteLine("The Success flag is: {0}", resultSet.Success);

        return false;
    }

    return true;
}

UpdateSingle()

UpdateSingle() takes a typed Artifact DTO. It doesn't return anything on a successful update. If an error occurs, the method returns kCura.Relativity.Client.APIException. For more information, see Exception handling.

The following code sample illustrates how to use of method to update a single choice:

///
/// Update a Choice DTO using the UpdateSingle operation on the DTO Repository.
///
public static bool Update_Choice_Using_Single_Operation(IRSAPIClient proxy)
{
    // STEP 1: Create a choice DTO and set the updated fields.
    // NOTE: Not all fields are available when updating admin choices.
    DTOs.Choice choiceDTO = new DTOs.Choice(1016503);

    // STEP 2: Update the choice DTO fields.
    choiceDTO.Name = "Updated Choice 2";
    choiceDTO.Order = 20;

    // STEP 3: Do the update.
    try
    {
        proxy.Repositories.Choice.UpdateSingle(choiceDTO);
    }
    catch (APIException ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);

        //The WriteResultSet<Choice> is returned in the Data collection of the Exception, keyed as "Result".
        WriteResultSet<DTOs.Choice> writeResultSet = (WriteResultSet<DTOs.Choice>)ex.Data["Result"];
        Console.WriteLine("The Success flag is: {0}", writeResultSet.Success);

        return false;
    }

    return true;
}

DeleteSingle()

DeleteSingle() takes either an Artifact ID or GUID. It doesn't return anything on a successful delete. If an error occurs, the method returns kCura.Relativity.Client.APIException. For more information, see Exception handling.

Note: You can use GUIDs only with Choice, Field, ObjectType, and RDO DTOs. With all other DTOs, you must use Artifact IDs.

The following code sample illustrates how to use the method to delete a choice specified by Artifact ID:

///
/// Creates, then deletes, a workspace choice using DeleteSingle by Artifact ID.
///
/// Returns a boolean indicating the success of the delete operation.
public static bool Delete_Workspace_Choice_using_DeleteSingle_By_ArtifactID(IRSAPIClient proxy)
{
    try
    {
        // STEP 1: Read the underlying Choice field to obtain the Choice Type ID.
        DTOs.Field fieldDTO = proxy.Repositories.Field.ReadSingle(new Guid("8A6747ED-713A-4F2D-B441-C4CD91C3BBA9"));  // Designation Field
        int? choiceTypeID = fieldDTO.ChoiceTypeID;

        // STEP 2: Create a workspace choice.
        DTOs.Choice workspaceChoice = new DTOs.Choice();
        workspaceChoice.ChoiceTypeID = choiceTypeID;
        workspaceChoice.Name = "Responsive";
        workspaceChoice.Order = 10;
        workspaceChoice.HighlightStyleID = (Int32)kCura.Relativity.Client.HighlightColor.Green;

        int newChoiceArtifactID = proxy.Repositories.Choice.CreateSingle(workspaceChoice);
        Console.WriteLine("New Choice: {0}", newChoiceArtifactID);

        // STEP 3:  Delete the workspace choice
        try
        {
            proxy.Repositories.Choice.DeleteSingle(newChoiceArtifactID);
            Console.WriteLine("Choice Deleted");
        }
        catch (APIException ex)
        {
            Console.WriteLine("An error occurred: {0}", ex.Message);

            //The WriteResultSet<Choice> is returned in the Data collection of the Exception, keyed as "Result".
            WriteResultSet<DTOs.Choice> writeResultSet = (WriteResultSet<DTOs.Choice>)ex.Data["Result"];
            Console.WriteLine("The Success flag is: {0}", writeResultSet.Success);

            return false;
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    return true;
}

The following code sample illustrates how to use the method to delete a choice specified by GUID:

///
/// Creates, then deletes, a workspace choice using DeleteSingle By Guid.
///
/// Returns a boolean indicating the success of the delete operation.
public static bool Delete_Workspace_Choice_using_DeleteSingle_ByGuid(IRSAPIClient proxy)
{
    try
    {
        // STEP 1:  Delete the choice, assumes we know its Guid.
        try
        {
            proxy.Repositories.Choice.DeleteSingle(new Guid("FF1EE13B-499D-4003-96CD-AC71BAE8C69C"));
            Console.WriteLine("Choice Deleted");
        }
        catch (APIException ex)
        {
            Console.WriteLine("An error occurred: {0}", ex.Message);

            //The WriteResultSet<Choice> is returned in the Data collection of the Exception, keyed as "Result".
            WriteResultSet<DTOs.Choice> writeResultSet = (WriteResultSet<DTOs.Choice>)ex.Data["Result"];
            Console.WriteLine("The Success flag is: {0}", writeResultSet.Success);

            return false;
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine("An error occurred: {0}", ex.Message);
        return false;
    }

    return true;
}

Exception handling

The single-artifact access methods throw kCura.Relativity.Client.APIException on an error. The exception inherits from System.Exception. The Message property indicates the error. The Data object populates with either the ResultSet<T> or the WriteResultSet<T> returned from the underlying CRUD operation. The Data object is a dictionary, so Relativity retrieves the result from the dictionary using the index Result.

This approach to exception handling simplifies development. The approach to exception handling eliminates the need to check for success after every operation. With this operation, developers can get rid of a lot of "boilerplate" code that under a different approach otherwise written for every call.

Note: All APIExceptions are logged on the server-side automatically using the policy defined in the Relativity instance. Do not log these types of exceptions using the Errors Service because the error is already logged by Relativity.

The code samples above illustrate how to use kCura.Relativity.Client.APIException.