Configure the Services API

The Services API is installed on the Relativity web server as an additional IIS application called Relativity.Services. When you install Relativity on your web server, the installer automatically configures the Services API to use Net.Pipe. WCF is a prerequisite for running Relativity Services and it is also automatically configured by the installer.

Note: You don’t need to complete any additional configuration steps for the Services API unless you want to use HTTPS or customize the client and server configuration using the CertificateFindValue setting. You may also need to configure Net.Pipe on the IIS if you ran the Relativity installer before rebooting your machine after Windows updates were installed. If Windows Server networking and communication components (for example, WCF) are not configured correctly by the Relativityinstaller, you may subsequently experience problems accessing RelativityServices. In these cases manual setup is required.

Most of the configuration of Relativity.Services is determined by the settings in the web.config file of the Relativity.Services virtual directory. A few of the configuration options are controlled in IIS. The configuration process includes configuring settings in IIS, testing the connectivity to the Services API, and troubleshooting the configuration settings.

You can use configuration overrides to enter custom values for endpoint configurations. In general, you will probably don't need to override the default configuration values.

This page contains the following information:

• Manually configure the Services API for the Relativity platform
• Set client configuration overrides
• Set server configuration overrides
• Server-side override values
• Override configuration references

See these related pages:

• Troubleshoot the Services API configuration

Manually configure the Services API for the Relativity platform

If you need to configure the Services API manually, use these guidelines to set up components available with the Relativity Server2021 platform.

Agents

• Services API Hosting – Self-hosted or on IIS (if available on your server)
• Relativity.Services URL – Use method on Relativity API Helpers to return URL.
• Transport Protocol – Net.Pipe
• Authentication method – We recommend Windows authentication over token authentication, which has increased overhead.

Custom pages or event handlers (except Pre and Post Install)

• Services API Hosting – Locally through IIS. The Relativity installer automatically adds the Services API to the web server. (Pre and Post Install event handlers don’t require a connection to the Services API.)
• Relativity.Services URL – Use method on Relativity API Helpers to return URL.
• Transport Protocol – Net.Pipe
• Authentication method – Use Windows authentication for full access as the service account or use token authentication for an audited, secure, and user-aware context.

Pre and Post Install event handlers

• Services API Hosting – Self-hosted or on IIS (The method for hosting the Services API depends on whether an agent or Procuro runs the Pre and Post event handlers, or whether they are run from the web server.)
• Relativity.Services URL – Use method on Relativity API Helpers to return URL.
• Transport Protocol – Net.Pipe
• Authentication method – Use Windows authentication for full access as the service account.

Applications

Services API Hosting – Host remotely.

Note: Due to certificate issues, the Services API shouldn't be hosted remotely for agents, custom pages, and event handlers. If you must use this configuration, use HTTPS as the transport protocol. In addition, use Windows authentication for full access as a service, or use Active Directory authentication by calling the LoginWithCredentials() method, and passing a username and password.

Service endpoints configuration options

The handling of incoming requests to Relativity REST services and the Kepler subset of the Services API is determined by the following options in the Instance setting table. For more information, see Instance settings on the Relativity Documentation site.

• KeplerServicesUri – The URL at which Relativity custom pages and event handlers can access the Services API Kepler services using API helpers. The default value is http://localhost/Relativity.Rest/API.
• KeplerServicesUriForAgents – The URL at which Relativity agents can access local Services API Kepler services using API helpers. The default port number (8990) can be changed if there is a port conflict with some other server application.

The default values of these configuration options should be changed only if your network configuration, for example, in the hosts file, prevents requests to the API service endpoints from being routed correctly.

Set client configuration overrides

Client configuration settings override single values. However, they don’t override all configuration values as a custom service and endpoint configuration would. You can programmatically apply configuration overrides in a client-side application by using the RSAPIClientSettings class.

The available client configuration overrides share the same name as server-side configuration overrides. Even though the names are the same, these values apply only to either the server or the client. Configuration issues may occur if a value configured on the client-side conflicts with that configured on the server-side, or vice versa. Ensure that the configuration override values on the client and server match.

To modify configuration settings programmatically, override the properties available on the RSAPIClientSettings class.

The following list includes the available override settings for the client:

Set server configuration overrides

You can configure single value or service-wide overrides on the server hosting the Services API. You can use single override values for all five of the services: Authentication, DataManipulation, FileTransfer, SetExecutor, and WorkspaceManager. These override values are configured in the kCura.Authentication.Config, kCura.DataManipulation.Config, kCura.FileTransfer.Config, kCura.SetExecutor.Config, and kCura.WorkspaceManager.Config sections, respectively. An additional configuration section called relativity.commonServiceValues.Config contains configuration values that apply equally to all services.

