Relativity Import API Guide · Relativity|ImportAPIGuide-2 TableofContents 1ImportAPI 5 1.1ImportAPIconcepts 5 1.2GettingStarted 5 1.3ImportAPIdevelopmentguide 5 1.4ImportAPIclasslibrary

Import API GuideVersion 8.0 | October 14, 2013

For the most recent version of this document, visit our developer's website.

http://kcura.com/relativity/Portals/0/Documents/8.0 Developers Site/index.htm#Relativity Platform/Home.htm

Relativity | Import API Guide - 2

Table of Contents

1 Import API 5

1.1 Import API concepts 5

1.2 Getting Started 5

1.3 Import API development guide 5

1.4 Import API class library 5

2 Import API concepts 5

2.1 ImportAPI class 6

2.1.1 Instantiating an ImportAPI object 6

2.1.2Working with the ImportAPI class 7

2.2 ImportBulkArtifactJob class 10

2.3 Authenticating through the Import API 10

2.4 Understanding field mapping 10

3 Setting up a development environment 11

3.1 Before you begin 11

3.2 Setting up your environment 11

3.3 Using an optional app.config file 14

4 Sample code for basic import tasks 15

4.1 Logging in through the Import API 15

4.2 Importing documents with native files 15

4.2.1 Creating a document import job 15

4.2.2Writing messages and errors 17

4.2.3 Creating a DataTable object for a document import job 17

4.3 Importing images 17

4.3.1 Creating an image import job 18


4.3.3 Creating a DataTable object 19

4.4 Importing produced images 20

4.4.1 Creating a production import job 20


4.4.3 Creating a DataTable object for a production 22

4.5 Importing Dynamic Objects 22

4.5.1 Creating an RDO import job 22


4.5.3 Creating a DataTable object 24


5 Import API development guide 24

5.1 Import API best practices 24

5.1.1 Use the Name field for Dynamic Objects 24

5.1.2 Use required identifiers in OverwriteMode 25

5.1.3 Specify a field as an identifier for document imports 25

5.1.4 Use the kCuraMarkerFilename field when copying files 25

5.1.5 Set NativeFilePathSourceFieldNamewhen copying native files 25

5.1.6 Use a unique identifier when importing child records 25

5.1.7 Set appropriate fields when importing extracted text 25

5.1.8 Catch the NeedToReLoginException to prevent import failures 25

5.1.9 Improve performance by using Import API settings 25

5.1.10 Use a single Import API instance per workspace 26

5.1.11 Determine optimum batch size for your environment 26

5.1.12 Avoid index fragmentation 26

5.1.13Miscellaneous ways to improve performance 26

5.2Mapping single or multiple object fields by ArtifactID 27

5.3 Specifying folders through the Settings class 27

5.4 Handling events 27

5.4.1 OnComplete 27

5.4.2 OnError 27

5.4.3 OnFatalException 28

5.4.4 OnMessage 28

5.4.5 OnProgress 28

5.5 Throwing exceptions 28

5.5.1 FieldValueImportException for Document Import API 29

5.6 Troubleshooting the Import API 29

5.6.1 BadImageImportFormatException error 29

5.6.2Missing text file 30

5.6.3Missing child object 30

5.6.4 Referencing a nonexistent ArtifactID 30

5.6.5Missing file 30

5.6.6Missing file specified for a document 30

5.6.7Missing file path 30

5.7Writing to an error log 31

5.8 Source table 31


5.9 Zero byte files 31

5.10 Sample Import API application 31

5.10.1 Viewing the Test Application 32


1 Import APIThe Relativity Import API provides functionality for programmatically importing large numbers of documents,images, and Dynamic Objects into a Relativity workspace. It facilitates the development of custom importutilities by providing methods for retrieving production sets, workspace fields, and performing other tasks.The Import API also supports the same settings for importing documents and images that are availablethrough the Relativity Desktop Client (RDC).

1.1 Import API conceptsFamiliarize yourself with the basic concepts about the classes and their members that comprise the ImportAPI. Learn about how the ImportAPI class simplifies the authentication, configuration, and import workflows.See Import API concepts below.

1.2 Getting StartedTo begin developing with the Import API, install the Relativity SDK and set up your developmentenvironment. Begin coding with the Import API by reviewing the sample code for importing documents,images, and Dynamic Objects. See Setting up a development environment on page 11.

1.3 Import API development guideAdvanced development topics include best practices, event handling, performancemetrics, and others. SeeImport API development guide on page 24.

1.4 Import API class libraryDocumentation for the Import API includes a fully commented class library.

2 Import API conceptsThe Import API provides functionality for creating custom import utilities for documents, images, productionsets, and Dynamic Objects. You can develop utilities for importing data from a staging database, eliminatingthe need to export it to a load file before adding it to Relativity. Data can also be imported from multiple,separate databases into Relativity, or from one Relativity workspace to another. The ImportAPI class includesthemethods, properties, and other members for developing these utilities. In addition, theImportBulkArtifactJob and ImageImportBulkArtifactJob classes support the import of large numbers ofartifacts and images respectively.

Note: While Import API continues to support the DataClientReader, kCura recommends using theImportAPI class for all new development projects.


2.1 ImportAPI classThe ImportAPI class is a top-level class that includes the functionality for importing documents, images,production sets, and Dynamic Objects. It includes methods for performing these import jobs, as well as othermethods for retrieving Workspace, Field, and other objects. This class resides in thekCura.Relativity.ImportAPI namespace.

Note: While Import API continues to support the DataClientReader, kCura recommends using theImportAPI class for all new development projects.

2.1.1 Instantiating an ImportAPI objectThe ImportAPI class includes overloaded constructors, which take a combination of authenticationinformation and a web service URL. All of the services in the ImportAPI class require authentication, so it isperformed when you instantiate the class. If authentication fails, an exception is thrown. See Authenticatingthrough the Import API on page 10.The following code sample illustrates how to create an instance of the ImportAPI class.

using kCura.Relativity.ImportAPI;

ImportAPI _importAPI = null;

