Processing API services for REST

The Processing API provides HTTP services based on .NET interfaces. The Relativity REST API supports these services, which you can use to automate processing by following standard Representational State Transfer (REST) features. For more information, see REST API.

Similar to the .NET interfaces on the Processing API, you can use the following services supported through REST to automate your processing workflows:

All of these services support create, read, and update operations except for the Processing Job Manager, which supports running inventory, discovery, and publishing jobs. You use the SaveAsync request for create and update operations. Additionally, all of these operations run asynchronously.

Note: You must install the Processing application in your Relativity environment to automate processing workflows with the Processing API. For more information, see Installing and configuring Processing on the Relativity Documentation site.

This page contains the following information:

See these related pages:

Client code sample

You can use the following .NET code as the REST client for performing any of the operations available in the Processing API. The code currently illustrates how to submit a discovery job, but you can modify it as follows to perform other operations:

//Set up the client.
HttpClient httpClient = new HttpClient();
httpClient.BaseAddress = new Uri("http://localhost/");
  
//Set the required headers.
httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
httpClient.DefaultRequestHeaders.Add("Authorization", "Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=");
  
//Call the operation that you want to run.
string url = "Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Job Manager/SubmitDiscoveryJobsAsync”;
StringContent content = new StringContent(QueryInputJSON);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
HttpResponseMessage response = httpClient.PostAsync(url, content).Result;
string result = response.Content.ReadAsStringAsync().Result;
bool success = HttpStatusCode.Ok == response.StatusCode;
  
//Parse the result with Json.NET.
JObject resultObject = JObject.Parse(result);

Custodians

A custodian is a user who's associated with the data included in a processing job. For more information, see Entity object on the RelativityOne Documentation site.

Create or update a custodian

Use this URL on the Processing Custodian Manager service to create or update a custodian:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Custodian Manager/SaveAsync

You can send a request for a custodian who is an individual or an entity, such as corporation, data location, or other construct.

The request to create or update a custodian who is an individual must contains the following fields:

{
   "Custodian":{
      "DocumentNumberingPrefix":"REL",
      "FirstName":"Custodian First Name",
      "LastName":"Custodian Last Name",
      "CustodianType":"Person"
   }, 
   "workspaceArtifactId":1093143
}

The request to create or update a custodian who is an entity contains the following fields:

{
   "Custodian":{
      "DocumentNumberingPrefix":"relativity-",
      "Name":"Relativity ODA LLC",
      "CustodianType":"Entity"
   }, 
   "workspaceArtifactId":1093143
}
{
   "Custodian":{
      "DocumentNumberingPrefix":"relativity-",
      "Name":"Relativity ODA LLC",
      "CustodianType":"Other"
   }, 
   "workspaceArtifactId":1093143
}

The response returns the Artifact ID of the custodian that was created or updated, such as the integer 1060372.

Read a custodian

Use this URL on the Processing Custodian Manager service to retrieve a custodian:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Custodian Manager/ReadAsync

The request must include Artifact ID for the custodian and the workspace:

{
   "ArtifactId":1041433,
   "WorkspaceArtifactId":1093143
}

The response for custodian who is an individual contains the following fields:

{
"DocumentNumberingPrefix": "Laura-"
"FirstName": "Laura"
"LastName": "Libera"
"CustodianType": "Person"
"ArtifactID": 1038911
"Name": "Libera, Laura"
}

The response for custodian that is an entity contains the same fields as a custodian who is a person. However, the CustodianType fields contains "Entity", and "FirstName" and "LastName" don't contain any values.

{
  "DocumentNumberingPrefix": "relativity-"
  "FirstName": "-"
  "LastName": "-"
  "CustodianType": "Entity"
  "ArtifactID": 1038912
  "Name": "Relativity ODA LLC"
}

Processing profiles

A processing profile defines the settings that processing engine uses when it publishes documents associated with a specific processing set. These settings include those for handling numbering, deNISTing, extraction, and deduplication tasks. For more information, see Processing profiles on the RelativityOne Documentation site.

Create or update a processing profile

