Relativity Transfer Service

Transfer Service API enables Relativity users to integrate with transfer orchestration systems, providing flexible automation for fast and reliable data delivery.

Transfer Service API currently supports Azure DataLake Blob Storage to Relativity transfers only.

Authentication

All endpoints require Bearer JWT authentication unless otherwise noted. Include an Authorization: Bearer <token> header in each request. For token generation instructions, refer to Relativity REST API authentication/Bearer token authentication.

Users assigned to OAuth2 Client cannot be assigned to the System Administrator Group and has to have access to the fileshare using default or client domain workflow.

How to start Azure to R1 transfer

Azure to Relativity transfers enable server-side data copying, providing high speed, low error rates, and minimal client configuration. The process requires no additional client machine setup.

The Transfer Service API is available at:

 https://{relativity_instance}/transfer-service/api/v2

For example, https://production.relativity.one/transfer-service/api/v2

Source requirements

Review the following source requirements for working with this service:

• Transfer Service requires sourcePath to be a valid SAS Url token from Azure DataLake Blob Storage that is publicly accessible.

  ADLS storage gen1 does not support directory-level SAS tokens. SAS tokens can only be created at the container level. For more information, see Generate a SAS token in ADLS storage gen1.

• Token lifetime should be at least 7 days (token must be valid for the duration of whole copy).
• Token has to be provided with List and Read permissions.

Generate a SAS token in ADLS storage gen1

If applicable, complete the following steps to generate a SAS token in ADLS storage gen1:

1. Navigate to the folder in storage.
2. Click on the three menu dots to the right of the folder.
3. Click Copy URL.
4. Navigate to the Blob container.
5. Click on the three menu dots to the right of the folder.
6. Click Generate SAS token.
7. Add necessary permission to the token.
8. Click Generate.
9. Copy the token, not the full URL provided.
10. Combine the folder path URL from step 3, and the SAS token from step 9 with a "?" delimiter in between.

Workflow

The following describes the workflow to transfer Azure to Relativity:

1. Register the transfer job using POST v2/transfer/jobs. A successful request queues the copy job.
2. Monitor job status by calling GET v2/transfer/jobs/. Status updates approximately every 10 seconds.
3. Retrieve the QC report after completion using GET v2/transfer/jobs//qc.

Job stages

Jobs progress through six stages based on the EnumerationStatistics.Status and TransferStatus fields:

1. EnumerationStatistics.Status = queued- copy operation is queued, waiting for agent pickup.
2. EnumerationStatistics.Status = inprogress and TransferStatus = InProgress- transfer and enumeration are ongoing. Transfer progress fields (successfulFiles, failedFiles, successfulBytes, failedBytes) update during this stage.
3. EnumerationStatistics.Status = failed- enumeration failed. The transfer will fail regardless of TransferStatus.
4. EnumerationStatistics.Status = completed and TransferStatus = InProgress- enumeration completed successfully. Data validation begins. During this stage, we will verify only unique file paths.
5. EnumerationStatistics.Status = completed and TransferStatus = Completed- transfer finished successfully. All enumerated files were transferred. QC report starts to generate.
6. EnumerationStatistics.Status = completed and TransferStatus = Failed- transfer finished with failures. All enumerated files were processed, but some failed. Failed paths are available in the QC report.

To access the QC report, EnumerationStatistics.Status must be completed and TransferStatus must be either Failed or Completed.

How to get QC report

After a transfer completes, a QC report is generated containing relative paths, sizes, and status for all transferred files. Call GET v2/transfer/jobs//qc to retrieve a SAS URL for downloading the report.

Report generation time varies with data size. If the endpoint returns 404, the report is not yet ready. Generation may take a few minutes.

QC report structure

The QC report is a CSV file with comma delimiters. Each row represents one file with the following columns:

Error codes

The following section describes the possible Azure error codes. Error codes are organized into the following ranges:

• ER_0xxxx- common and general errors (authentication, authorization)
• ER_1xxxx- blob state and preconditions
• ER_2xxxx - copy mechanics and limits
• ER_9xxxx - fallback/unknown errors

API endpoints

POST v2/transfer/jobs

The following section describes how to use POST to create and queue a new transfer job.

CreateTransferRequestv2

The following section describes the request fields and how to create a transfer request:

1
2
3
4
5
6
7
8
{
                "destinationPath": "string",
                "sourcePath": "string",
                "tags": {
                "key": "value"
                },
                "transferJobID": "00000000-0000-0000-0000-000000000000"
            }

Responses

• 200 - Success
• 400 - Bad Request
  Copy

  1
  2
  3
  4
  5
  {
      "statusCode": 400,
      "title": "string",
      "message": "string"
  }

GET v2/transfer/jobs/

The following section describes how to use GET to retrieve the current status and statistics for a transfer job.

Parameters

The following table lists the parameters:

Responses

200 - Success

GetJobResultv2

The following section describes the response fields and how to use GetJobResultv2() to get a job result:

TransferStatistics

The following table lists the TransferStatistics fields:

EnumerationStatistics

The following table lists the EnumerationStatistics fields:

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
{
  "transferStatus": "string",
  "transferJobID": "00000000-0000-0000-0000-000000000000",
  "destinationFullPath": "string",
  "sourceFullPath": "string",
  "tags": {
    "key": "value"
  },
  "transferStatistics": {
    "successfulFiles": 0,
    "failedFiles": 0,
    "skippedFiles": 0,
    "successfulBytes": 0,
    "failedBytes": 0,
    "skippedBytes": 0,
    "successfulEmptyDirectories": 0,
    "failedEmptyDirectories": 0,
    "skippedEmptyDirectories": 0
  },
  "enumerationStatistics": {
    "totalFiles": 0,
    "totalSize": 0,
    "totalEmptyDirectories": 0,
    "status": "string",
    "error": "string"
  },
  "transferType": "AzureToR1"
}

DELETE v2/transfer/jobs/{job_id}

The following section describes how to use DELETE to cancel an in-progress Cloud transfer job.

Parameters

The following table lists the parameters:

Responses

• 200 — Success - cancels the job. Response body is empty.

• 400 — Bad Request - returned when:
  • jobId is empty (00000000-0000-0000-0000-000000000000)
  • The job is not a Cloud transfer job
  • The job is already finished
  • The job is already cancelled
    Copy

    {
        "statusCode": 400,
        "title": "string",
        "message": "string"
    }

• 404 — Not Found - the job does not exist.

GET v2/transfer/jobs/{jobId}/qc

The following section describes how to use GET to retrieve a SAS URL for downloading the QC report for a finished transfer job:

Parameters

The following table lists the parameters:

Responses

200 - Success

GetTokenResult

The following section describes how to use GetTokenResult() to get a transfer request:

1
2
3
{
  "sasUrl": "https://example.com/resource"
}

404 - Not Found - the QC report has not been generated yet. Wait for the transfer to complete and retry.