Open topic with navigation
You can quickly begin importing documents, images, and Relativity Dynamic Objects (RDOs) by setting up your development environment and reviewing code samples that illustrate how to perform basic import tasks
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:
The Import API requires the following software:
|Operating System||VC++2010 (x86)||VC++2010 (x64)||VC++2017 (x86)||VC++2017 (x64)|
To develop with the Import API, you can use NuGet packages to simplify the initial setup and upgrades, and to ensure all required platform dependencies are installed.
Complete the following tasks before you set up your development environment:
Note: Upgrade all Visual Studio projects that currently reference the kCura.Relativity.DataReaderClient.dll to .NET 4.6.2.
Note: For information about compatible versions of the NuGet package and Relativity, see Import API compatibility matrix
Use the following steps to set up a Visual Studio 2017 project:
(Click to expand)
(Click to expand)
(Click to expand)
(Click to expand)
The Relativity WebAPI is the web service for accessing the Import API. Use the following format for the WebAPI URL:
The WebAPI URL can be set programmatically when you create an instance of the ImportAPI class. For more information, see ImportAPI class. It can also be set as the optional WebServiceURL property in the app.config file. The Import API generates an error when it is unable to resolve the location of the Relativity WebAPI.
The Import API is integrated with the Transfer API to support these data transfer modes:
Before data transfer is performed, the underlying Transfer API (TAPI) queries the resource server configurations and automatically selects the optimal available mode for the transfer job. This significantly improves the performance of import jobs. The import speed is also improved by asynchronous retry logic.
You can use configuration properties in the optional app.config file to force the Import API to use a specific transfer mode.
Direct mode provides faster performance, but it requires a connection to the network hosting the data, as well as specific Windows group permissions. Direct mode has direct access to write to the file repository, which bypasses the need to go through the web server in order to ingest the data, saving a significant amount of time.
With RelativityOne, direct mode can be used only on the Utility Server.
The following conditions must be met in order to load data using direct mode into Relativity Server instance:
Note: The Import API automatically uses the TapiForceBcpHttpClient app.config setting when the BCP share isn't accessible.
In addition to the direct and web modes, the Import API has integrated the Aspera file transfer mode to allow you to quickly upload documents to RelativityOne.
Aspera mode requires configuration on each file share resource server.
Windows doesn't support multiple active connections on the same UDP port. Therefore, the business firewall must allow a range of UDP ports to reach the Aspera server. Incoming client connections automatically increment to use the next available port in the range. Open these ports on any machine that stages any data to RelativityOne. This includes ports on your network, as well as local machine firewalls. You must make the following business firewall changes to ensure concurrent transfers can occur:
Note: You must make sure that both TCP and UDP ports are open on the client machine.
The following list includes the assembly binding redirects, which we recommend adding to your app.config file:
<?xml version="1.0" encoding="UTF-8"?> <configuration> <runtime> <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"> <dependentAssembly> <assemblyIdentity name="Newtonsoft.Json" publicKeyToken="30ad4fe6b2a6aeed" culture="neutral" /> <bindingRedirect oldVersion="0.0.0.0-220.127.116.11" newVersion="18.104.22.168" /> </dependentAssembly> <dependentAssembly> <assemblyIdentity name="ZetaLongPaths" publicKeyToken="b764f59068f31f38" culture="neutral" /> <bindingRedirect oldVersion="0.0.0.0-22.214.171.124" newVersion="126.96.36.199" /> </dependentAssembly> <dependentAssembly> <assemblyIdentity name="itextsharp" publicKeyToken="8354ae6d2174ddca" culture="neutral" /> <bindingRedirect oldVersion="0.0.0.0-188.8.131.52" newVersion="184.108.40.206" /> </dependentAssembly> </assemblyBinding> </runtime> </configuration>
You can optionally add an app.config file to the Visual Studio project used for development with the Import API. You can specify various configuration settings in this file, including the location of the WebAPI. For more information, see
Note: In the Import API, you can programmatically configure several settings required for an import application through the Settings property on the ImageImportBulkArtifact and ImportBulkArtifactJob classes. You can’t programmatically set the batch size, but you can update the ImportBatchSize value in the app.config, which has a default value of 1000 when not specified for an application.
By default, the Import API imports only metadata for native files with the size of 0 KB. In the viewer, users see extracted text when it exists for the file. If the file has no extracted text, users see a blank placeholder, and no viewer options will be available.
Alternately, you can configure the Import API to not import metadata for an empty file. To do this, add the following line to the <Relativity.DataExchange> section in the app.config file:
<add key="CreateErrorForEmptyNativeFile" value="True" />
For more information, see
After building your custom application, you need to add it to Relativity. For information on this process, see Deploy Import API applications.