Import API migration

Beginning with the Relativity Goatsbeard release, you must migrate any existing Import API applications to the new NuGet package called Relativity.DataExchange.Client.SDK. The Relativity SDK published in the Community will no longer include the Import API. In addition, the Relativity.Import.Client NuGet package has been deprecated.

The following information outlines how to migrate an existing Import API application to the new NuGet package.

Note: You must migrate to the Relativity.DataExchange.Client.SDK package to ensure that your custom applications continue to function properly. If you don't migrate your applications to the new package, they will fail.

See this related page:

NuGet package overview

Review the following information about the Relativity.DataExchange.Client.SDK package published to NuGet Gallery:

  • Package ID - Relativity.DataExchange.Client.SDK
  • Package versions - 1.13.28
  • Assemblies .NET - Relativity.DataExchange.Client.SDK.dll
  • Package dependencies - see the following table:
    PackageMinimum version
    Relativity.OutsideIn2021.4.0
    Relativity.Logging

    2019.5.1

    Relativity.ObjectManager12.1.171.20
    Relativity.Telemetry.Client3000.0.1
    Relativity.Transfer.Client7.4.10

Note: After migrating to the new NuGet package and successfully compiling your solution, you need to upload your custom Import API application to Relativity. You also need to deploy certain package dependencies. For detailed information about this process, see ADS deployment considerations.

Migrate to the NuGet package

Before you install the new Relativity.DataExchange.Client.SDK to an existing Visual Studio project, complete the following steps to remove legacy references to the Import API added from the Relativity SDK MSI file, or the Relativity.Import.Client NuGet package.

Step 1: Remove legacy references

To upgrade your Import API applications, you need to remove the legacy Import API .NET assemblies added from the Relativity SDK MSI file or references to the Relativity.Import.Client NuGet package.

Depending on how you added your Import API .NET assemblies, perform one of the following tasks:

Note: In your existing Visual Studio projects, remove only the .NET assemblies or uninstall only the package listed in the following sections.

Uninstall Relativity.Import.Client Nuget package

As of the Goatsbeard release, the Relativity.Import.Client Nuget package has been deprecated. If you added this package to your Visual Studio project, run the following command from the Package Manager Console to uninstall it:

Copy 
Uninstall-Package Relativity.Import.Client -RemoveDependencies
Dependencies error message

If the Package Manager Console displays a message indicating that it can't uninstall the Relativity.Import.Client Nuget package due to other dependencies, run the following command from the Package Manager Console:

Copy 
Uninstall-Package Relativity.Import.Client -RemoveDependencies -Force

Remove .NET assemblies and native binaries from the Relativity SDK MSI

If you added Import API from the Relativity SDK MSI file, remove the following files from all C# or VB.NET projects:

Relativity SDK DLLs
  • kCura.dll
  • kCura.ImageValidator.dll
  • kCura.OI.FileID.dll
  • kCura.Relativity.DataReaderClient.dll
  • kCura.Relativity.ImportAPI.dll
  • kCura.Relativity.ImportAPI.Extension.dll
  • kCura.Windows.Forms.dll
  • kCura.Windows.Process.dll
  • kCura.WinEDDS.Core.dll
  • kCura.WinEDDS.dll
  • kCura.WinEDDS.ImportExtension.dll
  • kCura.WinEDDS.TApi.dll
  • Relativity.dll
Relativity.Transfer.Client DLLs
  • Relativity.Transfer.Client.Aspera.dll
  • Relativity.Transfer.Client.Core.dll
  • Relativity.Transfer.Client.dll
  • Relativity.Transfer.Client.FileShare.dll
  • Relativity.Transfer.Client.Http.dll
  • Renci.SshNet.dll
  • Polly.dll
  • FaspManager.dll
Outside In DLLs
  • oi.dll
  • oi\cmmap000.bin
  • oi\oilink.exe
  • oi\oilink.jar
  • oi\sccca-R1.dll
  • oi\sccch-R1.dll
  • oi\sccda-R1.dll
  • oi\sccex-R1.dll
  • oi\sccfa-R1.dll
  • oi\sccfi-R1.dll
  • oi\sccfmt-R1.dll
  • oi\sccfnt-R1.dll
  • oi\sccfut-R1.dll
  • oi\sccind-R1.dll
  • oi\scclo-R1.dll
  • oi\sccut-R1.dll
  • oi\wvcore-R1.dll

Step 2: Add a reference to the new NuGet package

To install the new Relativity.DataExchange.Client.SDK package, run the following command from the Package Manager Console:

Copy 
Install-Package Relativity.DataExchange.Client.SDK

Step 3: Build the solution

Build the solution and verify that all projects compiled successfully.

If your build fails, complete the steps in the following sections as necessary:

Note: After migrating to the new NuGet package and successfully compiling your solution, you need to upload your custom Import API application to Relativity. You also need to deploy certain package dependencies. For detailed information about this process, see ADS deployment considerations.

Identify files with the File Identification API

Use the File Identification API in Relativity.DataExchange.Io API namespace to identify file types. See the following code sample:

Copy 
IFileTypeInfo fileTypeInfo1 = Relativity.DataExchange.Io.FileTypeIdentifierService.Instance.Identify()(@"C:\VOL00001\NATIVES\NATIVE00001\AZIPPER_0008560.xls");
int fileId = fileTypeInfo1.Id;
string fileType = fileTypeInfo1.Description;

Update any legacy code that uses the kCura.OI.FileID assembly to identify files types. The following code sample illustrates legacy code that must be updated to use the new File Identification API:

Copy 
FileIDData fileIdData1 = kCura.OI.FileID.Manager.Instance.GetFileIDDataByFilePath(@"C:\VOL00001\NATIVES\NATIVE00001\AZIPPER_0008560.xls");
int fileId = fileIdData1.FileID;
string fileType = fileIdData1.FileType;

Add a reference to Relativity.Other package

If your Import API application uses objects from the kCura or Relativity .NET assemblies, add a reference to the Relativity.Other package to continue using these components.

Catch the RelativityNotSupportedException

Beginning with the Goatsbeard release, the RelativityNotSupportedException is thrown when the API isn't compatible with the import or export API services provided by Relativity. See the following code sample:

Copy 
try {
 ImportAPI iapi = new ImportAPI(relativityUserName, relativityPassword, relativityWebAPIUrl);
} catch (RelativityNotSupportedException) {
 // This SDK version isn't supported by the import/export API services provided by Relativity!
}

Update any legacy code that throws the RelativityVersionMismatchException from the ImportAPI class constructor when the .NET assembly for the Import API didn’t match the Relativity version. The following code sample illustrates legacy code that must be updated with the new exception:

Copy 
try {
 ImportAPI iapi = new ImportAPI(relativityUserName, relativityPassword, relativityWebAPIUrl);
} catch (RelativityVersionMismatchException) {
 // This API assembly version doesn't match the Relativity assembly version!
}

Reference Relativity.DataExchange section in app.config file

As part of the Goatsbeard release, the app.config file now includes a single section called Relativity.DataExchange. This section contains all the configuration setting available for use with the Import API. If your Import API projects currently reference the config.app file, we recommend that you migrate them to the newly formatted version of it.

Note: The Goatsbeard release will continue to support the older version of the app.config file with the kCura.WinEDDS, kCura.Utility, and other sections, but you should plan to migrate to the newly formatted version of the file containing the Relativity.DataExchange section.

For more information, see the following pages;

ADS deployment considerations

After completing the migration process, you need to add your updated application to Relativity. For information on this process, see Deploy Import API applications.