As part of the Relativity Services API (RSAPI) Deprecation, content on this page referring to the RSAPI and the Patient Tracker application is now deprecated and is no longer supported. For setup information, see Lesson 1 - Set up your developer environment on the RelativityOne Developers site.

Set up your development environment

Use these general guidelines to set up your environment for developing custom software on the Relativity platform.

This page contains the following information:

Install .NET version 4.6.2

Beginning June 28, 2017, you must update your development environment to .NET 4.6.2 to use the latest version of the SDK:

  1. Download the Microsoft .NET Framework 4.6.2 Developer Pack from https://www.microsoft.com/en-us/download/details.aspx?id=53321. The file name is NDP462-DevPack-KB3151934-ENU.exe.
  2. Run the NDP462-DevPack-KB3151934-ENU.exe executable and follow the instructions in the installation wizard.
  3. Turn off applications when prompted by the installation wizard.
  4. Restart the machine on completion.

To develop using the latest Relativity SDK, you must update the applications' projects to target .NET 4.6.2. See Set up a project in Visual Studio.

Enable WebSocket

If you're using a version of IIS that supports the WebSocket protocol (IIS 8.0 and later), it's strongly recommended that you enable the WebSocketModule. For more information, see https://www.iis.net/configreference/system.webserver/websocket.

To enable the WebSocketModule, it may be necessary to add the httpRuntime targetFramework property to the Relativity.REST web.config file because WebSocket requires .NET 4.5 or later:

<system.Web>
    <httpRuntime targetFramework="4.6.2" />
</system.Web>

If any of the following errors occur, you must set targetFramework to 4.6.2:

  • Event log exception:
    WebSockets is unsupported in the current application configuration. To enable this, set the following configuration switch in Web.config
  • Web browser console:
    Error during WebSocket handshake: net::ERR_CONNECTION_RESET”

Install the Relativity SDK

You can use the Relativity SDK installer or NuGet, to set up a client-side development environment for programming with agents, custom page, event handlers, the Import API, the Services API, and the Relativity API Helpers. The Relativity SDK installer also includes the Publish to Relativity tool that stores reusable configurations for uploading custom pages and resource files. See Publish to Relativity tool.

To install the SDK:

  1. Download the installer from the Relativity Developers site. See Download the SDKs.
  2. Double-click the executable file for your version of the SDK installer. Follow the instructions in the installation wizard. The installer will add the Relativity SDK folder to the following default location:
    C:\Program Files\kCura Corporation\Relativity SDK\
  3. This folder contains subfolders for each of the client side development environments:

    • Client - contains the .dll and other files that you need to reference in a Visual Studio project used for development.
    • Documentation - contains a .CHM file containing the class library.
    • Samples - the sample RSAPI code in the installer is deprecated. For more information , see RSAPI deprecation process.
    • Tools - includes the RelativityServices API Diagnostic Tool and the Self Signed Certificate Creator utility. (Available only in the Services API subfolder.)

To use the NuGet packages:

Development environment settings

Relativity provides support for detailed error messaging and other features designed to facilitate development in your environment. You can use the following settings to control this functionality:

  • Developer mode - controls error messaging, performance of CSRF checks, and other features. You can set this mode in the Instance Settings table in the EDDS database.
  • ExceptionDetailsInFaults property - controls error messaging for Relativity.Services. You can set this property in the Relativity.Services web.config file.
  • CustomErrors property - controls error messaging for Relativity.REST. You can set this property in the REST.Services web.config file.

Note: During development and debugging, you should enable detailed error messaging by using Developer mode. For information about remote debugging, see Troubleshoot event handlers, Remotely debug agents, or Remotely debug custom pages.

Developer mode

Developer mode provides the following functionality to facilitate programming against Relativity:

  • Enables the Developer mode bar - the Relativity UI displays a bar across most pages when Developer mode is active. To disable the bar, you must turn off Developer mode.

    workspace displaying Developer Mode banner

    Note: Even though you have enabled this mode, the Developer Mode bar doesn't appear across workspaces that contain an application that has failed to upgrade properly. In this case, you see an orange message bar across the workspace page indicating that the workspace upgrade isn’t complete. Developer Mode is still enabled but you won't see this message.

  • Disables CSRF checks - the requirement for the cross-site request forgery (CSRF) header is disabled in the REST API, which means you can work with the API using a web browser.
  • Enables detailed messages - Relativity.Services and Relativity.REST return detailed error messages and stack traces for troubleshooting and debugging.
  • Displays service operations - when you enable Developer mode, service operations are returned in the metadata WSDL for the services. You can temporarily enable this mode to learn about the service operations.
  • Enables View Component GUIDs link - the details view of an application displays this link when you enable Developer mode. See View component GUIDs.

Note: When you enable Developer mode, the Relativity Applications tab displays the Lock, Unlock, and Uninstall Application buttons in the console for system-secured applications. kCura doesn't recommend modifying these applications. For more information, see Relativity applications on the Relativity Documentation site.

Enable Developer mode

