Federated Instance Manager (.NET)

Federated instances provide a way for administrators to manage a list of user displayed links to other Relativity instances. In the Relativity UI, links to federated instances appear in the User dropdown.

Federated instances in combination with an SSO configurations can enable users to seamlessly switch between multiple Relativity instances without the need to reenter their credentials.

The IFederatedInstanceManager interface allows you to programmatically interact with federated instances. Use this service when automating Relativity provisioning. Use this API after provisioning a Relativity instance to configure the Federated Instance to other Relativity instances.

You can also use the Federated Instance Manager REST service for cross-platform and browser-based applications. See Federated Instance Manager (REST).

Before programmatically interacting with federated instances, familiarize yourself with the Relativity federated instance user interface and review the information in the RelativityOne Documentation site . Note there is a strong correlation between the API operations and object properties and the user interface elements.

This page contains the following information:

Federated instance fundamentals

Use this guideline when working with federated instances:

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

Methods

The IFederatedInstanceManager interface contains the following methods:

• ReadAllAsync() - to read all federated instances defined for a Relativity instance, call the ReadAllAsync() method. This method returns a IReadOnlyCollection of federated instances. If there are no federated instances an empty list is returned.
• ReadAsync() - to read a single federated instance by name, call the ReadAsync() method and pass the name of the federated instance. This method returns a FederateInstance object with the specified name. A validation exception is returned if the named federated instance does not exist.
• CreateAsync() - To create a new federated instance, call the CreateAsync() method and pass it the FederatedInstance object. A validation exception is returned if required fields not populated or federated instance with name already exists.

• UpdateAsync() - updates a federated instance. A validation exception is returned if the required fields are not populated, federated instance does not exist or federated instance with updated name already exists.
  1. Update the InstanceUrl property on the FederatedInstance object. In this example, we add the HRD URL parameter to redirect the user to a Integrated Authentication provider:

     fedInstance.InstanceUrl = "http://myRelativity.com/Relativity?HRD=integrated"

     Note: You can't update the name of an existing federated instance.

  2. Call the UpdateAsync() method of the IFederatedInstanceManager interface and pass it the updated object:

     await fedInstanceManager.UpdateAsync(fedInstance);

• DeleteAsync() - to delete a federated instance, call the DeleteAsync() method and pass the name of the federated instance. A validation exception is returned if the federated instance does not exist.

Objects

• FederatedInstance - this object is comprised of the following required fields:
  • Name (string) - name of the Federated instance. This value is what will be displayed to Users. A federated instance name must be unique. The name can only contain alphanumeric characters and spaces.
  • InstanceUrl (System.Uri) - HTTP URL to the external Relativity Instance. The URL must include the http or https protocol prefix.

Code sample

This example demonstrates how to create a federated instance, update it to add the HRD redirect to the URL, and then delete it:

using (Relativity.Identity.{versionNumber}.Services.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);
    }
}