ARM API (REST) V1 to V3 migration guide - part 1

This is the first part of a guide providing information for migrating from the deprecated ARM V1 API to the current V3 API. All V1 endpoints have been marked as obsolete and will be removed in a future release. All new development should use V3 endpoints.

This is the first part of the migration guide. For the second part covering other endpoints, see ARM API (REST) V1 to V3 migration guide - part 2.

Breaking changes

Job ID type change

• V1: Job IDs are integers (int)
• V3: Job IDs are strings (string)

Impact: You must update your code to handle job IDs as strings instead of integers.

Deprecated V1 version:

1
2
3
// V1
                int jobId = 12345;
                var job = await archiveJobManager.ReadAsync(jobId);

V3 version:

1
2
3
// V3
                string jobId = "12345";  // Note: string type
                var job = await archiveJobManager.ReadAsync(jobId);

Response model changes

• V1: Create operations return int (job ID directly)
• V3: Create operations return response objects with JobID property

Deprecated V1 version:

1
2
// V1
                int jobId = await archiveJobManager.CreateAsync(request);

V3 version:

1
2
3
// V3
                CreateArchiveJobResponse response = await archiveJobManager.CreateAsync(request);
                string jobId = response.JobID;

NotificationOptions structure

• V1: had two separate booleans: NotifyJobCreator and NotifyJobExecutor.
• V3: merges these into a single boolean, NotifyJobRunner — when true, it notifies both the job creator and the person who ran the job.
• Also worth noting: AdditionalRecipients — when it's null or empty, no additional recipients are notified and instance-level recipients are not merged in.

Deprecated V1 version:

1
2
3
4
5
6
7
8
9
10
// V1
var request = new V1.ArchiveJobRequest
{
      // ...
      NotificationOptions = new V1.NotificationOptions
      {
          NotifyJobCreator = true,
          NotifyJobExecutor = true
      }
};

V3 version:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// V3
var request = new V3.ArchiveJobRequest
{
      // ...
      NotificationOptions = new V3.NotificationOptions
      {
          NotifyJobRunner = true,   // Replaces NotifyJobCreator + NotifyJobExecutor
          AdditionalRecipients = new List<string>
          {
              "reviewer1@example.com",
              "reviewer2@example.com"
          }
      }
};

MigratorOptions structure

• V1: Used typed classes for migrator-specific options
• V3: Uses generic Dictionary<string, object> for flexibility

1
2
3
4
5
6
7
8
9
// V3 - Generic dictionary approach
                var request = new ArchiveJobRequest
                {
                MigratorOptions = new Dictionary<string, object>
                {
                ["DocumentMigrator"] = new { /* migrator-specific settings */ },
                ["ProcessingMigrator"] = new { /* migrator-specific settings */ }
                }
                };

V1 MigratorOptions boolean flags to V3 ExcludedMigrators mapping

In V1, Archive jobs used MigratorOptions with boolean flags to control which migrators to include.

In V3, this is inverted - you specify which migrators to exclude using the ExcludedMigrators list.

Mapping table

Migration example

Deprecated V1 version:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// V1 - Boolean flags (Archive Job)
                var requestV1 = new V1.ArchiveJobRequest
                {
                WorkspaceID = 1234567,
                MigratorOptions = new V1.MigratorOptions
                {
                IncludeDatabaseBackup = true,   // Include
                IncludeDtSearch = false,        // Exclude
                IncludeConceptualAnalytics = false,  // Exclude
                IncludeStructuredAnalytics = true,   // Include
                IncludeDataGrid = true,         // Include
                IncludeQualityCheck = false     // Exclude
                }
                };

V3 version:

1
2
3
4
5
6
7
8
9
10
11
// V3 - ExcludedMigrators list (inverted logic)
                var requestV3 = new V3.ArchiveJobRequest
                {
                WorkspaceID = 1234567,
                ExcludedMigrators = new List<string>
                {
                "dtIndex",           // Was IncludeDtSearch = false
                "analytics-core"     // Was IncludeConceptualAnalytics = false
                // Database, StructuredAnalytics, and ADS are NOT in the list, so they will run
                }
                };