Use the SaveAsync endpoint to create or update a processing profile. Send a request to this URL on the Processing Profile Manager service:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Profile Manager/SaveAsync
{
   "processingProfileSaveRequest":{
      "ProcessingProfile":{
         "Name":"Modified Profile",
         "ArtifactId":1041094,
         "NumberingSettings":{
            "DefaultDocumentNumberingPrefix":"REL",
            "NumberingType":"DefineStartNumber",
            "DefaultStartNumber":4,
            "Delimiter":"Underscore",
            "NumberofDigits":"NumberofDigits4",
            "ParentChildNumbering":"SuffixAlways"
         },
         "InventoryDiscoverSettings":{
            "DeNIST":true,
            "DeNISTMode":"DoNotBreakParentChildGroups",
            "DefaultOCRlanguages":[
               "English"
            ],
            "DefaultTimeZoneID":1037890
         },
         "ExtractionSettings":{
            "Extractchildren":true,
            "ChildExtractionMethod":[
               "MSOfficeEmbeddedObjects",
               "EmailInlineImages"
            ],
            "ExcelTextExtractionMethod":"Native",
            "ExcelHeaderFooterExtraction":"ExtractAndPlaceAtEnd",
            "WordTextExtractionMethod":"Native",
            "PowerPointTextExtractionMethod":"Native",
            "OCR":true,
            "OCRAccuracy":"Medium",
            "OCRTextSeparator":true,
            "EmailOutput":"MHT"
         },
         "DeduplicationSettings":{
            "DeduplicationMethod":"Global",
            "PropagateDeduplicationData":true
         },
         "PublishSettings":{
            "UseSourceFolderStructure":false,
            "AutopublishSet":true,
            "DefaultDestinationFolder":{
               "ArtifactID":1003697
            }
         }
      },
      "WorkspaceId":1017155
   }
}

When a processing profile is successfully created or updated, the JSON response contains the ProcessingProfileId field, which is set to the Artifact ID of the profile.

{
   "ProcessingProfileId":1041094
}

Retrieve a processing profile

Use the ReadAsync endpoint to retrieve a processing profile. Send a request to this URL on the Processing Profile Manager service:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Profile Manager/ReadAsync

The request must contain a processingProfileReadRequest object with the following fields set:

{
   "processingProfileReadRequest":{
      "ProcessingProfileId":1041093,
      "WorkspaceId":1017196
   }
}

The response contains the following fields:

{
   "ProcessingProfile":{
      "NumberingSettings":{
         "DefaultDocumentNumberingPrefix":"Mod",
         "NumberingType":"DefineStartNumber",
         "DefaultStartNumber":4,
         "Delimiter":"Underscore",
         "NumberOfDigits":"NumberOfDigits4",
         "ParentChildNumbering":"SuffixAlways"
      },
      "InventoryDiscoverSettings":{
         "DeNIST":true,
         "DeNISTMode":"DoNotBreakParentChildGroups",
         "DefaultOCRlanguages":[
            "English"
         ],
         "DefaultTimeZoneID":1037890
      },
      "ExtractionSettings":{
         "Extractchildren":true,
         "ChildExtractionMethod":[
            "MSOfficeEmbeddedObjects",
            "EmailInlineImages"
         ],
         "ExcelTextExtractionMethod":"Native",
         "ExcelHeaderFooterExtraction":"ExtractAndPlaceAtEnd",
         "WordTextExtractionMethod":"Native",
         "PowerPointTextExtractionMethod":"Native",
         "OCR":true,
         "OCRAccuracy":"Medium",
         "OCRTextSeparator":true,
         "EmailOutput":"MSG"
      },
      "DeduplicationSettings":{
         "DeduplicationMethod":"Global",
         "PropagateDeduplicationData":true
      },
      "PublishSettings":{
         "UseSourceFolderStructure":false,
         "AutopublishSet":true,
         "DefaultDestinationFolder":{
            "ArtifactID":1003697
         }
      },
      "ArtifactID":1041093,
      "Name":"REL Fest 7 - Final REL",
      "IsNew":false
   }
}

Delete a processing profile

Use the DeleteAsync endpoint to remove a processing profile from Relativity. Send a request to this URL on the Processing Profile Manager service:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Profile Manager/DeleteAsync

The request must contain a processingProfileDeleteRequest object with the following fields set:

{
   "processingProfileDeleteRequest":{
      "ProcessingProfileId":1041026,
      "WorkspaceId":1017196
   }
}

The response contains the Deleted field, which is set to true when the processing profile is successfully removed from Relativity.

{
   "Deleted":true
}

Processing data sources

A data source contains the path used to specify the location of the files that you want to discover during processing. For more information, see Processing sets on the RelativityOne Documentation site.

Create or update a data source

Use this URL on the Processing Data Source Manager service to update or create a data source:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Data Source Manager/SaveAsync

The request must contain an InputPath field that specifies a file path, which the resource pool in the workspace can access. For more information, see Resource Pools on the Relativity 9.6 Documentation site. It may also contain the StartNumber and IsStartNumberVisible properties.

For more information, see Processing data sources.

