Get started with the ARM API

The ARM API provides a REST service that supports multiple operations required to archive, restore, and move Relativity workspace data. You can also use to view information on currently running ARM jobs or to list available workspaces or ARM archives. For example, you could use this service to populate a custom dialog in your application with scheduled ARM archive jobs.

For more information on the ARM application, see ARM Overviewon the RelativityOne Documentation site.

This page contains the following information:

See the following related pages:

Retrieve a list of available ARM archives

You can use the GetAvailableArchives endpoint to retrieve a list of available ARM archives using the POST method.

Send a POST request to this URL for the service:

<host>/Relativity.REST/api/Relativity.ARM/Configuration/AvailableArchives

The request does not require any parameters.

The response returns a status code of 200 when the service successfully retrieves a list of available ARM archives. The response is a list of the available ARM archive names.

Retrieve a list of available ARM archive directories

You can use the GetAvailableArchiveDirectories endpoint to retrieve a list of available ARM archive directories using the POST method.

Send a POST request to this URL for the service:

<host>/Relativity.REST/api/Relativity.ARM/Configuration/AvailableDirectories

The request does not require any parameters.

The response returns a status code of 200 when the service successfully retrieves a list of configured ARM archive locations. The response is a list of the configured ARM archive locations.

Get configuration data

You can use the GetConfigurationData endpoint to retrieve ARM configuration data using the POST method.

Send a POST request to this URL for the service:

<host>/Relativity.REST/api/Relativity.ARM/Configuration/GetConfigurationData

The request does not require any parameters.

The response returns a status code of 200 when the service successfully retrieves configuration data. The response is a list of the available ARM configuration data.

Set configuration data

You can use the SetConfigurationData endpoint to set configuration data for ARM using the POST method.

Send a POST request to this URL for the service:

<host>/Relativity.REST/api/Relativity.ARM/Configuration/SetConfigurationData

The body of the request requires the following parameters:

The response returns a status code of 200 when the service successfully sets ARM configuration data.

In case if someone tries to set ArchiveLocationType different than 1, exception will be returned:

