Relativity Export SDK

Table of contents

Introduction

• Prerequisites
• Gloassary

Getting Started

• 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

Code Samples

• List of samples
• Kepler samples
• Powershell samples

Introduction

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.

Prerequisites

1. 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

2. Appropriate user permissions need to be set.

3. For .NET Kepler Client install these nugets:

   • Relativity.Export.SDK
   • Relativity.Kepler.Client.SDK - for .NET Kepler Client

Glossary

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.

Getting started

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.

HTTP Clients

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

stringusernamePassword=string.Format("{0}:{1}",username,password);stringbase64usernamePassword=Convert.ToBase64String(Encoding.ASCII.GetBytes(usernamePassword));HttpClientclient=newHttpClient();client.DefaultRequestHeaders.Add("X-CSRF-Header","-");// Basic authenticationclient.DefaultRequestHeaders.Add("Authorization","Basic "+base64usernamePassword);varcreateExportUri=$"{relativityUrl}/export/v1/workspaces/{workspaceId}/jobs/{jobId}";varresponse=awaithttpClient.PostAsJsonAsync(createExportUri,payload);

Kepler .NET Client

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:
(Using Relativity.Kepler.Client.SDK package)

publicIServiceFactoryGetServiceFactory(){UrirelativityRestUri=newUri($"{this._host}relativity.rest/api");Credentialscredentials=newUsernamePasswordCredentials(this._username,this._password);ServiceFactorySettingssettings=newServiceFactorySettings(relativityRestUri,credentials);// Create proxy factory.returnnewServiceFactory(settings);}

Example of proxy creation:

// Get the instance of the service factory.IServicefactoryfactory=GetServiceFactory();// Use the factory to create an instance of the proxy.usingRelativity.Export.V1.IExportJobManagerjobManager=factory.CreateProxy<Relativity.Export.V1.IExportJobManager>();// Use the proxy to call the service.varresult=awaitjobManager.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 NuGet

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.

Installing via NuGet

Install-Package Relativity.Export.SDK

Installing via .NET CLI

dotnet add package Relativity.Export.SDK

Relativity.Kepler.Client.SDK NuGet

Public Relativity Kepler Client SDK.
Contains implementation of factories for kepler services and proxies.

Installing via NuGet

Install-Package Relativity.Kepler.Client.SDK

Installing via .NET CLI

dotnet add package Relativity.Kepler.Client.SDK

Authorization

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

Permissions

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	AddEditView

Tab Visibility
-

Admin Operation
Allow Export

Builders

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 export
• ExportArtifactSettings - contains information about artifacts to export
• ExportOutputSettings - 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.

Example of ExportSourceSettings

// Export source settingsvarsourceSettings=ExportSourceSettingsBuilder.Create().FromFolder(exportSourceArtifactID:folderID,viewID:viewID).WithSubfolders()// include subfolders.WithCustomStartAtDocumentNumber(1).Build();

Example of ExportArtifactSettings

// Artifact settingsvarartifactSettings=ExportArtifactSettingsBuilder.Create().WithDefaultFileNamePattern().WithoutApplyingFileNamePatternToImages().ExportImages(settings =>settings.WithImagePrecedenceArtifactIDs(newList<int>{-1})// Exports images.WithTypeOfImage(ImageType.Pdf)).ExportFullText(settings =>settings.ExportFullTextAsFile().WithTextFileEncoding("UTF-8").WithPrecedenceFieldsArtifactIDs(fulltextPrecedenceFieldsArtifactIds)).ExportNative(settings =>settings.WithNativePrecedenceArtifactIDs(newList<int>{-1}))// Exports native files.ExportPdf()// Export PDF files.WithFieldArtifactIDs(newList<int>{1003676,1003667})// Fields to export.WithoutExportingMultiChoicesAsNested().Build();

Example of ExportOutputSettings

// Subdirectory settingsvarsubdirectorySettings=SubdirectorySettingsBuilder.Create().WithSubdirectoryStartNumber(1).WithMaxNumberOfFilesInDirectory(100).WithDefaultPrefixes().OverridePrefixDefaults(prefixes =>{// Optional overridesprefixes.FullTextSubdirectoryPrefix="FULLTEXT_";prefixes.NativeSubdirectoryPrefix="NATIVE_";prefixes.ImageSubdirectoryPrefix="IMAGE_";prefixes.PdfSubdirectoryPrefix="PDF_";}).WithSubdirectoryDigitPadding(5).Build();// Volume settingsvarvolumeSettings=VolumeSettingsBuilder.Create().WithVolumePrefix("VOL_FOLDER_").WithVolumeStartNumber(1).WithVolumeMaxSizeInMegabytes(100).WithVolumeDigitPadding(5).Build();// Loadfile settingsvarloadfileSettings=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 settingsvaroutputSettings=ExportOutputSettingsBuilder.Create().WithoutArchiveCreation().WithDefaultFolderStructure().WithoutTransferJobID().WithDefaultDestinationPath().WithSubdirectorySettings(subdirectorySettings).WithVolumeSettings(volumeSettings).WithLoadFileSettings(loadfileSettings).Build();

Combined settings

// Export job settingsvarjobSettings=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

varjobSettings=ExportJobSettingsBuilder.Create().WithExportSourceSettings(exportSourceSettings =>// Export Source SettingsexportSourceSettings.FromSavedSearch(exportSourceArtifactID:savedSearchID).WithDefaultStartAtDocumentNumber()).WithExportArtifactSettings(artifactSettings =>// ....Build();

General flow description

1. 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.

2. Start Export Job
   Starts Export Job which enables the process that schedules export data from workspace based on the configuration assigned in previous step.

3. (Optional) Cancel Export Job
   If the job is running, you can cancel it.

4. 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.

Example of simple export job flow

Exporting native files from folder.

1. Create configuration

   C# Builders

// Workspace ID.intworkspaceID=1020245;// View ID.intviewID=1042326;// Folder ID.intfolderID=1003697;// Job related dataGuidjobID=Guid.NewGuid();string?applicationName="Export-Service-Sample-App";string?correlationID="Sample-Job";// Export source settingsvarsourceSettings=ExportSourceSettingsBuilder.Create().FromFolder(exportSourceArtifactID:folderID,viewID:viewID).WithCustomStartAtDocumentNumber(1).Build();// Artifact settingsvarartifactSettings=ExportArtifactSettingsBuilder.Create().WithDefaultFileNamePattern().WithoutApplyingFileNamePatternToImages().WithoutExportingImages().WithoutExportingFullText().ExportNative(settings =>settings.WithNativePrecedenceArtifactIDs(newList<int>{-1}))// Exports only native files.WithoutExportingPdf().WithFieldArtifactIDs(newList<int>{1003676,1003667})// Fields to export.WithoutExportingMultiChoicesAsNested().Build();// Subdirectory settingsvarsubdirectorySettings=SubdirectorySettingsBuilder.Create().WithSubdirectoryStartNumber(1).WithMaxNumberOfFilesInDirectory(100).WithDefaultPrefixes().OverridePrefixDefaults(prefixes =>{prefixes.NativeSubdirectoryPrefix="Native_";}).WithSubdirectoryDigitPadding(5).Build();// Volume settingsvarvolumeSettings=VolumeSettingsBuilder.Create().WithVolumePrefix("VOL_FOLDER_").WithVolumeStartNumber(1).WithVolumeMaxSizeInMegabytes(100).WithVolumeDigitPadding(5).Build();// Loadfile settingsvarloadfileSettings=LoadFileSettingsBuilder.Create().WithoutExportingMsAccess().WithoutCustomCultureInfo().WithLoadFileFormat(LoadFileFormat.CSV).WithEncoding("UTF-8").WithImageLoadFileFormat(ImageLoadFileFormat.IPRO).WithPdfFileFormat(PdfLoadFileFormat.IPRO_FullText).WithDelimiterSettings(delimiters =>delimiters.WithDefaultDelimiters()).Build();// Output settingsvaroutputSettings=ExportOutputSettingsBuilder.Create().WithoutArchiveCreation().WithDefaultFolderStructure().WithoutTransferJobID().WithDefaultDestinationPath().WithSubdirectorySettings(subdirectorySettings).WithVolumeSettings(volumeSettings).WithLoadFileSettings(loadfileSettings).Build();// Connect all settings in the Job buildervarjobSettings=ExportJobSettingsBuilder.Create().WithExportSourceSettings(sourceSettings).WithExportArtifactSettings(artifactSettings).WithExportOutputSettings(outputSettings).Build();

C#

// Workspace ID.intworkspaceID=1020245;// View ID.intviewID=1042326;// Folder ID.intfolderID=1003697;// Job related dataGuidjobID=Guid.NewGuid();string?applicationName="Export-Service-Sample-App";string?correlationID="Sample-Job";varsourceSettings=newExportSourceSettings(){ArtifactTypeID=10,ExportSourceArtifactID=folderID,ExportSourceType=ExportSourceType.Folder,ViewID=viewID,StartAtDocumentNumber=1};varartifactSettings=newExportArtifactSettings(){FileNamePattern="{identifier}",ApplyFileNamePatternToImages=false,ExportFullText=false,ExportImages=false,ExportNative=true,ExportPdf=false,FieldArtifactIDs=newList<int>(){1003676,1003667},NativeFilesExportSettings=newNativeFilesExportSettings(){NativePrecedenceArtifactIDs=newList<int>(){-1}},ExportMultiChoicesAsNested=false};varsubdirectorySettings=newSubdirectorySettings(){SubdirectoryStartNumber=1,MaxNumberOfFilesInDirectory=100,FullTextSubdirectoryPrefix=String.Empty,ImageSubdirectoryPrefix=String.Empty,NativeSubdirectoryPrefix="Native_",PdfSubdirectoryPrefix=String.Empty,SubdirectoryDigitPadding=5};varvolumeSettings=newVolumeSettings(){VolumePrefix="VOL_FOLDER_",VolumeStartNumber=1,VolumeMaxSizeInMegabytes=100,VolumeDigitPadding=5};varloadfileSettings=newLoadFileSettings(){ExportMsAccess=false,CultureInfo="en-US",LoadFileFormat=LoadFileFormat.CSV,Encoding="UTF-8",ImageLoadFileFormat=ImageLoadFileFormat.IPRO,PdfLoadFileFormat=PdfLoadFileFormat.IPRO_FullText,DelimitersSettings=newDelimitersSettings(){MultiRecordDelimiter=(char)059,NestedValueDelimiter=(char)092,NewlineDelimiter=(char)174,QuoteDelimiter=(char)254,RecordDelimiter=(char)020}};varoutputSettings=newExportOutputSettings(){CreateArchive=false,SubdirectorySettings=subdirectorySettings,LoadFileSettings=loadfileSettings,VolumeSettings=volumeSettings};varjobSettings=newExportJobSettings(){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
}
}

