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:

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:

Instantiate a ProductionDataSource object and set the properties:

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

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

Complete create data source code sample

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using Relativity.Productions.Services;
using Relativity.Services.Search;
using Relativity.Services.ServiceProxy;

namespace Relativity.Productions.Documentation.Samples.ProductionDataSourceManager
{
    public class CreateDataSource
    {
        public async Task CreateDataSource_Example()
        {
            var workspaceID   = 11111;            // ArtifactID of Workspace where Data source will be saved
            var productionID  = 22222;            // ArtifactID of Production to add the new data source to
            var placeholderID = 33333;            // ArtifactID of Placeholder to use with this data source
            var savedSearchID = 44444;            // ArtifactID of Saved Search containing documents for this data source
            var markupSetID   = 55555;            // ArtifactID of Markup Set to use for burning redactions
            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 (IProductionDataSourceManager productionDataSourceManager = serviceFactory.CreateProxy<IProductionDataSourceManager>())
            {
                try
                {
                    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)
                    };
                    dataSource.ArtifactID = await productionDataSourceManager.CreateSingleAsync(workspaceID, productionID, dataSource);

                }
                catch (Relativity.Services.Exceptions.ServiceException)
                {
                    // Log exception details
                }
            }
        }
    }
}

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.

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

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.

if (productionDataSource.UseImagePlaceholder == UseImagePlaceholderOption.WhenNoImageExists)
{
	// Read the placeholder, etc
}

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:

Read an existing data source.

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

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

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

Call the UpdateSingleAsync() method of the IProductionDataSourceManager interface passing in the workspace Artifact ID, the artifact ID of the production, and a ProductionDataSource object.
```
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.

await productionDataSourceManager.DeleteSingleAsync(workspaceID, dataSourceID);

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

Additional Resources
DevHelp Community	GitHub	Release Notes	NuGet
Share knowledge with the Relativity developer community.	Access tools and resources to build an application.	Review the most recent product release notes.	Create .NET Apps faster with NuGet.