{
    "ErrorType": "kCura.ARM.API.Errors.ServiceValidationException",
    "Message": "An ArchiveLocation with type ArmArchive (1) must be supplied\r\nThe location must be a valid UNC path\r\nThe RelativityWebApiUrl supplied could not be verified",
    "ErrorDetails": {
        "Errors": [
            {
                "Name": "ArmArchiveLocations",
                "AttemptedValue": [
                    {
                        "ArchiveLocationType": "DbmtArchive",
                        "Location": "\\\\p-dv-vm-cmkf55u.kcura.corp\\fileshare\\"
                    }
                ],
                "Message": "An ArchiveLocation with type ArmArchive (1) must be supplied",
                "Code": "predicate_error"
            },
            {
                "Name": "ArmArchiveLocations[0]",
                "AttemptedValue": {
                    "ArchiveLocationType": "DbmtArchive",
                    "Location": "\\\\p-dv-vm-cmkf55u.kcura.corp\\fileshare\\"
                },
                "Message": "The location must be a valid UNC path",
                "Code": "predicate_error"
            },
            {
                "Name": "RelativityWebApiUrl",
                "AttemptedValue": "https://P-DV-VM-CMKF55U.kcura.corp/RelativityWebAPI/",
                "Message": "The RelativityWebApiUrl supplied could not be verified",
                "Code": "predicate_error"
            }
        ],
        "ErrorDetails": null,
        "ClassName": "kCura.ARM.API.Errors.ServiceValidationException",
        "Message": "An ArchiveLocation with type ArmArchive (1) must be supplied\r\nThe location must be a valid UNC path\r\nThe RelativityWebApiUrl supplied could not be verified",
        "Data": null,
        "InnerException": null,
        "HelpURL": null,
        "StackTraceString": "   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Runtime.CompilerServices.TaskAwaiter.GetResult()\r\n   at Relativity.Kepler.Dynamic.Xapi.V2._kCura.ARM.Services.Interfaces.ArmConfigurationManagerController.<SetConfigurationDataAsync>d__20.MoveNext() in kCura.ARM.Services.Interfaces.IArmConfigurationManager_ServiceDispatch.cs:line 248\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Threading.Tasks.TaskHelpersExtensions.<CastToObject>d__3`1.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Controllers.ApiControllerActionInvoker.<InvokeActionAsyncCore>d__0.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Filters.ActionFilterAttribute.<CallOnActionExecutedAsync>d__5.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Web.Http.Filters.ActionFilterAttribute.<CallOnActionExecutedAsync>d__5.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Filters.ActionFilterAttribute.<ExecuteActionFilterAsyncCore>d__0.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Controllers.ActionFilterResult.<ExecuteAsync>d__2.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Filters.AuthorizationFilterAttribute.<ExecuteAuthorizationFilterAsyncCore>d__2.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Controllers.ExceptionFilterResult.<ExecuteAsync>d__0.MoveNext()",
        "RemoteStackTraceString": null,
        "RemoteStackIndex": 0,
        "ExceptionMethod": "8\nThrow\nmscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\nSystem.Runtime.ExceptionServices.ExceptionDispatchInfo\nVoid Throw()",
        "HResult": -2146233088,
        "Source": "mscorlib",
        "WatsonBuckets": null
    },
    "Errors": [
        {
            "Name": "ArmArchiveLocations",
            "AttemptedValue": [
                {
                    "ArchiveLocationType": "DbmtArchive",
                    "Location": "\\\\p-dv-vm-cmkf55u.kcura.corp\\fileshare\\"
                }
            ],
            "Message": "An ArchiveLocation with type ArmArchive (1) must be supplied",
            "Code": "predicate_error"
        },
        {
            "Name": "ArmArchiveLocations[0]",
            "AttemptedValue": {
                "ArchiveLocationType": "DbmtArchive",
                "Location": "\\\\p-dv-vm-cmkf55u.kcura.corp\\fileshare\\"
            },
            "Message": "The location must be a valid UNC path",
            "Code": "predicate_error"
        },
        {
            "Name": "RelativityWebApiUrl",
            "AttemptedValue": "https://P-DV-VM-CMKF55U.kcura.corp/RelativityWebAPI/",
            "Message": "The RelativityWebApiUrl supplied could not be verified",
            "Code": "predicate_error"
        }
    ]
}

In case of invalid UNC path will return different error:

{
    "ErrorType": "kCura.ARM.API.Errors.ServiceValidationException",
    "Message": "The location must be a valid UNC path\r\nThe RelativityWebApiUrl supplied could not be verified",
    "ErrorDetails": {
        "Errors": [
            {
                "Name": "ArmArchiveLocations[0]",
                "AttemptedValue": {
                    "ArchiveLocationType": "ArmArchive",
                    "Location": "\\\\//p-dv-vm-cmkf55u.kcura.corp\\fileshare\\"
                },
                "Message": "The location must be a valid UNC path",
                "Code": "predicate_error"
            },
            {
                "Name": "RelativityWebApiUrl",
                "AttemptedValue": "https://P-DV-VM-CMKF55U.kcura.corp/RelativityWebAPI/",
                "Message": "The RelativityWebApiUrl supplied could not be verified",
                "Code": "predicate_error"
            }
        ],
        "ErrorDetails": null,
        "ClassName": "kCura.ARM.API.Errors.ServiceValidationException",
        "Message": "The location must be a valid UNC path\r\nThe RelativityWebApiUrl supplied could not be verified",
        "Data": null,
        "InnerException": null,
        "HelpURL": null,
        "StackTraceString": "   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Runtime.CompilerServices.TaskAwaiter.GetResult()\r\n   at Relativity.Kepler.Dynamic.Xapi.V2._kCura.ARM.Services.Interfaces.ArmConfigurationManagerController.<SetConfigurationDataAsync>d__20.MoveNext() in kCura.ARM.Services.Interfaces.IArmConfigurationManager_ServiceDispatch.cs:line 248\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Threading.Tasks.TaskHelpersExtensions.<CastToObject>d__3`1.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Controllers.ApiControllerActionInvoker.<InvokeActionAsyncCore>d__0.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Filters.ActionFilterAttribute.<CallOnActionExecutedAsync>d__5.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Web.Http.Filters.ActionFilterAttribute.<CallOnActionExecutedAsync>d__5.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Filters.ActionFilterAttribute.<ExecuteActionFilterAsyncCore>d__0.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Controllers.ActionFilterResult.<ExecuteAsync>d__2.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Filters.AuthorizationFilterAttribute.<ExecuteAuthorizationFilterAsyncCore>d__2.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Controllers.ExceptionFilterResult.<ExecuteAsync>d__0.MoveNext()",
        "RemoteStackTraceString": null,
        "RemoteStackIndex": 0,
        "ExceptionMethod": "8\nThrow\nmscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\nSystem.Runtime.ExceptionServices.ExceptionDispatchInfo\nVoid Throw()",
        "HResult": -2146233088,
        "Source": "mscorlib",
        "WatsonBuckets": null
    },
    "Errors": [
        {
            "Name": "ArmArchiveLocations[0]",
            "AttemptedValue": {
                "ArchiveLocationType": "ArmArchive",
                "Location": "\\\\//p-dv-vm-cmkf55u.kcura.corp\\fileshare\\"
            },
            "Message": "The location must be a valid UNC path",
            "Code": "predicate_error"
        },
        {
            "Name": "RelativityWebApiUrl",
            "AttemptedValue": "https://P-DV-VM-CMKF55U.kcura.corp/RelativityWebAPI/",
            "Message": "The RelativityWebApiUrl supplied could not be verified",
            "Code": "predicate_error"
        }
    ]
}

In case of invalid e-mail path will return different error:

{
    "ErrorType": "kCura.ARM.API.Errors.ServiceValidationException",
    "Message": "Email is invalid",
    "ErrorDetails": {
        "Errors": [
            {
                "Name": "EmailNotificationSettings[0]",
                "AttemptedValue": {
                    "Email": "relativity.adminkcura.com",
                    "IsSentOnStart": true,
                    "IsSentOnPause": true,
                    "IsSentOnCancel": true,
                    "IsSentOnError": true,
                    "IsSentOnSuccess": true,
                    "IsSentOnWorkspaceVisible": false,
                    "JobId": 0
                },
                "Message": "Email is invalid",
                "Code": "predicate_error"
            }
        ],
        "ErrorDetails": null,
        "ClassName": "kCura.ARM.API.Errors.ServiceValidationException",
        "Message": "Email is invalid",
        "Data": null,
        "InnerException": null,
        "HelpURL": null,
        "StackTraceString": "   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Runtime.CompilerServices.TaskAwaiter.GetResult()\r\n   at Relativity.Kepler.Dynamic.Xapi.V2._kCura.ARM.Services.Interfaces.ArmConfigurationManagerController.<SetConfigurationDataAsync>d__20.MoveNext() in kCura.ARM.Services.Interfaces.IArmConfigurationManager_ServiceDispatch.cs:line 248\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Threading.Tasks.TaskHelpersExtensions.<CastToObject>d__3`1.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Controllers.ApiControllerActionInvoker.<InvokeActionAsyncCore>d__0.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Filters.ActionFilterAttribute.<CallOnActionExecutedAsync>d__5.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Web.Http.Filters.ActionFilterAttribute.<CallOnActionExecutedAsync>d__5.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Filters.ActionFilterAttribute.<ExecuteActionFilterAsyncCore>d__0.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Controllers.ActionFilterResult.<ExecuteAsync>d__2.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Filters.AuthorizationFilterAttribute.<ExecuteAuthorizationFilterAsyncCore>d__2.MoveNext()\r\n--- End of stack trace from previous location where exception was thrown ---\r\n   at System.Runtime.ExceptionServices.ExceptionDispatchInfo.Throw()\r\n   at System.Runtime.CompilerServices.TaskAwaiter.HandleNonSuccessAndDebuggerNotification(Task task)\r\n   at System.Web.Http.Controllers.ExceptionFilterResult.<ExecuteAsync>d__0.MoveNext()",
        "RemoteStackTraceString": null,
        "RemoteStackIndex": 0,
        "ExceptionMethod": "8\nThrow\nmscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089\nSystem.Runtime.ExceptionServices.ExceptionDispatchInfo\nVoid Throw()",
        "HResult": -2146233088,
        "Source": "mscorlib",
        "WatsonBuckets": null
    },
    "Errors": [
        {
            "Name": "EmailNotificationSettings[0]",
            "AttemptedValue": {
                "Email": "relativity.adminkcura.com",
                "IsSentOnStart": true,
                "IsSentOnPause": true,
                "IsSentOnCancel": true,
                "IsSentOnError": true,
                "IsSentOnSuccess": true,
                "IsSentOnWorkspaceVisible": false,
                "JobId": 0
            },
            "Message": "Email is invalid",
            "Code": "predicate_error"
        }
    ]
}