Restore job DestinationOptions properties removed

V1's DestinationOptions class (base class of RestoreDestinationOptions) included infrastructure configuration properties that are not available in V3:

• V1: DestinationOptions included DatabaseServerID, ResourcePoolID, CacheLocationID, FileRepositoryID, and UseDefaultWorkspaceConfiguration
• V3: RestoreDestinationOptions only includes MatterID

Impact: Infrastructure settings are now handled internally by the Relativity platform. You cannot specify database server, resource pool, cache location, or file repository for restored workspaces.

Deprecated V1 version:

1
2
3
4
5
6
7
8
9
10
11
12
13
// V1 - Explicit infrastructure configuration
                var request = new V1.RestoreJobRequest
                {
                DestinationOptions = new V1.RestoreDestinationOptions
                {
                MatterID = 1001234,
                DatabaseServerID = 1000,
                ResourcePoolID = 2000,
                CacheLocationID = 3000,
                FileRepositoryID = 4000,
                UseDefaultWorkspaceConfiguration = false
                }
                };

V3 version:

1
2
3
4
5
6
7
8
9
// V3 - Only MatterID is configurable
                var request = new V3.RestoreJobRequest
                {
                DestinationOptions = new V3.RestoreDestinationOptions
                {
                MatterID = 1001234
                // All infrastructure settings assigned automatically by platform
                }
                };

Complete list of V3 migrator names

V3 supports additional migrators beyond those available in V1's MigratorOptions. The complete list of migrator names that can be used in ExcludedMigrators is as follows.

Example of excluding multiple migrators:

1
2
3
4
5
6
7
8
9
10
11
12
var request = new V3.ArchiveJobRequest
                {
                WorkspaceID = 1234567,
                ArchiveDirectory = @"\\fileserver\archives\workspace",
                ExcludedMigrators = new List<string>
                {
                "dtIndex",              // Exclude dtSearch indexes
                "Invariant",           // Exclude Processing migrator
                "NonRepositoryFiles",   // Exclude non-repository files
                "Audit"                 // Exclude Audit migrator
                }
                };

Migrator-specific configuration options

In V1, migrator-specific settings were configured through typed option classes (FileOptions, ProcessingOptions, etc.).

In V3, all migrator-specific configuration uses the generic MigratorOptions dictionary.

V1 Archive job option classes changing to V3 MigratorOptions

V1 Structure (Archive jobs):

• MigratorOptions - Analytics and database settings
• FileOptions - Repository and linked file settings
• ProcessingOptions - Processing migrator settings
• ExtendedWorkspaceDataOptions - Extended workspace data settings

V3 Structure: All settings go into MigratorOptions dictionary.

Common V3 migrator keys

Available option keys:

Migration example: Archive job options

Deprecated V1 version:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
// V1 - Typed option classes
                var requestV1 = new V1.ArchiveJobRequest
                {
                WorkspaceID = 1234567,
                ArchiveDirectory = @"\\fileserver\archives\workspace",

                // Migrator include/exclude flags
                MigratorOptions = new V1.MigratorOptions
                {
                IncludeDatabaseBackup = true,
                IncludeDtSearch = false,
                IncludeDataGrid = true
                },

                // File-related settings
                FileOptions = new V1.FileOptions
                {
                IncludeRepositoryFiles = true,
                IncludeLinkedFiles = true,
                MissingFileBehavior = MissingFileBehavior.Skip
                },

                // Processing settings
                ProcessingOptions = new V1.ProcessingOptions
                {
                IncludeProcessing = true,
                IncludeProcessingFiles = true,
                ProcessingMissingFileBehavior = ProcessingMissingFileBehavior.Skip
                },

                // Extended workspace data
                ExtendedWorkspaceDataOptions = new V1.ExtendedWorkspaceDataOptions
                {
                IncludeExtendedWorkspaceData = true,
                ApplicationErrorExportBehavior = ApplicationErrorExportBehavior.Skip
                }
                };