try {_importAPI = new ImportAPI("[email protected]","RelativityPassword");

} catch (Exception ex) {Console.WriteLine("Login Failure: {0}", ex.Message);

}

In addition, you can programmatically set a value for the web service URL, which the ImportAPI uses tocommunicate with the Relativity WebAPI. For example, you could specify the location of theWebAPI using thefollowing URL:

https://relativity.kcura.com/relativitywebapi

If you don't programmatically specify the location of theWebAPI, the Import API attempts to resolve theserver name using the following process:

n Reads theWebServiceURL key set by an application in the local app.config file. If this attempt fails, itchecks theWindows Registry. See Using an optional app.config file on page 14.

n Reads the location fromWindows Registry set by the Relativity Desktop Client. If this attempt fails, theDataReaderClient generates an error.


Note: The Windows registry key named WebServiceURL is of type REG_SZ and is located in theHKCU\Software\kCura\Relativity node.

In this code sample, an instance of the ImportAPI class is created by using the constructor that takes ausername, password, and a web service URL.


ImportAPI _importAPI = null;

try {_importAPI = new ImportAPI("[email protected]","RelativityPassword", "http://myServer.kcura.com/relativitywebapi/");


}

2.1.2 Working with the ImportAPI classThe ImportAPI class includes methods for retrieving Workspaces, Fields, ProductionSets, and other objects. Italso includes methods for performing image, document, and production set import jobs. For moreinformation, see the kCura.Relativity.ImportAPI Namespace in the Import API class library.

2.1.2.1 Workspaces() methodTheWorkspaces() method returns an enumerable collection ofWorkspace objects containing all of theworkspaces accessible to the current user. TheWorkspace class contains a variety of properties, includingName and ArtifactID as illustrated in the following code sample.

IEnumerable<Workspace> workspaces = _importAPI.Workspaces();

foreach(Workspace ws in workspaces) {Console.WriteLine("Workspace: {0} ID: {1}", ws.Name, ws.ArtifactID);

}

2.1.2.2 GetProductionSets() methodThe GetProductionSets() method returns an enumerable collection of ProductionSet objects. Each objectrepresents an existing production set available for use with an ImageImportBulkArtifactJob. This methodreturns only production sets that meet these requirements:

n The production set must be in staging and not have any existing documents added.n The production set must be produced with the associated Imported field value set to Yes.

The following code sample illustrates how to use the GetProductionSets() method.


const int myWorkspaceId = 1015024;IEnumerable<ProductionSet> productionSets = _importAPI.GetProductionSets(myWorkspaceId);

foreach(ProductionSet production in productionSets) {Console.WriteLine("Production: {0} ID: {1}", production.Name,production.ArtifactID);

}

2.1.2.3 GetWorkspaceFields() methodThe GetWorkspaceFields() method takes a workspace ID and ArtifactTypeID. It returns an enumerablecollection of Field objects, which represent mappable fields in a workspace for the specified ArtifactTypeID.The returned collection is identical to fields that the Relativity Desktop Client displays, with the addition ofthose fields with a FieldType of File. You can use all the returned Field objects with the Import API, except forfields with the FieldType of File. The Relativity Services API can be used to populate these fields.The following code sample illustrates how to use the GetWorkspaceFields() method.

const int documentArtifactType = 10;const int myWorkspaceId = 1015024;IEnumerable<Field> fields = _importAPI.GetWorkspaceFields(myWorkspaceId,documentArtifactType);

foreach(Field field in fields) {Console.WriteLine("Field: {0} Category: {1}", field.Name,field.FieldCategory);

}

2.1.2.4 NewImageImportJob() methodThe NewImageImportJob() method returns an ImageImportBulkArtifactJob object that you can use for imageimports. Since this job is already authenticated, it doesn't required a username and password in the jobsettings.

2.1.2.5 NewNativeDocumentImportJob() methodThe NewNativeDocumentImportJob() method returns an object used for importing native documents. Sincethis job is already authenticated, it doesn't required a username and password in the job settings.

2.1.2.6 NewProductionImportJob() methodThe NewProductionImportJob() method takes ArtifactID property from a ProductionSet object, whichrepresents the destination production set in Relativity. It returns an ImageImportBulkArtifactJob object. Thismethod also pre-populates the Settings.ForProduction, and Settings.ProductionArtifactID properties requiredfor performing a production import. Use the GetProductionSets() method to retrieve the ArtifactID of thedestination production set as illustrated in the following code sample.


const int myWorkspaceId = 1015024;IEnumerable<ProductionSet> productionSets = _importAPI.GetProductionSets(myWorkspaceId);ProductionSet destinationProductionSet = productionSets.Single(p =>p.Name.Equals("My Destination Production Set"));

ImageImportBulkArtifactJob productionJob = _importAPI.NewProductionImportJob(destinationProductionSet.ArtifactID);

2.1.2.7 GetFileUploadMode() methodThe GetFileUploadMode() method determines the file upload mode used by the Import API. This methodtakes an integer specifying the workspace ArtifactID, and returns an upload mode only applicable to thisworkspace. Themode is returned as an UploadTypeEnum enumeration with one of the following values:

n Web - indicates the standard mode, which uploads files through the web server.n Direct - provides significantly faster uploads, and requires a connection to the network hosting the

data. It also requires specific Windows group permissions. If an upload in this mode fails, the systemreverts to Web mode.

2.1.2.8 NewObjectImportJob() methodThe NewObjectImportJob() method takes an ArtifactTypeID, and returns a new ImportBulkArtifactJob that ituses to import data into instances of an ArtifactType. Use the GetUploadableArtifactTypes() method toretrieve the required ArtifactType, and then pass the ArtifactType.ID property to the NewObjectImportJob()method. For more information, see the code sample for the GetUploadableArtifactTypes() method below.

2.1.2.9 GetUploadableArtifactTypes() methodThe GetUploadableArtifactTypes() method takes an integer specifying the workspace ArtifactID. It returns anenumerable collection of ArtifactType objects applicable only to the current workspace. This collectionrepresents only ArtifactTypeIDs that meet the following criteria:

