Production Placeholder Manager (.NET)

You can use the Services API to create, delete, read, and update placeholders that can then be added to productions. An equivalent set of operations with placeholders is available in 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 production placeholders:

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 interacting with ProductionPlaceholder objects. 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.

Placeholder fundamentals

When you create a production placeholder, you can either upload image data for the placeholder as the FileData property, or use HTML-formatted text as the CustomText property. Both of these types of inputs get converted into a JPG image and stored into a File-type field on the ProductionPlaceholder object. A production can then be set up to use this placeholder.

Note: The user must have the permissions required for working with placeholders.

Before programmatically interacting with production placeholders, familiarize yourself with the Relativity productions user interface and review the information in the RelativityOne Documentation site. A strong correlation exists between the API operations, object properties, and the user interface elements.

Key objects

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

  • IProductionPlaceholderManager – the interface defines asynchronous methods for working with placeholders.
  • ProductionPlaceholderRef – represents a reference to a placeholder. ProductionRef properties include only the Artifact ID and placeholder name.
  • ProductionPlaceholder – represents a Relativity production placeholder, for example, as returned by the read operation.
    • ArtifactID – artifact ID of the placeholder.
    • ArtifactTypeID – the Relativity artifact type ID of the placeholder.
    • CustomText – the custom HTML text of the placeholder.
    • FileData – the contents of the placeholder image.
    • FileID – the internal identifier of the placeholder preview image.
    • Filename – the file name of the placeholder image.
    • FileSize – the size of the uploaded file.
    • Name – descriptive name of the placeholder.
    • PlaceholderType – the type of the placeholder. Valid values are defiend by the PlaceholderType enum
  • PlaceholderType – the enumeration defines valid values for placeholder type. Values include:
    • 0 - Image- uses image files. Relativity supports TIF, JPEG, PNG, BMP, and GIF files for image placeholders.
    • 1 - Custom- uses custom text with rich formatting.

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

Placeholder properties

Follow these guidelines when setting the ProductionPlaceholder object properties when creating or updating placeholders:

  • You can't change placeholder type for an existing placeholder.
  • If PlaceholderType is Custom, then you must specify the CustomText. It is possible to create a blank placeholder using a CustomText with an empty string.
  • When updating an existing custom placeholder, include the PlaceholderType property.
  • Custom text is specified with HTML formatting. You can also add any document field or Bates number field to stamp on the placeholder. The field name inserts into your custom placeholder, but when you start the production, the field name dynamically updates per document. For example, [ControlNumber] updates with the control number field for the document the placeholder corresponds to. Custom type placeholders support document fields using the field name surrounded by brackets: [Document Field Name]. To include a square bracket as part of the placeholder text, you must escape the square bracket with a backslash: \[ Document Field Name\]
  • If PlaceholderType is Image, then you must specify the FileData and Filename properties when creating and updating a placeholder.
  • FileData must contain raw base64-encoded image data.

Create a placeholder

To create a placeholder:

  1. Instantiate a ProductionPlaceholder object and set the properties:
    ProductionPlaceholder placeholder = new ProductionPlaceholder()
    {
        Name = "Placeholder for excel sheets",
        PlaceholderType = PlaceholderType.Custom,
        CustomText = "This is an excel sheet."
    };
  2. Call the CreateSingleAsync() method of the IProductionPlaceholderManager interface passing in the workspace Artifact ID and the production placeholder object. The operation returns the Artifact ID of the created production placeholder.
    placeholder.ArtifactID = await productionPlaceholderManager.CreateSingleAsync(workspaceID, placeholder);

Note: If PlaceholderType is Custom, then you must specify the CustomText. It is possible to create a blank placeholder using a CustomText with an empty string. If PlaceholderType is Image, then you must specify the FileData and Filename properties.

Read a placeholder

To read a placeholder, call the ReadSingleAsync() method of the IProductionPlaceholderManager interface passing in the workspace Artifact ID and the Artifact ID of the production.

ProductionPlaceholder productionPlaceholder = await productionPlaceholderManager.ReadSingleAsync(workspaceID, placeholderID);

The returned ProductionPlaceholder object contains the placeholder information. You can use the information in further processing. For example, you can inspect the value of the PlaceholderType property to determine whether the placeholder is image or custom text.

if (productionPlaceholder.PlaceholderType == PlaceholderType.Custom)
{
   // Read the custom text
}

Update a placeholder

To update a production placeholder:

  1. Read an existing placeholder.
    ProductionPlaceholder placeholder = await productionPlaceholderManager.ReadSingleAsync(workspaceID, placeholderID);
  2. Change the values of the properties on the returned object as necessary.
    placeholder.Name = "Placeholder for excel sheets - No redactions";
    placeholder.CustomText = "<P><B>This is an excel sheet for document: [Control Number].</B></P>";			
  3. Call the UpdateSingleAsync() method of the IProductionPlaceholderManager interface passing in the workspace Artifact ID and the placeholder object with changed property values.
    await productionPlaceholderManager.UpdateSingleAsync(workspaceID, placeholder);

Delete a placeholder

To delete a placeholder, call the DeleteSingleAsync() method of the IProductionPlaceholderManager interface passing in the workspace Artifact ID and the Artifact ID of the production.

await productionPlaceholderManager.DeleteSingleAsync(workspaceID, placeholderID);

Note: You can delete placeholders that production data sources are using.

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