V3 version:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// V3 - Generic dictionary with migrator-specific keys
                var requestV3 = new V3.ArchiveJobRequest
                {
                WorkspaceID = 1234567,
                ArchiveDirectory = @"\\fileserver\archives\workspace",

                // Include/exclude logic moved to ExcludedMigrators
                ExcludedMigrators = new List<string>
                {
                "dtIndex"  // Was IncludeDtSearch = false
                },

                // All migrator-specific configuration in MigratorOptions dictionary
                MigratorOptions = new Dictionary<string, object>
                {
                ["Invariant"] = new
                {
                IncludeProcessingFiles = false                
                }

                // Additional migrator-specific settings can be added here as needed
                // The exact structure depends on each migrator's requirements
                }
                };

Migration example: Restore job options

Deprecated V1 version:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
// V1 - Restore with typed options
                var requestV1 = new V1.RestoreJobRequest
                {
                ArchivePath = @"\\fileserver\archive.zip",
                DestinationOptions = new V1.RestoreDestinationOptions
                {
                MatterID = 1001234
                },

                // Migrator destination settings
                MigratorsDestinationOptions = new V1.MigratorsDestinationOptions
                {
                StructuredAnalyticsServerID = 1000,
                ConceptualAnalyticsServerID = 2000,
                DtSearchLocationID = 3000
                },

                // User and group mappings
                UserMapping = new V1.UserMapping
                {
                AutoMapUsers = true,
                UserMappings = new List<UserMappingItem>()
                },
                GroupMapping = new V1.GroupMapping
                {
                AutoMapGroups = false,
                GroupMappings = new List<GroupMappingItem>()
                }
                };

V3 version:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// V3 - Restore with generic dictionary
                var requestV3 = new V3.RestoreJobRequest
                {
                ArchivePath = @"\\fileserver\archive.zip",
                DestinationOptions = new V3.RestoreDestinationOptions
                {
                MatterID = 1001234
                },

                // All configuration moved to MigratorOptions
                MigratorOptions = new Dictionary<string, object>
                {
                ["Common"] = new
                {
                FileFirstFlow = new
                {
                IsFilesFirstFlow = true,
                AdditionalFilesDirectoryPath = @"\\fileserver\processing\additional"
                }                
                },
                ["UserGroup"] = new
                {
                UserMapping = new
                {
                UserMappings = new object[] { }
                },
                GroupMapping = new
                {
                AutoMapGroups = false,
                GroupMappings = new object[] { }
                }
                }
                }
                };

Important notes for MigratorOptions:

• Generic Structure—V3 uses Dictionary<string, object> allowing any JSON-serializable object as values.
• Migrator Names—keys are case-sensitive.
• Property Naming—use camelCase for property names within migrator configuration objects.
• Flexibility—V3 allows configuring migrators that did not exist in V1 option classes.
• Priority—If a migrator is both in ExcludedMigrators and has configuration in MigratorOptions, then ExcludedMigrators takes precedence and the migrator will be excluded regardless of options.

For migrator-specific schema details, see the OpenAPI specification at ARM REST API Reference V3.

Feature availability matrix

The Job Status endpoint is covered in part 2 of the migration guide. For more information, see ARM API (REST) V1 to V3 migration guide - part 2.

Migration paths

Archive jobs

Archive jobs have full migration support. All CRUD operations are available in V3.

Create Archive Job

V1 Endpoint: POST /relativity-arm/v1/archive-jobs

V3 Endpoint: POST /relativity-arm/v3/archive-jobs

Deprecated V1 version:

1
2
3
4
5
6
7
8
9
// V1
                var request = new V1.ArchiveJobRequest
                {
                WorkspaceID = 1234567,
                ArchiveDirectory = @"\\fileserver\archives\workspace",
                ScheduledStartTime = DateTime.Now.AddHours(1),
                // ... other properties
                };
                int jobId = await archiveJobManager.CreateAsync(request);