To enable Developer mode, set the DeveloperMode instance setting to true. This value is available in the Relativity.Core section of the Instance settings table In the EDDS database. By default, the DeveloperMode instance setting is false. See Instance setting table on the Relativity Documentation site.

Note: Enable Developer mode only in a development environment. This value is set when the services are initialized. If you change the instance setting, you need to reset the application pool.

ExceptionDetailsInFaults property in the Services web.config file

You can use the ExceptionDetailsInFaults property to return detailed error messages for exceptions thrown by the Relativity.Services. You can configure this property as follows:

  • true - returns detailed error messages from the Relativity.Services.
  • false - disables detailed error messaging. This value is the default setting.

    Note: When Developer mode is enabled, it takes precedence over the ExceptionDetailsInFaults property. The Relativity.Services returns detailed error messages, and the ExceptionDetailsInFaults property is ignored.

To use this property, you must add it to the web.config file for Relativity.Services. Add the following key-value pair to the relativity.commonServiceValues.Config section of the web.config:

<relativity.commonServiceValues.Config>
     <add key="ExceptionDetailsInFaults" value="false"/>
</relativity.commonServiceValues.Config>     

CustomErrors property in the REST web.config file

The CustomErrors property controls the level of detail provided in messages returned by the Relativity.REST service. You can set the CustomErrors property to one of the following values:

  • On - returns generic error messages from Relativity.REST. This value is the default setting.

    Note: In a production environment, the CustomErrors property should always be set to On.

  • Off - returns detailed error messages for troubleshooting and debugging Relativity.REST.
  • RemoteOnly - returns detailed error messages only to local callers, such as a developer working on a local machine. All other users receive generic error messages.

To set this value, locate the web.config file for Relativity.REST. Update the customErrors property in the system.web section of the file:

<system.web>
     <customErrors mode="On" />
</system.web>      

Note: When Developer mode is enabled, it takes precedence over the Custom Errors property. The Relativity.REST returns detailed error messages, and the CustomErrors property is ignored.

Set up a project in Visual Studio

For developing on the Relativity platform, we recommend that you use Visual Studio 2015 or higher. Relativity templates for agents, custom pages, and event handlers are also supported on these versions of Visual Studio. See Visual Studio templates for Relativity.

Use the following steps to set up a Visual Studio project:

  1. To run the installer, double-click the kCura.Relativity.SDK.Setup.msi, and follow the instructions in the installation wizard.
  2. Create a new project or class in Visual Studio. If you already have an existing project, use the following steps to select the .NET Framework 4.6.2 and reference the required .dll files.
  3. Open the Solution Explorer.

    setting project properties in Visual Studio

  4. Confirm that the Target framework is .NET Framework 4.6.2
    1. In the Solution Explorer, expand your project and right-click Properties.
    2. Click Open to display the Application tab in the left pane.
    3. Select .NET Framework 4.6.2 in the Target framework box.

      selecting .NET 4.5 as the target framework

  5. To add references to .dll files, right-click References in the Solution Explorer.
  6. Click Add References to display the Reference Manager dialog.
  7. Click Browse and select .dll files from the folders added by the SDK installer.
  8. Depending on your development project, add references to one or more of the following .dll files in the Relativity SDK.

    selecting .dlls available in the Relativity SDK

    • kCura.Agent.dll - used to develop custom agents. This is available in the following folder:

      ...\Program Files\kCura Corporation\Relativity SDK\Agents\Client

    • Relativity.CustomPages.dll - used to develop custom pages. This is available in the following folder:

      ...\Program Files\kCura Corporation\Relativity SDK\Custom Pages\Client

    • kCura.EventHandler.dll - used to develop custom event handlers. This is available in the following folder:

      ...\Program Files\kCura Corporation\Relativity SDK\Event Handlers\Client

    • Relativity.API.dll - used to access helper classes for returning a database context and connecting to the Services API. Reference this library when developing agents, custom pages, and event handlers. This is available in the following folder:

      ...\Program Files\kCura Corporation\Relativity SDK\Relativity API\Lib

    • Relativity.Services.Interfaces.dll, Relativity.Services.ServiceProxy.dll, Relativity.Kepler.dll, and Relativity.Services.DataContracts.dll - used to access the proxy class and service manager interfaces in the Services API, which interact with the Relativity business layer. These are available in the following folder:

      ...\Program Files\kCura Corporation\Relativity SDK\Services API\Client

    Note: Don't set the Specific Version option on your references in Visual Studio. When a custom assembly is loaded for an event handler, agent, or custom page, common .dll files are automatically copied into the domain from the lib folder. If you set the Specific Version option in Visual Studio, it may not match the version of the .dll files installed on the environment. This mismatch may prevent your application from executing properly.

  9. For development with the Services API, complete these additional steps:
    1. Add references to the following .NET framework assemblies: System.Runtime.Serialization and System.ServiceModel. (In the Reference Manager dialog, expand Assemblies, and then click Framework.)

      adding .NET framework assemblies for the Services API

  10. Add your custom code to the project.
  11. Once your development environment is set up, you are ready to build your first application.