Import documents with native files

You can use the Import API to add documents to a workspace programmatically by using the methods available on the ImportAPI class. You can also import document metadata, native files, and extracted text associated with documents.

Note: On GitHub, you can find can comprehensive samples illustrating how to import native documents, images, objects, and productions. For additional code samples, see the Import API samples repository.

This page contains the following information:

Create a document import job

When importing documents to a workspace, you instantiate the ImportAPI class and call its NewNativeDocumentImportJob() 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 code samples that demonstrate how to write messages and create a DataTable object.

Note: If your environment is configured to use RSA authentication, then you can enter your Relativity account username, and RSA passcode when instantiating the ImportAPI class.

static void ImportDocument()
{
     Int32 workspaceArtifactID = 1015495;
     Int32 identifyFieldArtifactID = 1003667;
      
     String relativityUserName = "jane.doe@relativity.com";
     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";
       
     // Indicates the column containing the ID of the parent document.
     importJob.Settings.ParentObjectIdSourceFieldName = "Parent Document ID"; 

     // Indicates the column containing the ID of the Data Grid records already created for the documents.
     importJob.Settings.DataGridIDColumnName = "Data Grid ID";

     // The name of the document identifier column must match the name of the document 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 a control number.
     importJob.Settings.IdentityFieldId = identifyFieldArtifactID;
      
     importJob.SourceData.SourceData = GetDocumentDataTable().CreateDataReader();
      
     Console.WriteLine("Executing import...");
      
     importJob.Execute();
}

Note: The importJob.Settings.DataGridIDColumnName property is used on append and overlay to create a mapping between the document and the records in Data Grid when an external system, for example, Invariant already populated the Data Grid records and you want to share them with Relativity. For overlay, the GUID specified in the load file replaces the current mapping.

Write messages and errors

You can use these methods to display messages about the status of an import job and any errors that may occur during it. The previous code sample uses these methods 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);
}        

Create a DataTable object for a document import job

You can create a DataTable object that includes metadata required to import documents to Relativity, such as an document identifier and a file path. The GetDocumentDataTable() method illustrates how to create and populate 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 the workspace.
     table.Columns.Add("Doc ID Beg", typeof(string)); 
     table.Columns.Add("Native File", typeof(string));
     table.Columns.Add("Parent Document ID", typeof(string));
     table.Rows.Add("video", "C:\\video.wmv", "");
     table.Rows.Add("text", "C:\\text.txt", "video");
      
     return table;
}   

Upload custom assemblies

In the Relativity, upload any custom assemblies for your application and the Import API assemblies as resource files. You must manually add the Import API assemblies in order for your custom application to function properly. For more information, see Resource files on the Relativity Documentation site.

Additional Resources

DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.