V3 version:

1
2
3
4
5
6
7
8
9
10
11
// V3
                var request = new V3.ArchiveJobRequest
                {
                WorkspaceID = 1234567,
                ArchiveDirectory = @"\\fileserver\archives\workspace",
                ScheduledStartTime = DateTime.Now.AddHours(1),
                MigratorOptions = new Dictionary<string, object>(),  // Generic instead of typed
                // ... other properties
                };
                CreateArchiveJobResponse response = await archiveJobManager.CreateAsync(request);
                string jobId = response.JobID;  // String instead of int

Read Archive Job

V1 Endpoint: GET /relativity-arm/v1/archive-jobs/{jobID}

V3 Endpoint: GET /relativity-arm/v3/archive-jobs/{jobID}

Deprecated V1 version:

1
2
3
// V1
                int jobId = 12345;
                ArchiveJobResponse job = await archiveJobManager.ReadAsync(jobId);

V3 version:

1
2
3
// V3
                string jobId = "12345";  // String type
                ArchiveJobResponse job = await archiveJobManager.ReadAsync(jobId);

Update Archive Job

V1 Endpoint: PUT /relativity-arm/v1/archive-jobs/{jobID}

V3 Endpoint: PUT /relativity-arm/v3/archive-jobs/{jobID}

Deprecated V1 version:

1
2
3
4
// V1
                int jobId = 12345;
                var request = new V1.ArchiveJobRequest { /* updated properties */ };
                await archiveJobManager.UpdateAsync(jobId, request);

V3 version:

1
2
3
4
// V3
                string jobId = "12345";  // String type
                var request = new V3.ArchiveJobRequest { /* updated properties */ };
                UpdateArchiveJobResponse response = await archiveJobManager.UpdateAsync(jobId, request);

Delete Archive Job

V1 Endpoint: DELETE /relativity-arm/v1/archive-jobs/{jobID}

V3 Endpoint: DELETE /relativity-arm/v3/archive-jobs/{jobID}

Deprecated V1 version:

1
2
3
// V1
                int jobId = 12345;
                await archiveJobManager.DeleteAsync(jobId);

V3 version:

1
2
3
// V3
                string jobId = "12345";  // String type
                await archiveJobManager.DeleteAsync(jobId);

Restore jobs

Restore jobs have full migration support, apart from most DestinationOptions properties being removed. All CRUD operations are available in V3.

DestinationOptions properties removed

This is a breaking change to restore requests.

The following properties from V1's DestinationOptions (base class of RestoreDestinationOptions) are not available in V3:

• DatabaseServerID - Database server for restored workspace
• ResourcePoolID - Resource pool for restored workspace
• CacheLocationID - Cache location for restored workspace
• FileRepositoryID - File repository for restored workspace
• UseDefaultWorkspaceConfiguration - Use default workspace configuration override

Impact: These infrastructure settings are now handled internally by the Relativity platform. V3's RestoreDestinationOptions only includes MatterID.

Migration: Remove these properties from your restore requests. The platform will automatically assign appropriate infrastructure resources based on system configuration.

Create Restore Job

V1 Endpoint: POST /relativity-arm/v1/restore-jobs

V3 Endpoint: POST /relativity-arm/v3/restore-jobs

Deprecated V1 version:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// V1
                var request = new V1.RestoreJobRequest
                {
                ArchivePath = @"\\fileserver\archives\workspace\archive.zip",
                ScheduledStartTime = DateTime.Now.AddHours(1),
                DestinationOptions = new V1.RestoreDestinationOptions
                {
                MatterID = 1001234,
                DatabaseServerID = 1000,      // Not available in V3
                ResourcePoolID = 2000,        // Not available in V3
                CacheLocationID = 3000,       // Not available in V3
                FileRepositoryID = 4000       // Not available in V3
                },
                // ... other properties
                };
                int jobId = await restoreJobManager.CreateAsync(request);