n The object with the associated ArtifactTypeID can accept data.n The authenticated user has permissions to upload to the object with the associated ID.

The following code sample illustrates how to use the GetUploadableArtifactTypes() method.

const int myWorkspaceId = 1015024;IEnumerable<ArtifactType> artifactTypes = _importAPI.GetUploadableArtifactTypes(myWorkspaceId);ArtifactType desiredArtifactType = artifactTypes.Single(a => a.Name.Equals("MyCustom Object Type"));

ImportBulkArtifactJob objectImportJob = _importAPI.NewObjectImportJob(desiredArtifactType.ID);


2.2 ImportBulkArtifactJob classThe ImportBulkArtifactJob class provides the functionality for adding a large number of Artifact objects to aWorkspace. It includes a Settings property used to set import parameters, as well as the Execute() methodused for loading data, and retrieving messages from the OnMessage event. The following diagram illustrateshow the ImportBulkArtifactJob class interacts with other classes during a bulk import.

2.3 Authenticating through the Import APIThe ImportAPI class supports the following authentication methods:

n Relativity username and password - the user must be a member of the System Administrators groupin Relativity. These permissions are similar to those required to import a load file through the RelativityDesktop Client.

n Windows authentication - the user is validated against the Relativity WebAPI instance located atWebServiceURL. This authentication method doesn't require a Relativity username and password.

Note: Authentication is performed when the ImportAPI class is instantiated because all the servicesavailable through this class require it. If authentication fails, an exception is thrown.

2.4 Understanding field mappingThe Import API performs field mapping during the first stage of execution for an import job that uses theImportBulkArtifactJob class. After the Execute() method is called on the ImportBulkArtifactJob instance, theOnMessage event is raised multiple times, and passes Status objects that each have a Message property. ThisMessage property contains information about the progress of the Import job, including these actions takenbefore the execution begins:

n Message -Getting source data from databasen Message -Updating settingsn Message - Executing

Field mapping occurs after the OnMessage event passes the following execution message: [Timestamp: DATE_TIME] [Record Info: X]message. The next OnMessage event passes the detailed information about themapping process in theMessage property. The content of this Message is a single string that includes thefollowing information:

n Mapping is indicated with theMessage: Source field [SRC_FIELD_NAME] --> Destination field [DEST_FIELD_NAME]. Each source to destination message contains one field per line, and it is separated fromother messages by a new line.

n SRC_FIELD_NAME is identical to DEST_FIELD_NAME under normal conditions. In general, a namedcolumn in the data sourcematches the display name of a field in a destination workspace.

n DEST_FIELD_NAMEmay be replaced with the following text:o Filename - a special indicator related to KCURAMARKERFILENAME. Before the import, files are

copied to a local directory using the filename in kCuraMarkerFilename field except when linkspoint to them, or when this field doesn’t exist. The Import API copies the files from their currentlocation in this case. The values in the _KCURAMARKERFILENAME column are used for filenames


when this column is in the table. Otherwise, the original filenames are used.o NativeFilePath - indicates the SRC_FIELD_NAME used as the NativeFilePathColumn.o NOT MAPPED (Target field not found) - indicates that a source field does not have a matching

destination field in Relativity. During Import, Relativity ignores this field unless the SRC_FIELD_NAME is used as the FolderPathSourceFieldName.

After field mapping completes, the OnMessage events pass themessages Progress Info and Record Info.

3 Setting up a development environmentTo develop with the Import API, you need to install the 32 or 64-bit version of the Relativity SDK, whichcontains the required client libraries. If you want to use the Import API to develop both 32-bit and 64-bitapplications, then you need to install both versions of the SDK.The Relativity SDK Installer adds a folder called Import API to one of the following installation directories bydefault:

n 64-bit version - installs in ...\Program Files\kCura Corporation\Relativity SDK\ImportAPIn 32-bit version - installs in ...\Program Files (x86)\kCura Corporation\Relativity SDK\ImportAPI

This Import folder includes these subfolders:

n Client - contains the .dlls that must be referenced by a Visual Studio project used for development withthe Import API.

n Documentation - contains the Relativity - Import API.chm file with the Import API class library.n Samples – contains sample code for a demo application and a test harness for the Import API. See

Sample Import API application on page 31.

3.1 Before you beginComplete the following tasks before you set up your development environment:

n Confirm that you have .NET version 4 installed on your development machine.

Note: Upgrade all Visual Studio projects that currently reference the kCura.Relativity.DataReaderClient.dll to.NET 4.0.

n (Required only for Relativity 8 versions with build numbers of 8.0.179.2 or earlier) Install the RelativityDesktop Client. For more information, see the Desktop Client Guide on the kCura documentation site.

n See the Development environment guidelines page on the Relativity developers site to obtain a copy ofthe Relativity SDK Installer.

3.2 Setting up your environmentUse the following steps to set up a Visual Studio 2010 project:

1. See the Development environment guidelines page on the Relativity developers site, and then double-click the kCura.Relativity.SDK.Setup.msi. Follow the instructions in the installation wizard.

2. Create a new Console Application in Visual Studio. (The following steps use Visual Studio 2010 as anexample.)


3. Open the Solution Explorer.

4. Confirm that the Target framework is .NET Framework 4. (In the Solution Explorer, expand your pro-ject and right-click Properties. Click Open to display the Application tab in the left pane. Select .NETFramework 4 in the Target framework box.)

Note: Do not select .NET Framework 4 Client Profile in the Target framework box.

5. Add references to the following .dlls. (In the Solution Explorer, right-click References, and then click AddReferences to display the Add Reference dialog box. Click the Browse tab, and select each of the .dlls.)


The ImportAPI subfolder is installed at one of these locations by default:n 64-bit version - installs in ...\Program Files\kCura Corporation\Relativity SDK\Im-

portAPI\Client\x64n 32-bit version - installs in ...\Program Files (x86)\kCura Corporation\Relativity SDK\Im-

