Production Manager (REST)

The Relativity REST API includes a Production Manager service that provides the operations for working with productions. You can use the service to create, read, stage, run, cancel, and delete existing productions. The supported operations are equivalent to the methods for interacting with Production objects in the Relativity Services API. Overall, the service is designed to help you integrate Relativity productions with other business processes, applications, and tools.

This page contains the following information:

See these related pages:

• Production placeholders
• Production data sources

Production fundamentals

Before programmatically interacting with Relativity productions, familiarize yourself with the Relativity productions user interface and review the information in the RelativityOne Documentation site.

Follow these basic guidelines when working with the Production Manager service:

• The user interacting with the Production Manager service must have the permissions required for working with Relativity productions.
• You must assign a data source before you stage it. After you read a production, check the DataSources property.
• You can't run a production that hasn't been staged. Check the Status field of the ProductionMetadata property.
• You can't rerun a produced production.

Client code sample

The following is an example of .NET REST code for reading a production. You can use this code for all Production Manager service operations with different endpoint URLs and input JSON values.

//Set up the REST 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 c2FtcGxlYWRtaW5AcmVsYXRpdml0eS5yZXN0OlMwbTNwQHNzdzByZA==");

//Call read production.
            
string url = "/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/ReadSingleAsync";
StringContent content = new StringContent(CreateInputJSON, Encoding.UTF8, "application/json");
HttpResponseMessage response = httpClient.PostAsync(url, content).Result;
string result = response.Content.ReadAsStringAsync().Result;
bool success = HttpStatusCode.Created == response.StatusCode;

//Parse the result with Json.NET.
            
JObject resultObject = JObject.Parse(result);        

Get all productions

To get all productions a user has access to in a workspace, send a request to the following Production Manager service URL:

<host>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/GetAllAsync

The request must include the workspaceArtifactID and mode parameters. The mode parameter defines what data source and placeholder information is include with the by production objects:

• 0 - None – No data sources or placeholders are returned.
• 1 - OnlyDataSources – Data sources are returned without placeholders.
• 2 - DataSourcesAndPlaceholders – Both data sources and their associated placeholders are returned.

{
  "workspaceArtifactID": 1019837,
  "mode": 0
}

The response returns a collection of ProductionRef objects containing the names and Artifact IDs of productions.

Note: GetAllAsync can sometimes take a long time to execute in environments with a lot of productions because of the amount of data it returns. As an alternative, you can use Object Query for Productions (ArtifactTypeID = 17). For more information, see Legacy Object Query Manager (REST).

Get produced productions from documents

To get information about productions that have already been produced in a workspace, send a POST request to the following Production Manager service URL:

<host>/Relativity.Rest/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/GetProducedProductionsFromDocumentsAsync

Notes:
• If a workspace has a lot of documents, split up your request into smaller ones.
• To use this endpoint, you must have both Document and Production view permissions.

The endpoint returns all productions that have a partial intersection with the list of documents that you passed. For example, if a produced production contains only one of the document IDs passed, the request would return that production. As a result, this is a great method to use if you want to see how many times a specific document has been produced in a workspace and in which productions it occurs. More specifically, the request returns the List<ProductionSlim> producedProductions object. Each ProductionSlim for a producedProduction contains the ArtifiactID, Name, BeginBates, EndBates, and DateProduced.

For the GetProducedProductionsFromDocumentsAsync endpoint, you can provide a request body that retrieves information about produced productions or information about produced productions that can be re-produced.

Get production image metadata

To get production image metadata, send a request to the following Production Manager service URL:

<host>/Relativity.Rest/Api/Relativity.Productions.Services.IProductionModule/Production%20Manager/GetProductionImagesAsync

Retrieved metadata includes:

Field	Data type	Description
DocumentID	int	The Artifact ID of the document the production image belongs to.
FileID	int	The File ID of the file the production image belongs to.
PageNumber	int	The page number of the document the production image belongs to.
HasRedactions	boolean	Whether a production image has redactions. If the production image has redactions, the value is True.
FileGuid	string	The GUID of the file the production image belongs to.

Note: All endpoints contain an Errors property, which will return any information about why the API call did not succeed.

For the GetProductionImagesAsync endpoint, you can provide a request body that retrieves metadata for specific production images and for every production image in a production.

Get production status details

To retrieve production status details, send a POST request to the following Production Manager service URL:

<host>/Relativity.Rest/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/GetProductionStatusDetails

