Instance Setting Manager (.NET)

The Instance Setting Manager API exposes the following methods on the IInstanceSettingManager interface in the Relativity.Services.Environment.<VersionNumber>.InstanceSetting namespace.

Note: The <VersionNumber> variable indicates the version number of the API. The version number uses the format uppercase V and an integer version number, such as V1 in .NET.

• CreateAsync() method - adds a new instance setting to a Relativity environment. This method takes an InstanceSettingRequest object as an argument. It returns the Artifact ID of the new instance setting. See Create an instance setting.
• DeleteAsync() method - removes an instance setting from a Relativity environment. It takes the Artifact ID of an instance setting. This method returns a task. See Delete an instance setting.
• ReadAsync() method - retrieves the properties for an instance setting. This method takes the Artifact ID of an instance setting as an argument. It returns a InstanceSettingResponse object. See Read an instance setting.
• UpdateAsync() method - modifies Machine, Value, Encrypted, Keywords and Notes properties on an instance setting. This method takes an InstanceSettingRequest object, and an optional DateTime object to restrict the update to the date last modified. This method returns a task. See Update an instance setting.

The Instance Setting Manager API includes the following classes and enumeration:

• InstanceSettingRequest class - represents the data used to create or update an instance setting. Its properties include the name of the instance setting, its value and a default value, and others. The CreateAsync() and UpdateAsync() methods take an object of this type.
• InstanceSettingResponse class - represents the response from a read operation. Its properties include the name of an instance setting, its Artifact ID, the section of the Instance settings table where it exists, and others. See InstanceSettingResponse Class.
• InstanceSettingValueTypeEnum enumeration - indicates the value type of an instance setting, such as text, Integer32, TrueFalse, or other. See InstanceSettingValueTypeEnum Enumeration.

To use this endpoint, the caller must have the following:

• Add permissions for the instance setting set at the instance level. See Instance security on the RelativityOne Documentation site.

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

To use this endpoint, the caller must have the following:

• View permissions for instance settings set at the instance level. See Instance security on the RelativityOne Documentation site.

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

To use this endpoint, the caller must have the following:

• Edit permissions for instance settings set at the instance level. See Instance security on the RelativityOne Documentation site.

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

To use this endpoint, the caller must have the following:

• Delete permissions for instance settings set at the instance level. See Instance security on the RelativityOne Documentation site.

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

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