

Last date modified: June 18 2025
The Relativity Transfer SDK is designed for uploading and downloading data to and from RelativityOne fileshares.
The Relativity Transfer SDK includes the following core features:
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Minor improvements around statistics reporting
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Fixed possible runtime issue with assembly version
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Added support to download data directly to a drive as well as upload from a drive
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Improved job registration and exposed retry policy option
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Fixed issue where transfer got stuck
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Added skip top level directory
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Lowest Version | Highest Version |
---|---|
1.2.13.0 | Latest |
Initial Version
Lowest Version | Highest Version |
---|---|
13.2.0.0 | Latest |
Lowest Version | Highest Version |
---|---|
1.2.13.0 | Latest |
Review the following guidelines for working with the Relativity Transfer SDK.
Within each tenant or client domain storage area, the Staging Area consists of the following four folders:
You are only able to write to and access data within these designated Staging Area folders. For more information on Staging Area, see the Staging Area topic on the RelativityOne Documentation site.
Current Relativity Transfer SDK clients will not be affected by this change, however, we strongly recommend adjusting your workflows to align with the specified four folders. New Relativity Transfer SDK clients are required to comply with this update.
Use the following as an example on how to implement the Relativity Transfer SDK:
Using any authentication method supported by RelativityOne, provide the Source Path, Destination Path and your Relativity Instance URL address.
During the transfer you can track the job progress, this includes the percentage progress, total number of transferred GB and files, and predicted time to completion. As well as more detailed information about already transferred files paths.
Skipped and failed files display with corresponding paths.
Transfer summary includes the transfer job id, sum of total bytes and files transferred, quantity of empty directories, elapsed time and final status of the job.
Use the code samples in the following sections to learn about calling the methods available in the Relativity Transfer SDK.
To use the Transfer SKD sample code and documentation in the Relativity GitHub repository, click here.
These code samples illustrate the following best practices for working with the SDK:
Use the following code sample to list the necessary namespaces:
1
2
3
4
5
6
using System;
using System.Threading.Tasks;
using Relativity.Transfer.SDK.Core.ProgressReporting;
using Relativity.Transfer.SDK.Interfaces;
using Relativity.Transfer.SDK.Interfaces.Paths;
using Relativity.Transfer.SDK.Interfaces.ProgressReporting;
Implement IRelativityAuthenticationProvider to provide the RelativityOne access token. If the access token expires or is invalid, the implementation of this interface will be invoked to obtain a new token for the RelativityOne instance.
Once defined, use fluent builder to create the instance of Transfer SDK client with two different authentication types:
1
2
3
4
5
6
7
8
9
var clientName = "<YourCompanyName>"; // Needed for troubleshooting scenarios, should you have any. No PII is collected.
var relativityAddress = "<YourTenantAddress>"; // Regular Relativity address, like https://<YourCompaneName>.relativity.one/Relativity
var authenticationProvider = CreateAuthenticationProvider(); // Provide us with authentication method to Relativity (e.g. OAuth)
var transferClient = TransferClientBuilder.FullPathWorkflow
.WithAuthentication(authenticationProvider)
.WithClientName(clientName)
.WithStagingExplorerContext() // or .WithWorkspaceContext(sampleWorkspaceId)
.Build();
Use the following code sample to subscribe to all, none, or some Transfer progress updates. Subscribing is optional, but is the only way to obtain information on which individual items failed or were skipped.
Relativity does not store any information about file paths due to privacy concerns.
1
2
3
4
5
6
7
8
ITransferProgressHandler progressHandler = TransferProgressHandlerBuilder
.Instance
.OnStatistics(StatisticHook.OnStatisticsReceived) // Updates about overall status (% progress, transfer rates, partial statistics)
.OnSucceededItem(StatisticHook.OnSucceededItemReceived) // Updates on each transferred item
.OnFailedItem(StatisticHook.OnFailedItemReceived) // Updates on each failed item (and reason for it)
.OnSkippedItem(StatisticHook.OnSkippedItemReceived) // Updates on each skipped item (and reason for it)
.OnProgressSteps(StatisticHook.OnProgressStepsReceived) // Updates on each job's progress steps (percentage progress and state)
.Create();
Use the UploadDirectoryOptions and UploadFileOptions to upload a directory or file to a specified location with custom options.
Use SkipTopLevelDirectory to upload the entire contents of a source directory but not create a directory:
Use TransferRetryPolicyDefinition to define transfer retry behavior:
1
2
3
4
5
// UploadDirectoryOptions with Linear policy example.
var transferJobOptions = new UploadDirectoryOptions
{
TransferRetryPolicyDefinition = TransferRetryPolicyDefinition.LinearPolicy(deltaBackoff: TimeSpan.FromSeconds(1), maxAttempts: 10)
};
Use ExclusionPolicy to determine if a file is or is not excluded from a transfer:
If all files in a source directory are excluded by the exclusion policy, the directory will not be created.
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
// Implement custom exclusion policy.
public class CustomExclusionPolicy: IFileExclusionPolicy
{
public async Task<bool> ShouldExcludeAsync(IFileReference fileReference)
{
// Exclude files containing "TestCase"
if (fileReference.AbsolutePath.Contains("TestCase"))
{
return await Task.FromResult(true);
}
// Exclude pdf files
if (fileReference.SystemProperties["Extension"].ToString().EndsWith("pdf"))
{
return await Task.FromResult(true);
}
return await Task.FromResult(false);
}
}
// Set ExclusionPolicy on options.
// UploadDirectoryOptions
var transferJobOptions = new UploadDirectoryOptions
{
ExclusionPolicy = new TestCaseFilesExclusionPolicy()
};
Use the UploadDirectoryAsync() method to upload a directory to a specified location.
Using the method to transfer a whole disk data set may contain hidden files and folders such as, $RECYCLE.BIN. This hidden content may change the quantity of transferred items in the statistics.
1
2
3
4
5
6
var transferJobId = Guid.NewGuid();
var source = new DirectoryPath(@"C:\your_source_directory");
var destination = new DirectoryPath(@"\\files.<YourCompanyName>.relativity.one\T001\your_destination_directory"); // Destination requires path in Relativity Fileshare UNC notation
var progressHandler = CreateProgressHandler(); // Your implementation of ITransferProgressHandler. Optional, however it's strongly recommended you track and log progress of the transfer, as Relativity does not log PII data, which includes file paths
TransferJobResult result = await transferClient.UploadDirectoryAsync(transferJobId, source, destination, progressHandler, default);
Use the UploadDirectoryOptions to upload a directory to a specified location with custom options.
Use the SkipTopLevelDirectory option to upload the entire contents of a source directory but does not create a directory.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
private static async Task UploadDirectoryAsync(ITransferFullPathClient transferClient)
{
DirectoryPath sourceDirectory = GetSource();
DirectoryPath destinationDirectory = GetDestination();
ITransferProgressHandler progressHandler = GetProgressHandler();
var transferJobOptions = new UploadDirectoryOptions
{
SkipTopLevelDirectory = true
};
TransferJobResult result = await transferClient
.UploadDirectoryAsync(_TRANSFER_JOB_ID, sourceDirectory, destinationDirectory,transferJobOptions, progressHandler, default)
.ConfigureAwait(false);
}
Use the UploadFileAsync() method to upload a file to a specified location.
1
2
3
4
5
6
var transferJobId = Guid.NewGuid();
var source = new FilePath(@"C:\your_source_directory\file.txt");
var destination = new DirectoryPath(@"\\files.<YourCompanyName>.relativity.one\T001\your_destination_directory"); // Destination requires path in Relativity Fileshare UNC notation
var progressHandler = CreateProgressHandler(); // Your implementation of ITransferProgressHandler. Optional, however it's strongly recommended you track and log progress of the transfer, as Relativity does not log PII data, which includes file paths
TransferJobResult result = await transferClient.UploadFileAsync(transferJobId, source, destination, progressHandler, default);
Use the UploadItemsAsync() method to upload a list of items.
1
2
3
4
5
6
var transferJobId = Guid.NewGuid();
IAsyncEnumerable<TransferEntity> sources = ...; // Provide a list of items to transfer, single item consists of source file path and relative transfer destination file path
var destinationRoot = new DirectoryPath(@"\\files.<YourCompanyName>.relativity.one\T001\your_destination_directory"); // Destination requires path in Relativity Fileshare UNC notation, this is a root directory to which files are transferred
var progressHandler = CreateProgressHandler(); // Your implementation of ITransferProgressHandler. Optional, however it's strongly recommended you track and log progress of the transfer, as Relativity does not log PII data, which includes file paths
TransferJobResult result = await transferClient.UploadItemsAsync(transferJobId, sources, destinationRoot, progressHandler, default);
Use the .DownloadFileAsync() method to download a file to a specified location.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
// Every transfer job in Relativity requires a unique id
Guid _TRANSFER_JOB_ID = Guid.NewGuid();
DownloadDirectoryOptions options = new DownloadDirectoryOptions
{
TransferRetryPolicyDefinition = TransferRetryPolicyDefinition.NoRetryPolicy()
};
FilePath sourceFile = new FilePathPath(@"\\file.<YourCompanyName>.relativity.one\T001\your_source_directory\your_file.txt"); // Source requires path in Relativity Fileshare UNC notation
DirectoryPath destinationDirectory = new DirectoryPath(@"C:\your_destination_directory");
TransferJobResult result = await transferClient
.DownloadFileAsync(_TRANSFER_JOB_ID, sourceFile, destinationDirectory, options, progressHandler, default);
.ConfigureAwait(false);
Use the .DownloadDirectoryAsync() method to download a directory to a specified location.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
// Every transfer job in Relativity requires a unique id
Guid _TRANSFER_JOB_ID = Guid.NewGuid();
DownloadDirectoryOptions options = new DownloadDirectoryOptions
{
SkipTopLevelDirectory = true,
TransferRetryPolicyDefinition = TransferRetryPolicyDefinition.NoRetryPolicy()
};
DirectoryPath sourceDirectory = new DirectoryPath(@"\\files.<YourCompanyName>.relativity.one\T001\your_source_directory"); // Source requires path in Relativity Fileshare UNC notation
DirectoryPath destinationDirectory = new DirectoryPath(@"C:\your_destination_directory");
TransferJobResult result = await transferClient
.DownloadDirectoryAsync(_TRANSFER_JOB_ID, sourceDirectory, destinationDirectory, options, progressHandler, default);
.ConfigureAwait(false);
Job base is a workflow that allows users of Relativity.Transfer.SDK to perform a transfer from an existing job. This is needed when you do not know the destination/source path on Relativity Fileshare.
Job based workflow only supports transferring directories.
Complete the following steps to use the job based workflow:
1
2
3
4
5
6
7
8
9
10
11
var clientName = <Your_company_name>
var authenticationProvider = CreateAuthenticationProvider(); // Provide us with authentication method to Relativity (e.g. OAuth)
// build Transfer SDK client supporting job based workflow
var transferClient = TransferClientBuilder
.JobBasedWorkflow
.WithAuthentication(authenticationProvider)
.WithClientName(clientName)
.WithStagingExplorerContext() // or .WithWorkspaceContext(sampleWorkspaceId)
.Build();
1
2
3
4
5
6
7
8
9
var jobBuilder = new TransferJobBuilder(authenticationProvider);
var transferJobId = Guid.NewGuid();
var destinationPath = new DirectoryPath(@"\\files.<YourCompanyName>.relativity.one\T001\your_destination_directory"); // Destination requires path in Relativity Fileshare UNC notation
// Register a new job with the specified destination path
await jobBuilder
.NewJob()
.CreateUploadDirectoryJobAsync(transferJobId, destinationPath)
.ConfigureAwait(false);
1
2
3
4
5
6
7
var existingJobId = <Job_Id_From_Previous_Transfer>
var newJobId = Guid.NewGuid();
// Register a new job from the existing job with the specified destination path
await jobBuilder
.FromExistingJob(existingJobId)
.CreateUploadJobAsync(newJobId)
.ConfigureAwait(false);
1
2
3
4
5
6
7
var transferJobId = <Your_registered_transfer_job_id>
var sourcePath = new DirectoryPath(@"C:\your_source_directory");
var cancellationToken = <Cancellation_Token>
var result = await transferClient
.UploadDirectoryAsync(transferJobId, sourcePath, ConsoleStatisticHook.GetProgressHandler(), cancellationToken)
.ConfigureAwait(false);
Why was this not helpful?
Check one that applies.
Thank you for your feedback.
Want to tell us more?
Great!
Additional Resources |
|||
DevHelp Community | GitHub | Release Notes | NuGet |