Note: You must have the production view permission to use this endpoint.

This method requires you to pass these parameters:

Parameter	Data type	Description
workspaceArtifactId	int	The Artifact ID of the workspace.
productionArtifactId	int	The Artifact ID of the production.

A GetProductionStatusDetails request returns the string name of the current status. Depending on the status of the production, different fields are returned.

Note: Statuses not included in the table below will not return any production metadata other than the status name. If you want information about a production with a status not listed in the table, use the ReadSingleAsync endpoint. See Read a production.

Status	Fields returned
Staged	TotalDocumentCount TotalImagesCount DocumentsWithImages DocumentsWithPlaceholders DocumentsWithRedactions DocumentsWithNatives
StartingProduction	TotalDocumentCount TotalImagesCount DocumentsWithImages DocumentsWithPlaceholders DocumentsWithRedactions DocumentsWithNatives
ErrorStartingProduction	TotalDocumentCount TotalImagesCount DocumentsWithImages DocumentsWithPlaceholders DocumentsWithRedactions DocumentsWithNatives
StagingError	TotalDocumentCount TotalImagesCount DocumentsWithImages DocumentsWithPlaceholders DocumentsWithRedactions DocumentsWithNatives
CreatingBrandingQueueRecords	ProductionStartTime BrandingQueueRecordsCount BrandingQueueRecordsTotal
Produced	DateProduced FirstBatesValues LastBatesValue TotalDocumentCount TotalImagesCount DocumentsWithImages DocumentsWithPlaceholders DocumentsWithRedactions DocumentsWithNatives ImageSizeInGb ProductionRunDate CompletedReproductions
Branding	ProductionStartTime ImagesBranded ImagesToBeBranded ImagesWithErrors
Error	TotalDocumentCount TotalImagesCount DocumentsWithImages DocumentsWithPlaceholders DocumentsWithRedactions DocumentsWithNatives ProductionRunDate ImagesWithErrors ImagesBranded ImagesToBeBranded

Get productions eligible for re-production

To retrieve productions that can be re-produced and that meet specific criteria, send a POST request to the following Production Manager service URL:

<host>/Relativity.Rest/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/GetProductionsEligibleForReproductionAsync

Note: You must have the document and production view permissions to use this endpoint.

This method requires you to pass these parameters:

Parameter	Data type	Description
workspaceArtifactID	int	The Artifact ID of the workspace.
databaseToken	string	A unique identifier representing the database token of a custom mass operation. Only document mass operations are supported. Notes: It is recommended to only pass in a database token corresponding to 10,000 or less document artifact IDs. If more documents are needed, the request should be split up into smaller batches, and the results reconstructed to get the desired productions. The precision of the filtering provided by this endpoint means that this is an expensive call; it is recommended not to hammer the environment with chained requests.
reproductionType	ReproductionType	The re-production type that returned productions should be compatible with. Re-production types include: ReproduceDocument - re-produce a document with new branding or markup sets. The re-produced document must have the same number of pages before and after re-production. Documents in the production to be re-produced must be images. ReplaceDocumentWithPlaceholder - replace a document with a placeholder. Documents in the production to be re-produced must be images. ReplacePlaceholderWithDocument - replace a placeholder with the original document. Documents in the production to be re-produced must be placeholders.

To generate a database token for select documents:

1. Create a custom mass operation. See Develop Mass Operation handlers.
2. In Relativity, navigate to the Resource Files tab and add the custom mass operation by clicking New Resource File.
3. Navigate to the Object Type tab and link the custom mass operation to the Document object. See Adding a custom mass operation.
4. Navigate to the Documents tab within a workspace.
5. Select the documents that you want to retrieve produced production information for.
6. In the mass operations bar, click the custom mass operation. A database token is generated that corresponds to a table in the database that holds the selected documents. The database token is at the end of the URL on the page that opens.

Note: Passing a database token eliminates a second server trip to retrieve the requested document IDs of the custom mass operation.

A GetProductionsEligibleForReproduction request returns the List<ProductionSlim> producedProductions object. Each ProductionSlim for a producedProduction contains the ArtifiactID, Name, BeginBates, EndBates, and DateProduced. Example scenarios include:

