Production Placeholder Manager API
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 Relativity 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 - Custom- uses custom text with rich formatting.
- 1 - Image- uses image files. Relativity supports TIF, JPEG, PNG, BMP, and GIF files for image placeholders.
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:
- 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."
};
- 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.
Complete create custom placeholder code sample
public async Task CreateCustomPlaceholder_Example()
{
var workspaceID = 11111;// ArtifactID of Workspace where Placeholder exists
var userName = "user@test.com";// User's login
var userPassword = "abc123456!";// User's password
var relativityRestUri = @"http://localhost/relativity.rest/api";
var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, userPassword);
ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityRestUri), usernamePasswordCredentials);
ServiceFactory serviceFactory = new ServiceFactory(settings);
using (IProductionPlaceholderManager productionPlaceholderManager = serviceFactory.CreateProxy<IProductionPlaceholderManager>())
{
try
{
ProductionPlaceholder placeholder = new ProductionPlaceholder()
{
Name = "Placeholder for excel sheets",
PlaceholderType = PlaceholderType.Custom,
CustomText = "This is an excel sheet."
};
placeholder.ArtifactID = await productionPlaceholderManager.CreateSingleAsync(workspaceID, placeholder);
}
catch (Relativity.Services.Exceptions.ServiceException)
{
// Log exception details
}
}
}
Complete create image placeholder code sample
public async Task CreateImagePlaceholder_Example()
{
var workspaceID = 11111;// ArtifactID of Workspace where Placeholder exists
var userName = "user@test.com";// User's login
var userPassword = "abc123456!";// User's
var relativityRestUri = @"http://localhost/relativity.rest/api";
var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, userPassword);
ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityRestUri), usernamePasswordCredentials);
ServiceFactory serviceFactory = new ServiceFactory(settings);
string fileLocation = @"\\servername\share\Placeholder.jpg";
string filename = Path.GetFileName(fileLocation);
byte[] fileData = ReadFully(fileLocation);
using (IProductionPlaceholderManager productionPlaceholderManager = serviceFactory.CreateProxy<IProductionPlaceholderManager>())
{
try
{
ProductionPlaceholder placeholder = new ProductionPlaceholder()
{
Name = "Placeholder for excel sheets",
PlaceholderType = PlaceholderType.Image,
Filename = filename,
FileData = fileData
};
placeholder.ArtifactID = await productionPlaceholderManager.CreateSingleAsync(workspaceID, placeholder);
}
catch (Relativity.Services.Exceptions.ServiceException)
{
// Log exception details
}
}
}
private byte[] ReadFully(string fileLocation)
{
MemoryStream ms = new MemoryStream();
byte[] buffer = new byte[16 * 1024];
int read;
using (FileStream reader = new FileStream(fileLocation, FileMode.Open))
{
while ((read = reader.Read(buffer, 0, buffer.Length)) > 0)
{
ms.Write(buffer, 0, read);
}
}
return ms.ToArray();
}
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
}
Complete read placeholder code sample
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Relativity.Productions.Services;
using Relativity.Services.ServiceProxy;
namespace Relativity.Productions.Documentation.Samples.ProductionPlaceholderManager
{
public class ReadPlaceholder
{
public async Task ReadPlaceholder_Example()
{
int workspaceID = 11111; // Workspace where Placeholder exists
int placeholderID = 22222; // Placeholder ArtifactID to read
var userName = "user@test.com"; // User's login
var userPassword = "abc123456!"; // User's password
var relativityRestUri = @"http://localhost/relativity.rest/api";
var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, userPassword);
ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityRestUri), usernamePasswordCredentials);
ServiceFactory serviceFactory = new ServiceFactory(settings);
using (IProductionPlaceholderManager productionPlaceholderManager = serviceFactory.CreateProxy<IProductionPlaceholderManager>())
{
try
{
ProductionPlaceholder productionPlaceholder = await productionPlaceholderManager.ReadSingleAsync(workspaceID, placeholderID);
if (productionPlaceholder.PlaceholderType == PlaceholderType.Custom)
{
// Read the custom text
}
// Use productionPlaceholder in a SaveSingleAsync call to update its contents
}
catch (Relativity.Services.Exceptions.ServiceException)
{
// Log exception details
}
}
}
}
}
Update a placeholder
To update a production placeholder:
- Read an existing placeholder.
ProductionPlaceholder placeholder = await productionPlaceholderManager.ReadSingleAsync(workspaceID, placeholderID);
- 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>";
- 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);
Complete update custom placeholder code sample
public async Task UpdateCustomPlaceholder_Example()
{
var workspaceID = 11111; // ArtifactID of Workspace where Placeholder exists
int placeholderID = 22222; // ArtifactID of Custom Placeholder to update
var userName = "user@test.com"; // User's login
var userPassword = "abc123456!"; // User's password
var relativityRestUri = @"http://localhost/relativity.rest/api";
var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, userPassword);
ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityRestUri), usernamePasswordCredentials);
ServiceFactory serviceFactory = new ServiceFactory(settings);
using (IProductionPlaceholderManager productionPlaceholderManager = serviceFactory.CreateProxy<IProductionPlaceholderManager>())
{
try
{
// Read the placeholder you would like to update, so we get the fully filled object
ProductionPlaceholder placeholder = await productionPlaceholderManager.ReadSingleAsync(workspaceID, placeholderID);
// Update the placeholder (change the name, change the custom text)
placeholder.Name = "Placeholder for excel sheets - No redactions";
placeholder.CustomText = "<P><B>This is an excel sheet for document: [Control Number].</B></P>";
await productionPlaceholderManager.UpdateSingleAsync(workspaceID, placeholder);
}
catch (Relativity.Services.Exceptions.ServiceException)
{
// Log exception details
}
}
}
Complete update image placeholder code sample
public async Task UpdateImagePlaceholder_Example()
{
var workspaceID = 11111; // ArtifactID of Workspace where Placeholder exists
int placeholderID = 33333; // ArtifactID of Image Placeholder to update
var userName = "user@test.com"; // User's login
var userPassword = "abc123456!"; // User's password
var relativityRestUri = @"http://localhost/relativity.rest/api";
var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, userPassword);
ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityRestUri), usernamePasswordCredentials);
ServiceFactory serviceFactory = new ServiceFactory(settings);
string fileLocation = @"\\servername\share\Placeholder.jpg";
string filename = Path.GetFileName(fileLocation);
byte[] fileData = ReadFully(fileLocation);
using (IProductionPlaceholderManager productionPlaceholderManager = serviceFactory.CreateProxy<IProductionPlaceholderManager>())
{
try
{
// Read the placeholder you would like to update, so we get the fully filled object
ProductionPlaceholder placeholder = await productionPlaceholderManager.ReadSingleAsync(workspaceID, placeholderID);
// Update the placeholder (change the name, change uploaded image)
fileLocation = @"\\servername\share\ReplacementPlaceholder.jpg";
filename = Path.GetFileName(fileLocation);
fileData = ReadFully(fileLocation);
placeholder.Name = "Placeholder for excel sheets - No redactions";
placeholder.Filename = filename;
placeholder.FileData = fileData;
await productionPlaceholderManager.UpdateSingleAsync(workspaceID, placeholder);
}
catch (Relativity.Services.Exceptions.ServiceException)
{
// Log exception details
}
}
}
private byte[] ReadFully(string fileLocation)
{
MemoryStream ms = new MemoryStream();
byte[] buffer = new byte[16 * 1024];
int read;
using (FileStream reader = new FileStream(fileLocation, FileMode.Open))
{
while ((read = reader.Read(buffer, 0, buffer.Length)) > 0)
{
ms.Write(buffer, 0, read);
}
}
return ms.ToArray();
}
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.
Complete delete placeholder code sample
using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using Relativity.Productions.Services;
using Relativity.Services.ServiceProxy;
namespace Relativity.Productions.Documentation.Samples.ProductionPlaceholderManager
{
public class DeletePlaceholder
{
public async Task DeletePlaceholder_Example()
{
int workspaceID = 11111; // Workspace where Placeholder exists
int placeholderID = 22222; // Placeholder ArtifactID to delete
var userName = "user@test.com"; // User's login
var userPassword = "abc123456!"; // User's password
var relativityRestUri = @"http://localhost/relativity.rest/api";
var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, userPassword);
ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityRestUri), usernamePasswordCredentials);
ServiceFactory serviceFactory = new ServiceFactory(settings);
using (IProductionPlaceholderManager productionPlaceholderManager = serviceFactory.CreateProxy<IProductionPlaceholderManager>())
{
try
{
await productionPlaceholderManager.DeleteSingleAsync(workspaceID, placeholderID);
// Delete is successful if exception was not thrown
}
catch (Relativity.Services.Exceptions.ServiceException)
{
// Log exception details
}
}
}
}
}