{
   "processingDataSource": {
      "Custodian":1038885,
      "DestinationFolder":1003697,
      "DocumentNumberingPrefix":"REL",
      "InputPath":"\\\\localhost\\FileShare\\My Documents\\History of English.msg",
      "OcrLanguages":[
         "English"
      ],
      "Order":123,
      "ProcessingSet":{
         "ArtifactID":1038907
      },
      "TimeZone":1036905,
      "IsStartNumberVisible":true,
      "StartNumber":8,
      "ArtifactID":1038908,
      "Name":"1038908 - History of English"
   },
   "workspaceArtifactId":1378006
}

The response returns the Artifact ID of the data source that was created or updated, such as the integer 1046822.

Read a data source

Use this URL on the Processing Data Source Manager service to retrieve a data source:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Data Source Manager/ReadAsync

The request must include Artifact ID for the data source that you want to read, and the workspace where the data source resides:

{
   "ArtifactId":1038908,
   "workspaceArtifactId":1378006
}

The response for a read operation returns a JSON object with the following fields. The Name field for the processing set is always an empty string, while the Name field for the data source usually contains its Artifact ID.

{
  "Custodian": 1038885,
  "DestinationFolder": 1003697,
  "DocumentNumberingPrefix": "REL-",
  "InputPath": "\\localhost\FileShare\My Documents\History of English.msg",
  "IsNew": false,
  "OcrLanguages": [
    "English"
  ],
  "Order": 123,
  "ProcessingSet": {
    "ArtifactID": 1038907,
    "Name": ""
  },
  "TimeZone": 1036905,
  "StartNumber": 8,
  "IsStartNumberVisible": true,
  "ArtifactID": 1038908,
  "Name": "1038908 - History of English"
}

Validate deletion of a data source

You can use the ValidDeleteAsync endpoint to check if the specified processing data source is safe to be deleted. For example, if the processing set is already discovered or canceled. Use this URL on the Processing Data Source Manager service for deletion validation of the processing sets with the criteria specified in the JSON request:

<Host>/relativity.rest/api/Relativity.Processing.Services.IProcessingModule/workspace/{workspaceId}/processing-data-sources/{processingDataSourceId}/validate-delete
		

The request must include the following fields:

The response includes the following fields:

{
			"CanDelete": false,
			"Reasons": [
			"You can't delete the data source because the processing set has already been discovered."
			]
		}

Processing sets

A processing set object links a processing profile to one or more data sources. For more information, see Processing sets on the RelativityOne Documentation site.

Create or update a processing set

Use this URL on the Processing Set Manager service to create or update a processing set:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Set Manager/SaveAsync

The request must include the Artifact ID for the workspace that contains the processing set, and the name and Artifact ID of the processing profile. You can also optionally include a list of recipients who receive email notifications after the creation or update of the processing set completes.

{
   "workspaceArtifactId":1093143,
   "ProcessingSet":{
      "EmailNotificationRecipients":[
         "jsmith@relativity.com",
         "bjones@relativity.com"
      ],
      "Name":"Processing Set  Name",
      "Profile":{
         "ArtifactID":1041350
      }
   }
}

The response returns the Artifact ID of the processing set that was created or updated, such as the integer 1046784.

Read a processing set

Use this URL on the Processing Set Manager service to retrieve a processing set:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Set Manager/ReadAsync

The request must include Artifact ID for the processing set and the workspace that contains it:

{
   "artifactId":1045777,
   "workspaceArtifactId":1093143
}

The response includes the following fields. The Name field for the processing profile is always an empty string.

{
   "Profile":{
      "ArtifactID":1056549,
      "Name":"",
      "IsNew":false
   },
   "ArtifactID":1090382,
   "Name":"My Processing Set"
}

Retrieve aggregate information for processing sets

Use the GetDocumentAggregates endpoint to retrieve document aggregates and other information about processing sets with the status of Completed or Completed with errors in a specific workspace. For more information about the GetDocumentAggregates() method, see Retrieve a list of processing sets and related aggregate information.

Use this URL on the Processing Set Manager service to retrieve the processing sets with the criteria specified in the JSON request:

<host>/Relativity.Rest/api/Relativity.Processing.Services.IProcessingModule/Processing Set Manager/GetDocumentAggregates

The request must include the following fields:

In addition, the request may optionally include these fields:

{
    "request":{
        "WorkspaceArtifactId":1023139,
        "PageSize":15,
        "Page":0,
        "SortColumnName":"PublishedDocumentSizeInBytes",
        "SortDescending":true
    }
}

The response includes the following fields:

