Production Manager API

The Services API supports operations with productions. You can use the API to create, read, stage, run, cancel, and delete existing productions to enable integration with other business processes and applications.

You can also work with productions using the Relativity REST API.

This page contains the following information:

See these related pages:

Before you begin

Complete the following prerequisites to begin working with Relativity productions:

Development guidelines

Use these guidelines when automating production workflows:

Productions fundamentals

Before programmatically interacting with productions, familiarize yourself with the Relativity productions user interface and review the information in the RelativityOne Documentation site. Note there is a strong correlation between the API operations and object properties and the user interface elements.

Use these guidelines when working with productions:

Production objects

Use these objects in the Relativity.Productions.Services namespace to interact with Relativity productions:

For complete information about the objects available in the Relativity.Productions.Services namespace, see Productions API.

Get all productions

To get a list of all productions a user has access to in a workspace, call the GetAllProductionsAsync() method of the IProductionManager interface passing in the workspace Artifact ID:

List<ProductionRef> listProductionRefResult;

...
listProductionRefResult = await productionManager.GetAllAsync(workspaceArtifactID);

This returns a list of ProductionRef objects containing the names and Artifact IDs of productions. You can use the information in further processing. For example, you can use the Artifact ID to read an individual production.

The GetAllProductionsAsync() method can take the DataSourceReadMode additional optional parameter. The parameter is set using the DataSourceReadMode enumeration:

Get produced productions from documents

Get produced productions from documents is a series of endpoints that you can use to retrieve information about productions that have already been produced in a workspace by passing either a list of document Artifact IDs or a mass operation database token corresponding to document Artifact IDs. The endpoints return 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.

Overloaded methods include:

A get produced productions from documents request returns the List<ProductionSlim> producedProductions object. Each ProductionSlim for a producedProduction contains the ArtifiactID, Name, BeginBates, EndBates, and DateProduced.

Get produced productions by passing a list of documents

If you want to retrieve information about productions that have already been produced in a workspace by passing a list of documents, use this overloaded method:

List<ProductionSlim> producedProductions = await productionManager.GetProducedProductionsFromDocumentsAsync(int workspaceId, IEnumerable<int> documentIds);

Note: This endpoint does not filter out productions that use Existing production numbering, which includes re-productions. For information on production numbering types, see Production sets.

This method requires you to pass the following parameters:

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

documentIDs

IEnumerable<int>

The Artifact IDs of documents.

Get produced productions that can be re-produced by passing a list of documents

If you want to retrieve information about productions that have already been produced in a workspace and that can be re-produced by passing a list of documents, use this overloaded method:

List<ProductionSlim> producedProductions = await productionManager.GetProducedProductionsFromDocumentsAsync(int workspaceId, IEnumerable<int> documentIds, bool excludeNonReproducible);

This method requires you to pass the following parameters:

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

documentIDs

IEnumerable<int>

The Artifact IDs of documents.

excludeNonReproducible boolean If true, only productions that can be re-produced will be returned. Productions that use Existing production numbering, which includes re-productions, are filtered out. For information on production numbering types, see Production sets.

Get produced productions by passing a database token

If you create a custom mass operation on the document object, you can pass the generated database token from the custom mass operation through this overloaded method to retrieve produced production information:

List<ProductionSlim> producedProductions = await productionManager.GetProducedProductionsFromDocumentsAsync(int workspaceId, string databaseToken);

Note: This endpoint does not filter out productions that use Existing production numbering, which includes re-productions. For information on production numbering types, see Production sets.

This method requires you to pass the following 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.

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.

Get produced productions that can be re-produced by passing a database token

If you create a custom mass operation on the document object, you can pass the generated database token from the custom mass operation through this overloaded method to retrieve information about produced productions that can be re-produced:

List<ProductionSlim> producedProductions = await productionManager.GetProducedProductionsFromDocumentsAsync(int workspaceId, string databaseToken, bool excludeNonReproducible);

This method requires you to pass the following 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.

excludeNonReproducible boolean If true, only productions that can be re-produced will be returned. Productions that use Existing production numbering, which includes re-productions, are filtered out. For information on production numbering types, see Production sets.

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.

Get production image metadata

You can use the GetProductionImagesAsync() method to retrieve metadata for production images. Overloaded methods include:

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.

Get metadata for specific production images

If you want to retrieve metadata for specific production images in the same workspace and production, use this overloaded method:

 ImageFilesResult result = await productionManager.GetProductionImagesAsync(int workspaceId, int productionId, list<int> documents);

This method requires you to pass the following parameters:

Parameter Data type Description
workspaceArtifactId int The Artifact ID of the workspace.
productionArtifactId int The Artifact ID of the production.
documents list<int> A list of document Artifact IDs.

Get metadata for every production image in a production

If you want to retrieve metadata for every produced file currently associated with a workspace and production, use this overloaded method:

PagedImageFilesResult result = await productionManager.GetProductionImagesAsync(int workspaceId, int productionId, int start, int length, int pageSize);

This method requires you to pass the following parameters:

Parameter Data type Description
workspaceArtifactId int The Artifact ID of the workspace.
productionArtifactId int The Artifact ID of the production.
start int The index (i.e. 1 is the first record) of the record you want from within the entire result set.
length int The number of results to return. Enter a value less than or equal to 0 to return the entire result set.
pageSize int The non-negative number of results returned in a single page.

This endpoint is paginated and has a maximum page size of 100,000 results. If results exceed 100,000, the endpoint returns a string URI of the previous and next pages. Use GetProductionImagesAsync(string pageUri) to go back and forth between paged results. See Get paged results from a previously called dataset.

Get paged results from a previously called dataset

If the results from GetProductionImagesAsync(int workspaceId, int productionId, int start, int length, int pageSize) exceed 100,000, use this overloaded method to go back and forth between the paged results:

PagedImageFilesResult result = await productionManager.GetProductionImagesAsync(string pageUri);

For example, if GetProductionImagesAsync(int workspaceId, int productionId, int start, int length, int pageSize) returns 3 pages of results, you can use the GetProductionImagesAsync(string pageUri) to retrieve pages 2 and 3.

This method requires you to pass the following parameter:

Parameter Data type Description
pageUri string The URI of the requested page.

Get production status details

To retrieve production status details, use the GetProductionStatusDetails() method:

ProductionStatusDetailsResult result = await productionManager.GetProductionStatusDetails(int workspaceId, int productionId);

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, use the GetProductionsEligibleForReproductionAsync() method and pass the workspace artifact ID, a re-production type, and a mass operation database token corresponding to document artifact IDs:

List<ProductionSlim> producedProductions = await productionManager.GetProductionsEligibleForReproductionAsync(int workspaceId, string databaseToken, reproductionType);

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 placeholder:

  1. Instantiate a Production object and set the properties depending on the type of production and numbering scheme. For more information, see Production objects.
    var production = new Production
    {
        Name = "Page Level Production Sample",
        Details = new ProductionDetails
        {
            DateProduced  = new DateTime(2016, 12, 12),
            EmailRecipients   = "pagelevelnumber@relativity.com; emosewa@gmail.com",
            ScaleBrandingFont = true,
            BrandingFontSize  = 25,
        },
    
        Numbering = new PageLevelNumbering
        {
            BatesPrefix= "ADBE",
            BatesSuffix= "DRAFT",
            BatesStartNumber   = 20,
            NumberOfDigitsForDocumentNumbering = 5
        },
    
        Footers = new ProductionFooters
        {
            LeftFooter = new HeaderFooter("Left Footer")
            {
                Type = HeaderFooterType.FreeText,
                FreeText = "This is confidential page"
            }
        },
    
        Keywords = "PageLevel, Complete Setting",
        Notes= "Page level numbering production"
    };
    
  2. Call the CreateSingleAsync() method of the IProductionManager interface passing in the workspace Artifact ID and the production object. The operation returns the Artifact ID of the created production:
    int productionId = await productionManager.CreateSingleAsync(workspaceId, production);
    

Read a production

To read a production, call the ReadSingleAsync() method of the IProductionManager interface passing in the workspace Artifact ID and the production Artifact ID:

Production production = await productionManager.ReadSingleAsync(workspaceId, productionId);

The returned Production object contains the Relativity production information. You can use the information in further processing. For example, you can read the Status field of the ProductionMetadata property to determine whether the production can be run.

var productionStatus = production.ProductionMetadata.Status;
if (productionStatus == ProductionStatus.New)
{
    // do something, like Stage this production
}

The GetAllProductionsAsync() method can take the DataSourceReadMode additional optional parameter. The parameter is set using the DataSourceReadMode enumeration:

Stage a production

To stage a production, call the StageProductionAsync() method of the IProductionManager interface passing in the workspace Artifact ID and the production Artifact ID:

Production production = await productionManager.StageProductionAsync(workspaceId, productionId);

The returned ProductionJobResult object represents the outcome of the stage operation. The information includes a flag indicating whether a staging job was successfully created in the queue, the job ID, and any messages and errors.

bool wasJobCreated = result.WasJobCreated;
int productionJobId = result.JobID;
List<string> messages = result.Messages;
List<string> errors = result.Errors;

Run a production

To run a production, call the RunProductionAsync() method of the IProductionManager interface passing in the workspace Artifact ID, the production Artifact ID, and Boolean values that specify whether to suppress warning messages and override production restrictions. For more information about production restrictions, see the RelativityOne Documentation site.

result = await productionManager.RunProductionAsync(workspaceId, productionJobId, suppressWarnings, overrideConfilcts);

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 will fail due to the production restrictions warning.