portAPI\Client\x86Add these .dlls in the ImportAPI subfolder to your project:

n kCura.Relativity.ImportAPI.dlln kCura.Relativity.DataReaderClient.dlln kCura.Data.dlln kCura.EDDS.Import.dlln kCura.ImageValidator.dlln kCura.OI.FileID.dlln kCura.Utility.dlln kCura.Windows.Forms.dlln kCura.Windows.Process.dlln kCura.WinEDDS.dlln kCura.WinEDDS.ImportExtension.dlln Relativity.dll

6. Copy the following .dll files from the SDK installation directory to the .\bin folder of your project.

Note: If you are using Relativity 8 with a build number of 8.0.179.2 or earlier, you must copy these .dll filesfrom the installation folder of the Relativity Desktop Client to the .\bin folder of your project.


n sccfi.dlln sccfut.dlln scclo.dlln sccut.dlln wvcore.dlln FreeImage.dlln FreeImageNET.dll

7. For information about writing code for specific types of import jobs, see Sample code for basic importtasks on the next page.

3.3 Using an optional app.config fileYou can optionally add an app.config file to the Visual Studio project used for development with the ImportAPI. You can specify various configuration settings in this file, including the location of theWebAPI.

Note: The ImportAPI class provides the ability to programmatically configure settings required for animport application. See ImportAPI class on page 6.

As illustrated in the following code sample, you need to add these XML elements to the<configuration>...</configuration> section of the app.config file:

<configSections><section name="kCura.WinEDDS"type="System.Configuration.DictionarySectionHandler, System,Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" />

</configSections><kCura.WinEDDS>

<add key="ImportBatchMaxVolume" value="52428800" /><add key="ImportBatchSize" value="500" /><add key="ExportBatchSize" value="1000" />

</kCura.WinEDDS>

You can specify the location ofWebAPI by adding theWebServiceURL key to kCura.WinEDDS section of theapp.config file. For example, use the following format for the URL:

https://relativity.kcura.com/relativitywebapi

You need to provide the location of theWebAPI because the Import API communicates with it. If thisinformation is not set programmatically with theWebServiceURL() property, then the Import API attempts toresolve the server name by reading theWebServiceURL key from the local app.config file. The Import APIgenerates an error when it is unable to resolve the location of the Relativity WebAPI.


4 Sample code for basic import tasksUsing the Import API, the sample code illustrates how to perform basic tasks, such as importing documents,images, and Dynamic Objects. While the import process for all of these object types is very similar, these codesamples highlight the following differences:

n Data sources – Image imports use a different data source than that used by documents or DynamicObjects. They use a DataTable which requires the implementation of the GetDataTable() method, whiledocuments and Dynamic Objects require an implementer of the IDataReader class and use theGetDataReader() method.

n IDataReader retrieval -When working with DataTable objects, use their CreateDataReader() method toretrieve an IDataReader. When executing SQL, use the ExecuteReader() method of the SqlCommandobject to retrieve an IDataReader.

n Import classes-Use an instance of the ImageImportBulkArtifactJob for image imports, and an instanceof the ImportBulkArtifactJob for importing document and Dynamic Object.

4.1 Logging in through the Import APITo log in, you create an instance of the ImportAPI class on page 6. Since all the services available within thisclass require authentication, the constructor takes a username and password. An exception is thrown whenauthentication fails. The following code sample illustrates how to create an instance of the ImportAPI class:


ImportAPI _importAPI = null;try {

_importAPI = new ImportAPI("[email protected]","RelativityPassword");


}

The constructor also takes a WebServiceURL value.

4.2 Importing documents with native filesYou can use the Import API to add documents to a workspace programatically by using methods available onthe ImportAPI class. You can also import import document metadata, native files, and extracted textassociated with your documents.

4.2.1 Creating a document import jobWhen importing documents to a workspace, you you instantiate the ImportAPI class and call itsNewNativeDocumentImportJob() method. You use a DataTable object as the data source for a document


import job. This sample code illustrates how to perform these tasks, as well as references the following codesamples that demonstrate how to write messages and create a DataTable object.

static void ImportDocument(){

Int32 workspaceArtifactID = 1015495;Int32 identifyFieldArtifactID = 1003667;

String relativityUserName = "[email protected]";String relativityPassword = "<your password>";String relativityWebAPIUrl = "http://localhost/Relativitywebapi/";

ImportAPI iapi = new ImportAPI(relativityUserName, relativityPassword,relativityWebAPIUrl);

var importJob = iapi.NewNativeDocumentImportJob();

importJob.OnMessage += ImportJobOnMessage;importJob.OnComplete += ImportJobOnComplete;importJob.OnFatalException += ImportJobOnFatalException;importJob.Settings.CaseArtifactId = workspaceArtifactID;importJob.Settings.ExtractedTextFieldContainsFilePath = false;

// Indicates file path for the native file.importJob.Settings.NativeFilePathSourceFieldName = "Native File";

// The name of the document identifier column must match the name of thedocument identifier field// in the workspace.importJob.Settings.SelectedIdentifierFieldName = "Doc ID Beg";importJob.Settings.NativeFileCopyMode = NativeFileCopyModeEnum.CopyFiles;importJob.Settings.OverwriteMode = OverwriteModeEnum.Append;

// Specify the ArtifactID of the document identifier field, such as acontrol number.importJob.Settings.IdentityFieldId = identifyFieldArtifactID;

importJob.SourceData.SourceData = GetDocumentDataTable().CreateDataReader();

Console.WriteLine("Executing import...");

importJob.Execute();}


4.2.2 Writing messages and errorsYou can use thesemethods to display messages about the status of an import job and any errors that mayoccur during it. The previous sample code uses thesemethods for capturing this information.

static void ImportJobOnMessage(Status status){

Console.WriteLine("Message: {0}", status.Message);}

static void ImportJobOnFatalException(JobReport jobReport){

Console.WriteLine("Fatal Error: {0}", jobReport.FatalException);}

