File Field Manager (.NET)

The File Field Manager API exposes a service for uploading and downloading files linked to file fields. For uploads, the overloaded UploadAsync() method supports the use of progress indicators and cancellation tokens. As a sample use case, you might leverage this service to create a custom page with links for downloading files from Relativity.

You can also use File Field Manager service through REST. However, this service doesn't support cancellation tokens or progress indicators through REST. For more information, see File Field Manager (REST).

This page contains the following information:

• File Field Manager API fundamentals
• Downloading files from file fields
• Uploading files to file fields

File Field Manager API fundamentals

The Relativity.Services.FileField namespace contains the IFileFieldManager interface, which exposes the following methods:

• DownloadAsync() method - downloads the contents of a file referenced by a file field in a specified workspace. See Downloading files from file fields.
• UploadAsync() method - uploads the contents of a file to temporary storage. This method returns a reference to the Field object linked to the uploaded file. You can optionally pass a progress indicator, or a progress indicator and a cancellation token to this overloaded method. See Uploading files to file fields.

  Note: Use an object of type System.IProgress or System.Threading.CancellationToken provided by the .NET framework for progress and cancellation functionality respectively.

Sample workflow for working with file fields

The sample workflow outlines how you might use the Object Manager API in conjunction to the File Field Manager API to add files to Relativity:

1. Create a Relativity object with field of type File. For example, you could use the Object Manager API to create an RDO with a File field. See Create an RDO and its specified fields.
2. Upload a file as the value for the File field created in step 1. Use the File Field Manager API to upload this file. See Uploading files to file fields.
3. Save the updated RDO. Use the Object Manager API to update RDO. See Object Manager (.NET).

After you upload a file to Relativity via the File Field Manager API, it is added to temporary storage on the server until the RDO with the File field is saved. If the RDO with the File field and associated file aren’t saved, the server deletes it after about twenty-four hours.

Downloading files from file fields

To download a file from a file field, pass the following arguments to the DownloadAsync() method:

• The Artifact ID of the workspace that contains the file field.

  Note: Set the {workspaceId} to -1 to indicate the admin-level context.

• A RelativityObjectRef object that acts as a key or reference to the object that contains the file.
• A FieldRef object that acts as a key or reference to field associated with the file.

The DownloadAsync() method returns the content of the file as a stream.

public async Task<bool> DownloadAsync(IHelper helper)
{
    var objectArtifactId = this.SampleRDO_ID;
    var fieldArtifactId = this.SampleField_File_ID;
    var workspaceID = this.SampleWorkspace_ID;
    var relativityObject = new RelativityObjectRef
    {
        ArtifactID = objectArtifactId
    };
    var field = new FieldRef() { ArtifactID = fieldArtifactId };

    bool success = false;

    using (IFileFieldManager proxy = helper.GetServicesManager().CreateProxy<IFileFieldManager>(ExecutionIdentity.User))
    {
        Logging.ISampleLogger logger = _logger.ForContext("MethodName", nameof(DownloadAsync), false);

        try
        {
            IKeplerStream stream = await proxy.DownloadAsync(workspaceID, relativityObject, field);
            Stream file = stream.GetStreamAsync().Result;

            success = stream.GetStreamAsync().Status == TaskStatus.RanToCompletion;
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unhandled Exception");
        }
    }

    return success;
}

Uploading files to file fields

To upload a file to a file field, pass the following arguments to the UploadAsync() method:

• The Artifact ID of the workspace that contains the file field.

  Note: Set the {workspaceId} to -1 to indicate the admin-level context.

• A FieldRef object that acts as a key or reference to field that you want linked to the file.
• A RelativityObjectRef object that acts as a key or reference to the object that will contain the file.
• A string representing the name of file.
• A stream representing the content of the file.
• An optional progress indicator, or a progress indicator and a cancellation token.

The UploadAsync() method returns a FieldRef object.

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

    var objectArtifactId = this.SampleRDO_ID;
    var fieldArtifactId = this.SampleField_File_ID;
    var workspaceID = this.SampleWorkspace_ID;
    var fileName = "LoremIpsum.docx";
    var relativityObject = new RelativityObjectRef
    {
        ArtifactID = objectArtifactId
    };
    var field = new FieldRef() { ArtifactID = fieldArtifactId, Name = fileName };
    var filePath = string.Format("{0}\\SampleFiles\\{1}", Directory.GetCurrentDirectory(), fileName);

    using (IFileFieldManager proxy = helper.GetServicesManager().CreateProxy<IFileFieldManager>(ExecutionIdentity.User))
    {
        Logging.ISampleLogger logger = _logger.ForContext("MethodName", nameof(DownloadAsync), false);

        try
        {
            var keplerStream = new KeplerStream(File.OpenRead(filePath));
            var uploadedFile = await proxy.UploadAsync(workspaceID, field, relativityObject, fileName, keplerStream);

            success = uploadedFile?.UploadedFileGuid != null;
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unhandled Exception");
        }
    }

    return success;
}