Restore jobs

You can use the ARM API to create, modify, delete, and retrieve details for ARM restore jobs.

Create a Restore job

You can use the CreateJob endpoint to create and validate a Restore job with the specification that is entered.

To create a Restore job, you will use the POST method.

Send a request to this URL for the Restore service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Restore/Create

The body of the request requires the following parameters that define the ARM restore job specification to be added to the job list:

The following parameters further define options for the restore job:

{
    "Contract": {
    "MatterId": 1000002,
    "ArchivePath": "\\\\relativityfileshare\\ARMArchives\\123",
    "JobPriority": "Low",
    "ResourcePoolId": 1015040,
    "DatabaseServerId": 1015096,
    "FileRepositoryId": 1014887,
    "CacheLocationId": 1015534,
    "StructuredAnalyticsServerId": 1016368,
    "AnalyticsIndexServerId": 101639,
    "AutoMapUsers": true,
    "GroupIdMappings": {
        1015045 : 1015048,
        1015032 : 1015036}
    }
}

The response returns a status code of 200 when the service successfully creates a Restore job and also returns the following additional fields for the new RestoreJob object:

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Retrieve details of a Restore job

You can use the ReadJob endpoint to retrieve the details of an Restore job using the POST method.

Send a request to this URL for the Restore service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Restore/Read

The request must have the following parameters:

{
    "JobId": 123
}

The response returns a status code of 200 when the service successfully retrieves a restore job and along with all properties for the RestoreJob object. See Create a Restore job for the property definitions for the RestoreJob object.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Update a Restore job

You can use the UpdateJob endpoint to update an existing Restore job using the POST method.

Send a request to this URL for the Restore service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Restore/Update

The request must have the following parameters:

{
    "JobId": 123,
    "Contract": {
    "MatterId": 1000002,
    "ArchivePath": "\\relativityfileshare\ARMArchives\123",
    "JobPriority": "Low",
    "ResourcePoolId": 1015040,
    "DatabaseServerId": 1015096,
    "FileRepositoryId": 1014887,
    "CacheLocationId": 1015534,
    "StructuredAnalyticsServerId": 1016368,
    "ConceptualAnalyticsServerId": 101639,      
    "AutoMapUsers": true,
    "UserIdMappings": {
        2215045 : 2215048,
        2215032 : 2215036},
    "GroupIdMappings": {
        1015045 : 1015048,
        1015032 : 1015036}
    }
}

The response returns a status code of 200 when the service successfully retrieves a restore job and along with all properties for the RestoreJob object. See Create an Archive job for the property definitions for the RestoreJob object.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Archive jobs

You can use the ARM API endpoint to create, modify, delete, and retrieve details for ARM archive jobs.

Create an Archive job