V3 version:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// V3
                var request = new V3.RestoreJobRequest
                {
                ArchivePath = @"\\fileserver\archives\workspace\archive.zip",
                ScheduledStartTime = DateTime.Now.AddHours(1),
                DestinationOptions = new V3.RestoreDestinationOptions
                {
                MatterID = 1001234
                // Infrastructure settings (DatabaseServerID, ResourcePoolID, etc.)
                // are now handled internally by the platform
                },
                MigratorOptions = new Dictionary<string, object>(),  // Generic instead of typed
                // ... other properties
                };
                CreateRestoreJobResponse response = await restoreJobManager.CreateAsync(request);
                string jobId = response.JobID;  // String instead of int

Read Restore Job

V1 Endpoint: GET /relativity-arm/v1/restore-jobs/{jobID}

V3 Endpoint: GET /relativity-arm/v3/restore-jobs/{jobID}

Deprecated V1 version:

1
2
3
// V1
                int jobId = 12345;
                RestoreJobResponse job = await restoreJobManager.ReadAsync(jobId);

V3 version:

1
2
3
// V3
                string jobId = "12345";  // String type
                RestoreJobResponse job = await restoreJobManager.ReadAsync(jobId);

Update Restore Job

V1 Endpoint: PUT /relativity-arm/v1/restore-jobs/{jobID}

V3 Endpoint: PUT /relativity-arm/v3/restore-jobs/{jobID}

Deprecated V1 version:

1
2
3
4
// V1
                int jobId = 12345;
                var request = new V1.RestoreJobRequest { /* updated properties */ };
                await restoreJobManager.UpdateAsync(jobId, request);

V3 version:

1
2
3
4
// V3
                string jobId = "12345";  // String type
                var request = new V3.RestoreJobRequest { /* updated properties */ };
                UpdateRestoreJobResponse response = await restoreJobManager.UpdateAsync(jobId, request);

Delete Restore Job

V1 Endpoint: DELETE /relativity-arm/v1/restore-jobs/{jobID}

V3 Endpoint: DELETE /relativity-arm/v3/restore-jobs/{jobID}

Deprecated V1 version:

1
2
3
// V1
                int jobId = 12345;
                await restoreJobManager.DeleteAsync(jobId);

V3 version:

1
2
3
// V3
                string jobId = "12345";  // String type
                await restoreJobManager.DeleteAsync(jobId);

Job actions

For Job Status, see ARM API (REST) V1 to V3 migration guide - part 2.

Run Job

V1 Endpoint: POST /relativity-arm/v1/jobs/{jobID}/run

V3 Endpoint: POST /relativity-arm/v3/jobs/{jobID}/run

Deprecated V1 version:

1
2
3
// V1
                int jobId = 12345;
                await jobActionManager.RunAsync(jobId);

V3 version:

1
2
3
// V3
                string jobId = "12345";  // String type
                RunJobResponse response = await jobActionManager.RunAsync(jobId, new RunJobRequest());

V3 requires a RunJobRequest parameter (currently an empty object, but required for the method signature).

Cancel Job

V1 Endpoint: POST /relativity-arm/v1/jobs/{jobID}/cancel

V3 Endpoint: POST /relativity-arm/v3/jobs/{jobID}/cancel

Deprecated V1 version:

1
2
3
// V1
                int jobId = 12345;
                await jobActionManager.CancelAsync(jobId);

V3 version:

1
2
3
// V3
                string jobId = "12345";  // String type
                CancelJobResponse response = await jobActionManager.CancelAsync(jobId, new CancelJobRequest());

V3 requires a CancelJobRequest parameter (currently an empty object, but required for the method signature).

Pause Job - not available in V3

V1 Endpoint: POST /relativity-arm/v1/jobs/{jobID}/pause

V3 Endpoint: None

Migration: There is no pause functionality in V3. The only job control actions available are Run and Cancel.

Terminate Job - not available in V3