2. Create export job

   .NET Kepler

usingRelativity.Export.V1.IExportJobManagerjobManager=serviceFactory.CreateProxy<Relativity.Export.V1.IExportJobManager>();varvalidationResult=awaitjobManager.CreateAsync(workspaceID,jobID,jobSettings,applicationName,correlationID);

3. Start export job

   .NET Kepler

// Start export jobvarstartResponse=awaitjobManager.StartAsync(workspaceID,jobID);// Check for errors that occured during job startif(!string.IsNullOrEmpty(startResponse.ErrorMessage)){_logger.LogError($"<{startResponse.ErrorCode}> {startResponse.ErrorMessage}");// ...}

4. Check export job status

   .NET Kepler

do{varstatus=awaitjobManager.GetAsync(workspaceID,jobID);Console.WriteLine($"Job status: {status.Value.JobStatus}");}while(jobStatus?.Value.JobStatusis not ExportStatus.Completed
and not ExportStatus.CompletedWithErrors
and not ExportStatus.Failed
and not ExportStatus.Cancelled);

Export Job States

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 Codes

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 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	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

Samples

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.

List of samples

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

Kepler Samples

To run the sample code:

1. Replace the variables with your url and credentials in Program.cs.

usingSystem.Text;usingRelativity.Export.Samples.RelConsole.Helpers;System.Console.OutputEncoding=Encoding.UTF8;System.Console.InputEncoding=Encoding.UTF8;// Replace with your Relativity instance urlstringrelativityUrl="http://host/";// Replace with your Relativity credentialsstringusername="username";stringpassword="password";awaitOutputHelper.StartAsync(args,relativityUrl,username,password);

2. Replace the required variables within the samples
   For example in Export_FromFolder_NativeFiles sample replace

// ...// with your workspace IDintworkspaceID=1020245;// with your view IDintviewID=1042326;// with your folder IDintfolderID=1003697;// with your field artifact IDs.WithFieldArtifactIDs(newList<int>{1003676,1003667})// ...

3. 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

Powershell Samples

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