{
  "TotalPublishedDocuments": 15,
  "TotalPublishedDocumentSizeInBytes": 3563255,
  "TotalProcessingSets": 2,
  "ProcessingSetDocumentInfo": [
    {
      "ProcessingSetId": 1038688,
      "ProcessingSetName": "Test 1",
      "ProcessingSetDateCreated": "2016-06-02T19:25:42.547",
      "PublishedDocumentCount": 14,
      "PublishedDocumentSizeInBytes": 3531511
    },
    {
      "ProcessingSetId": 1042347,
      "ProcessingSetName": "Test 2",
      "ProcessingSetDateCreated": "2016-06-09T19:17:27.253",
      "PublishedDocumentCount": 1,
      "PublishedDocumentSizeInBytes": 31744
    }
  ]
}

Retrieve summary data for processing sets

Use the GetSummaryDataAsync endpoint to retrieve processing set summary data in a specific workspace to display to console, such as environment errors, discover and publish status, and more. For more information about the GetSummaryDataAsync() method, see Retrieve summary data of processing sets to display to console.

Use this URL on the Processing Set Manager service to retrieve the processing sets with the criteria specified in the JSON request:

<host>/Relativity.Rest/api/Relativity.Processing.Services.IProcessingModule/workspace/{workspaceId}/processing-sets/{processingSetId}/summary
				

The request must include the following fields:

The response includes the following fields:

{
    "SetState": {
        "ArtifactId": 1043783,
        "InventoryStatus": "4bab4cc3-a8a8-438c-a649-6fd4e0d111eb",
        "DiscoverStatus": "be180e9d-8abf-41f8-8507-37bd1d22f72e",
        "PublishStatus": "fc78eb19-b905-479c-9c3c-6fc49b95ea08",
        "Canceled": false,
        "ProcessingProfileId": 1040502
    },
    "HasRunningJobs": false,
    "EnvironmentErrors": [],
    "DataSourceIds": [
        1043784
    ],
    "DataSourceHasDocumentLevelErrors": false,
    "DataSourceHasJobLevelErrors": false
}

Inventory jobs

Use the SubmitInventoryJobsAsync endpoint to run an inventory job. Before you run a discovery job, you may want to exclude irrelevant raw files from your data set, such as eliminating NIST file types. You can perform this task by executing an inventory job. You can only run an inventory job on processing sets that haven't been discovered. If you want to apply filtering to your data, set your filters through the Relativity UI after the inventory job completes. For more information, see Inventory on the RelativityOne Documentation site.

Use this URL on the Processing Job Manager service to run an inventory job:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Job Manager/SubmitInventoryJobsAsync

The request must include Artifact ID for the processing set and the workspace where it resides:

{
   "InventoryJob":{
      "ProcessingSetId":1046785,
      "WorkspaceArtifactId":1093143
   }
}

The response returns the status code of 200 when the job completes successfully.

Discovery jobs

After you create a processing set and add a data source to it, you can initiate a discovery or processing job. During a job run, the processing engine discovers files in the data source based on the values specified in the processing set. For more information, see Processing on the RelativityOne Documentation site.

Use this URL on the Processing Job Manager service to run a discovery job:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Job Manager/SubmitDiscoveryJobsAsync

The request must include Artifact ID for the processing set and the workspace where it resides:

{
   "DiscoveryJob":{
      "ProcessingSetId":1046785,
      "WorkspaceArtifactId":1093143
   }
}

The response returns the status code of 200 when the job completes successfully.

Publishing jobs

Use the SubmitPublishJobsAsync endpoint to run publishing jobs. You can provide reviewers in Relativity with access to process data by publishing it to a workspace after it has been discovered. You must run a discovery job on the date before you can run a publishing job on it. For more information, see Publishing files on the RelativityOne Documentation site.

Use this URL on the Processing Job Manager service to run an publishing job:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Job Manager/SubmitPublishJobsAsync

The request must include Artifact ID for the processing set and the workspace where it resides:

{
   "PublishJob":{
      "ProcessingSetId":1046785,
      "WorkspaceArtifactId":1093143
   }
}

The response returns the status code of 200 when the job completes successfully.

Cancel jobs

You can use the SubmitCancelJobAsync endpoint to cancel inventory, discovery, and publishing jobs for a specific processing set. Use this URL on the Processing Job Manager service to cancel a job:

<host>/Relativity.REST/api/Relativity.Processing.Services.IProcessingModule/Processing Job Manager/SubmitCancelJobAsync

The request must include Artifact ID for the processing set and the workspace where it resides:

{
   "CancelJob":{
      "ProcessingSetId":1046785,
      "WorkspaceArtifactId":1093143
   }
}

The response returns the status code of 200 when the job is submitted successfully. However, this return value doesn't indicate that the job has been canceled. Multiple factors influence when a worker picks up a cancel job and how long the job takes to execute. For example, the amount of data and system state can affect this outcome.

Note: The submission of cancel job returns successfully when the job associated with a processing set has already been canceled.

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