1. Navigate to the Services API web.config in the following directory on the server:

   <YourInstallationDirectory>\kCura Corporation\Relativity\Relativity.Services

2. Open the web.config in a text or other editor.
3. Locate the <configSections>…</configSections> tags in the file.
4. Define the configuration override settings for each of the configuration sections between these tags. See the following example:

   <configSections>
        <section name="kCura.Config" type="System.Configuration.DictionarySectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
        <section name="kCura.Authentication.Config" type="System.Configuration.DictionarySectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
        <section name="kCura.DataManipulation.Config" type="System.Configuration.DictionarySectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
        <section name="kCura.FileTransfer.Config" type="System.Configuration.DictionarySectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
        <section name="kCura.SetExecutor.Config" type="System.Configuration.DictionarySectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
        <section name="relativity.commonServiceValues.Config" type="System.Configuration.DictionarySectionHandler, System, Version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089"/>
        <section name="customBasicAuthentication" type="Thinktecture.CustomBasicAuthentication.CustomBasicAuthenticationSection, Thinktecture.CustomBasicAuthenticationModule"/>
   </configSections>
   <kCura.Config>
        <add key="encryptedConnectionString" value="…"/>
   </kCura.Config>
   <relativity.commonServiceValues.Config>
        <add key="ExceptionDetailsInFaults" value="true"/>
   </relativity.commonServiceValues.Config>
   <kCura.Authentication.Config>
   </kCura.Authentication.Config>
   <kCura.DataManipulation.Config>
   </kCura.DataManipulation.Config>
   <kCura.FileTransfer.Config>
   </kCura.FileTransfer.Config>
   <kCura.SetExecutor.Config>
   </kCura.SetExecutor.Config>
   <kCura.WorkspaceManager.Config>
   </kCura.WorkspaceManager.Config>
   

5. Add override settings under configuration sections as necessary:

   <add key=”OverrideName” value=”OverrideValue”/>

   Replace OverrideName and OverrideValue with the appropriate override key and value as illustrated below:

   <add key=”ExceptionDetailsInFaults” value=”false”/>

   Note: An error will be thrown if a key exists in a section of the configuration file where it doesn't belong. For example, ExceptionDetailsInFaults is only valid in relativity.commonServiceValues.Config, so an error will be thrown if it is incorrectly placed in kCura.Authentication.Config. Verify that you don't have any typographical errors in the key. Keys are case sensitive.

Server-side override values

The following list includes the available override settings for each service.

Override configuration references

For more information about override configuration options, review the following references:

• IncludeExceptionDetailInFaults Property:

  http://msdn.microsoft.com/en-us/library/system.servicemodel.servicebehaviorattribute.includeexceptiondetailinfaults.aspx

• MaxArrayLength Property:

  http://msdn.microsoft.com/en-us/library/system.xml.xmldictionaryreaderquotas.maxarraylength(v=vs.100).aspx

• MaxBufferSize Property:

  http://msdn.microsoft.com/en-us/library/system.servicemodel.basichttpbinding.maxbuffersize.aspx

• MaxBufferPoolSize Property:

  http://msdn.microsoft.com/en-us/library/system.servicemodel.basichttpbinding.maxbufferpoolsize.aspx

• MaxConcurrentCalls Property:

  http://msdn.microsoft.com/en-us/library/system.servicemodel.description.servicethrottlingbehavior.maxconcurrentcalls.aspx

• MaxConcurrentInstances Property:

  http://msdn.microsoft.com/en-us/library/system.servicemodel.description.servicethrottlingbehavior.maxconcurrentinstances.aspx

• MaxConcurrentSessions Property:

  http://msdn.microsoft.com/en-us/library/system.servicemodel.description.servicethrottlingbehavior.maxconcurrentsessions.aspx

• MaxDepth Property:

  http://msdn.microsoft.com/en-us/library/system.xml.xmldictionaryreaderquotas.maxdepth.aspx

• MaxReceivedMessageSize Property:

  http://msdn.microsoft.com/en-us/library/system.servicemodel.wshttpbindingbase.maxreceivedmessagesize.aspx

• MaxStringContentLength Property:

  http://msdn.microsoft.com/en-us/library/system.xml.xmldictionaryreaderquotas.maxstringcontentlength.aspx

• ReceiveTimeout Property:

  http://msdn.microsoft.com/en-us/library/system.servicemodel.channels.binding.receivetimeout.aspx

• SendTimeout Property:

  http://msdn.microsoft.com/en-us/library/system.servicemodel.channels.binding.sendtimeout.aspx