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

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

  • IProductionManager – the interface defines the available methods for working with productions.
  • 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.
  • 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
  • ProductionJobResults – represents the result of a run or stage operation.
  • 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
  • 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.

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:

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 ProductionJobResults 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 Relativity 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 ProductionJobResults 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;

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