V1 Endpoint: DELETE /relativity-arm/v1/jobs/{jobID}/terminate

V3 Endpoint: None

Migration: Use the Cancel action instead. Note that Cancel provides graceful shutdown while Terminate was immediate.

Deprecated V1 version:

1
2
// V1 - Terminate (immediate)
                await jobActionManager.TerminateJobAsync(jobId);

V3 version:

1
2
// V3 - Use Cancel instead (graceful)
                CancelJobResponse response = await jobActionManager.CancelAsync(jobId);

Features without a migration path

The following V1 features are not available in V3. There is no public API migration path for these features:

Move Jobs - not available in V3

• POST /relativity-arm/v1/move-jobs
• GET /relativity-arm/v1/move-jobs/{jobID}
• PUT /relativity-arm/v1/move-jobs/{jobID}
• DELETE /relativity-arm/v1/move-jobs/{jobID}

Impact: If your integration relies on Move jobs, you will need to find an alternative solution as this functionality is not exposed in the V3 public API.

Database Restore Jobs - not available in V3

• POST /relativity-arm/v1/database-restore-jobs
• GET /relativity-arm/v1/database-restore-jobs/{jobID}
• PUT /relativity-arm/v1/database-restore-jobs/{jobID}
• DELETE /relativity-arm/v1/database-restore-jobs/{jobID}

Impact: Database-only restore operations are not available through the V3 public API.

Download Logs - not available in V3

• GET /relativity-arm/v1/jobs/{jobID}/logs

Impact: Job execution logs cannot be downloaded through the V3 public API.

Quality Check Results - not available in V3

• GET /relativity-arm/v1/jobs/{jobExecutionID}/qualityCheckResult

Impact: Quality check results are not available through the V3 public API.

Archive Information - not available in V3

• POST /relativity-arm/v1/archive-information
• GET /relativity-arm/v1/archive-information/additional-files-directories/{workspaceId}

Impact: Archive metadata inspection is not available through the V3 public API.

Task Retry - not available in V3

• POST /relativity-arm/v1/tasks/{taskId}/retry

Impact: Individual task retry is not available through the V3 public API.

Part 1 migration checklist

Check that you have completed the following before moving on to the second part of the migration guide:

1. Update job ID handling
   • Change job ID variables from int to string.
   • Update database schemas storing job IDs.
   • Update any job ID parsing/conversion logic.
2. Update API calls
   • Replace V1 endpoint URLs with V3 equivalents.
   • Update service interface references (V1 to V3 namespaces).
   • Handle new response models from Create operations.
3. Update request models
   • Convert typed MigratorOptions to Dictionary<string, object>.
   • Review and update all request property mappings.
4. Handle removed features
   • Identify dependencies on Move Jobs.
   • Identify dependencies on Database Restore Jobs.
   • Identify dependencies on Pause/Terminate actions.
   • Identify dependencies on Logs or Quality Check endpoints.
   • Plan alternative approaches for unavailable features.
5. Testing
   • Test all Archive Job operations (Create, Read, Update, Delete).
   • Test all Restore Job operations (Create, Read, Update, Delete).
   • Test Run and Cancel job actions.
   • Verify error handling for all operations.

If these are complete, move to ARM API (REST) V1 to V3 migration guide - part 2.

Additional resources

• OpenAPI Specification: See ARM REST API Reference V3 for complete API documentation.
• V3 Interface Definitions: Located in Relativity.ARM.Services.Interfaces.V3 namespace.
• Model Definitions: Located in Relativity.ARM.Services.Interfaces.V3.Models namespace.

Getting help

If you encounter issues during migration or require functionality that is not available in V3:

1. Review both migration guides:
   1. ARM API (REST) V1 to V3 migration guide - part 1
   2. ARM API (REST) V1 to V3 migration guide - part 2
2. Check ARM REST API Reference V3 for detailed endpoint and model documentation.
3. Contact Relativity Support for assistance. Select "Developer Services" as the topic of the ticket.