static void ImportJobOnComplete(JobReport jobReport){

Console.WriteLine("Job Finished With {0} Errors: ",jobReport.ErrorRowCount);

}

4.2.3 Creating a DataTable object for a document import jobYou can create a DataTable object that includes metadata required to import documents to Relativity, such asan document identifier and a file path. The GetDocumentDataTable() method illustrates how to create andpopulate this table object, which is referenced in a previous code sample.

public static DataTable GetDocumentDataTable(){

DataTable table = new DataTable();

// The document identifer column name must match the field name in theworkspace.table.Columns.Add("Doc ID Beg", typeof(string));table.Columns.Add("Native File", typeof(string));table.Rows.Add("video", "C:\\video.wmv");table.Rows.Add("text", "C:\\text.txt");

return table;}

4.3 Importing imagesYou can use the Import API to add images to Relativity programatically by using methods available on theImportAPI class.


4.3.1 Creating an image import jobWhen you create an image import job, you instantiate the ImportAPI class and call its NewImageImportJob()method. You use a DataTable object as the data source for an image import job. This sample code illustrateshow to perform these tasks, as well as references the following code samples that demonstrate how to writemessages and create a DataTable object.

static void ImportImage(){

Int32 workspaceArtifactID = 1015495;Int32 identifyFieldArtifactID = 1003667;



var importJob = iapi.NewImageImportJob();

importJob.OnMessage += ImportJobOnMessage;importJob.OnComplete += ImportJobOnComplete;importJob.OnFatalException += ImportJobOnFatalException;

importJob.Settings.AutoNumberImages = false;

// You can use the Bates number as an identifier for an image.importJob.Settings.BatesNumberField = "Bates";importJob.Settings.CaseArtifactId = workspaceArtifactID;

// Use this code for grouping images associated with a document.importJob.Settings.DocumentIdentifierField = "Doc";

// Indicates filepath for an image.importJob.Settings.FileLocationField = "File";

// Specifies the ArtifactID of a document identifier field, such as acontrol number.importJob.Settings.IdentityFieldId = identifyFieldArtifactID;importJob.Settings.OverwriteMode = OverwriteModeEnum.Append;importJob.SourceData.SourceData = GetImageDataTable();


importJob.Execute();


iapi = null;}








}

4.3.3 Creating a DataTable objectYou can create a DataTable object that includes metadata required to import images to Relativity, such as anidentifier for associating images with a specific document, and a file path. The GetImageDataTable() methodillustrates how to create and populate this table object, which is referenced in a previous sample code.

public static DataTable GetImageDataTable(){


// Column names don't need to correspond to field names.table.Columns.Add("Bates", typeof(string));table.Columns.Add("Doc", typeof(string));table.Columns.Add("File", typeof(string));

//Group three images under A_1 document.table.Rows.Add("A_1", "A_1", "C:\\VOL01\\IMAGES\\IMG001\\Test000001.tif");table.Rows.Add("A_2", "A_1", "C:\\VOL01\\IMAGES\\IMG001\\Test000002.tif");table.Rows.Add("A_3", "A_1", "C:\\VOL01\\IMAGES\\IMG001\\Test000003.tif");


//Group two images under B_1 document.table.Rows.Add("B_1", "B_1", "C:\\VOL01\\IMAGES\\IMG001\\SDF000001.tif");table.Rows.Add("B_2", "B_1", "C:\\VOL01\\IMAGES\\IMG001\\SDF000002.tif");

return table;}

4.4 Importing produced imagesYou can add produced images to a production set in Realtivity by using methods available on the ImportAPIclass.

4.4.1 Creating a production import jobWhen importing produced images, you pass the ArtifactID of the target production set to theNewProductionImportJob() method on the ImportAPI class. You use a DataTable object as the data source fora production import job. This sample code illustrates how to perform these tasks, as well as references thefollowing code samples that demonstrate how to write messages and create a DataTable object.

static void ImportProduction(){

Int32 workspaceArtifactID = 1015495;Int32 identityFieldArtifactID = 1003667;String productionSetName = "TestProduction";



//Pass the ArtifactID of a workspace to retrieve a collection of productionsets.var productionList = iapi.GetProductionSets(workspaceArtifactID);

//Select a production. You add the production sets to this production.var desiredProduction = productionList.Single(p => p.Name.Equals(productionSetName, StringComparison.InvariantCultureIgnoreCase));var importJob = iapi.NewProductionImportJob(desiredProduction.ArtifactID);

importJob.OnMessage += ImportJobOnMessage;importJob.OnComplete += ImportJobOnComplete;importJob.OnFatalException += ImportJobOnFatalException;


//Specify the ArtifactID of the document identifier field, such as a controlnumber.importJob.Settings.IdentityFieldId = identityFieldArtifactID;importJob.Settings.AutoNumberImages = false;

// You can use the Bates number as an identifier for an image.importJob.Settings.BatesNumberField = "Bates";importJob.Settings.CaseArtifactId = workspaceArtifactID;

// Use this code for grouping images associated with a document.importJob.Settings.DocumentIdentifierField = "Doc";importJob.Settings.ExtractedTextFieldContainsFilePath = false;

// Indicates file path for an image.importJob.Settings.FileLocationField = "FileLoc";importJob.Settings.NativeFileCopyMode = NativeFileCopyModeEnum.CopyFiles;importJob.Settings.OverwriteMode = OverwriteModeEnum.Overlay;

importJob.SourceData.SourceData = GetProductionDataTable();










}


4.4.3 Creating a DataTable object for a productionYou can create a DataTable object that includes metadata required to import images to Relativity, such as anidentifier for associating images with a specific document, and a file path. The GetProductionDataTable()method illustrates how to create and populate this table object, which is referenced in a previous codesample.

