This DTO has been deprecated as part of the Relativity Services API (RSAPI) Deprecation and is no longer supported. For more information and alternative APIs, see RSAPI deprecation process.

Document

In Relativity, documents consist of the content for a review or other tasks, and they are stored in workspaces. For more information, see the Relativity Documentation site.

The Services API supports all CRUD and query operations on a Document DTO.

Note: You can also perform a full set of CRUD operations on clients using the single-artifact access methods common to all Relativity DTOs. For more information, see Single-artifact access.

Fields on a Document DTO

The Document DTO supports fields available on documents through the Relativity web UI as well as the following specialized fields:

FolderName – represents the name of the folder in the Relativity, where the Document is located.
HasImages – indicates whether images of the Document exist.
HasNative – indicates whether a native file exists for the Document.
RelativityImageCount – provides the number of images associated with a Document.

Note: Because of potentially large size of the extracted text field, it is not automatically retrieved when you query the document object for all fields. To retrieve the document extracted text, you must perform an explicit read operation. For more information and a code sample, see Read a document.

For an example of working with different types of fields on the Document DTO, see Update a Document

Create a Document

When you call the Create() method on a Document DTO, you can set only these properties:

RelativityNativeFileLocation – specifies the local path for the document native uploaded to Relativity, such as c:\myFolder\myDocument.docx. It is a required property that is used only by the Create() method.
TextIdentifier – specifies the name of the document. It is a required property for the Create() method. See TextIdentifier property on DTOs.
ParentArtifact – indicates the folder where the document is added. It is an optional property.

Only these fields are supported on the Create() method for Document. The values of any other fields won't be updated if you attempt to set them during a create operation. After the Create() method completes, you can use the Update() method to populate other fields on the Document object.

Note: You can't update the native file through the Services API unless you delete and then recreate the document. However, you can use the Import API to update the native file.See Import API.

Sample code

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
36
37
38
39
40
41
42
43
44
45
46
47

