Test the Services API configuration
You can test the availability and configuration of the Services API in your environment by using the Platform Status tab in Relativity. The Platform Status tab displays error messages with troubleshooting information when they detect endpoint configuration errors. You can also test the Services API configuration by using the diagnostic tool in the Relativity SDK.
This page contains the following information:
Platform Status tab
Use the Platform Status tab in Relativity to verify that the Services API is configured properly in your environment. This tab displays the status of all instances of the Services API, including self-hosted instances (instances hosted on the agent server inside the agent Windows service).
- The Server Diagnostics tab displays the total number of monitored Services API instances in your Relativity environment and the number of failed diagnostic tests.
- For each Services API instance, the tab displays the number of configured endpoints, the number of endpoints that failed the tests, and the date and time the test results were last refreshed.
The Platform Status Agent performs Diagnostics. Install the Platform Status Agent on any web or agent server. The Relativity 10.3 upgrade adds the agent to web and agent resource servers. For new installs, resource servers may not self-register. In this case, add Platform Status manually. If no results display when you open the Platform Status tab, or if a known instance of the Services API is missing an entry on the tab, then configure the diagnostics. For more information, see Configure the Platform Status diagnostics.
Note: Services API endpoints are only tested against the instance on the server itself. If you configure the agents in your Relativity environment to use instances of Services API other than the default self-hosted instance (using the ServicesAPIHostingOnAgentServersMode and ServicesAPIHostingOnAgentServersPredefinedURL options), the remote endpoints will not be tested.
Services API instance details
To display the details for a Services API instance, click the server name.
Only the Net Named Pipes endpoint testing is enabled by default.
- The built-in Relativity system admin account credentials test the username/password authentication.
- Relativity service account credentials test Windows authentication.
Click Refresh to refresh the diagnostic test results. Refreshing the data or running the diagnostic tests might cause a slight delay.
Note: Out-of-the-box Relativity only supports Net Named Pipes as the Services API endpoint type. Enable other endpoint types by updating the Instance setting table. For more information, see Install the Platform Status Agent
View the diagnostic test details
To view the details of the diagnostic test for a Services API endpoint:
- Click the server name to display the instance details.
- Click View Diagnostics. The panel displays the test results.
You can copy and paste the text from the panel.
For detailed information about possible errors and troubleshooting, see Endpoint configuration errors and Troubleshoot the Services API configuration.
Configure the Platform Status diagnostics
In certain cases it's necessary to reinstall the Platform Status Agent or enable or disable diagnostics for non-default endpoint types within an instance.
Install the Platform Status Agent
Installing the Platform Status Agent enables diagnostics for a Services API instance. To install the agent, use the Agents tab.
Note: You can install the agent on multiple agent server types, Agent and/or Web Background Processing.
Enable diagnostics for endpoints
Enable testing of an endpoint other than Net Named Pipes with a Services API instance by setting the value of the Enabled column for the endpoint to 1 in the EDDS.PlatformStatusAgent table. A combination of the server ID, agent type, self-hosted flag, and endpoint type identify the endpoint.
The following SQL statement example illustrates how to enable diagnostics for Net Named Pipes with username and password authentication for a self-hosted instance of the Services API:
1 2 3 4 5 6 | UPDATE [EDDS].[eddsdbo].[PlatformStatusAgent] SET [Enabled] = 1 where [SERVER] = 1020958 AND [AgentType] = 1 AND [SelfHosted] = 1 AND [Endpoint] = 4 |
The following values identify the endpoint types:
| Endpoint | Value |
|---|---|
| HTTP with username and password (UserNamePasswordHTTP) | 1 |
| HTTPs with username and password (UserNamePasswordHTTPS) | 2 |
| NetTCP with username and password (UserNamePasswordNetTCP) | 3 |
| Net Named Pipes with username and password (UserNamePasswordNetNamedPipe) | 4 |
| HTTP with Windows authentication (IntegratedHTTP) | 5 |
| HTTPs with Windows authentication (IntegratedHTTPS) | 6 |
| NetTCP with Windows authentication (IntegratedNetTCP) | 7 |
| Net Named Pipes with Windows authentication (IntegratedNetNamedPipe) | 8 |
Set the Enabled column value to 0 to disable testing for an endpoint.
For detailed information about the data values, see PlatformStatusAgent table.
The following SQL statement example illustrates how to change the default test frequency of 60 minutes to 5 minutes for all endpoints of the self-hosted Services API instance on myserver.domain.com:
1 2 3 4 5 | UPDATE [EDDS].[eddsdbo].[PlatformStatusAgent]SET [RunFrequency] = 5 where [SERVER] = 1020958AND [AgentType] = 1AND [SelfHosted] = 1 |
The following SQL statement illustrates how to force the tests to run for the UserNamePasswordNetNamedPipe endpoint on a single server by setting the Status column value to 1 ("Waiting").
1 2 3 4 5 6 | UPDATE [EDDS].[eddsdbo].[PlatformStatusAgent] SET [Status] = 1where [SERVER] = 1020958AND [AgentType] = 1AND [SelfHosted] = 1AND [Endpoint] = 4 |
The following SQL statement illustrates how to look up the name of the server for the server Artifact ID in the PlatformStatusAgent table.
1 2 3 4 5 | SELECT [ResourceServer].[Name] FROM [EDDS].[eddsdbo].[ResourceServer] INNER JOIN [EDDS].[eddsdbo].[Agent] ON ResourceServer.ArtifactID = Agent.ServerArtifactID WHERE Agent.ArtifactID = 1020958 |
PlatformStatusAgent table
PlatformStatusAgent table stores information about the Relativity Services API diagnostic test results displayed on the Platform Status tab. Each row corresponds to a type of test that can be run on a single endpoint of a Services API instance. Therefore, each Services API instance has 48 rows, corresponding to 8 endpoint types and 6 test types.
| Column | What it stores |
|---|---|
| ID | The internal ID of the Services API endpoint instance. |
| Server | The artifact ID of the diagnostic Platform Status Agent running on the server that is hosting the Services API instance. |
| AgentType |
The Services API instance type. Valid values include:
|
| SelfHosted |
A Boolean value indicating whether or not the instance of the Services API is self-hosted. Services API instances running on agent servers are self-hosted (running as a Windows service rather than in the IIS server). |
| Endpoint |
The Services API endpoint type. Valid values include:
|
| Test |
The diagnostic test type. Valid values include:
|
| Enabled | A Boolean value indicating whether or not diagnostics are enabled for the endpoint. |
| Status |
The status of the most recent test. Valid values include:
|
| LastUpdate | The date and time of the most recent test. |
| Success | A Boolean value indicating whether or not the most recent diagnostic test for the endpoint ran successfully. |
| LastSuccess | The date and time of the most recent successful test. |
| RunFrequency | The run frequency of the test in minutes. |
| Details | The text with the details of the most recent successful diagnostic test. |
Endpoint configuration errors
If the Relativity Services API Diagnostic Tool detects the wrong configuration of Services an error messages displays. Review the details of the error message, then update the endpoint configuration for the RSAPIClient proxy using the suggested resolution.
Unable to authenticate username/password combination against Relativity
If invalid Relativity credentials are specified, you receive the following error message:
1 2 | Unable to authenticate username/password combination against Relativity. Please contact your Relativity Administrator. |
Verify that the username and password are spelled correctly and that the user exists in the Relativity instance you are connecting to.
Ambiguous CertificateFindValue defined
You receive the following error message when the CertificateFindValue needs to be more specific:
1 2 3 | The value '<VALUE>' was specified as the server-side CertificateFindValue, but there is more than one matching certificate. Remove certificates with duplicate SubjectName values from the Certificate Store, or provide a more specific SubjectName. |
If the supplied CertificateFindValue in the server-side web.config file needs to be more specific when this error is thrown. (See '<VALUE>' in the message.) If the name supplied for the CertificateFindValue matches multiple certificates in IIS, update the CertificateFindValue to identify a unique certificate name, or remove the duplicate certificates. See Configure the Services API.
No CertificateFindValue defined
You receive the following error message when no value was supplied as the server-side CertificateFindValue:
1 2 | Nothing was specified as the server-side CertificateFindValue. Provide the SubjectName value of a valid certificate in the Certificate Store. |
This error occurs when no value was defined for the CertificateFindValue, or an empty string ("") was used. Add an entry similar to the following example to the relativity.commonServiceValues.config section of the Relativity.Services web.config file:
<add key=”CertificateFindValue” value=”myCert.subjectName.com” /> |
Invalid CertificateFindValue defined
You receive the following error message when an invalid value was supplied as the server-side CertificateFindValue:
1 2 | The value '<VALUE>' was specified as the server-side CertificateFindValue, but a matching certificate couldn't be found. Double check the name and spelling and ensure the certificate is in the correct Certificate Store. |
This error occurs when the value supplied as the CertificateFindValue doesn't match any existing certificate. Ensure the certificate is in the appropriate store, and that spelling is correct.
Invalid server format
You receive the following error message when the server address supplied was in an invalid format:
The supplied server is in an invalid format. Check for any typing mistakes. |
Verify that there aren't any spelling or typographical errors.
Invalid configuration keys present
You receive the following error message when invalid keys are present in a specific section of the server-side web.config file:
1 2 | The '<SECTION>' section of the web.config contains invalid keys: <KEYS>. Ensure no typographical errors were made and that each key is in the appropriate section. |
In this message, <SECTION> represents the part of the web.config file that contains invalid keys. <KEYS> is a comma-separated list of the offending keys. Ensure that each key is in the correct section, and that no spelling or typographical errors exist. The keys are case-sensitive.
Insufficient permissions in IIS
You receive the following error message when the account that the Relativity.Services application pool runs under has insufficient permissions to access a certificate:
1 2 3 | The account that IIS is running under does not have sufficient permissions to the private key of the certificate referred to by the server-side CertificateFindValue. Via the 'Certificates' snap-in of the Microsoft Management Console, give the appropriate account permissions to the private key. |
Follow the instructions provided in the error message.
Protocol not configured properly
You receive the following error message when a protocol hasn't been properly configured:
1 2 3 | The protocol '<VALUE>' has not been configured correctly. Ensure that all necessary Windows features are installed, that '<VALUE>' has been added to the list of Enabled Protocols for the IIS application, and the site has a binding for '<VALUE>'. |
In the error message, <VALUE> indicates the protocol that requires further configuration before it is usable.
Remote name unreachable
You receive the following error message when the server address supplied can't be reached:
The supplied server '<SERVER>' could not be reached. |
Verify that no spelling or typographical errors exist, and that Windows can resolve the supplied host name.
HTTP requested, but SSL is required
You receive the following error message when the server requires SSL, but an attempt was made to communicate using HTTP:
A connection attempt was made with HTTP, but the server requires SSL. |
HTTP must be allowed in IIS if you want to use any of the endpoint configurations that involve HTTP, such as IntegratedHTTP, or UserNamePasswordHTTP.
SSL trust failure
You receive the following error message when there is an issue establishing an SSL connection:
1 2 3 4 5 | The Certificate Authority of the server's certificate is not trusted by the client. If the server is using a self-signed certificate, install that certificate on the client in the Trusted Root Certification Authorities of the Local Machine if you trust it. The specified server name does not match the SubjectName value of the certificate of the HTTPS binding in IIS. Either use a different certificate on the server, or use a client-side server name that matches against the SubjectName. |
Ensure the server’s certificate is trusted and that the client is using an appropriate address to reach the server to resolve this error. The address must match the SubjectName of the certificate attached to the HTTPS binding in IIS.
Relativity Services API Diagnostic Tool
You can use the Relativity Services API Diagnostic Tool to verify that the Services API is configured properly in your environment. This tool tests the WSDL endpoint configuration for the RSAPIClient proxy, and tests all services that it runs in the background. The tool displays error messages when it detects a problem. See Endpoint configuration errors.
Note: The diagnostic tool performs the same endpoint test as the Platform Status tab while allowing the user to specify credentials other than the default system admin for username and password authentication and Relativity service account for Windows authentication.
- Navigate to the following DiagnosticTool folder in your installation directory, and click ProxyDiagnostic.exe. For example, use the following path if the SDK is installed on drive C:
C:\Program Files\kCura Corporation\Relativity SDK\Services API\Tools\DiagnosticTool\ProxyDiagnostic.exe -
Click the executable to launch the Services API Diagnostic Tool.
- Enter Username and Password you use for authentication. Leave these fields blank if you aren't using this type of authentication.
- Enter the name of Server where the Services API is running. (The Services API Diagnostic Tool requires the machine name. You can enter the URL for the server, and the API Diagnostic Tool parses the name from this string.)
- In the Authentication tree, select the authentication methods that you want to test. Right-click on this list to select or clear all the check boxes.
By default, all of the authentication methods are selected. Initially, test all methods to identify which endpoint types are available in your environment. If you don't want to expose an endpoint type, disable the particular types.
- (Optional) Select the Auto-Detect CertificateFindValue box if a CertificateFindValue is defined in the web.config for your server. The Services API Diagnostic Tool automatically populates the CertificateFindValue box with the current server setting. See Server-side override values.
Note: Leave the Auto-Detect CertificateFindValue box blank if you aren't setting the CertificateFindValue in the web.config file.
- Click Run Diagnostics. The Current EndPointType box updates with status messages as the test proceeds. The Services API Diagnostic Tool automatically detects the CertificateFindValue for the server.
- Review the results of the endpoint tests in the Authentication tree:
- Green Status – indicates the endpoint type is available and if the connection is successful.
- Red Status – indicates failure to connect with this endpoint. Complete step 9 to obtain more information about a failure.
- (Optional) Complete the following tasks if you want to view the exception thrown when the endpoint test failed:
- Select only the failed endpoint in the Authentication tree.
- Select the Display ServiceOperationFailed Events option.
- Click Run Diagnostics to display exception details including the exception thrown and the stack trace as in the following illustration.
Note: You can perform additional troubleshooting to resolve these errors. See Endpoint configuration errors and Troubleshoot the Services API configuration.
- (Optional) Click Copy to Clipboard to copy the error messages generated in the Current EndpointType box.