public static DataTable GetProductionDataTable(){


// Column names don't need to correspond to field names.table.Columns.Add("Bates");table.Columns.Add("Doc", typeof(string));table.Columns.Add("FileLoc", typeof(string));

//Group three images under A_1 document.table.Rows.Add("A_1", "A_1", "C:\\VOL01\\IMAGES\\IMG001\\Test000001.tif");table.Rows.Add("A_2", "A_1", "C:\\VOL01\\IMAGES\\IMG001\\Test000002.tif");table.Rows.Add("A_3", "A_1", "C:\\VOL01\\IMAGES\\IMG001\\Test000003.tif");

//Group two images under B_1 document.table.Rows.Add("B_1", "B_1", "C:\\VOL01\\IMAGES\\IMG001\\SDF000001.tif");table.Rows.Add("B_2", "B_1", "C:\\VOL01\\IMAGES\\IMG001\\SDF000002.tif");

return table;}

4.5 Importing Dynamic ObjectsYou can use the Import API to add Relativity Dynamic Objects (RDOs) to a workspace programatically by usingmethods available on the ImportAPI class.

4.5.1 Creating an RDO import jobWhen importing RDOs to a workspace, you pass an ArtifactType.ID to the GetUploadableArtifactTypes() onthe ImportAPI class. You use a DataTable object as the data source for an RDO import job. This sample codeillustrates how to perform these tasks, as well as references the following code samples that demonstrate howto write messages and create a DataTable object.

static void ImportObject(){

Int32 workspaceArtifactID = 1015495;Int32 identityFieldArtifactID = 1038772;String artifactTypeName = "TestObject";




// Pass the ArtifactID of the workspace. You add your RDOs to thisworkspace.var artifactTypeList = iapi.GetUploadableArtifactTypes(workspaceArtifactID);

// Use this code to choose type of object that you want to add.var desiredArtifactType = artifactTypeList.Single(at => at.Name.Equals(artifactTypeName));

var importJob = iapi.NewObjectImportJob(desiredArtifactType.ID);importJob.OnComplete += ImportJobOnComplete;importJob.OnFatalException += ImportJobOnFatalException;

// Use this setting for Name field of the object.importJob.Settings.SelectedIdentifierFieldName="Name";

// Specifies the ArtifactID of a document identifier field, such as acontrol number.importJob.Settings.IdentityFieldId = identityFieldArtifactID;

importJob.Settings.CaseArtifactId = workspaceArtifactID;importJob.Settings.OverwriteMode = OverwriteModeEnum.AppendOverlay;importJob.SourceData.SourceData = GetObjectDataTable().CreateDataReader();











}

4.5.3 Creating a DataTable objectYou can create a DataTable object that includes the Field name of each RDO that you want to import to aworkspace. The GetObjectDataTable() method illustrates how to create and populate this table object, whichis referenced in a previous sample code .

public static DataTable GetObjectDataTable(){


// Column names must match the object field name in the workspace.table.Columns.Add("Name", typeof(string));table.Rows.Add("TestObject");

return table;}

5 Import API development guideUse the Import API development guide to explore advanced programming topics, such as event handling,exceptions, and best practices. You can also find information about the test harness for the Import API, whichis a complex sample application.

5.1 Import API best practicesReview the following guidelines to optimize your application development with the Import API.

5.1.1 Use the Name field for Dynamic ObjectsUse the Name field with a unique identifier to reference Dynamic Objects.


5.1.2 Use required identifiers in OverwriteModeUse the following identifiers for documents and Dynamic Objects when setting OverwriteMode to Overlay:

n Documents – use control numbern Dynamic Objects – use name

5.1.3 Specify a field as an identifier for document importsUse the SelectedIdentifierFieldName() property to specify a field as an identifier when you are importing newdocuments. During document import, the control number is used when the specified identifier can't beresolved, while an error is generated when the control number can't be resolved.

5.1.4 Use the kCuraMarkerFilename field when copying filesYou can optionally use the kCuraMarkerFilename field when NativeFileCopyMode is set to CopyFiles. Set thisfield to the filename that you want displayed in Relativity. If you want to use the filename on disk, don't setthis field.

5.1.5 Set NativeFilePathSourceFieldName when copying native filesWhen the NativeFileCopyMode property is set to any value other than DoNotImportNativeFiles, you must setthe NativeFilePathSourceFieldName.

5.1.6 Use a unique identifier when importing child recordsSet the ParentObjectIdSourceFieldName property with the unique identifier of a parent record whenimporting records that are the children in a parent/child relationship.

5.1.7 Set appropriate fields when importing extracted textSet the ExtractedTextEncoding and ExtractedTextFieldContainsFilePath fields when you import extracted text.

5.1.8 Catch the NeedToReLoginException to prevent import failuresWhen the authentication token expires during an import job, the NeedToReLoginException is thrown and theimport job fails. You can prevent this failure by catching the exception, logging in, and resuming the importprocess. You can also useWindows Authentication, which internally handles token renewal.

5.1.9 Improve performance by using Import API settingsYou can improve performance by using settings that control how the Import API handles metadata associatedwith objects:

n Skip Outside In file identification - Use the OIFileIdMapped property to skip file identification throughthe Import API. The OIFileIdColumnName and OIFileTypeColumnName properties must be set to val-ues that indicate the columns in the SourceData property, which contain the OutsideInFileId and theOutsideInFileType properties.


n Skip file size checking - Use FileSizeMapped property to skip file size checking through the Import API.The FileSizeColumn property must be set to the value that indicates the column in the SourceData prop-erty, which contains the FileSize.

n Disable checks on extracted text files - Use the DisableExtractedTextEncodingCheck setting to bypassthe process of directly detecting the encoding of each file in an import job. When you use this setting,make sure that all files have the same encoding. In addition, use the Dis-ableExtractedTextFileLocationValidation to skip the validation of the location for native files.

n Map objects by ArtifactID – Use the ObjectFieldIdListContainsArtifactId setting to identify fields thatshould bemapped by ArtifactID instead of by name.

Note: You can map fields by name through both the Relativity Desktop Client (RDC) and the Import API. Thisfunctionality requires loading a large metadata table of fields into memory. Since the RDC loads this table andthe workspace at the same time, users don’t often notice any delay during an import job. The Import API loadsthese fields as they are created with a constructor, which may cause a performance delay.