Productions in workspace	Parameters passed	Productions returned
Production A Document 1, produced as a placeholder Production B Document 2, produced as a placeholder	Documents requested via a database token Document 1 Document 2 ReproductionType ReplacePlaceholderWithDocument	Both productions are returned because they meet the specified re-production type and have a partial match to the list of documents requested.
Production A Document 1, produced as a placeholder Document 3, produced as a placeholder Production B Document 2, produced with images	Documents requested via a database token Document 1 Document 3 ReproductionType ReplacePlaceholderWithDocument	Production A is returned because it contains both of the requested documents and both documents meet the specified re-production type. Production B is NOT returned because it does not contain any of the requested documents.
Production A Document 1, produced as a placeholder Document 2, produced with images	Documents requested via a database token Document 1 Document 2 ReproductionType ReproduceDocument	Production A is returned.

Create a production

To create a new production, send a request to the following Production Manager service URL:

<host>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/CreateSingleAsync

The request must include the workspaceArtifactID and the production object.

The following is a sample request for creating a production with page-level numbering and a branding font size of 50:

{
  "workspaceArtifactID": 1019837,
  "Production": {
    "Details": {
      "EmailRecipients": "recipient@mycompany.com",
      "BrandingFontSize": 50,
      "ScaleBrandingFont": false
    },
    "Numbering": {
      "NumberingType": "PageLevel",
      "AttachmentRelationalField": {
        "ArtifactID": 0,
        "ViewFieldID": 0,
        "Name": ""
      },
      "BatesPrefix": "ABC",
      "BatesSuffix": "",
      "BatesStartNumber": 1,
      "NumberOfDigitsForDocumentNumbering": 7
    },
    "SortOrder": [],
    "Headers": {
      "LeftHeader": {
        "Type": "None",
        "Field": {
          "ArtifactID": 0,
          "ViewFieldID": 0,
          "Name": ""
        },
        "FreeText": "",
        "FriendlyName": "Left Header"
      }
    },
    "Footers": {
      "LeftFooter": {
        "Type": "None",
        "Field": {
          "ArtifactID": 0,
          "ViewFieldID": 0,
          "Name": ""
        },
        "FreeText": "",
        "FriendlyName": "Left Footer"
      }
    },
    "ShouldCopyInstanceOnWorkspaceCreate": false,
    "Name": "Prod Page Level"
  }
}

The following is a sample request for creating a production with page-level numbering and a branding font size of 50:

{
  "workspaceArtifactID": 999999,
  "Production": {
    "Details": {
      "EmailRecipients": "recipient@mycompany.com",
      "BrandingFontSize": 10,
      "ScaleBrandingFont": false
    },
    "Numbering": {
      "NumberingType": "ExistingProduction",
      "ExistingProduction": {
        "ArtifactID": 888888
      },
      "AttachmentRelationalField": {
        "ArtifactID": 0,
        "ViewFieldID": 0,
        "Name": ""
      },
      "MergeWithExistingSet": false
    },
    "SortOrder": [],
    "Headers": {
      "LeftHeader": {
        "Type": "None",
        "Field": {
          "ArtifactID": 0,
          "ViewFieldID": 0,
          "Name": ""
        },
        "FreeText": "",
        "FriendlyName": "Left Header"
      }
    },
    "Footers": {
      "LeftFooter": {
        "Type": "None",
        "Field": {
          "ArtifactID": 0,
          "ViewFieldID": 0,
          "Name": ""
        },
        "FreeText": "",
        "FriendlyName": "Left Footer"
      }
    },
    "ShouldCopyInstanceOnWorkspaceCreate": false,
    "Name": "Existing Prod Level"
  }
}

The response returns the Artifact ID of the production.

Read a production

To read a production, send a request to the following Production Manager service URL:

<host>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/ReadSingleAsync

The request must include the workspaceArtifactID, productionArtifactID, and DataSourceReadMode parameters. The DataSourceReadMode parameter defines what data source and placeholder information is include with the by production objects:

• 0 - None – No data sources or placeholders are returned.
• 1 - OnlyDataSources – Data sources are returned without placeholders.
• 2 - DataSourcesAndPlaceholders – Both data sources and their associated placeholders are returned.

{
  "workspaceArtifactID": 1019837,
  "productionArtifactID": 1043598,
  "DataSourceReadMode": 0
}

The response returns a Production object with properties such as data sources, details, numbering, sort order, headers and footers, and production metadata.

Stage a production

To stage a production, send a request to this URL for the Production Manager service:

<host>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/StageProductionAsync

The request must include the workspaceArtifactID and productionArtifactID parameters.

