Federated Instance Manager (.NET)

Federated instances enable users to easily switch between different Relativity environments using single sign-on. Relativity admins can manage the list of links to other environments displayed to the user in the UI. For more information, see Federated instances in the RelativityOne Documentation site.

The Federated Instance Manager API supports CRUD operations on federated instances. You can use this API after configuring a Relativity environment to use federated instances. For example, you can retrieve a list of all federated instances defined for a Relativity environment.

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

This page contains the following information:

The Relativity.Identity.SDK contains this API. For compatibility and package installation instructions, see Download the SDKs and NuGet packages.

Fundamentals for the Federated Instance Manager API

Review the following information to learn about the methods and classes used by the Federated Instance Manager API.

Guidelines for the Federated Instance Manager API

Review the following guidelines for the Federated Instance Manager API.

Calls to the UpdateAsync() method

Use these steps when modifying a federated instance:

  1. Update the InstanceUrl property on the FederatedInstance object. This code sample uses the HRD URL parameter to redirect the user to an Integrated Authentication provider:
  2. fedInstance.InstanceUrl = "http://myRelativity.com/Relativity?HRD=integrated"

    Note: You cannot update the name of an existing federated instance.

  3. Call the UpdateAsync() method and pass it the updated object:
  4. await fedInstanceManager.UpdateAsync(fedInstance);

Code sample

The following code sample illustrated how to create a federated instance and add a HRD redirect to the URL.

Note: The Relativity user accessing the API must have the permissions for working with federated instance objects.

using (IFederatedInstanceManager federatedInstanceManager = new ServiceFactory(settings).CreateProxy<IFederatedInstanceManager>())
    IReadOnlyCollection<FederatedInstance> federatedInstances = await federatedInstanceManager.ReadAllAsync();
    FederatedInstance expectedInstance = new FederatedInstance() {
        Name = "Other Instance",
        InstanceUrl = new Uri("https://otherInstance.com/Relativity") }
    if (!federatedInstances.ToList().Exists(x => x.Name.Equals(expectedInstance.Name)))
        await federatedInstanceManager.CreateAsync(expectedInstance);