5.1.10 Use a single Import API instance per workspaceYou can improve performance by using a single Import API instance per workspace. In addition, minimize thenumber of times the Import API instance is created or destroyed. (The Import API loads field metadata atcreation, which may cause a performance delay.)

5.1.11 Determine optimum batch size for your environmentYou may want to use import batch sizes of 1000 files initially. After further testing, you can customize thebatch size for your environment needs.

5.1.12 Avoid index fragmentationWhen running large jobs through the Import API, you may experience decreased performance due to indexfragmentation. Avoid this issue by rebuilding all of your indexes before starting a large import job. Additionalsteps that you can take to minimize fragmentation include:

n Rebuilding indexes on the fly.n Importing documents for an hour, rebuilding the indexes, and then resuming the import job.n Upgrading to the latest version of Relativity.

5.1.13 Miscellaneous ways to improve performanceAdditional best practices to improve performance include:

n Consider using Append rather than Append/Overlay mode. Append mode is much faster. See the Over-writeModeEnum Enumeration in the Import API class library.

n Use ArtifactIDs when creating multiple object and single object fields to facilitate performance.n Creation of certain objects such as folders can affect performance.


5.2 Mapping single or multiple object fields by ArtifactIDYou can map instances of single or multiple object fields by name or ArtifactID. When multiple instances of anobject share the same name, you can uniquely identify them by mapping them with their ArtifactIDs. Forexample, you can assign unique ArtifactIDs to custodians with the same name.To map a field, assign the ArtifactID for the field to the Settings.ObjectFieldIdListContainsArtifactId property ofa ImportBulkArtifactJob instance. A document is flagged with an error when an instance of a single or multipleobject field is linked to an ArtifactID that doesn't exist in the workspace. This document is not imported intothe workspace.

5.3 Specifying folders through the Settings classIn the Import API, you can use the FolderPathSourceFieldName property on the Settings class to specify afolder used during import. The Import API handles a folder specified with this property as follows:

n If the folder already exists, Relativity imports the documents to it.n If the folder doesn't exist, Relativity creates it and imports the documents to it.n If you specify a folder path that includes nested folders, Relativity creates all of the these folders.

The ImageSettings class also includes a FolderPathSourceFieldName property, which provides similarbehavior.

5.4 Handling eventsThe Import API raises events that display information about the progress of an import job and provide detecterrors.

5.4.1 OnCompleteThis OnComplete event occurs when an import job is finished. A JobReport object is passed with detailedinformation about the job. A completed job may have errors if the data wasn't imported properly. JobReporthas the following public properties:

n StartTime – a DateTime object containing the time the import began.n EndTime – a DateTime object containing the time the import terminated.n FieldMap – For document imports with native files, this property contains a List of all fields in the

source data, and the fields to which they aremapped in the Relativity workspace.n TotalRows – the number of rows that were processed.n ErrorRowCount – the number of rows that contained errors.n ErrorRows – a List of rows with errors. This property includes the row number, message, and document

identifier.n FatalException – This exception is available when a fatal exception causes the import to terminate.

5.4.2 OnErrorOnError contains a single parameter named Row, which is declared as an IDictionary. This event is raised whenan error occurs while importing a row of data. TheMaximumErrorCount is a configurable setting available onall import jobs that determines the number of errors to return.


If you are using the ImportBulkArtifactJob class, the Row parameter contains the following key-value pairs foreach record that causes an error and fails to be imported:

n Line number – the row number from the SourceData that caused an error. It is a 1-based index. (Thefirst row of a SourceData contains data rather than column names.)

n Identifier – the value in the identifier field for the document that errored, which is the control numberin Relativity, by default.

n Message – an error message indicating why the record errored. This message is similar to those in theRelativity Desktop Client.

If you are using the ImageImportBulkArtifactjob class, the Row parameter contains the following key-valuepairs for each record that causes an error and fails to be imported:

n Line number – the row number from the SourceData that caused an error. It is a 1-based index. (Thefirst row of a SourceData contains data rather than column names.)

n FileID – the identifier of the image file that errored.n DocumentID – the value in the identifier field of the document associated with the image that errored.n Message – an error message indicating why the record errored. This message is similar to those used in

the Relativity Desktop Client.

5.4.3 OnFatalExceptionThe OnFatalException event is raised when an import job encounters a fatal exception caused by invalidimport settings or other issues. It passes a JobReport object with detailed information about the exception.

5.4.4 OnMessageThe OnMessage event is used to monitor the progress of an import job programmatically. It contains a Statusparameter, which contains a Message property. TheMessage property returns values that indicate theprogress of the import job, and can be displayed to users. This message is similar to those used in theRelativity Desktop Client.

5.4.5 OnProgressThe OnProgress event is raised after each row in a data set is imported. It contains the number of processedrows.

5.5 Throwing exceptionsThe Import API provides the following exceptions that may be thrown during an import job:

n ImportSettingsException - This exception is thrown when a required parameter isn't set. It containsthe Setting and AdditionalInfo properties. The AdditionalInfo property has a value only as applicable,such as when one of two interdependent properties isn't set.

