Instance Setting Manager (.NET)

The Instance Setting Manager API supports create, read, update, and delete operations in a Relativity environment. With the create method, you can set the value for the instance setting, and its initial or default value. For general information, see Instance settings on the Relativity Documentation site.

Sample use cases for the Instance Setting Manager API include:

  • Updating instance setting values to support behavior implemented by a custom application. You might implement a custom application that sends out email notifications and want to programmatically update the From and To fields on the messages by setting the EmailFrom and EmailTo instance settings.
  • Updating instance setting values to modify or customize existing Relativity behavior. For example, you might want to programmatically change the time frame for running off hour agents by updating the AgentOffHourEndTime and AgentOffHourStartTime instance settings.

You can also use the Instance Setting Manager service through REST. For more information, see Instance Setting Manager (REST).

Fundamentals for the Instance Settings Manager API

The Instance Setting Manager API contains the following methods, classes, and enumerations.

Create an instance setting

Instance settings are used to control specific behavior in Relativity, such as query time outs, time frames for running certain agents, and other configuration options. For more information and a list of available settings, see Instance settings on the Relativity Documentation site.

To create an instance setting, call the CreateAsync() method by passing an InstanceSettingRequest object to it. The method returns the Artifact ID of the new instance setting.

Copy 
public async Task<bool> Create(Relativity.Environment.V1.InstanceSetting.IInstanceSettingManager instanceSettingManagerProxy)
{
    bool success = false;
  
    try
    {
        InstanceSettingRequest request = GetRequestTemplate("SampleName", "SampleSection");
        request.ValueType = InstanceSettingValueTypeEnum.Text;
        request.Value = "Sample Text Value";
        request.InitialValue = "Sample Text Initial Value";
  
        int artifactID = await instanceSettingManagerProxy.CreateAsync(request);
        if (artifactID != 0)
        {
            _logger.LogDebug("Instance Setting has been created");
            success = true;
        }
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Exception while creating Instance Setting");
        throw;
    }
  
    return success;
}

Read an instance setting

Use the ReadAsync() method to retrieve the properties for an instance setting. Pass the Artifact ID of an instance setting to this method. It returns an InstanceSettingResponse object.

Copy
The following code sample illustrates how to create an instance setting, and then read its properties.
public async Task<bool> Read(Relativity.Environment.V1.InstanceSetting.IInstanceSettingManager instanceSettingManagerProxy, int artifactID)
{
    bool success = false;
 
    try
    {
        InstanceSettingResponse response = await instanceSettingManager.ReadAsync(artifactID);
        if (response != null && response.ArtifactID == artifactID)
        {
            _logger.LogDebug(string.Format("Retrieved an Instance Setting: section: '{0}', name: '{1}'", response.Section, response.Name));
            success = true;
        }
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Exception while reading Instance Setting");
        throw;
    }
  
    return success;
}

Update an instance setting

You can update the Machine, Value, Encrypted, Keywords and Notes properties of an instance setting. To update an instance setting, call the UpdateAsync() method by passing an InstanceSettingRequest object to it.

Additionally, you can restrict the update of an instance setting to the date that it was last modified, Pass the value of LastModifiedOn property as an argument to one of the overloaded update methods. You can get the value of this property from an InstanceSettingResponse object, which is returned by the ReadAsync() method.

Copy 
public async Task<bool> Update(Relativity.Environment.V1.InstanceSetting.IInstanceSettingManager instanceSettingManagerProxy, int artifactID)
{
    bool success = false;
 
    try
    {
        InstanceSettingRequest request = GetRequestTemplate("SampleName", "SampleSection");
        request.ValueType = InstanceSettingValueTypeEnum.Text;
        request.Value = "Modified Text Value";
        request.ArtifactID = artifactID;
  
        await instanceSettingManager.UpdateAsync(request);
        _logger.LogDebug("Updated an Instance Setting");
        success = true;
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Exception while updating Instance Setting");
    }
 
    return success;
}

Delete an instance setting

To delete an instance setting, call the DeleteAsync() method by passing the Artifact ID of an instance setting to it.

Copy
The following code sample illustrates how to create and then delete an instance setting
public async Task<bool> Delete(Relativity.Environment.V1.InstanceSetting.IInstanceSettingManager instanceSettingManagerProxy, int artifactID)
{
    bool success = false;
 
    try
    {
        await instanceSettingManager.DeleteAsync(artifactID);
        _logger.LogDebug("Deleted an Instance Setting");
        success = true;
    }
    catch (Exception ex)
    {
        _logger.LogError(ex, "Exception while deleting Instance Setting");
        throw;
    }
 
    return success;
}

Helper method in code samples

The code samples for the Instance Setting Manager API use the GetRequestTemplate() method as a helper for demonstrating calls to this service. This method sets general properties for a sample instance setting.

Copy 
private static InstanceSettingRequest GetRequestTemplate(string name, string section)
{
    return new InstanceSettingRequest
    {
        Name = name,
        Section = section,
        Machine = "",
        Encrypted = false,
        Description = "Sample Description",
        Keywords = "Sample Keywords",
        Notes = "Sample Notes"
    };
}