You can use the CreateJob endpoint to creates and validate an Archive job with the specification that is entered.

To create an Archive job, you will use the POST method.

Send a request to this URL for the Archive service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Archive/Create

The body of the request requires the following parameters that define the ARM archive job specification to be added to the job list:

The ArchiveJob object also has the following parameters that set options for the archive job:

{
    "Contract": {
        "WorkspaceId": 123456,
        "JobPriority": "Low",
        "ArchiveDirectory": ".\",
        "IncludeDatabaseBackup": false,
        "IncludeRepositoryFiles": false,
        "IncludeLinkedFiles": false,
        "MissingFileBehavior": "SkipFile"
        "RecurringSchedule": "0 0 1 * * *", // Recurs on the first minute of the first hour of the first day of every month
        "RecurrenceEndTime": "2018-01-00T12:00:00",
        "HistoryLength": 3
    }
}    

The response returns a status code of 200 when the service successfully creates an archive job and also returns the object fields specified with the following additional fields for the created ArchiveJob object:

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Retrieve details of an Archive job

You can use the ReadJob endpoint to retrieve the details of an Archive job using the POST method.

Send a request to this URL for the Archive service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Archive/Read

The request must have the following parameters:

{
    "JobId": 123
}

The response returns a status code of 200 when the service successfully retrieves an archive job and along with all properties for the ArchiveJob object. See Create an Archive job for the property definitions for the ArchiveJob object.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Update an Archive job

You can use the UpdateJob endpoint to update an existing Archive job using the POST method.

Send a request to this URL for the Archive service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Archive/Update

The request must have the following parameters:

{
    "JobId": 123,
    "Contract": {
        "WorkspaceId": 123456,
        "JobPriority": "Low",
        "ArchiveDirectory": ".\",
        "IncludeDatabaseBackup": false,
        "IncludeRepositoryFiles": false,
        "IncludeLinkedFiles": false,
        "MissingFileBehavior": "SkipFile"
    }
}

The response returns a status code of 200 when the service successfully retrieves an archive job and along with all properties for the ArchiveJob object. See Create an Archive job for the property definitions for the ArchiveJob object.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Move jobs

You can use the ARM API to create, modify, delete, and retrieve details for ARM Move jobs.

Create a Move job

You can use the CreateJob endpoint to create and validate a Move job with the specification that is entered.

To create a Move job, you will use the POST method.

Send a request to this URL for the Move service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Move/Create

The body of the request requires the following parameters that define the ARM move job specification to be added to the job list:

The MoveJob object also has the following additional parameters that set customized options for the move job:

{
        "Contract": {
        "SourceWorkspaceId": 123456,
        "JobPriority": "Low",
        "DestinationResourcePoolId": 1015040,
        "DestinationCacheLocationId": 1015534,
        "DestinationDatabaseServerId": 1015096,
        "LinkToExistingDocuments": false,
        "IncludeDatabaseBackup": true,
        "MissingFileBehavior": "SkipFile"
    }
}

The response returns a status code of 200 when the service successfully creates a Move job and also returns the following additional fields for the MoveJob object:

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Retrieve details of a Move job

You can use the ReadJob endpoint to retrieve the details of a Move job using the POST method.

Send a request to this URL for the Move service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Move/Read

The request must have the following parameters:

{
    "JobId": 123
}

The response returns a status code of 200 when the service successfully retrieves a Move job and along with all properties for the MoveJob object. See Create an Archive job for the property definitions for the MoveJob object.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Update a Move job

You can use the UpdateJob endpoint to update an existing Move job using the POST method.

Send a request to this URL for the Move service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Move/Update

The request must have the following parameters:

{
    "JobId": 123,
    "Contract": {
        "SourceWorkspaceId": 123456,
        "JobPriority": "Low",
        "DestinationResourcePoolId": 1015040,
        "DestinationCacheLocationId": 1015534,
        "DestinationDatabaseServerId": 1015096,
        "LinkToExistingDocuments": false,
        "MissingFileBehavior": "SkipFile"
    }
}

