Connect to the Services API

You can connect to the Services API in different ways depending on the use case. In custom applications that run inside Relativity, you can connect to the Services API from agents, custom pages, or event handlers by using API Helpers to create the proxy. In standalone custom applications you must manually create the client proxy using Relativity service manager interfaces through the ServiceFactory class or using the RSAPIClient class. You can use token login and programmatically apply client-side overrides to certificate and identity configuration settings.

This page contains the following information:

• Connect from Relativity applications with API Helpers
• Connect from standalone applications
  • Connect with RSAPIClient proxy
  • Connect using ServiceFactory class

Connect from Relativity applications with API Helpers

The Relativity API Helpers simplify the creation of the RSAPIClient proxy in custom pages, event handlers, and agents used by Relativity applications by providing a helper method for this purpose. The CreateProxy() method is available on the IServicesMgr interface in the Relativity API namespace. In your code, call this method on the object returned by the GetServiceManager() method. GetServiceManager() is available on the agent, custom page, and event handler helper classes also provided in the Relativity API Helpers. This CreateProxy() method uses the ExecutionIdentity enumeration to specify the authentication type.

The ExecutionIdentity enumeration includes the CurrentUser, System, and Manual enums. The behavior of the CurrentUser and System enums differ by the context in which you use them as summarized in the following table:

The Manual enum on the ExecutionIdentity enumeration requires the consumer (such as an agent or event handler) to provide a username and password at login. After creating the proxy, you must call the LoginWithCredentials() method.

You can find code samples illustrating how to use the helper method and ExecutionIdentity enumeration on the following pages:

• Advanced agent code sample
• Advanced custom page code sample
• Pre Save event handlers and Pre Load event handlers (For a complete list of all event handlers with code samples, see Getting started with event handlers.)

Connect from standalone applications

To connect to the Services API from standalone custom applications (for example, desktop or console applications) you must manually create the client proxy.

Note: Before connecting to the Services API from a standalone application, make sure you have included references to the required libraries in your program. At a minimum, you need kCura.Relativity.Client and Relativity.Services.ServiceProxy.

The Services API supports the following transport protocols:

• HTTP
• HTTPs
• Net Named Pipes
• NetTCP

You can use these authentication methods with the Services API:

• User name-password
• Integrated Windows
• Token

Depending on what services you want to authenticate to, you can create the proxy by using the RSAPIClient class or the ServiceFactory class:

• The RSAPIClient class provides access to a large subset of the Services API operations. Use this class to create a proxy to interact with DTOs, search, and perform advanced operations.
• ServiceFactory class provides access to all Relativity Services API interfaces.
  • Use ServiceFactory to create proxies to any of the Relativity service interfaces. Service interfaces can only be accessed through ServiceFactory. You cannot access them through RSAPIClient.
    • IAnalyticsSearchManager
    • IClientManager
    • IdtSearchManager
    • IKeywordSearchManager
    • IMatterManager
    • INotificationManager
    • IPivotManager
    • IPermissionManager
    • IProductionManager
    • IProductionPlaceholderManager
  • You can also use ServiceFactory as another way of instantiating an RSAPIClient proxy. See examples in Connect using ServiceFactory

Connect with RSAPIClient proxy

The RSAPIClient class can be used to create a proxy to the Relativity Authentication, DataManipulation, SetExecutor, and FileTransfer services.

Basic login

The basic constructor for RSAPIClient accepts the System.URI object specifying the URI of the Service API instance and an AuthenticationType object.

• The URI string must be in the <protocol>://<host>/Relativity.Services format. All the following are valid URIs:
  Copy

  1
  2
  3
  4
  http://localhost/Relativity.Services
  https://myserver.mycompany.corp/Relativity.Services
  net.pipe://172.17.66.18/Relativity.Services
  net.tcp://127.0.0.1/Relativity.Services

• AuthenticationType object specifies the authentication method for the connection. Use one these child classes of AuthenticationType.
  • UsernamePasswordCredentials – authentication with Relativity user credentials.
  • IntegratedAuthCredentials – authentication with the current Windows user context.
  • TokenCredentials – authentication with a token.

The following is an example of using RSAPIClient to create the Services API proxy for an HTTP endpoint using user name and password authentication:

1
2
3
4
5
6
7
8
9
10
11
12
13

try
{
     using (IRSAPIClient proxy = 
          new RSAPIClient(new Uri("net.pipe://localhost/Relativity.Services"), new UsernamePasswordCredentials("relativity.user@relativity.com", "Pwd@1234")))
     {
          // Add your custom code.
     }
}
catch (Exception ex)
{
     Console.WriteLine(ex.Message);
}

This is an example of creating a proxy for a Net.Pipe endpoint with integrated Windows credentials:

1
2
3
4
5
6
7
8
9
10
11
12
13