n ImportSettingsConflictException - This exception is thrown a property is set to a value that conflictswith another property. It contains properties that identify the initial setting and the conflictSetting(that is the property causing the conflict. The exception message contains additional information aboutthe conflict.


5.5.1 FieldValueImportException for Document Import APIThe FieldValueImportException object is thrown when a field can't be populated with incoming data during adocument import job. This exception returns the following properties:

n RowNumber - a Int64 containing the number of the row in the data fail that caused an import failure.n FieldName - a string containing the display name of the Relativity field that wasn't set.n InnerException - a lower-level exception object containing detailed information about the exception

type, such as NullReferenceException, or InvalidCastException.In addition, theMessage property also displays information about an exception as illustrated in the followingexample:

Error in row {row number} , field {field name}. {Message from inner exception}

5.6 Troubleshooting the Import APIYou can troubleshoot an import job by using the information in the error message to identify the cause of afailure. Most non-fatal errors are RowError objects that are a part of the JobReport.ErrorRows property.

5.6.1 BadImageImportFormatException errorWhen you attempt to build a project, you receive the following BadImageImportFormatException message:

This error occurs when you attempt to build your application against wrong target platform for the .dllsinstalled by the Relativity SDK installer. For example, you may be attempting to build a 64-bit application with32-bit .dlls.To resolve this issue, download the version of the Relativity SDK installer required for your application. InVisual Studio, select the appropriate configuration for your target platform in the Configuration Managerdialog as illustrated here:


For information about downloading the Relatvity SDK installer, see Development environment guidelines onthe Relativity 8 Developers site.

5.6.2 Missing text fileWhen the ExtractedTextFieldContainsFilePath setting is enabled, and the extracted text file for a row can't befound, the following error message is displayed:

Error in line {number}, column “{column}”. Error: full text file specifieddoes not exist.

This error message points to the column for extracted text. {number} indicates the line number where theerror occured, and {column} indicates the column order, such as A, B, C, and so on. To resolve this error,verify that the extracted text file exists and that it can be accessed by the Import API. Make sure that the pathdoesn't contain any typographical or other errors.

5.6.3 Missing child objectWhen a single or multiple object field specified by the ObjectFieldIdListContainsArtifactId setting doesn't exist,the following error message is displayed:

An object field references a child object which does not exist.

To resolve this error, verify that the destination workspace and the ArtifactID for the field are correct.

5.6.4 Referencing a nonexistent ArtifactIDWhen an invalid ArtifactID is specified by the ObjectFieldIdListContainsArtifactId setting for valid single ormultiple object field, the following error message is displayed:

An object field references an artifact ID which doesn’t exist for the object.

To resolve this error, confirm that the ArtifactID maps to a valid single or multiple object instance.

5.6.5 Missing fileA fatal error occurs when a file can't be found during import. The following error message is displayed:

Could not find file ‘{filename}’.

{filename} indicates the value supplied in the image file path.

5.6.6 Missing file specified for a documentWhen an image import is performed with DisableImageLocationValidation set to False and an image file ismissing, the following error message is displayed:

One of the files specified for this document does not exist.

To resolve this error, confirm that the file exists and is accessible by the Import API.

5.6.7 Missing file pathA fatal error occurs when an image import is performed with DisableImageLocationValidation set to True andno image file path has been supplied. The following error message is displayed:

The path is not of a legal form.

To resolve this error, confirm that a valid path is specified and is accessible by the Import API.


5.7 Writing to an error logYou can use the ExportErrorReport() method on the ImportBulkArtifactJob and ImageImportBulkArtifactJobclasses to write an error log. This method takes a filePathAndName parameter, which specifies the location forthe error log. It exports an empty file when a job doesn't generate any errors, and overwrites the existingerror log. The Import API generates detailed error messages as illustrated in the following example:

Error in row 6, field "sampledecimalfield". Input string was not in a correctformat.

5.8 Source tableYour source database table can consist entirely of text fields (such as varchar and nvarchar). The Import APIconverts these text fields to one of the Relativity data types, such as Boolean, Date, Integer, Currency, orDecimal. Empty text fields in the source table are converted to NULL values.

5.9 Zero byte filesBy default, the Import API imports only metadata for native files with the size of 0 KB. In the viewer, users seeextracted text when it exists for the file. If the file has no extracted text, users see a blank placeholder, and noviewer options will be available.Alternately, you can configure the Import API to not import metadata for an empty file. To do this, add thefollowing line to the <kCura.WinEDDS> section in the app.config file:

<add key="CreateErrorForEmptyNativeFile" value="True" />

For additional information, see the Configuring the RDC feature in the Admin guide on the kCuradocumentation site.

5.10 Sample Import API applicationThe Relativity Import API Test Application is a test harness that demonstrates how to import native files fordocuments, images, and produced images. You can obtain the commented source code for this applicationfrom the following folder.

...\Program Files\kCura Corporation\Relativity SDK\ImportAPI\Samples\DataReaderClient.TestHarness

Use the following guidelines for working with the sample application:

n Verify that the correct Solution Platform is selected before building the sample project.n To capture detailed logging information, set the value of theWriteFullLog key to True in the app.config

file. By default, the sample application maximizes import performance by logging minimal information.n To increase the timeout for queries, update the value (in seconds) of the SqlTimeOut key in the app.-

config file. By default, the sample application uses a 60 second timeout for queries against the sourcedatabase.


5.10.1 Viewing the Test ApplicationThe UI for the Import API Test Application includes the following dialog boxes that you can use to log in toRelativity, as well as select the destination workspace and adjust the settings for a specific import job:

n Relativity Login dialog box - requires a username and password for Relativity. In addition, you need toprovide the URL for the web service.

n Available Workspace list - requires you to select a destination workspace and the type of Artifact thatyou are importing. It also includes links to dialog boxes used to configure settings for an import job.


n Native Document Import dialog box - includes a list of settings that you can configure for importingnative files.



n Image Import dialog box - includes a list of settings that you can configure for importing images.

n Production Import dialog box - includes a list of settings that you can configure for importing pro-ductions.



Proprietary RightsThis documentation (“Documentation”) and the software to which it relates (“Software”) belongs to kCuraCorporation and/or kCura’s third party software vendors. kCura grants written license agreements whichcontain restrictions. All parties accessing the Documentation or Softwaremust: respect proprietary rights ofkCura and third parties; comply with your organization’s license agreement, including but not limited tolicense restrictions on use, copying, modifications, reverse engineering, and derivative products; and refrainfrom any misuse or misappropriation of this Documentation or Software in whole or in part. The Software andDocumentation is protected by the Copyright Act of 1976, as amended, and the Software code is protectedby the Illinois Trade Secrets Act. Violations can involve substantial civil liabilities, exemplary damages, andcriminal penalties, including fines and possible imprisonment.©2013. kCura Corporation. All rights reserved. Relativity® and kCura® are registered trademarks of kCuraCorporation.