{
  "workspaceArtifactID": 1019837,
  "productionArtifactID": 1043598
}

The response returns a ProductionJobResult object. The object specifies whether a staging job was successfully created in the queue, the job ID, and any messages and errors.

{
  "JobID": 5936,
  "Errors": [],
  "Messages": [],
  "WasJobCreated": true
}

Run a production

To run a production, send a request to the following Production Manager service URL:

<host>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/RunProductionAsync

The request must include the workspaceArtifactID, productionArtifactID, suppressWarnings (optional), and overrideConflicts (optional) parameters.

{
  "workspaceArtifactID": 1019837,
  "productionArtifactID": 1043598,
  "suppressWarnings": true,
  "overrideConflicts": false
}

Note: If you don't have production restrictions defined in the workspace, you must supply the suppressWarnings with the value of true. Otherwise, the production fails due to the production restrictions warning.

The response returns a ProductionJobResult object. The object specifies whether a production job was successfully created in the queue, the job ID, and any messages and errors.

{
  "JobID": 5937,
  "Errors": [],
  "Messages": [
    "There is no specified Production Restriction for this workspace."
  ],
  "WasJobCreated": true
}

Mass stage and run productions

To mass stage and run productions, post a request to the following Production Manager service URL:

<host>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/MassStageAndRunProductionsAsync

A mass stage and run productions request returns the IEnumerable<ProductionJobResult> object. Each ProductionJobResult has a list of errors, messages, and warnings explaining why a request failed or containing other important information.

For the MassStageAndRunProductionsAsync endpoint, you can pass either select productions or a re-production job.

Cancel a production job

To cancel a staging or a production job, send a request to the following Production Manager service URL:

<host>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/CancelJobAsync

The request must include the workspaceArtifactID and productionArtifactID parameters.

{
    "workspaceID": 1019837,
    "productionID" : 1043598
}

This cancels the job in the production or branding queue and sets the Status property of a production to 'New' if it is being staged, or 'Staged' if it is being produced. The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.

Note: The cancel operation does not validate whether a production job exists for the specified Artifact ID.

Cancel production jobs

You can cancel a single production job or mass cancel several production jobs.

The CancelJobAsync and the MassCancelAsync endpoints cancel jobs in the production or branding queue. They set the Status property for each production to New if it is being staged, or Staged if it is being produced. They don't validate whether a job exists for the artifact ID of a production specified in the ProductionID property on a ProductionJobRef object. For more information about this class in .NET, see Production Manager (.NET).

Cancel a single production job

To cancel a staging or a production job, send a request to the following Production Manager service URL:

<hostname>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/CancelJobAsync

For the CancelJobAsync endpoint, you can provide a request body that contains the artifact IDs of the workspace and production, or you can provide a request that contains only the artifact ID of the job. See the following sample requests.

Note: To avoid unexpected results, don't add the artifact IDs of the workspace, production, and job to a single JSON request. If the job ID doesn't correspond with the other fields in the request, then the cancel operation is attempted using only the workspace ID and production ID pair. If that operation fails, the cancel operation is attempted using only the job ID.

Use one of the following formats for the body of the request:

• Format 1 - JSON request with artifact IDs for the workspace and production - this request contains the following fields:
  • jobRef - represents a key or reference to a production job object. It contains the following fields:
    • WorkspaceID - the artifact ID of the workspace that contains the production to cancel.
    • ProductionID - the artifact ID of the production that you want to cancel.

  {
     "jobRef":{
        "WorkspaceID":1019837,
        "ProductionID":1043598
     }
  }

• Format 2 - JSON request with the artifact ID for only the job - this request contains the following fields:
  • jobRef - represents a key or reference to a production job object. It contains the following field:
    • JobID - the artifact ID of the production job that you want to cancel.

  {
     "jobRef":{
        "JobID":123
     }
  }

The response contains the following fields:

• WorkspaceID - the artifact ID of the workspace containing the canceled production.
• ProductionID - the artifact ID of the canceled production.
• JobID - the artifact ID of the canceled production job.
• CancelSuccessfullySent - a Boolean value indicating whether the cancel request was successfully sent.
• Errors - a list of any errors that occurred during the cancel operation.

{
   "WorkspaceID":1019837,
   "ProductionID":1043598,
   "JobID":0,
   "CancelSuccessfullySent":true,
   "Errors":
}

Mass cancel production jobs

To cancel multiple staging or a production jobs, send a request to the following Production Manager service URL:

