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:
Complete the following prerequisites to begin working with Relativity production placeholders:
Download the Relativity SDK and the Productions SDK. See Download the SDKs and NuGet packages.
Use these guidelines when automating production workflows:
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.
Use these objects in the Relativity.Productions.Services namespace to interact Relativity placeholders:
For complete information about the objects available in the Relativity.Placeholders.Services namespace, see Productions API.
Follow these guidelines when setting the ProductionPlaceholder object properties when creating or updating placeholders:
To create a placeholder:
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);
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.
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 } } }
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 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 { 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(); }
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 }
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 } } } } }
To update a production placeholder:
ProductionPlaceholder placeholder = await productionPlaceholderManager.ReadSingleAsync(workspaceID, placeholderID);
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);
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 } } }
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(); }
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.
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 } } } } }
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 |