The returned ProductionJobResult object represents the outcome of the run. The information includes a flag indicating whether a production job was successfully created in the queue, the job ID, and any messages and errors.

bool wasJobCreated = result.WasJobCreated;
int productionJobId = result.JobID;
List<string> messages = result.Messages;
List<string> errors = result.Errors;

Mass stage and run productions

Use this endpoint to stage and run multiple productions in the same workspace with a single call. Overloaded methods include:

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.

Stage and run select productions

If you want to stage and run select productions in the same workspace with a single call, use this overloaded method:

IEnumerable<ProductionJobResult> results = await productionManager.MassStageAndRunProductionsAsync(int workspaceId, list<int> productionIds);

This method requires you to pass these parameters:

Parameter Data type Description
workspaceArtifactID int The Artifact ID of a workspace.
productionIDs List<int>

A list of all production artifact IDs to run. The productions can be in a state other than New. Production statuses include:

  • New, StagingError - Relativity will attempt to queue the production for a stage and run job.
  • Staged, ErrorStartingProduction - Relativity will attempt to queue the production for a run job.
  • Error - Relativity will attempt to queue the production for a rerun job.
    Notes:
  • Relativity recommends making sure that each production is in a good state before using the mass stage and run productions endpoint because the API is transactional. If one production in the request fails to queue, none of the productions in the request will queue. For example, if there are 3 productions in a mass stage and run production request and two productions succeed but the third cannot be queued, none of the productions in the request will succeed.
  • Although there is no limit on the number of productions that can be passed into a request, running the productions themselves is dependent on the environment, particularly the number of Production Manager agents available. For example, if your environment only has a few Production Manager agents and you queue 10 productions, the Production Manager agents may not have the capacity to run all 10 productions simultaneously; however, the Production Manager agents will eventually run all 10 productions without further user input.

Stage and run productions associated with a re-production job

If you want to stage and run productions associated with a re-production job, use this overloaded method:

IEnumerable<ProductionJobResult> results = await productionManager.MassStageAndRunProductionsAsync(int workspaceId, int reproductionJobId);

This method requires you to pass these parameters:

Parameter Data type Description
workspaceArtifactID int The Artifact ID of a workspace.
reproductionJobID int

The re-production job ID of a re-production job.

    Notes:
  • Relativity recommends making sure that each production is in a good state before using the mass stage and run productions endpoint because the API is transactional. If one production in the request fails to queue, none of the productions in the request will queue. For example, if there are 3 productions in a mass stage and run production request and two productions succeed but the third cannot be queued, none of the productions in the request will succeed.
  • Although there is no limit on the number of productions that can be passed into a request, running the productions themselves is dependent on the environment, particularly the number of Production Manager agents available. For example, if your environment only has a few Production Manager agents and you queue 10 productions, the Production Manager agents may not have the capacity to run all 10 productions simultaneously; however, the Production Manager agents will eventually run all 10 productions without further user input.

Cancel production jobs

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

The CancelJobAsync() and the MassCancelAsync() methods 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.

Cancel a single production job

To cancel a single staging or a production job, call the CancelJobAsync() method of the IProductionManager interface by passing a ProductionJobRef object to it.

await productionManager.CancelJobAsync(jobRef);

When instantiating a ProductionJobRef object, set the ProductionID and WorkspaceID properties, or set the JobID property. See the following sample code.

Note: To avoid unexpected results, don't set the ProductionID, WorkspaceID, and JobID properties on a single ProductionJobRef object. If the value for the JobID property doesn't correspond with the other properties in the ProductionJobRef object, then the cancel operation is attempted using only the ProductionID and WorkspaceID properties. If that operation fails, the cancel operation is attempted using only the JobID property.

Mass cancel production jobs

To cancel multiple staging or production jobs, call the MassCancelAsync() method by passing a list of ProductionJobRef objects to it.

await productionManager.MassCancelAsync(jobsToBeCanceled);

When instantiating a ProductionJobRef object, set the ProductionID and WorkspaceID properties, or set the JobID property. See the following sample code.

Note: To avoid unexpected results, don't set the ProductionID, WorkspaceID, and JobID properties on a single ProductionJobRef object. If the value for the JobID property doesn't correspond with the other properties in the ProductionJobRef object, then the cancel operation is attempted using only the ProductionID and WorkspaceID properties. If that operation fails, the cancel operation is attempted using only the JobID property.

Delete a production

To delete a production, call the RunProductionAsync() method of the IProductionManager interface passing in the workspace Artifact ID and the production Artifact ID.

await productionManager.DeleteSingleAsync(workspaceId, productionId);

Mass Retry production jobs

To retry multiple production error or delete jobs in a single call, use the MassRetryAsync() method:

MassRetryResult result = await productionManager.MassRetryAsync(list<ProductionJobRef> jobsToBeRetried);

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:

 

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