Get started with the Import API

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:

See these related topics:

Import API dependencies

The Import API requires the following software:

  • Microsoft .NET 4.6.2 or above
  • Set the platform target to x64 to support images. For more information, see Set up a development environment
  • Redistributables listed in the following table:
    Operating SystemVC++2010 (x86)VC++2010 (x64)VC++2017 (x86)VC++2017 (x64)
    32-bitü ü 
    64-bitüüüü

Set up a development environment

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.

Before you begin

Complete the following tasks before you set up your development environment:

  • Confirm that you have .NET version 4.6.2 installed on your development machine.

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

  • Add the NuGet package called Relativity.DataExchange.Client.SDK to your Visual Studio projects used for import applications. For detailed steps, see Set up your environment.

    Note: For information about compatible versions of the NuGet package and Relativity, see Import API compatibility matrix

Set up your environment

Use the following steps to set up a Visual Studio 2017 project:

  1. Create a new Console Application in Visual Studio. (The following steps use Visual Studio 2017 as an example.)
  2. Open the Solution Explorer.

    (Click to expand)

    Solution Explorer in Visual Studio 2017

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

    (Click to expand)

    .NET 4.5 as the target framework

  4. Click the Build tab and set the platform target to x64. (Build > Configuration Manager).

    (Click to expand)

    Platform target set to x64

  5. Add the NuGet package reference called Relativity.DataExchange.Client.SDK. (In the Solution Explorer, right-click References > Manage NuGet Packages. Type the package identifier.)
      Notes:
    • Use the Relativity.DataExchange.Client.SDK package in any new projects. The Relativity.Import.Client package has been deprecated, and any existing projects must be migrated to the Relativity.DataExchange.Client.SDK package. Your custom applications will fail if you don't migrate them to the new package. For more information, see Import API migration.
    • The Import API NuGet package includes all required third-party .NET dependencies and the custom scripts used to copy the native libraries to the target path.

    (Click to expand)

    NuGet package

  6. Add your custom code to the project. For sample code, see this list of related topics.
  7. You may need to include additional assemblies (such as Outside In (OI) binaries to your project, based on how it is deployed to Relativity. See the topic Deploy Import API applications for more details.

Import API endpoint URL

The Relativity WebAPI is the web service for accessing the Import API. Use the following format for the WebAPI URL:

https://<Relativity host>/relativitywebapi

For example:

https://relativity.relativity.com/relativitywebapi

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.

Transfer modes

The Import API is integrated with the Transfer API to support these data transfer modes:

  • Web - uses the HTTP client. This is the default mode. Because of the limitations of the HTTP protocol and varying network bandwidth, it is the slowest.
  • Direct- uses the file share client. Direct mode provides the fastest transfer speed.
  • Aspera - uses the Aspera client. It is significantly faster than Web mode. The Aspera mode is only available in RelativityOne environments.

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

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.

Requirements

The following conditions must be met in order to load data using direct mode into Relativity Server instance:

  • The Active Directory account running the load must have direct access to the Relativity File Repository.

    Note: The Import API automatically uses the TapiForceBcpHttpClient app.config setting when the BCP share isn't accessible.

  • The loaded data must be located on the Relativity system network/domain.
  • The computer running the application that uses the Import API must be located on the Relativity system network/domain.
  • The group of users responsible for uploading documents through the Win Relativity component (Relativity Upload Users) must have Full Control in the Document Repository Share. This allows members of this group to import and export in Direct mode. Non-members can only import and export in Web mode.

Aspera mode

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.

Port considerations

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:

  • Allow inbound/outbound connections to the server on the TCP port 33001.
  • Allow outbound connections to the server on the UDP ports 33001 - 33050
  • Allow outbound connections to the server on TCP port 9092.

    Note: You must make sure that both TCP and UDP ports are open on the client machine.

Assembly binding redirects

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-12.0.0.0" newVersion="6.0.0.0" />
         </dependentAssembly>
         <dependentAssembly>
            <assemblyIdentity name="ZetaLongPaths" publicKeyToken="b764f59068f31f38" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-1.0.0.27" newVersion="1.0.0.27" />
         </dependentAssembly>
         <dependentAssembly>
            <assemblyIdentity name="itextsharp" publicKeyToken="8354ae6d2174ddca" culture="neutral" />
            <bindingRedirect oldVersion="0.0.0.0-5.1.2.0" newVersion="5.1.2.0" />
         </dependentAssembly>
      </assemblyBinding>
   </runtime>
</configuration>

Optional app.config file

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 Configuring the RDC on the RelativityOne Documentation site.

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. For more information, see ImportBulkArtifactJob class.

Zero byte files

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 Configuring the RDC on the RelativityOne Documentation site.

Data encoding

The Import API allows you to specify the character encoding of extracted text. However, all object metadata are imported as UTF-16.

ADS deployment considerations

After building your custom application, you need to add it to Relativity. For information on this process, see Deploy Import API applications.