try
{
     using (IRSAPIClient proxy = 
          new RSAPIClient(new Uri("net.pipe://localhost/Relativity.Services"), new IntegratedAuthCredentials()))
     {
          // Add your custom code.
     }
}
catch (Exception ex)
{
     Console.WriteLine(ex.Message);
}

After you instantiate the proxy, use its APIOptions.WorkspaceID property to set the Relativity workspace ID you want to access. Set the value to -1 to access Relativity in admin mode (to interact with master EDDS database).

1
proxy.APIOptions.WorkspaceID = 123456789;

After you set the APIOptions.WorkspaceID property, you can use the proxy to interact with Relativity objects.

Token login

Tokens can be an effective ways of managing user sessions, for example, in cases when it is necessary to switch users during a Services API session. Within the Relativity platform, you can use tokens for establishing connections in the following ways:

• Services API – To log in to the Services API, you create the proxy using the TokenCredential authentication type. You can also create a proxy and log in to the Services API by using the Relativity API Helpers. The helper classes facilitate creating the proxy and retrieving the session token from an agent, custom page, or event handler. They use this one-time session token as a parameter in the TokenLogin() method on the RSAPIClient class. As a best practice, use the helper classes to facilitating creating a proxy and authenticating to the Services API.
• Relativity – You can use a token to log in to the Relativity interface. The RSAPIClient class has the GenerateRelativityAuthenticationToken() method that you can use to obtain an authorization token for this purpose.

Note: To enable token login, you must set the TrustedIPsForTokenLogin configuration option value in the kCura.EDDS.Web section of the Instance setting table to include the IP address used to access the URL, or a value of ‘any’ to allow all IP addresses. For more information about the Instance setting table, see the Instance setting table on the Relativity Documentation site..

You can perform a token login by creating the proxy with the TokenCredential authentication type. When you specify the AuthenticationType, the proxy automatically logs in to the Services API so you don't need to call a login method.

The following code sample illustrates how to use this authentication type when creating the proxy.

1
2
3
4
5
6
7
8
9
10
11
12
13

try
{
     using (IRSAPIClient proxy = 
          new RSAPIClient(new Uri("http://localhost/Relativity.Services"), new TokenCredentials(token)))
     {
          // Add your custom code.
     }
}
catch (Exception ex)
{
          Console.WriteLine(ex.Message);
}

Note: You can also append this authorization token to an HTTP query string as authToken=<value>. See REST API Authentication.

APIOptions class

The APIOptions class controls who makes a call for any given method, where this user is making the call to, and how that call behaves. The members of this class include the following properties:

• Token – represents an authenticated user. This property is automatically populated with a token value when the user is authenticated so you don’t need to explicitly call a login method. However, if you want to switch to another user, you can call the Login(), LoginWithCredentials(), or TokenLogin() to authenticated the new user.
• WorkspaceID – represents the unique identifier for a workspace in Relativity. A value of -1 indicates the master EDDS database.

• StrictMode – determines the convention used when returning or supplying fields to the Create(), Read(), Update(), Delete(), and Query() methods. When this field is True, a subset of fields (using consistent names and datatypes) are available across the various methods. Strict mode is enabled by default for the Services API DTOs.

RSAPIClientSettings class

You can programmatically set client-side configuration by passing an RSAPIClientSettings object to the overloaded constructor for the RSAPIClient class.

This RSAPIClientSettings class can be used to define the CertificateFindValue and the CertificateValidation settings. See Configure the Services API.

RSAPIClientServiceOperationFailed event

RSAPIClientServiceOperationFailed event is raised when the RSAPIClient throws an exception due to a failure or operation error. See RSAPIClientServiceOperationFailed event in the Services API class libraries.

Connect using ServiceFactory

ServiceFactory constructor takes an instance of the ServiceFactorySettings class.

Use the CreateProxy<T> method to return an instance of RSAPIClient or the specified Relativity service interface.

The following is an example of RSAPIClient proxy creation with ServiceFactory:

1
2
3
4
5
6
7
8
9
ServiceFactorySettings settings = new ServiceFactorySettings(
      new Uri("net.pipe://localhost/relativity.services/"), 
      new Uri("http://localhost/relativity.rest/api"), 
      new IntegratedAuthCredentials());

using (IRSAPIClient rsapiProxy = new ServiceFactory(settings).CreateProxy<IRSAPIClient>()) 
{
    //operations on IRSAPIClient
}

After you create the proxy, you can interact with it the same way as described in the Connect with RSAPIClient proxy section above.

This is an example of creating a proxy to dtSearch Manager service:

1
2
3
4
5
6
7
8
9
ServiceFactorySettings settings = new ServiceFactorySettings(
      new Uri("net.pipe://localhost/relativity.services/"), 
      new Uri("http://localhost/relativity.rest/api"), 
      new IntegratedAuthCredentials());

using (IdtSearchManager dtSearchProxy = new ServiceFactory(settings).CreateProxy<IdtSearchManager>())
{
     //operations on IdtSearchManager
}

After you create the proxy, you can use it to perform dtSearch Manager service operations.