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:

var objectType = new ObjectType();        

Set the values for the appropriate fields:

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:

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

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

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:

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.

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

Call the Query() method of the ObjectType repository:

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.

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:

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

Set the values for the appropriate fields:

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:

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

Call the Create() method of the Field repository:

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

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

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:

fileFieldArtifactId        

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

ourFileContainerInstanceArtifactId        

Create an UploadRequest instance:

var uploadRequest = new UploadRequest(proxy.APIOptions);        

Set the values for the appropriate fields:

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:

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:

void UploadCompleteHandler(UploadCompleteEventArgs eventArgs)

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

proxy.UploadComplete += UploadCompleteHandler;        

Call the Upload() method on the RSAPIClient:

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:

fileFieldArtifactId        

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

ourFileContainerInstanceArtifactId        

Create a FileRequest instance as follows:

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

Register an event handler for the DownloadComplete event:

proxy.DownloadComplete += DownloadCompleteHandler;        

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

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

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:

fileFieldArtifactId     

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

ourFileContainerInstanceArtifactId     

Create a FileRequest instance as follows:

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

Call the Clear() method on the RSAPIClient:

proxy.Clear(fileRequest);    

Additional Resources

DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.