Production Data Source Manager API

Production data sources associate productions with multiple sets of document returned by Relativity saved searches. Use the Services API to create, delete, read, and update data sources associated with productions. An equivalent set of operations with data sources is available in the Relativity REST API.

This page contains the following sections:

• Before you begin
• Create a data source
• Read a data source
• Update a data source
• Delete a data source

See these related pages:

• Production Manager API
• Production Placeholder Manager API

Before you begin

Complete the following prerequisites to begin working with Relativity production data sources:

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 ProductionDataSource objects. Catch any ServiceExceptions raised by your code as shown in the following code samples.
• If necessary, use logging for runtime debugging. For more information, see Log from a Relativity application .

Production data source fundamentals

Before programmatically interacting with production data sources, familiarize yourself with the Relativity productions user interface and review the information in the Relativity Documentation site. There is a strong correlation between the API operations, object properties, and the user interface elements.

Note: The user must have the permissions required for working with production data sources.

Key objects

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

• IProductionDataSourceManager – the interface defines asynchronous methods for working with data sources.
• ProductionDataSourceRef – represents a reference to a data source. ProductionDataSourceRef properties include only the Artifact ID and data source name.
• ProductionDataSource – represents a Relativity production data source, for example, as returned by the read operation. Properties include:
  • ArtifactID – production data source artifact ID.
  • ArtifactTypeID – the Relativity artifact type ID of the production data source.
  • BurnRedactions – tndicates whether or not to burn redactions when producing image type productions.
  • MarkupSet – markup set to be used with the DataSource
  • Name – descriptive name of the DataSource.
  • Placeholder – placeholder to be used with the DataSource.
  • PlaceholderFileData – the raw base64-encoded image data of the placeholder image.

    Note: The PlaceholderFileData property is available beginning in October 2017. The property is read-only and available only for data source associated with already produced productions. It is set internally during production run and cannot be altered. Setting the value on a data source object during a create or update causes an exception.

  • PlaceholderFileName – the file name of the placeholder image.

    Note: The PlaceholderFileName property is available beginning in October 2017. The property is read-only and available only for data source associated with already produced productions. It is set internally during production run and cannot be altered. Setting the value on a data source object during a create or update causes an exception.

  • PlaceholderFileSize – the size of the placeholder image.

    Note: The PlaceholderFileSize property is available beginning in October 2017. The property is read-only and available only for data source associated with already produced productions. It is set internally during production run and cannot be altered. Setting the value on a data source object during a create or update causes an exception.

  • PlaceholderFileID – the identifier of the placeholder image.

    Note: The PlaceholderFileID property is available beginning in October 2017. The property is read-only and available only for data source associated with already produced productions. It is set internally during production run and cannot be altered. Setting the value on a data source object during a create or update causes an exception.

  • ProductionType – type of production that applies to this data source. Valid values are defined by ProductionType enum.
  • SavedSearch – saved search containing documents to be produced.
  • UseImagePlaceholder – option for when to use image placeholder. Valid values are defined by UseImagePlaceholderOption enum.

    Note: ProductionDataSource object does not contain the information of the production associated with the data source, such as Artifact ID or name.

• UseImagePlaceholderOption – the enum defines valid values for Use Image Placeholder property. Values include:
  • 0 - NeverUseImagePlaceholder- never use image placeholder.
  • 1 - AlwaysUseImagePlaceholder- always use the image placeholder, even if image exists.
  • 2 - WhenNoImageExists- only use image placeholder when images do not exist.

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

Create a data source

To create a data source:

1. Instantiate a ProductionDataSource object and set the properties:

   1 2 3 4 5 6 7 8 9 10

   ProductionDataSource dataSource = new ProductionDataSource() {     Name                = "Excel Sheets",     SavedSearch         = new SavedSearchRef(savedSearchID),     ProductionType      = ProductionType.ImagesAndNatives,     UseImagePlaceholder = UseImagePlaceholderOption.WhenNoImageExists,     Placeholder         = new ProductionPlaceholderRef(placeholderID),     BurnRedactions      = true,     MarkupSet           =  new MarkupSetRef(markupSetID) };

2. Call the CreateSingleAsync() method of the IProductionDataSourceManager interface passing in the workspace Artifact ID, the artifact ID of the production, and a ProductionDataSource object. The operation returns the Artifact ID of the created production data source:

   int dataSourceID = await productionDataSourceManager.CreateSingleAsync(workspaceID, productionID, dataSource);

Read a data source

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

The returned ProductionDataSource object contains the data source information. You can use the information in further processing, for example to inspect the property values and determine whether the data source needs to be updated.

Beginning in October 2017, the ReadSingleAsync() method takes an additional optional parameter withPlaceholderImage with default value as false. This parameter indicates whether or not to return placeholder image content for the requested data source. The placeholder image is only available for data sources associated with already produced productions.

• withPlaceholderImage set to true – values for the read-only placeholder image properties are populated on data source object.
• withPlaceholderImage set to false (default) - values for the read-only placeholder image properties are not populated on data source object.

Update a data source

To update a data source:

1. Read an existing data source.

   ProductionDataSource productionDataSource = await productionDataSourceManager.ReadSingleAsync(workspaceID, dataSourceID);

2. Change the values of the properties on the returned object as necessary.

   1 2	productionDataSource.Name = "Updated datasource name"; productionDataSource.SavedSearch = new SavedSearchRef(savedSearchID);

3. Call the UpdateSingleAsync() method of the IProductionDataSourceManager interface passing in the workspace Artifact ID, the artifact ID of the production, and a ProductionDataSource object.

   1	await productionDataSourceManager.UpdateSingleAsync(workspaceID, productionID, productionDataSource);

Delete a data source

To delete a data source, call the DeleteSingleAsync() method of the IProductionDataSourceManager interface passing in the workspace Artifact ID and the Artifact ID of the data source.

Note: You cannot delete data sources from productions that have been produced.