The response returns a status code of 200 when the service successfully updates a Move job along with all properties for the MoveJob object. See Create an Archive job for the property definitions for the MoveJob object.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Retrieve job information

List ARM jobs

You can use the ListJobs endpoint to list existing ARM jobs using the POST method.

Send a request to this URL for the service:

  <host>/Relativity.REST/api/Relativity.ARM/Jobs/Status/List

The request must have the following parameters:

{
   "ListJobContract":
   {
      "JobRecurrence": "AllTypes",  // Allowed types: "AllTypes", "Transient" (Single Execution), "Recurring"
      "JobCompletionState": "AllStates"  // Allowed states: "AllStates", "CompleteJobs", "IncompleteJobs"
   }
}

The response returns a status code of 200 when the service successfully retrieves details for matching ARM jobs and displays each job in a list.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Retrieve job information

You can use the ReadJobStatus endpoint to read the progression status of an existing ARM job using the POST method.

Send a request to this URL for the Status service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Status/ReadJob

The request must have the following parameters:

{
    "JobId": 123
    "JobExecutionId": 1 // optional parameter
}

The response returns a status code of 200 when the service successfully retrieves progress details for the requested ARM job along with the following JobStatus properties for the requested job.

Note: The JSON response includes only fields containing values. The response doesn't include any fields with nullable objects.

Perform a job action

Execute an existing ARM job

You can use the RunJob endpoint to execute an existing ARM job using the POST method.

Send a request to this URL for the Run service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Action/Run

The request must have the following parameters:

{
    "JobId": 123
}

The response returns a status code of 200 when the service successfully executes an ARM job. There is no response body.

Cancel an ARM job

You can use the CancelJob endpoint to cancel an ARM job using the POST method.

Send a request to this URL for the Cancel service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Action/Cancel

The request must have the following parameters:

{
    "JobId": 123
}

The response returns a status code of 200 when the service successfully cancels an ARM job. There is no response body.

Pause an ARM job

You can use the PauseJob endpoint to pause an ARM job using the POST method.

Send a request to this URL for the Pause service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Action/Pause

The request must have the following parameters:

{
    "JobId": 123
}

The response returns a status code of 200 when the service successfully pauses an ARM job. There is no response body.

Delete an ARM job

You can use the DeleteJob endpoint to delete an ARM job using the POST method.

Send a request to this URL for the Delete service:

<host>/Relativity.REST/api/Relativity.ARM/Jobs/Action/Delete

The request must have the following parameters:

{
    "JobId": 123
}

The response returns a status code of 200 when the service successfully cancels an ARM job. There is no response body.

Troubleshooting errors

The ARM API validates requests if they can be executed. If validation fails, a ServiceValidationException exception will be returned.

For example, if a user attempts to delete a job with a JobId that does not exist, the following response is returned (unrelated fields omitted for clarity):

{
	"ErrorType": "kCura.ARM.API.Errors.ServiceValidationException",
	"Message": "Job Not Found.\r\n",
	"ErrorDetails": {
		"Errors": [{
			"Name": "IJobRepository",
			"AttemptedValue": 626,
			"Message": "Job Not Found.",
			"Code": "Job_NotFound"
		}],
		"ErrorDetails": null,
		"ClassName": "kCura.ARM.API.Errors.ServiceValidationException",
		"Message": "Job Not Found.\r\n"
	},
	"Errors": [{
		"Name": "IJobRepository",
		"AttemptedValue": 626,
		"Message": "Job Not Found.",
		"Code": "Job_NotFound"
	}]
}

Please review the “Message” and “Errors” collection for details. In this case, the user passed in the wrong JobId (i.e., AttemptedValue).

Each error is an Errors object with the following properties:

Community Updates

Aero Developer FAQ Evolving the Platform Most recent release notes
Learn more Learn more Learn more

Additional Resources

   
Access Third-Party Tools with GitHub     Create .NET Apps Faster with NuGet
Visit github     visit nuget