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.

File field

A File type field is used to upload a file for a non-document object. When you add a File field, Relativity automatically creates other fields containing file metadata, such as File Size, File Icon, and Text fields.

Note: The following sample code uses the variable called proxy to reference an instance of the RSAPIClient class that already has the APIOptions property set. For simplicity, this sample code doesn't check on completed operations or provide error handling.

This page contains the following information:

Create a File field on an RDO

You can create a dynamic object and then add a File field on it. The following sections describe this two part process.

Create a Dynamic ObjectType

Create a Dynamic ObjectType that will be referenced in other code samples illustrating File field usage. This Dynamic ObjectType will be called Our File Container.

Create an ObjectType instance as follows:

Copy 

var objectType = new ObjectType();

Set the values for the appropriate fields:

Copy 

objectType.CopyInstancesOnWorkspaceCreation = false;
objectType.Name = “Our File Container”;
objectType.ParentArtifactTypeID = (int)ArtifactType.Case;
objectType.Pivot = false;
objectType.RelativityApplications = new FieldValueList<RelativityApplication>();
objectType.SnapshotAuditingEnabledOnDelete = true;

Using the DTO layer, call the Create() method of the ObjectType repository:

Copy 

var createResults = proxy.Repositories.ObjectType.Create(objectType);

Save the value of the ArtifactID property for later use in file uploading:

Copy 

var ourFileContainerInstanceArtifactId = createResults.Results[0].Artifact.ArtifactID;

To create an instance of the Dynamic ObjectType, you need to determine the DescriptorArtifactTypeID, which is a unique identifier for the newly created Dynamic Object type. Create a Query instance as follows:

Copy 

var query = new Query<ObjectType>();

Set the values for the appropriate fields. In general, you request only the fields that you need, rather than use the AllFields directive.

Copy 

query.Condition = new TextCondition(“Name”, TextConditionEnum.EqualTo, “Our File Container”);
query.Fields = FieldValue.AllFields;

Call the Query() method of the ObjectType repository:

Copy 

var queryResults = proxy.Repositories.ObjectType.Query(query);

Save the value of the DescriptorArtifactTypeID property for later use in field creation. You might also want to confirm that the query executed successfully.

Copy 

var descriptorArtifactTypeId = queryResults.Results[0].Artifact.DescriptorArtifactTypeID;

Create a File field

You can create a new File field on a Dynamic ObjectType. In the following sample code, the variable descriptorArtifactTypeId refers to the value retrieved from Create a File field on an RDO.

Create a Field instance:

Copy 

var field = new kCura.Relativity.Client.DTOs.Field();

Set the values for the appropriate fields:

Copy 

field.AllowGroupBy = false;
field.AllowPivot = false;
field.AllowSortTally = false;
field.FieldTypeID = FieldType.File;
field.IgnoreWarnings = true;
field.IsRequired = false;
field.Linked = false;
field.Name = “File Field For Our File Container”;

This ObjectType was added in Create a File field on an RDO:

Copy 

field.ObjectType = new ObjectType { DescriptorArtifactTypeID = descriptorArtifactTypeId }; 
field.OpenToAssociations = false;
field.Width = String.Empty;
field.Wrapping = false;

Call the Create() method of the Field repository:

Copy 

var createResults = proxy.Repositories.Field.Create(field);

Save the value of the ArtifactID property for use in file uploading later:

Copy 

var fileFieldArtifactId = createResults.Results[0].Artifact.ArtifactID;

Upload to a File field

You can upload a file to a File field. You need to obtain the following identifiers to upload the file:

  • ArtifactID of the File field associated with the object type
  • ArtifactID of the object instance with a File field that needs to be populated

Use this variable for the newly created File field:

Copy 

fileFieldArtifactId

Use this variable for the newly created instance of our Dynamic Object type (Our File Container):

Copy 

ourFileContainerInstanceArtifactId

Create an UploadRequest instance:

Copy 

var uploadRequest = new UploadRequest(proxy.APIOptions);

Set the values for the appropriate fields:

Copy 

uploadRequest.Metadata.FileName = @”C:\path\to\my\file.docx”;
uploadRequest.Metadata.FileSize = new FileInfo(uploadRequest.Metadata.FileName).Length;

This optional property indicates that the current contents in the File field will be overwritten:

Copy 

uploadRequest.Overwrite = true; 
uploadRequest.Target.FieldId = fileFieldArtifactId;
uploadRequest.Target.ObjectArtifactId = ourFileContainerInstanceArtifactId;

(Optional) Use an event handler when uploading to a File field. See the following example of a signature for an event handler:

Copy 

void UploadCompleteHandler(UploadCompleteEventArgs eventArgs)

(Optional) Register an event handler for the UploadComplete event:

Copy 

proxy.UploadComplete += UploadCompleteHandler;

Call the Upload() method on the RSAPIClient:

Copy 

proxy.Upload(uploadRequest);

Download from a File field

