Production Manager (.NET)

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:

  • Add the Relativity.Productions.Services.Interfaces.dll reference to your Visual Studio project. You can find the file in the Production SDK.
  • Use a try-catch block around your code for reading objects and submitting jobs. Catch any ServiceExceptions that your code raises as shown in the following code samples.
  • If necessary, use logging for runtime debugging. For more information, see Log from a Relativity application.

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:

  • The user must have the permissions required for working with Relativity production and placeholder objects.
  • A production must be assigned a data source before it is staged. After you read a production, check the DataSources property.
  • A production that hasn't been staged cannot be run. Check the Status field of the ProductionMetadata property.
  • A produced production can't be rerun.

Production objects

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

  • DataSourceReadMode – the enumeration defines valid values for the optional DataSourceReadMode parameter when performing a read of Production object. Values include:
    • 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.
  • ImageFilesResult - metadata about produced images.
  • IProductionManager – the interface defines the available methods for working with productions.
  • jobsToBeRetried - 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.
  • PagedImageFilesResult - metadata about produced images.
  • PlaceholderImageFormat – the enumeration defines valid values for PlaceholderImageFormat property of the Production object. Values include:
    • 0 - Tiff – Brand placeholders as Group IV TIFF files
    • 1 - Jpeg – Brand placeholders as JPEG files
  • ProductionRef – represents a reference to a Relativity production. ProductionRef properties include only the Artifact ID and production name.
  • Production – represents a production, for example, as returned by the read operation.
    • ArtifactID – the Artifact ID of production.
    • PlaceholderImageFormat – a single-choice field specifying the placeholder image ( TIFF or JPEG) that is branded when the production is run. The value can be set when creating or updating a production using the PlaceholderImageFormat enumeration. The default is TIFF.

      Note: The PlaceholderImageFormat property is available beginning in October 2017.

    • DataSources – one or more data sources that hold the documents to be included in the production.
    • Details – production settings (correspond to the Production Details section of the Relativity UI).
    • Footers – describes what kind of information goes on the page footers.
    • Headers – describes what kind of information goes on the page headers.
    • Keywords – optional field for recording additional information associated with the production as keywords.
    • Name – descriptive name of reference
    • Notes – detailed description of the production.
    • Numbering – the numbering scheme for the production documents.
    • ProductionMetadata – production metadata. Relativity creates and updates the information in this object.
    • RelativityApplications – Relativity applications associated with this production.
    • ShouldCopyInstanceOnWorkspaceCreate – indicates whether the production should be copied when the containing workspace is used as a template for creating another workspace.
    • SortOrder – determines how the documents in the production will be sorted. A maximum of 5 sorts are allowed.
  • ProductionDataSource – represents a data source that holds the documents to be included in the production (based on a Relativity saved search). Referenced by the DataSources property of the Production class.
  • ProductionDetails – represents the details of a production as captured by the Production Details section on the Relativity UI. Referenced by the ProductionDetails property of the Production class.
  • ProductionFooters – represents the set of footers on the produced page. Referenced by the Footers property of the Production class.
  • ProductionHeaders – represents the set of headers on the produced page. Referenced by the Headers property of the Production class.
  • ProductionJobResult – represents the result of a run or stage operation.
    • JobID - the job ID of the production job.
    • Errors - error messages if job was not created.
    • Messages - informational messages about the job.
    • Warnings - warning messages about the job.
    • WasJobCreated - a boolean field specifying whether the job was created.
    • ProductionID - the Production ID of the production.
    • WorkspaceID - the Workspace ID where the production is located.
  • ProductionMetadata – metadata for the production created and updated by Relativity.
  • ProductionNumberingBase – base class representing the numbering scheme for production documents. The Numbering property of the Production class can be populated by one of the following classes that inherit from ProductionNumberingBase and represent a specific production numbering scheme:

    • DocumentFieldNumbering
    • DocumentLevelNumbering
    • ExistingProductionNumbering
    • OriginalImageNumbering
    • PageLevelNumbering
  • ProductionSlim - metadata about a produced production. Metadata includes:
    • ArtifactId - the Artifact ID of the produced production.
    • Name - the name of the produced production.
    • BeginBates - the first bates value of the produced production.
    • EndBates - the last bates value of the produced production.
    • DateProduced - the date the production was produced.
  • ReproductionJobResult - represents the result of a create a re-projection job operation.

    • ReproductionJobID - the re-production job ID.
    • ProductionsCreated - a list of the productions created from the re-production job.
      • InnerReproductionJobResult - information about the created production jobs.
        • ProductionID - the production ID of the production.

        • ParentProductionID - the production ID of the original production.

        • Errors - error messages if the production job was not created.

        • Warnings - warning messages about the production job.

        • Messages - informational messages about the production job.

    • WasJobCreated - a boolean value specifying whether the job was created.
      • Errors - error messages if the re-production job was not created.
      • Warnings - warning messages about the re-produciton job.
      • Messages - informational messages about the re-produciton job.
  • ReproductionStatus - the status of a re-production job. Statuses include:
    • Created - re-production job was been created, but not yet run.
    • Running - re-production job is currently running without errors.

      Note: A production status of Staged will result in a ReproductionStatus of Running because it is still a halfway step between New and Produced.

    • RunningWithErrors - re-production job is currently running but some productions have errored.
    • Completed - re-production job has completed all productions successfully.
    • CompletedWithErrors - re-production job has completed all productions, but some have errored.
    • DoesNotExist - invalid re-production job. If all productions in the re-production job have been deleted, a status of DoesNotExist will be returned.
  • ReproductionType - the type of re-production job. A re-production job can only have one type. 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.

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:

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

    Use this overloaded method to retrieve information about productions that have already been produced in a workspace by passing a list of documents. See Get produced productions by passing a list of documents

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

    Use this overloaded method to retrieve information about productions that have already been produced in a workspace and that can be re-produced by passing a list of document Artifact IDs. See Get produced productions that can be re-produced by passing a list of documents

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

    Use this overloaded method to retrieve produced production information by passing a database token corresponding to document Artifact IDs. See Get produced productions by passing a database token

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

    Use this overloaded method to retrieve information about produced productions that can be re-produced by passing a database token corresponding to document Artifact IDs. See Get produced productions that can be re-produced by passing a database token

    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.

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:

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

    Use this overloaded method to retrieve metadata for specific production images in the same workspace and production. See Get metadata for specific production images.

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

    Use this overloaded method to retrieve metadata for every produced file currently associated with a workspace and production. See Get metadata for every production image in a production.

    If the returned dataset is too large for a single page of results, the method returns a pageUri that links to the next pages. To view subsequent pages, use GetProductionImagesAsync(string pageUri). See Get paged results from a previously called dataset.

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

      Use this overloaded method to go back and forth between paged results from a dataset called with GetProductionImagesAsync(int workspaceId, int productionId, int start, int length, int pageSize). See Get paged results from a previously called dataset.

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:

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

    Use this overloaded method to stage and run select productions in the same workspace with a single call. See Stage and run select productions.

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

    Use this overloaded method to stage and run productions associated with a re-production job. See Stage and run productions associated with a re-production job.

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);
    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.

 

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