Instance Setting Manager API

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:

You can also use the Instance Setting Manager service through the REST API, which supports the same functionality available through .NET. For more information, see Instance Setting Manager service.

This page contains the following information:

Fundamentals for the Instance Settings Manager API

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

Methods

The Instance Setting Manager API exposes the following methods on the IInstanceSettingManager interface in the Relativity.Services.Interfaces.InstanceSetting namespace:

Classes and enumerations

The Instance Setting Manager API includes the following classes and enumeration available in the Relativity.Services.Interfaces.InstanceSetting.Model namespace:

Additionally, this API includes the following class in the Relativity.Services.Interfaces.InstanceSetting namespace:

Note: You can find information about running the following code samples in Relativity SDK samples. For information about the helper methods used in these code samples, see Helper methods in code samples.

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 a workspace ID of -1 and an InstanceSettingRequest object to it. The method returns the Artifact ID of the new instance setting. See the following code sample:

public async Task<bool> Create(Client.SamplesLibrary.Helper.IHelper helper)
{
    bool success = false;

    using (IInstanceSettingManager instanceSettingManager = helper.GetServicesManager().CreateProxy<IInstanceSettingManager>(ExecutionIdentity.User))
    {
        try
        {
            InstanceSettingRequest request = GetRequestTemplate();
            request.ValueType = InstanceSettingValueTypeEnum.Text;
            request.Value = "Sample Text Value";
            request.InitialValue = "Sample Text Initial Value";

            int artifactID = await instanceSettingManager.CreateAsync(ADMIN_WORKSPACE_ID, request);
            if (artifactID != 0)
            {
                DataHelper.DeleteData[Data.Constants.INSTANCE_SETTING_LIST].Add(artifactID);
                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 a workspace ID of -1 and the Artifact ID of an instance setting to this method. It returns an InstanceSettingResponse object.

The following code sample illustrates how to create an instance setting, and then read its properties.

public async Task<bool> Read(Client.SamplesLibrary.Helper.IHelper helper)
{
    bool success = false;

    using (IInstanceSettingManager instanceSettingManager = helper.GetServicesManager().CreateProxy<IInstanceSettingManager>(ExecutionIdentity.User))
    {
        int artifactID;

        try
        {
            InstanceSettingRequest request = GetRequestTemplate();
            request.ValueType = InstanceSettingValueTypeEnum.Integer32;
            request.Value = "32768";
            request.InitialValue = "16384";

            artifactID = await instanceSettingManager.CreateAsync(ADMIN_WORKSPACE_ID, request);
            DataHelper.DeleteData[Data.Constants.INSTANCE_SETTING_LIST].Add(artifactID);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Exception while creating Instance Setting");
            throw;
        }

        try
        {
            InstanceSettingResponse response = await instanceSettingManager.ReadAsync(ADMIN_WORKSPACE_ID, artifactID);
            if (response != null && response.ArtifactID == artifactID)
            {
                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 a workspace ID of -1 and an InstanceSettingRequest object to it. See the following code sample.

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.

public async Task<bool> Update(Client.SamplesLibrary.Helper.IHelper helper)
{
    bool success = false;

    using (IInstanceSettingManager instanceSettingManager = helper.GetServicesManager().CreateProxy<IInstanceSettingManager>(ExecutionIdentity.User))
    {
        string name = GenerateRandomName();
        int artifactID;

        try
        {
            InstanceSettingRequest request = GetRequestTemplate();
            request.ValueType = InstanceSettingValueTypeEnum.Integer64;
            request.Value = "-1";
            request.InitialValue = "0";

            artifactID = await instanceSettingManager.CreateAsync(ADMIN_WORKSPACE_ID, request);
            DataHelper.DeleteData[Data.Constants.INSTANCE_SETTING_LIST].Add(artifactID);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Exception while creating Instance Setting");
            throw;
        }

        try
        {
            InstanceSettingRequest request = new InstanceSettingRequest
            {
                ArtifactID = artifactID,
                Value = "2"
            };

            await instanceSettingManager.UpdateAsync(ADMIN_WORKSPACE_ID, request);
            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 a workspace ID of -1 and the Artifact ID of an instance setting to it. The following code sample illustrates how to create and then delete an instance setting.

public async Task<bool> Delete(Client.SamplesLibrary.Helper.IHelper helper)
{
    using (IInstanceSettingManager instanceSettingManager = helper.GetServicesManager().CreateProxy<IInstanceSettingManager>(ExecutionIdentity.User))
    {
        int artifactID;

        try
        {
            InstanceSettingRequest request = GetRequestTemplate();
            request.ValueType = InstanceSettingValueTypeEnum.TrueFalse;
            request.Value = "True";
            request.InitialValue = "False";

            artifactID = await instanceSettingManager.CreateAsync(ADMIN_WORKSPACE_ID, request);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Exception while creating Instance Setting");
            throw;
        }

        try
        {
            await instanceSettingManager.DeleteAsync(ADMIN_WORKSPACE_ID, artifactID);
        }
        catch (Exception ex)
        {
            DataHelper.DeleteData[Data.Constants.INSTANCE_SETTING_LIST].Add(artifactID);
            _logger.LogError(ex, "Exception while deleting Instance Setting");
            throw;
        }
    }
}

Helper methods in code samples

The code samples for the Instance Setting Manager API use the following helper methods to demonstrate how to make calls to this service:

Note: You can obtain the complete code sample by installing Relativity SDK samples.

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