- Http Clients
- Kepler .NET Client
- NuGet
- Authorization
- Permissions
- Builders
- General flow description
- Example of simple export job flow
- Export Job States
- Error Codes
- Export Job States
The Relativity Export Service API is a service designed to facilitate the efficient export of documents, images, PDFs, native files, and Relativity Dynamic Objects (RDOs) from within Relativity workspaces.
This service leverages the RESTful API architecture to streamline the creation, configuration, and execution of export jobs, allowing for a seamless data transfer experience.
With its advanced job configuration options, the API offers a high degree of flexibility, enabling users to tailor the export process to specific requirements.
Moreover, the service incorporates error handling mechanisms to swiftly pinpoint and address any issues that may arise during the export process, ensuring a smooth and reliable operation.
-
The following Relativity applications must be installed:
Application GUID Location Export 4abc11b0-b3c7-4508-87f8-308185423caf workspace DataTransfer.Legacy 9f9d45ff-5dcd-462d-996d-b9033ea8cfce instance -
For .NET Kepler Client install these nugets:
- Relativity.Export.SDK
- Relativity.Kepler.Client.SDK - for .NET Kepler Client
Data exporting - Functionality that extracts data from selected workspace.
ExportJobSettings - Configuration which decides about export behavior e.g. export source, items to export, structure of exported files, etc.
ExportJob - Contains data about the job current state and progress. It is created during export job creation and is updated during export process.
Kepler service - API service created but using the Relativity Kepler framework. This framework provides you with the ability to build custom REST Endpoints via a .NET interface. Additionally, the Kepler framework includes a client proxy that you can use when interacting with the services through .NET.
See more information
Item Error - An error that may occur during the export process and concerns only one exported record from job.
Export Service is built as a standard Relativity Kepler Service. It provides sets of endpoints that must be called sequentially in order to execute export. The following sections outline how to make calls to export service.
You can make calls to a export service using any standard REST or HTTP client, because all APIs (Keplers APIs) are exposed over the HTTP protocol. You need to set the required X-CSRF-Header.
More details
string usernamePassword = string.Format("{0}:{1}", username, password);
string base64usernamePassword = Convert.ToBase64String(Encoding.ASCII.GetBytes(usernamePassword));
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
// Basic authentication
client.DefaultRequestHeaders.Add("Authorization", "Basic " + base64usernamePassword);
var createExportUri = $"{relativityUrl}/export/v1/workspaces/{workspaceId}/jobs/{jobId}";
var response = await httpClient.PostAsJsonAsync(createExportUri, payload);
You can access Kepler service from any .NET language using the client library provided as part of the Kepler framework. It exposes a factory class that you can use to create the client proxy by passing URIs to export services and credentials. Then use .NET proxy to interact with a export service as a set of .NET objects. When you call a member method, the proxy makes a corresponding HTTP request to the respective service endpoint.
More details
Example of factory creation:
(UsingRelativity.Kepler.Client.SDK
package)
public IServiceFactory GetServiceFactory()
{
Uri relativityRestUri = new Uri($"{this._host}relativity.rest/api");
Credentials credentials = new UsernamePasswordCredentials(this._username, this._password);
ServiceFactorySettings settings = new ServiceFactorySettings(relativityRestUri, credentials);
// Create proxy factory.
return new ServiceFactory(settings);
}
Example of proxy creation:
// Get the instance of the service factory.
IServicefactory factory = GetServiceFactory();
// Use the factory to create an instance of the proxy.
using Relativity.Export.V1.IExportJobManager jobManager = factory.CreateProxy<Relativity.Export.V1.IExportJobManager>();
// Use the proxy to call the service.
var result = await jobManager.CreateAsync(
workspaceID,
jobID,
jobSettings,
applicationName,
correlationID);
Kepler contracts for export service are exposed in Relativity.Export.SDK
package.
You can also find factory implementations in the Relativity.Kepler.Client.SDK
package
Relativity.Export.SDK
is a .NET library that contains kepler interfaces for export service.
It provides and simplifies executing export in client application. Relativity.Export.SDK
targets .NET Framework 4.6.2
and .NET standard 2.0
.
Install-Package Relativity.Export.SDK
dotnet add package Relativity.Export.SDK
Public Relativity Kepler Client SDK.
Contains implementation of factories for kepler services and proxies.
Install-Package Relativity.Kepler.Client.SDK
dotnet add package Relativity.Kepler.Client.SDK
HTTP clients
Export Service API conforms to the same authentication rules as other Relativity REST APIs.
The more details can be found under the following link: REST API Authentication
Kepler .NET client
The Kepler framework uses a proxy to handle client requests. The more details can be found under the following link: Proxies And Authentication
The following Relativity permissions are required to use export features provided in Export Service API.
Object Security Section | Permissions |
---|---|
Production | View |
Relativity Export Service Job | Add Edit View |
Tab Visibility |
---|
- |
Admin Operation |
---|
Allow Export |
Builders provided in Relativity.Export.SDK
package help to create settings for export job in correct and consistent way. It is highly recommended to prepare these objects in such a way in .NET application. They are implemented in fluent api pattern so it is very easy to use them. Moreover, using them in client application will avoid the risk of incorrect and inconsistent configuration which may lead to errors during export process.
Each builder final step results in IFinalStep<>
generic interface which is used to build final object via Build()
method.
Main components of export job settings are:
ExportSourceSettings
- contains information about source of data to exportExportArtifactSettings
- contains information about artifacts to exportExportOutputSettings
- contains information about output format and structure of exported files
which are all later combined into ExportJobSettings
.
The following example shows how to create export job settings using builders that exports native, fulltext, images and PDF files from folder.
// Export source settings
var sourceSettings = ExportSourceSettingsBuilder.Create()
.FromFolder(exportSourceArtifactID: folderID, viewID: viewID)
.WithSubfolders() // include subfolders
.WithCustomStartAtDocumentNumber(1)
.Build();
// Artifact settings
var artifactSettings = ExportArtifactSettingsBuilder.Create()
.WithDefaultFileNamePattern()
.WithoutApplyingFileNamePatternToImages()
.ExportImages(settings => settings
.WithImagePrecedenceArtifactIDs(new List<int> { -1 }) // Exports images
.WithTypeOfImage(ImageType.Pdf))
.ExportFullText(settings => settings
.ExportFullTextAsFile()
.WithTextFileEncoding("UTF-8")
.WithPrecedenceFieldsArtifactIDs(fulltextPrecedenceFieldsArtifactIds))
.ExportNative(settings => settings
.WithNativePrecedenceArtifactIDs(new List<int> { -1 })) // Exports native files
.ExportPdf() // Export PDF files
.WithFieldArtifactIDs(new List<int> { 1003676, 1003667 }) // Fields to export
.WithoutExportingMultiChoicesAsNested()
.Build();
// Subdirectory settings
var subdirectorySettings = SubdirectorySettingsBuilder.Create()
.WithSubdirectoryStartNumber(1)
.WithMaxNumberOfFilesInDirectory(100)
.WithDefaultPrefixes()
.OverridePrefixDefaults(prefixes =>
{
// Optional overrides
prefixes.FullTextSubdirectoryPrefix = "FULLTEXT_";
prefixes.NativeSubdirectoryPrefix = "NATIVE_";
prefixes.ImageSubdirectoryPrefix = "IMAGE_";
prefixes.PdfSubdirectoryPrefix = "PDF_";
})
.WithSubdirectoryDigitPadding(5)
.Build();
// Volume settings
var volumeSettings = VolumeSettingsBuilder.Create()
.WithVolumePrefix("VOL_FOLDER_")
.WithVolumeStartNumber(1)
.WithVolumeMaxSizeInMegabytes(100)
.WithVolumeDigitPadding(5)
.Build();
// Loadfile settings
var loadfileSettings = LoadFileSettingsBuilder.Create()
.WithoutExportingMsAccess()
.WithoutCustomCultureInfo()
.WithCustomDateFormat("O")
.WithLoadFileFormat(LoadFileFormat.CSV)
.WithEncoding("UTF-8")
.WithImageLoadFileFormat(ImageLoadFileFormat.IPRO)
.WithPdfFileFormat(PdfLoadFileFormat.IPRO_FullText)
.WithDelimiterSettings(delimiters =>
delimiters.WithDefaultDelimiters())
.Build();
// Output settings
var outputSettings = ExportOutputSettingsBuilder.Create()
.WithoutArchiveCreation()
.WithDefaultFolderStructure()
.WithoutTransferJobID()
.WithDefaultDestinationPath()
.WithSubdirectorySettings(subdirectorySettings)
.WithVolumeSettings(volumeSettings)
.WithLoadFileSettings(loadfileSettings)
.Build();
// Export job settings
var jobSettings = ExportJobSettingsBuilder.Create()
.WithExportSourceSettings(sourceSettings)
.WithExportArtifactSettings(artifactSettings)
.WithExportOutputSettings(outputSettings)
.Build();
It's possible to use builders in a method chaining manner to create settings, but it's less readable and more error prone.
Example
var jobSettings = ExportJobSettingsBuilder.Create()
.WithExportSourceSettings(exportSourceSettings => // Export Source Settings
exportSourceSettings.FromSavedSearch(exportSourceArtifactID: savedSearchID)
.WithDefaultStartAtDocumentNumber())
.WithExportArtifactSettings(artifactSettings =>
// ...
.Build();
-
Create Export Job
Creates export job entity in particular workspace. Job is defined by its unique Id generated by user and provided in the request which is used in the next steps. -
Start Export Job
Starts Export Job which enables the process that schedules export data from workspace based on the configuration assigned in previous step. -
(Optional) Cancel Export Job
If the job is running, you can cancel it. -
Check Export Job status
You can check the status of the export job, it will indicate whenever it failed, was completed or is still running.
Exporting native files from folder.
- Create configuration
C# Builders
// Workspace ID.
int workspaceID = 1020245;
// View ID.
int viewID = 1042326;
// Folder ID.
int folderID = 1003697;
// Job related data
Guid jobID = Guid.NewGuid();
string? applicationName = "Export-Service-Sample-App";
string? correlationID = "Sample-Job";
// Export source settings
var sourceSettings = ExportSourceSettingsBuilder.Create()
.FromFolder(exportSourceArtifactID: folderID, viewID: viewID)
.WithCustomStartAtDocumentNumber(1)
.Build();
// Artifact settings
var artifactSettings = ExportArtifactSettingsBuilder.Create()
.WithDefaultFileNamePattern()
.WithoutApplyingFileNamePatternToImages()
.WithoutExportingImages()
.WithoutExportingFullText()
.ExportNative(settings => settings.WithNativePrecedenceArtifactIDs(new List<int> { -1 })) // Exports only native files
.WithoutExportingPdf()
.WithFieldArtifactIDs(new List<int> { 1003676, 1003667 }) // Fields to export
.WithoutExportingMultiChoicesAsNested()
.Build();
// Subdirectory settings
var subdirectorySettings = SubdirectorySettingsBuilder.Create()
.WithSubdirectoryStartNumber(1)
.WithMaxNumberOfFilesInDirectory(100)
.WithDefaultPrefixes()
.OverridePrefixDefaults(prefixes =>
{
prefixes.NativeSubdirectoryPrefix = "Native_";
})
.WithSubdirectoryDigitPadding(5)
.Build();
// Volume settings
var volumeSettings = VolumeSettingsBuilder.Create()
.WithVolumePrefix("VOL_FOLDER_")
.WithVolumeStartNumber(1)
.WithVolumeMaxSizeInMegabytes(100)
.WithVolumeDigitPadding(5)
.Build();
// Loadfile settings
var loadfileSettings = LoadFileSettingsBuilder.Create()
.WithoutExportingMsAccess()
.WithoutCustomCultureInfo()
.WithLoadFileFormat(LoadFileFormat.CSV)
.WithEncoding("UTF-8")
.WithImageLoadFileFormat(ImageLoadFileFormat.IPRO)
.WithPdfFileFormat(PdfLoadFileFormat.IPRO_FullText)
.WithDelimiterSettings(delimiters =>
delimiters.WithDefaultDelimiters())
.Build();
// Output settings
var outputSettings = ExportOutputSettingsBuilder.Create()
.WithoutArchiveCreation()
.WithDefaultFolderStructure()
.WithoutTransferJobID()
.WithDefaultDestinationPath()
.WithSubdirectorySettings(subdirectorySettings)
.WithVolumeSettings(volumeSettings)
.WithLoadFileSettings(loadfileSettings)
.Build();
// Connect all settings in the Job builder
var jobSettings = ExportJobSettingsBuilder.Create()
.WithExportSourceSettings(sourceSettings)
.WithExportArtifactSettings(artifactSettings)
.WithExportOutputSettings(outputSettings)
.Build();
C#
// Workspace ID.
int workspaceID = 1020245;
// View ID.
int viewID = 1042326;
// Folder ID.
int folderID = 1003697;
// Job related data
Guid jobID = Guid.NewGuid();
string? applicationName = "Export-Service-Sample-App";
string? correlationID = "Sample-Job";
var sourceSettings = new ExportSourceSettings()
{
ArtifactTypeID = 10,
ExportSourceArtifactID = folderID,
ExportSourceType = ExportSourceType.Folder,
ViewID = viewID,
StartAtDocumentNumber = 1
};
var artifactSettings = new ExportArtifactSettings()
{
FileNamePattern = "{identifier}",
ApplyFileNamePatternToImages = false,
ExportFullText = false,
ExportImages = false,
ExportNative = true,
ExportPdf = false,
FieldArtifactIDs = new List<int>() { 1003676, 1003667 },
NativeFilesExportSettings = new NativeFilesExportSettings()
{
NativePrecedenceArtifactIDs = new List<int>() { -1 }
},
ExportMultiChoicesAsNested = false
};
var subdirectorySettings = new SubdirectorySettings()
{
SubdirectoryStartNumber = 1,
MaxNumberOfFilesInDirectory = 100,
FullTextSubdirectoryPrefix = String.Empty,
ImageSubdirectoryPrefix = String.Empty,
NativeSubdirectoryPrefix = "Native_",
PdfSubdirectoryPrefix = String.Empty,
SubdirectoryDigitPadding = 5
};
var volumeSettings = new VolumeSettings()
{
VolumePrefix = "VOL_FOLDER_",
VolumeStartNumber = 1,
VolumeMaxSizeInMegabytes = 100,
VolumeDigitPadding = 5
};
var loadfileSettings = new LoadFileSettings()
{
ExportMsAccess = false,
CultureInfo = "en-US",
LoadFileFormat = LoadFileFormat.CSV,
Encoding = "UTF-8",
ImageLoadFileFormat = ImageLoadFileFormat.IPRO,
PdfLoadFileFormat = PdfLoadFileFormat.IPRO_FullText,
DelimitersSettings = new DelimitersSettings()
{
MultiRecordDelimiter = (char)059,
NestedValueDelimiter = (char)092,
NewlineDelimiter = (char)174,
QuoteDelimiter = (char)254,
RecordDelimiter = (char)020
}
};
var outputSettings = new ExportOutputSettings()
{
CreateArchive = false,
SubdirectorySettings = subdirectorySettings,
LoadFileSettings = loadfileSettings,
VolumeSettings = volumeSettings
};
var jobSettings = new ExportJobSettings()
{
ExportArtifactSettings = artifactSettings,
ExportOutputSettings = outputSettings,
ExportSourceSettings = sourceSettings
};
JSON
{
"ExportSourceSettings": {
"ArtifactTypeID": 10,
"ExportSourceType": 2,
"ExportSourceArtifactID": 1003697,
"ViewID": 1042326,
"StartAtDocumentNumber": 1
},
"ExportArtifactSettings": {
"FileNamePattern": "{identifier}",
"ApplyFileNamePatternToImages": false,
"ExportNative": true,
"ExportPdf": false,
"ExportImages": false,
"ExportFullText": false,
"ExportMultiChoicesAsNested": false,
"ImageExportSettings": null,
"FullTextExportSettings": null,
"NativeFilesExportSettings": {
"NativePrecedenceArtifactIDs": [-1]
},
"FieldArtifactIDs": [1003676, 1003667]
},
"ExportOutputSettings": {
"LoadFileSettings": {
"LoadFileFormat": 1,
"ImageLoadFileFormat": 1,
"PdfLoadFileFormat": 2,
"Encoding": "UTF-8",
"DelimitersSettings": {
"NestedValueDelimiter": "\\",
"RecordDelimiter": "\u0014",
"QuoteDelimiter": "\u00FE",
"NewlineDelimiter": "\u00AE",
"MultiRecordDelimiter": ";"
},
"ExportMsAccess": false,
"CultureInfo": null
},
"VolumeSettings": {
"VolumePrefix": "VOL_FOLDER_",
"VolumeStartNumber": 1,
"VolumeMaxSizeInMegabytes": 100,
"VolumeDigitPadding": 5
},
"SubdirectorySettings": {
"SubdirectoryStartNumber": 1,
"MaxNumberOfFilesInDirectory": 100,
"ImageSubdirectoryPrefix": "",
"NativeSubdirectoryPrefix": "Native_",
"FullTextSubdirectoryPrefix": "",
"PdfSubdirectoryPrefix": "",
"SubdirectoryDigitPadding": 5
},
"CreateArchive": false,
"FolderStructure": 0,
"DestinationPath": null
}
}
- Create export job
.NET Kepler
using Relativity.Export.V1.IExportJobManager jobManager = serviceFactory.CreateProxy<Relativity.Export.V1.IExportJobManager>();
var validationResult = await jobManager.CreateAsync(
workspaceID,
jobID,
jobSettings,
applicationName,
correlationID);
- Start export job
.NET Kepler
// Start export job
var startResponse = await jobManager.StartAsync(workspaceID, jobID);
// Check for errors that occured during job start
if (!string.IsNullOrEmpty(startResponse.ErrorMessage))
{
_logger.LogError($"<{startResponse.ErrorCode}> {startResponse.ErrorMessage}");
// ...
}
- Check export job status
.NET Kepler
do
{
var status = await jobManager.GetAsync(workspaceID, jobID);
Console.WriteLine($"Job status: {status.Value.JobStatus}");
} while (jobStatus?.Value.JobStatus is not ExportStatus.Completed
and not ExportStatus.CompletedWithErrors
and not ExportStatus.Failed
and not ExportStatus.Cancelled);
Value | State | Description |
---|---|---|
0 | New | Export job created but not started yet. |
1 | Scheduled | Export job scheduled and waiting for an agent. |
2 | Running | Job executing, export of data is currently in progress. |
3 | Completed | Export job completed. All records processed without errors. |
4 | CompletedWithErrors | Export job completed with some errors. All records processed but one or more item level errors occurred. |
5 | Failed | Export job failed with a fatal error. Not all records were processed. |
6 | Cancelled | Job cancelled by user. |
7 | Transferring | Export from Relativity to Transfer Service location completed. The transfer job is in progress, and export results are syncing to the destination location. |
Error handling in Export Service returns Error Codes and Error Messages:
- in every response for failed HTTP request
- when requested by user for all item errors that occurred during export of particular data source
Error code structure Error code returned from the Export Service API endpoint has the following structure:
[Source].[ErrorType].[Operation].[ErrorNumber]
Examples:
Error code | Description |
---|---|
JOB.01 | Incorrect total items processed number |
Sources
Source | Description |
---|---|
JOB | Jobs |
CONF | Configuration |
EXT | External |
ITEM | Item |
MES | Message |
IO | Input/Output |
Error Types
Type | Description |
---|---|
GET | Receiving data |
CRE | Creatiing |
IMG | Image file |
PDF file | |
MSA | MsAccess |
PRO | Production |
LFL | Main load file |
SCH | Scheduling |
TS | Transfer service |
OM | Object manager |
SQL | Structured Query Language |
FS | Folder service |
DG | Data grid |
DATA | Corrupted data |
VLD | Validation |
Operations
Operation | Description |
---|---|
GET | Get |
COPY | Copy |
SAVE | Save |
DELETE | Delete |
CHECK | Check |
There are two types of sample application that demonstrate the use of Export Service API features.
RelConsole
- .NET console application (.NET 6, C#, Kepler Client).Powershell
- Powershell scripts.
Sample Name | .NET & Kepler | Powershell |
---|---|---|
Export_FromFolder_NativeFiles | Sample 1 | Sample 1 |
Export_FromFolder_Images | Sample 2 | Sample 2 |
Export_FromFolder_PDF | Sample 3 | Sample 3 |
Export_FromFolder_FullText | Sample 4 | Sample 4 |
Export_FromFolder_All | Sample 5 | Sample 5 |
Export_FromSavedSearch_NativeFiles | Sample 6 | Sample 6 |
Export_FromSavedSearch_Images | Sample 7 | Sample 7 |
Export_FromSavedSearch_PDF | Sample 8 | Sample 8 |
Export_FromSavedSearch_FullText | Sample 9 | Sample 9 |
Export_FromSavedSearch_All | Sample 10 | Sample 10 |
Export_FromProduction_NativeFiles | Sample 11 | Sample 11 |
Export_FromProduction_Images | Sample 12 | Sample 12 |
Export_FromProduction_PDF | Sample 13 | Sample 13 |
Export_FromProduction_Fulltext | Sample 14 | Sample 14 |
Export_FromProduction_All | Sample 15 | Sample 15 |
Export_RDO | Sample 16 | Sample 16 |
Job_ListExportJobs | Sample 17 | Sample 17 |
Job_StartAllRunnableJobs | Sample 18 | Sample 18 |
Job_GetSettings | Sample 19 | Sample 19 |
Job_Cancel | Sample 20 | Sample 20 |
To run the sample code:
- Replace the variables with your url and credentials in
Program.cs
.
using System.Text;
using Relativity.Export.Samples.RelConsole.Helpers;
System.Console.OutputEncoding = Encoding.UTF8;
System.Console.InputEncoding = Encoding.UTF8;
// Replace with your Relativity instance url
string relativityUrl = "http://host/";
// Replace with your Relativity credentials
string username = "username";
string password = "password";
await OutputHelper.StartAsync(args, relativityUrl, username, password);
- Replace the required variables within the samples
For example in Export_FromFolder_NativeFiles sample replace
// ...
// with your workspace ID
int workspaceID = 1020245;
// with your view ID
int viewID = 1042326;
// with your folder ID
int folderID = 1003697;
// with your field artifact IDs
.WithFieldArtifactIDs(new List<int> { 1003676, 1003667 })
// ...
- Run the sample via
dotnet run {selectedSampleID}
command.
Arguments:{selectedSampleID}
- ID of the sample to run.-json
- appends additional json details to the sample output.-noui
- disables some UI elements on the initial screen
Example:
Runnnig sample with ID 1 and appending json details to the output
dotnet run 1 -json
Example:
Showing the sample list
dotent run
To run a sample code:
-
Install Powershell "Pester" Module (ver. >= 5.3.3)
Find-Module -Name "Pester" | Install-Module -Force;
-
Uncomment line with sample invocation you want to run in run-sample-export.ps1.
Describe "Sample export" { . "$global:rootDir\SamplesCollection\export-folder-all.ps1" # . "$global:rootDir\SamplesCollection\export-folder-full-text.ps1"
-
Set the proper credentials and host address of your Relativity instance in "run-sample-export.ps1".
$hostAddress = "https://sample-host/" $userName = "sample@username" $password = "password!"
-
Replace required variables within the sample. It is required in each sample. Example in export-folder-all.ps1 sample replace
# ... # Your workspace ID: this is where we point to the workspace where we want to export from [int]$workspaceId = 1022188 # Export settings parameters # Your view ID: view will provide us with available data to export, requires folder to be visible there. # Your folder ID: our targetted folder. If you want to export from the workspace root, the ID is different from the workspace ID. # ExportSourceType: ExportFolder or ExportFolderWithSubfolders [int]$viewId = 1003684 [int]$folderID = 1003697 [bool]$withSubfolders = $true # ArtifactIds: Example: 1003668 - Extracted Text, 1003677 - Folder Name, 1003676 - Artifact ID, 1003667 - Control Number $fulltextPrecedenceFieldsArtifactIds = '[1003668,1003677]' $fieldArtifactIds = '[1003676,1003667]' #...
-
Invoke run-sample-export.ps1