<hostname>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/MassCancelAsync

In the following JSON request, the JobsToBeCanceled field contains a list of productions that use two different formats:

• Format 1 - The artifact IDs of the workspace and production.
• Format 2 - The artifact ID of the job.

For more information about these formats, see Cancel a single production job.

{
   "JobsToBeCanceled":[
      {
         "WorkspaceID":1017567,
         "ProductionID":1038975
      },
      {
         "WorkspaceID":1017567,
         "ProductionID":1038978
      },
      {
         "JobID":123
      }
   ]
}

The response contains the following fields:

• NumberOfJobsRequestedForCancel - an integer value representing the total number of cancel jobs requested.
• NumberOfJobsCancelWasRequestedSuccessfully - an integer value representing the total number of cancel jobs successfully requested.
• CancelJobResults - represents the results of cancel operation on a production job. It contains the following fields:
  • WorkspaceID - the artifact ID of the workspace containing the canceled production.
  • ProductionID - the artifact ID of the canceled production.
  • JobID - the artifact ID of the canceled production job.
  • CancelSuccessfullySent - a Boolean value indicating whether the cancel request was successfully sent.
  • Errors - a list of any errors that occurred during the cancel operation.

{
   "NumberOfJobsRequestedForCancel":3,
   "NumberOfJobsCancelWasRequestedSuccessfully":1,
   "CancelJobResults":[
      {
         "WorkspaceID":1017567,
         "ProductionID":1038975,
         "JobID":0,
         "CancelSuccessfullySent":false,
         "Errors":[
            "This production cannot be canceled."
         ]
      },
      {
         "WorkspaceID":1017567,
         "ProductionID":1038978,
         "JobID":0,
         "CancelSuccessfullySent":true,
         "Errors":""
      },
      {
         "WorkspaceID":0,
         "ProductionID":0,
         "JobID":123,
         "CancelSuccessfullySent":false,
         "Errors":[
            "Invalid Production JobRef. Cannot find Production based on WorkspaceID and ProductionID, or based on JobID."
         ]
      }
   ]
}

Delete a production

To delete a production, send a request to the following Production Manager service URL:

<host>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/DeleteSingleAsync

The request must include the workspaceArtifactID and productionArtifactID parameters.

{
  "workspaceArtifactID": 1019837,
  "productionArtifactID": 1043598
}

The response does not contain any data. Success or failure is indicated by the HTTP status code. For more information, see HTTP status codes.

Mass Retry production jobs

To retry multiple production error or delete jobs in a single call, send a request to the following Production Manger service URL:

<hostname>/Relativity.REST/api/Relativity.Productions.Services.IProductionModule/Production%20Manager/MassRetryAsync

Notes:
• The Mass Retry endpoint will only retry jobs that are in the Production queue. Jobs that cannot be retried include: new jobs, staged jobs, jobs with a status of canceling, and jobs with a status of waiting to be assigned an agent.
• To use the Mass Retry endpoint, you must have the correct permissions to retry production jobs. Users with the Change priority permission do not need workspace or production permissions.

This method requires you to pass the following parameter:

Parameter	Data type	Description
jobsToBeRetried	list<ProductionJobRef>	A list of ProductionJobRef objects representing the production jobs to be retried. When instantiating a ProductionJobRef object, either set the ProductionID and WorkspaceID properties or set the JobID property. To avoid unexpected results, don't set all three properties on a single ProductionJobRef object.   If you include all three properties on a single ProductionJobRef object, the mass retry operation is attempted using the WorkspaceID and the ProductionID pair first, and then if the mass retry job fails, the JobID is used. However, if the JobID does not correspond to the Workspace ID and ProductionID pair, only the WorkspaceID and ProductionID pair will be used for the mass retry operation; the JobID will not be retried.

 

The return type is MassRetryResult. MassRetryResult contains:

• int NumberOfJobsRequestedForRetry - the total number of retry jobs requested.
• int NumberOfJobsRetryWasRequestedSuccessfully - the total number of retry jobs successfully requested.
• List<RetryJobResult> RetryJobResults - a list of results for each job in the retry request. Results include:
  • WorkspaceID - the Workspace ID of the workspace.
  • ProductionID - the Production ID of the production.
  • JobID - the Job ID of the production job.
  • RetrySuccessfullySent - a boolean indicator of whether the retry job was successfully sent.
  • Errors - information about why the job failed.

• List<string> Errors - information about why the job failed.