public static int Create_Document(IRSAPIClient proxy)
{
     //STEP 1: Create the Document object, specifying an optional Parent Folder. The name of
            
     //the identifier field will change depending on the workspace, so use the TextIdentifier
            
     // property.
            
     DTOs.Document document = new DTOs.Document();
     document.RelativityNativeFileLocation = "C:\\SourceCode\\Mainline\\EDDS\\kCura.Relativity.Client.APISamples\\SampleFiles\\LoremIpsum.docx";
     document.TextIdentifier = "My New Document 001";
      
     //STEP 2: The Parent Folder is specified by setting Parent Artifact ID.
            
     Int32 folderId = 1003697;
      
     //This step is optional.
            
     document.ParentArtifact = new DTOs.Artifact(folderId);
     WriteResultSet<DTOs.Document> createResults = new WriteResultSet<DTOs.Document>();
      
     //STEP 3: Attempt to create the document.
            
     try
     {
          createResults = proxy.Repositories.Document.Create(document);
     }
     catch (Exception ex)
     {
          // If an error occurs while trying to create the document, write an error message.
          Console.WriteLine("Error: " + ex.Message);
          return -1;
     }
     //Check for success.
     if (createResults.Success)
     {
          Console.WriteLine("Created a new document with ArtifactId = 
               {0}", createResults.Results.First().Artifact.ArtifactID);
          return createResults.Results.First().Artifact.ArtifactID;
     }
     else
     {
          Console.WriteLine("Error creating the document: {0}", createResults.Message);
          return -1;
     }
}

Read a Document

The Read() method doesn't return a native file for a document. You must use the Download() method if you want the original native file. However, you can retrieve extracted text with the Read() method.

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 static bool Read_Document(IRSAPIClient proxy)
{
     // STEP 1: Create an object specifying the Artifact ID
     // and which fields to return.
     DTOs.Document document = new DTOs.Document(1035472);
     document.Fields = FieldValue.AllFields;
      
     // STEP 2: Call the read method on the Document Repository.
     ResultSet<DTOs.Document> results = new ResultSet<DTOs.Document>();
     try
     {
          results = proxy.Repositories.Document.Read(document);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     if (!results.Success)
     {
          Console.WriteLine("Error: " + results.Message);
          return false;
     }
      
     // STEP 3: Get the Document artifact from the read results.
     DTOs.Document documentArtifact = results.Results.FirstOrDefault().Artifact;
      
     Console.WriteLine("Document Control Number: " + documentArtifact.TextIdentifier);
     Console.WriteLine("Document Last Modified: " + documentArtifact.SystemLastModifiedOn);
     Console.WriteLine("Document Artifact ID: " + documentArtifact.ArtifactID);
      
     return true;
}

Update a Document

You can modify properties of the Document by calling the Update() method.

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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

public static bool Update_Document(IRSAPIClient proxy)
{
     // STEP 1: Create an object specifying the Artifact ID
     // and which fields to return.
     DTOs.Document document = new DTOs.Document(1035472);
     document.Fields = FieldValue.AllFields;
      
     // STEP 2: Read current values.
     ResultSet<DTOs.Document> results = new ResultSet<DTOs.Document>();
     try
     {
          results = proxy.Repositories.Document.Read(document);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     if (!results.Success)
     {
          Console.WriteLine("Error: " + results.Message);
          return false;
     }
      
     // STEP 3: Get the Artifact from the read results.
     DTOs.Document docArtifact = results.Results[0].Artifact;
     Console.WriteLine("Document Artifact ID: " + docArtifact.ArtifactID);
     Console.WriteLine("Document Text Identifier: " + docArtifact.TextIdentifier);
      
     DTOs.Artifact singleObject1 = (DTOs.Artifact)(docArtifact["Single Object"].Value);
     Console.WriteLine("Document Single Object: " + singleObject1.ArtifactID.ToString());

      
     // STEP 4: Modify properties of the document.
     // Specify a new value for Text Identifier, a property of the Artifact.
     docArtifact.TextIdentifier = "John552";
      
     // Specify a new value for Single Object, a custom field in Relativity.
     // Custom fields must be accessed using the Fields collection.
     // For a Single Object, we specify the ArtifactID.
     docArtifact["Single Object"].Value = 1036035;
      
     // Specify a list of ArtifactIDs for a MultiObject field
     //1038592, 1038594 are ArtifactIDs of the object populating the value of TestMultiObjectField. 
     docArtifact.Fields.Add(new FieldValue("TestMultiObjectField", new List<int> {1038592, 1038594}));

     // STEP 5: Call the Update method on the Document Repository.
     WriteResultSet<DTOs.Document> writeResultSet = null;
     try
     {
          writeResultSet = 
               proxy.Repositories.Document.Update(new List<DTOs.Document> { docArtifact });
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     if (writeResultSet.Success)
     {
          Console.WriteLine("Document updated successfully");
           
          docArtifact = results.Results[0].Artifact;
          Console.WriteLine("Document Artifact ID: " + docArtifact.ArtifactID);
          Console.WriteLine("Document Text Identifier: " + docArtifact.TextIdentifier);
           
          int singleObjectID = (int)(docArtifact["Single Object"].Value);
          Console.WriteLine("Document Single Object: " + singleObjectID.ToString());
     }
     else
     {
          string message = writeResultSet.Message;
          if (message == null && writeResultSet.Results.Count > 0 && !writeResultSet.Results[0].Success)
               message = writeResultSet.Results[0].Message;
          Console.WriteLine("Error: " + message);
          return false;
     }
      
     // STEP 6: Read back the updated Artifact.
     try
     {
          results = proxy.Repositories.Document.Read(document);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     if (!results.Success)
     {
          Console.WriteLine("Error: " + results.Message);
          return false;
     }
      
     // STEP 7: Get the updated property values from the read results.
     docArtifact = results.Results[0].Artifact;
     Console.WriteLine("Document Artifact ID: " + docArtifact.ArtifactID);
     Console.WriteLine("Document Text Identifier: " + docArtifact.TextIdentifier);
      
     DTOs.Artifact singleObject2 = (DTOs.Artifact)(docArtifact["Single Object"].Value);
     Console.WriteLine("Document Single Object: " + singleObject2.ArtifactID.ToString());
      
     return true;
}

You can also use the UpdateSingle() method. The following code sample illustrates how to work with different field types when updating a single Document.

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
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
public static void Update_Document(IRSAPIClient proxy)
{
    var documentArtifactID = 1038649;

    try
    {
        // Create a Document DTO specifying the artifactID of the existing document we want to represent
        var document = new DTOs.Document(documentArtifactID);

        // Modify a property on the document, in this case we are updating the identifier
        document.TextIdentifier = "John559";

        // Add the fields to be updated to the Document DTO's field collection e.g. FieldValue(fieldReference, fieldValue)

        // Fixed Length Text Field
        document.Fields.Add(new FieldValue("Example_FixedLengthTextField", "The new value for the text field"));

        // Long Text Field
        // --Both field names and Guids can be used to reference fields
        var LongTextFieldGuid = new Guid("51B5C5EB-7EE9-44F9-848A-67916B4CD2B9");
        document.Fields.Add(new FieldValue(LongTextFieldGuid, "This is the new value for the long text field it's field was referenced by Guid but it can also be referenced by the field's name"));

        // Date Fields
        document.Fields.Add(new FieldValue("Example_DateField", new DateTime(2015, 05, 18)));

        // Yes/No Field
        document.Fields.Add(new FieldValue("Example_YesNoField", true));

        // Whole Number Field
        document.Fields.Add(new FieldValue("Example_WholeNumberField", 7));

        // Decimal Field
        document.Fields.Add(new FieldValue("Example_DecimalField", 15.4));

        // Currency Field
        document.Fields.Add(new FieldValue("Example_CurrencyField", 12.51));

        // User Field
        var userArtifactID = 1015986;
        document.Fields.Add(new FieldValue("Example_UserField", new DTOs.User(userArtifactID)));

        // Single Choice Field
        // --To Completely unselect a single choice field, pass in null for a field value
        var sChoiceArtifactID = 1038752;
        document.Fields.Add(new FieldValue("Example_SingleChoiceField", new DTOs.Choice(sChoiceArtifactID)));

        // Multiple Choice Field
        // --To Completely unselect a multiple choice field, pass in null for a field value
        // --Below Guids are used to reference Choices however ArtifactIDs can also be used
        var mChoiceOneArtifactID = new Guid("D7637296-F6A3-46D8-9460-39601C6F5B3E");
        var mChoiceTwoArtifactID = new Guid("33008530-32CB-48D9-851C-14E2DCD9219C");
        var multipleChoiceValue = new DTOs.MultiChoiceFieldValueList{
            new DTOs.Choice(mChoiceOneArtifactID),
            new DTOs.Choice(mChoiceTwoArtifactID)
        };
        document.Fields.Add(new FieldValue("Example_MultipleChoiceField", multipleChoiceValue));

        // Single Object Field
        // --The integers  represent the Artifact ID of the object linked to the field
        var obj1ArtifactID = 1038729;
        document.Fields.Add(new FieldValue("Example_SingleObjectField",  obj1ArtifactID));

        // Multi Object Field
        // --The integers  represent the Artifact ID of the object linked to the field
        var obj2ArtifactID = 1038730;
        document.Fields.Add(new FieldValue("Example_MultiObjectField", new List<Int32> { obj1ArtifactID, obj2ArtifactID }));

        // Send the update command
        proxy.Repositories.Document.UpdateSingle(document);
    }
    catch (Exception ex)
    {
        Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
    }
}

Special considerations for updating Data Grid fields

When updating data grid-enabled document fields, note the following:

Audit records are created for updated Data Grid-enabled fields.
The oldValue and newValue stored with the Data Grid-enabled field audit details are truncated if they exceed 1,000,000 characters, same as the fields stored in the SQL database.
If you update both SQL and Data Grid fields, and the SQL portion of the update fails, in most cases the change to Data Grid is successfully committed and an audit record is created, while the SQL fields remains unchanged.

Delete a Document

This code sample illustrates how to remove a document from Relativity by calling the Delete() method on the Document repository.

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

public static bool Delete_Document(IRSAPIClient proxy)
{
     DTOs.Document doc = new DTOs.Document(1035605);
      
     WriteResultSet<DTOs.Document> writeResultSet = new WriteResultSet<DTOs.Document>();
     try
     {
          writeResultSet = proxy.Repositories.Document.Delete(doc);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     if (!writeResultSet.Success)
     {
          string message = writeResultSet.Message;
           
          if (message == null && writeResultSet.Results.Count > 0 && !writeResultSet.Results[0].Success)
               message = writeResultSet.Results[0].Message;
          Console.WriteLine("Error: " + message);
          return false;
     }
     else
     {
          Console.WriteLine("Document updated successfully");
     }
      
     return true;
}

Query for a Document

The Services API doesn't support query conditions for the following fields on the Document DTO:

Batch_AssignedTo
Batch_BatchSet
Batch_Status
Note: The Services API returns query results for the Batch_AssignedTo, Batch_BatchSet, and Batch_Status fields.
RelativityNativeFileLocation (Set only during a create operation.)

This code sample illustrates how to set query conditions, call the Query() method on the Document repository, and iterate through the result set.

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
36
37

public static bool Query_Document_by_Control_Number(IRSAPIClient proxy)
{
     // STEP 1: Setup your query criteria.
     TextCondition criteria = new TextCondition("Control Number", TextConditionEnum.EqualTo, "AS000005");
     Query<DTOs.Document> query = new Query<DTOs.Document>
     {
          Condition = criteria,
          RelationalField = new FieldValue("Group Identifier"),
          Fields = new List<FieldValue> { new FieldValue("Control Number") }
     };
      
     // STEP 2: Call the Query() method in the Document repository.
     QueryResultSet<DTOs.Document> result = null;
     try
     {
          result = proxy.Repositories.Document.Query(query, 0);
     }
     catch (Exception ex)
     {
          Console.WriteLine(string.Format("An error occurred: {0}", ex.Message));
          return false;
     }
      
     Console.WriteLine(string.Format("Number of documents returned: {0}", result.TotalCount));
     Console.WriteLine(string.Format("Additional Pages of Query Results Available?: {0}", !string.IsNullOrEmpty(result.QueryToken)));
      
     // STEP 3: Iterate the returned Document result.
     foreach (DTOs.Result<DTOs.Document> docResult in result.Results)
     {
          DTOs.Document doc = docResult.Artifact;
          Console.WriteLine("Document Control Number: " + doc.TextIdentifier);
          Console.WriteLine("Document Artifact ID: " + doc.ArtifactID);
     }
      
     return true;
}

Supported data grid query operators

Use these operators to query Data Grid-enabled fields:

IS SET
IS NOT SET

Notes:

The IS SET condition operator excludes the Data Grid records where the field is null or has an empty string value.
IS LIKE operator is not supported.

Download a native file

You can use the Download() method on the repository for the Document DTO to download a native file. You can download a native file from Relativity as a Stream object, or specify an output path on disk.

Note: Use the Download() method on the Document Repository class rather than this method on the FileTransferProxy class. This approach is recommended for downloading native files. See File field.

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
36
37
38
39
40
41
42
43

public static Stream Download_Document_Native(IRSAPIClient proxy)
{
    //STEP 1: Define the ArtifactID of the document which has a native file.
    
    DTOs.Document doc = new DTOs.Document(1035607);
    
    //STEP 2: Listen to the Failure event to get exceptions.
    
    proxy.Failure += FileTransferFailureHandler;
    
    //STEP 3: Call the DownloadNative() method.
    
    KeyValuePair<DownloadResponse, Stream> documentNativeResponse;
    try
    {
        documentNativeResponse = proxy.Repositories.Document.DownloadNative(doc);
    }
    catch (Exception ex)
    {
        //If an error occurs while trying to download the document, write an error message.
        
        Console.WriteLine("Error: " + ex.Message);
        return null;
    }
    //STEP 4: A 'null' Key and Value from the response indicates failure.
    
    if (documentNativeResponse.Key != null && documentNativeResponse.Value != null)
    {
        Console.WriteLine("Download succeeded: {0} bytes", documentNativeResponse.Value.Length);
        return documentNativeResponse.Value;
    }
    else
    {
        return null;
    }
}

private static void FileTransferFailureHandler(FailureEventArgs eventArgs)
{
    Console.WriteLine("The following error occurred during the download for the document with ArtifactId {0}:
                {1}", eventArgs.TargetField.ObjectArtifactId, eventArgs.Exception);
}

Additional Resources
DevHelp Community	GitHub	Release Notes	NuGet

Document

Fields on a Document DTO

Create a Document

Sample code

Read a Document

Update a Document

Special considerations for updating Data Grid fields

Delete a Document

Query for a Document

Supported data grid query operators

Download a native file

Additional Resources