You can download a file from a File field. The Services API provides an overloaded Download() method for this purpose:

  • DownloadResponse Download(FileRequest fileRequest, string outputPath) – Downloads the file to the location specified by outputPath.
  • KeyValuePair<DownloadResponse, Stream> Download(FileRequest fileRequest) – Downloads the file to the Stream of the KeyValuePair.

In addition, you need to obtain the following identifiers to upload the file:

  • ArtifactID of the File field associated with the object type
  • ArtifactID of the object instance with a file that needs to be downloaded

Use this variable for the ArtifactID of the newly created File field:

Copy 

fileFieldArtifactId

Use this variable for the newly created instance of our Dynamic Object type (Our File Container):

Copy 

ourFileContainerInstanceArtifactId

Create a FileRequest instance as follows:

Copy 

var fileRequest = new FileRequest(proxy.APIOptions);
fileRequest.Target.FieldId = fileFieldArtifactId;
fileRequest.Target.ObjectArtifactId = ourFileContainerInstanceArtifactId;

Register an event handler for the DownloadComplete event:

Copy 

proxy.DownloadComplete += DownloadCompleteHandler;

Call one of the overload Download() methods on the RSAPIClient:

Copy 

proxy.Download(fileRequest, @”C:\path\to\downloaded\file.docx”);

Get a download URL for a File field

You can retrieve a URL from the File field on a Dynamic Object and then use the URL to download the associated file. The following code sample illustrates how to call the GetFileFieldDownloadURL() method on the proxy and download the required file. For information working with files through the REST API, see Download files from Relativity Dynamic Objects

Copy 

public static bool GetFileFieldDownloadURL(IRSAPIClient proxy)
{
     // STEP 1: Set APIOptions and instantiate a new DownloadURLRequest with the APIOptions.
     proxy.APIOptions.WorkspaceID = 1015926;
     var downloadUrlRequest = new DownloadURLRequest(proxy.APIOptions);
      
     // STEP 2: Set properties in the DownloadURLRequest.
     downloadUrlRequest.BaseURI = new Uri("http://localhost");
      
     // Set the ObjectArtifactID or ObjectArtifactGuid that identifies the instance of the RDO.
     downloadUrlRequest.Target.ObjectArtifactGuid = new Guid("B5FD94BB-0226-4CA5-B227-5F3F7BEE4D8A");
      
     // Set the FieldID, FieldName, or FieldGuid of the File File.
     downloadUrlRequest.Target.FieldId = 1042467;
      
     // STEP 3: Call the GetFileFieldDownloadURL method on the proxy.
     DownloadURLResponse response;
     try {
          response = proxy.Repositories.RDO.GetFileFieldDownloadURL(downloadUrlRequest);
     }
     catch (Exception ex) {
          Console.WriteLine("An error occurred calling GetFileFieldDownloadURL: {0}", ex.Message);
          return false;
     }
      
     if (response.Success) {
          Console.WriteLine("File Field Download URL: {0}", response.URL);
     }
     else {
          Console.WriteLine("An error occurred calling GetFileFieldDownloadURL: {0}", response.Message);
          return false;
     }
      
     // STEP 4: Download the File using the URL.
     HttpClient httpClient = new HttpClient();
     httpClient.BaseAddress = new Uri("http://localhost/");
      
     HttpResponseMessage httpResponse = httpClient.GetAsync(response.URL).Result;
      
     if (httpResponse.IsSuccessStatusCode) {
          try {
               // Read the file.
               Stream resultStream = httpResponse.Content.ReadAsStreamAsync().Result;
               var contentDisposition = httpResponse.Content.Headers.ContentDisposition;
                
               string fileName = contentDisposition.FileName;
                
               using (var fileStream = File.Create("C:\\path" + fileName)) {
                    resultStream.CopyTo(fileStream);
               }
               Console.WriteLine("Received file: {0}", fileName);
          }
          catch (Exception ex) {
               // An exception occurred when attempting to read and save the file locally.
               // Handle the exception.
               Console.WriteLine("Error saving File locally: {0}", ex.Message);
               return false;
          }
     }
     else {
          Console.WriteLine("HTTP response not successful: {0}", httpResponse.StatusCode);
          return false;
     }
      
     return true;
}

Clear a File field

You can clear a File field through the Services API. You need to obtain the following identifiers to clear the field:

  • ArtifactID of the File field associated with the object type
  • ArtifactID of the object instance with a File fields that needs to be cleared

Use this variable for the ArtifactID of the newly created File field:

Copy 

fileFieldArtifactId

Use this variable for the newly created instance of our Dynamic Object type:

Copy 

ourFileContainerInstanceArtifactId

Create a FileRequest instance as follows:

Copy 

var fileRequest = new FileRequest(proxy.APIOptions);
fileRequest.Target.FieldId = fileFieldArtifactId;
fileRequest.Target.ObjectArtifactId = ourFileContainerInstanceArtifactId;

Call the Clear() method on the RSAPIClient:

Copy 

proxy.Clear(fileRequest);