RelativityOne developer considerations

RelativityOne includes rearchitected e-discovery features available as a SaaS product. It offers most of the same functionality provided by a Relativity Server instance of Relativity. It also supports the same APIs and other platform features, such as tools, scripts, ADS applications, and utilities available for application development.

If you're familiar with custom development for Relativity, use the information on this page to ensure that your existing applications function properly in a RelativityOne instance. If you're new to custom development, use these considerations in conjunction with other information about the Relativity APIs to jump start the implementation of your applications. For more information, see Tools and Resources.

See Also:

• Debugging custom applications and support for custom applications

RelativityOne architectural overview

RelativityOne provides the same developer functionality as Relativity Server. Many of the same developer concepts apply to RelativityOne, including agents, event handlers, custom pages, APIs, and ADS deployment. In general, applications written for Relativity Server work in the RelativityOne cloud.

Even though Relativity and RelativityOne share the same functionality, the cloud is a very different hosting environment from a Relativity Server data center. ADS applications should follow the guidelines outlined in this page in order to run efficiently in the cloud. By following these guidelines, you can also ensure that your applications perform better and are more resilient in the cloud.

Infrastructure

Use the following guidelines to learn about how key elements of the RelativityOne infrastructure affect application development:

• RelativityOne fundamentals
• Application integration
• SQL server coding considerations
• SQL tenant admin operational overview
• Analytics servers
• Data Grid
• Internet Information Services (IIS) and Windows Services

RelativityOne fundamentals

Most importantly, treat RelativityOne as a service rather than a collection of servers. The RelativityOne application itself and our operations team handle the RelativityOne infrastructure, including installation, upgrades, and infrastructure components, such as servers. The infrastructure of a cloud PaaS service such as RelativityOne is constantly in flux. Servers are regularly added, removed, and reconfigured. In some cases, a traditional server may not be running your code, and your physical data may not exist on the same server or same geographical region. This configuration is the standard architecture of cloud offerings.

In a Relativity Server instance of Relativity, you have deep access to all of the infrastructure components. You may think in terms of the technology hosting the code, such as servers, IIS, and Windows. These concepts may not be applicable to RelativityOne, which is run in the cloud.

If you run .NET code within a supported extensibility point, your application probably works in RelativityOne like it currently does for a Relativity Server instance. If you leverage any of the following concepts, you may need to update your code in order to future-proof your application:

• Windows Registry
• Windows APIs
• Windows NT Services
• Internet Information Services (IIS)
• Windows user accounts for authentication
• Active Directory
• SQL Server (working at the master database level rather than a specific database)
• Local temporary file storage

Application integration

Custom applications or solutions that require their own infrastructure must be hosted outside of RelativityOne. For example, customers or development partners may host integrations through Azure, AWS, a Relativity Server solution, or other options. If your custom application uses Azure as its infrastructure, the optimum hosting environment would be the same data center as your RelativityOne instance, but this setup isn't required. Your application won't have access to the infrastructure in the RelativityOne environment. For more information, see RelativityOne developer considerations

SQL server coding considerations

Review the following information about how to work with SQL Servers in a RelativityOne environment.

Caution: Accessing the SQL Server is not audited and does not appear in the Relativity UI audit lists. Directly interacting with the SQL Server or performing maintenance operations on a database has the potential to put the database in a bad state. All SQL Server access should be avoided; please use APIs instead.

Access to SQL servers and databases

• In general, treat the SQL Server in RelativityOne as a service rather than a server. RelativityOne provides applications with a connection string to the appropriate database. Storing and retrieving data, creating tables, and running queries are all safe operations in RelativityOne. However, avoid directly interacting with the SQL Server itself or performing maintenance operations on a database.
• If your application creates its own databases, contact Client Services for additional information about testing and other requirements.
• Don't back up SQL databases from an ADS application in RelativityOne. Taking backups improperly can result in critical downtime for the target database in a disaster recovery scenario. Contact Client Services if your application needs to back up or restore SQL databases in RelativityOne.
• In a RelativityOne instance, don't assume that the Relativity service account automatically has SQL system admin rights as it does in Relativity Server instances. If your application requires SQL system admin rights, contact Client Services for additional information about testing and other requirements.
• Don't use cross-database transactions in your application code. If you attempt to use cross-database transactions, technical and architectural challenges exist with the Distributed Transaction Coordinator in Windows, which may get invoked in this situation. Instead, use eventually-consistent, rollback, and self-healing code strategies to ensure that your databases remain synchronized without the use of cross-database ACID transactions.
• Not all servers in the RelativityOne environment are linked. For example, other SQL Servers in your environment may not be linked to the primary SQL Server for RelativityOne. Invariant servers and their store servers may not be linked to the primary and workspace servers.

  Note: Invariant stores and databases are different entities.

Connecting to SQL instance using server FQDN (EDDS ResourceServer)

If you are connecting to your SQL instance using a connection string referencing server FQDN found in the EDDS ResourceServer table:

1. Ensure that you formulate your connection strings as follows:
   Copy

   1
   $sqlConnection.ConnectionString = "Server=abscefg007.ServerFarm.Relativity.com\sqlInstanceName;Database=master;User Id=$sqlConnectionUsername;Password=$sqlConnectionPasswordText;MultiSubnetFailover=True;"

2. If you are connecting using .NET Core, you must set the MultiSubnetFailover to TRUE.
3. If you are connecting using SSMS, configure your connection as follows:
   1. Start up SSMS.
   2. In the “Connect to Database” popup, click the [options] button.
   3. On the Additional Connection Properties tab, add the following entry:
      • MultiSubnetFailover = TRUE

Note: You should only need to do this once for each SQL instance you are trying to connect to. If you experience connection issues, please contact Support, and then provide the exact code included in your connection string.

SQL Server query resiliency

Even though SQL Servers are performant, your application may experience transient database errors at some point during its operation. Develop your applications to be resilient and gracefully handle these error scenarios.

A well-designed application should:

• Handle timeouts possibly by waiting a certain number of seconds, and then retrying a query.
• Handle errors by interpreting the error, like a deadlock or a lock timeout, and taking the appropriate action.

You can find guidelines about how to handle transient failures in the cloud on the Microsoft site. The following links provide Azure-specific information, but they also generally apply to Relativity Server instances and to building resilient software for the cloud:

• Retry guidance for specific services - this article discusses the Azure SQL database, but it is also applicable to conventional SQL Server applications.
• Transient fault handling - this article provides general advice about why faults occur in the cloud, challenges posed by these faults, and general guidelines for design fault handling mechanisms.
• Retry pattern and Circuit Breaker pattern - these describe specific design patterns to use in your software development. Use the retry pattern when your query is likely to succeed the second time, such as temporary deadlock. Use the circuit breaker pattern when your query is likely to fail, as in the case of SQL Server queries that time out after 30 seconds.

Direct SQL access and location considerations

You can connect to a SQL server for RelativityOne through direct SQL access (DSA). Use the best practices outlined in this section to ensure that your custom applications remain compatible with RelativityOne. These best practices describe how to discover your RelativityOne environment and build dynamic code that changes with your environment.

Caution: In general, you should use the services available through the REST API rather than a direct connection to SQL. Direct SQL is not audited and has the potential to cause disruption in your instance. For more information, see REST API.

Summary of best practices

Review the following best practices for making DSA connections to RelativityOne:

• RelativityOne supports only building dynamic connection strings through DSA.
• Don’t hardcode connections to Relativity databases. Instead, plan that the name of an SQL instance may change, workspaces may move to different instances, and other updates may occur. Build this flexibility into your custom applications. See Returning a list of SQL instances and instance values.
• Consider implementing a central library that contains the logic consumed by your applications. You can easily update this centralized code when an internal schema or other change occurs in RelativityOne.
• Note that different accounts have varying levels of access to database tables. For more information, see Direct SQL access in RelativityOne.

Returning a list of SQL instances and instance values

The sp_getSQLinstances stored procedure returns a list of SQL instances of the following types:

• SQL – Primary
• SQL – Distributed
• Invariant
• Invariant Stores

Execute this stored procedure from the EDDS instance using the following syntax:

• EXEC EDDS..sp_getSQLInstances

The logic in the bullets below explain where the SQL instance values are found.

• SQL Server connections and file paths
  • Note that the BCPPath is located on the file share. Additionally, custom loads may not be as performant as those run in a Relativity Server installation. See Application performance.
  • Ensure that your application can use named SQL instances.
  • Ensure that your application can use non-default SQL ports.
• EDDS database - The EDDS database is housed on a SQL server instance. Build the connection to this database server from a look-up to a configuration file or other source of truth. For example, you might use a management database located outside of the RelativityOne environment.
• Other Relativity databases - Build dynamic connections to all other Relativity database types, such as Invariant stores and workspaces. A dynamic connection ensures that your application can access these databases when they are moved to other Relativity instances or the instances are moved to other servers.
• Workspaces - Build connections to workspaces by referencing the server location (DBLocation) of the workspace in the EDDS.EDDSDBO.ExtendedCase view.
  • SELECT DBLocation FROM EDDS.eddsdbo.ExtendedCase WHERE Name = ‘WorkspaceName'
• Invariant and Invariant stores - To locate Invariant stores, find the Invariant database on the EDDS.eddsdbo.InstanceSetting table. Use the following query:
  • SELECT VALUE FROM EDDS.eddsdbo.instancesetting WHERE NAME = 'InvariantServerName'
  • After you have found the Invariant server, use the following query to locate the Invariant Store server:
    • SELECT value1 FROM [invariantServerName].invariant.dbo.appsettings WHERE category = 'SqlServer' AND subcategory = 'InvariantStore'

Client use databases (_DB1, _DB2, _DB3)

When considering storage options for your custom application, our recommendation is to utilize Relativity Dynamic Objects (RDO). You can use Relativity Dynamic Objects (RDO) in place of custom tables, with instances of the RDO acting as rows and the RDO's fields as columns. Unlike writing in SQL, the Object Manager service offers a supported API surface to interact with RDOs. In the event that RDOs do not meet your application needs, we also offer client use databases.

Client use databases (_DB1,_DB2,_DB3) are supplied in RelativityOne as an intermediary data staging location, or a housing location for SQL stored procedures. These databases are not part of any core component of Relativity. These databases do not contain data by default, are not used by the Relativity platform, and the data storage capacity is capped at 5GB.

Common use cases include:

• You need to host several SQL stored procedures or functions for use across your RelativityOne instance.
• You have non-Relativity application configurations that need to be stored somewhere local to where your application runs.
• You need to create a temporary staging table for ETL type activities.
• You need to create a temporary central queue or data repository for an outside application that does not interact with any custom agents or objects.
• When using a Relativity Dynamic Object (RDO) is not feasible for reasons of portability or compatibility.

Cases where a client use database is NOT supported:

• When the sought-after functionality would be better suited as an RDO.
• Permanent storage of large amounts of data. Data storage capacity of these databases is capped at 5 GB.
• You have data that depends upon multiple tables in a workspace or in EDDS and are able to store the data in a Relativity object.
• Permanent references to workspaces that may (at the moment) be on the same SQL instance. Database location in RelativityOne is ephemeral, the location of a database is subject to change.

SQL tenant admin operational overview

The following operations are available only to TenantAdmin accounts:

• Calling stored procedures as a tenant admin
• Creating a new user login
• Adding or changing user roles
• Changing a user password
• Enabling or disabling a user login

Calling stored procedures as a tenant admin

Only CMDSA administrators can run the following calls that create and configure user accounts using a single stored procedure:

• DBTenantDSA.dbo.cdp_CMDSA_TenantLoginMGR

To support having multiple contained databases for multiple security authorities, the following prefix table serves as a reference for future compatibility.

Note: The use of R1 prefixes by tenants is prohibited. An attempt to create a login with an R1 prefix will fail.

You may notice that in the contained database, there are additional stored procedures. If other stored procedures in the database are called directly, there may be failures or incomplete entries. It is inadvisable to run any procedure except _DBTenantDSA.dbo.cdp_CMDSA_TenantLoginMGR.

Creating a new user login

The following is a sample call for creating a new SQL users account, which also lists options.

Running the call below creates the user. Any associated roles are added to the user in the user’s default database (coded in a system allowlist table). The login creator cannot change the default database. A separate system process reviews the default database (e.g., _db1 for TenantAdmin) and propagates the roles found in this database to all others.

1
2
3
4
5
6
7
8
USE _DBTenantDSA
EXEC dbo.cdp_CMDSA_TenantLoginMGR
@LoginName = 'Elaine' -- Name of the SQL login to be created.
, @tenantSQLLogin = 'Elaine.Ellis'
, @tenantGroup = 'home'
, @LoginAction = 'CREATE' --(CREATE, DISABLE, ENABLE, ALTER) - Required, choose one.
, @Password = 'temporary password used here' --Required with CREATE
, @Roles = 'data_reader,data_writer,ddlOnTenantOwnedSchema,ExecuteOnTenantOwnedSchema'

Adding or changing user roles

To add or change roles, you must include the complete list of roles the user should have in the call you make. Any roles the user currently has will be replaced by the list entered in the stored procedure call below. Only the roles listed in the sample procedure are available {scott}, and all fall within the restrictions listed in the permissions table:

• data_reader - able to read SQL, inherits access rights from tenantAdmin
• data_writer - able to edit SQL data, inherits access rights from tenantAdmin
• ddlOnTenantOwnedSchema - create, modify, and delete database tables, indexes, and relationships in tenant schema
• ExecuteOnTenantOwnedSchema - able to run external scripts and procedures in tenant schema

The following is a sample call for adding or changing the list of roles a user has.

1
2
3
4
5
USE _DBTenantDSA
EXEC dbo.cdp_CMDSA_TenantLoginMGR
@LoginName =  'Elaine'
, @LoginAction =    'ALTER' --(CREATE, DISABLE, ENABLE, ALTER) - Required, choose one
, @Roles = 'data_reader,data_writer,ddlOnTenantOwnedSchema,ExecuteOnTenantOwnedSchema'

Changing a user password

The following is a sample call for altering a user's password.

1
2
3
4
5
USE _DBTenantDSA
EXEC dbo.cdp_CMDSA_TenantLoginMGR
@LoginName =  'Elaine'
, @LoginAction =    'ALTER' --(CREATE, DISABLE, ENABLE, ALTER) - Required, choose one
, @Password = 'temporary password used here' --Required with CREATE

Note: Users will NOT be prompted to change their passwords. They must right-click on their login in SSMS and change it themselves. See Changing your own CMDSA login password.

Changing your own CMDSA login password

On the EDDS server, you must run the following SQL while logged in using the identity of the login that needs a password change. This will change the password on the primary server. Within 15 minutes, the changed password will automatically propagate to all other instances in your RelativityOne environment.

1
2
3
USE [master]
GO
ALTER LOGIN [CMDSACreatedLogin] WITH PASSWORD=N'thePassword' OLD_PASSWORD=N'TheOldPassword'

Enabling or disabling a user login

Running the following procedure directly alters the user's login on this server once the job runs.

1
2
3
4
USE _DBTenantDSA
EXEC dbo.cdp_CMDSA_TenantLoginMGR
@LoginName =  'Elaine'
, @LoginAction =    'DISABLE/ENABLE' --(CREATE, DISABLE, ENABLE, ALTER) - Required, choose one

Note: It may take up to 20 minutes to disable a user across all SQL instances.

Analytics servers

In RelativityOne, Analytics services are hosted as a multi-tenant shared service with a single URI endpoint. Authenticating to the Analytics shared service works differently in RelativityOne than in a Relativity Server instance. If your application needs to access the Analytics server directly for conceptual or structured analytics, contact Client Services for more information.

Data Grid

In RelativityOne, DataGrid services are hosted as a multi-tenant shared service with a single URI endpoint. Authenticating to the DataGrid shared service works differently in RelativityOne than a Relativity Server instance. If your application needs to access DataGrid functionality directly, contact Client Services for more information.

Internet Information Services (IIS) and Windows Services

You currently do not have access to IIS or NT Services in a RelativityOne environment. If you want to restart IIS, contact Relativity Support.

Application development

You can find a list of best practices for developing custom Relativity applications at Best practices for building applications. Next, review the following best practices specifically for RelativityOne application development.

General best practices for RelativityOne

The following list contains general best practices for RelativityOne application development:

• Agents run in a cloud compute platform in RelativityOne. Use the Workload Discovery APIs to horizontally scale your jobs and spin up multiple agent containers in RelativityOne Compute. Multiple agents cannot be added via the Agents tab; an agent is created automatically on this tab when a Resource File containing an agent is added to the instance. See Agent Scaling Guidelines for more details.
• When using supported APIs, follow the same development process for RelativityOne as you would for Relativity Server. You can use supported authentication methods when developing custom applications for RelativityOne; see Identity (authentication and user accounts) .
• Custom Applications in the Repository workspace are prohibited

Applications with external dependencies

Review the following limitations on applications that consume external dependencies:

• Applications that require vertical scaling, custom application installations, or high levels of observability should be hosted outside of the RelativityOne ecosystem
• If an external API requires authentication, consider storing its credentials via supported methods. See Storing and using external API credentials for more details.

Application performance

When developing for RelativityOne you can improve the performance of your custom applications by following these guidelines.

Input/Output (I/O) considerations

• Design your application to be "chunky" rather than "chatty." In other words, don’t make multiple small requests for data. Batch your requests into larger chunks when possible. This applies to file IO, API design, and database access. Large numbers of small network operations may be throttled by the cloud infrastructure.
• In the cloud, concurrency is an effective strategy for scaling to handle large workloads. Individual, single-threaded operations may run slower and have higher latencies. However, the cloud allows much higher levels of concurrency than a Relativity Server instance. Consider using multiple agents to break work into smaller chunks that can be handled concurrently.
• Networking differs in the Azure cloud from a Relativity Server instance. In particular, there are rate limits on ingress network traffic to a given VM or service. These limits may cause individual file transfers to run slower than Relativity Server instances. Use multiple agents or workers to speed up the process.

  RelativityOne is currently hosted in Microsoft Azure. You may find it helpful to understand this environment in which your application is running. For more information on general Azure cloud limits, see Azure subscription and service limits, quotas, and constraints available on the Microsoft site.

Azure load balancing considerations

When developing an application, consider that each RelativityOne environment sits behind an Azure load balancer with sticky sessions enabled. If you plan on passing URLs, tokens, cookies or other entities, consider the impact load balancing may have on these requests.

Data storage

• The workspace data for your RelativityOne environment may be stored in multiple geographic locations. In RelativityOne, data storage is like a Relativity Server environment using multiple distributed SQL Servers located in different geographic regions, but linked together.

For any RelativityOne instance, the data will never be stored outside of the borders of a country. For example, if a RelativityOne instance is anchored in the UK-South region, all data and backups will be in that region. A copy of the backups (for disaster recovery purposes) could be stored in a different region (e.g., UK-West), but the data would never be stored outside of the country.

Use these strategies to improve data interactions:

• Cache data locally before sending it to a remote server.
• Don't use the same file path for reading and writing data.
• Code defensively by considering the geographical location of your data, CPU usage, and other factors that influence application performance.
• Don't modify the configuration settings for data shares in your RelativityOne environment. These configurations are optimum for RelativityOne environments, and modifying them may have unintended consequences.

Import and store data in RelativityOne

Use the following information to learn about how to import and store data in RelativityOne.

Import options for RelativityOne

RelativityOne supports the following options for importing data:

• ARM - Uses the file system through standard network shares. For more information, see ARM on the Relativity Documentation site
• Staging Explorer (in Relativity Desktop Client) - For more information, see Staging Explorer on the Relativity Documentation site.
• Relativity Desktop Client (RDC) - When using direct mode, you must run the RDC on the utility server for the RelativityOne environment. Only the utility server has the necessary network access for direct mode. For more information, see Relativity Desktop Client on the Relativity Documentation site.
• You can configure RelativityOne to provide node-to-node transfers. For example, you can use Aspera servers for a Relativity Server instance of Relativity.

Note: Use a RelativityOne import feature for data sets less than 5 TB. You can ship data sets larger than 5 TB to Microsoft for blob storage, which may be more efficient. Contact Client Services for additional information on this workflow.

Cloud data storage

The following factors affect the transfer and storage of data in RelativityOne:

• When you move large amounts of data, transfer it directly and avoid compressing it. Compressing, transferring, and then decompressing data often takes more time than a direct transfer.
• Scale horizontally rather than vertically to achieve optimum performance in the cloud architecture. Although individual operations might have higher latency or slower throughput, cloud services generally handle many concurrent operations better than Relativity Server architectures.

Security considerations

Use the following information to learn about security features in RelativityOne.

TLS 1.2 support

RelativityOne uses TLS 1.2 for all APIs and cross-process communication. Older protocols such as TLS 1.0 and crypto algorithms such as RC4 are disabled. Every .NET AppDomain for agents, event handlers, and custom pages is configured to use only TLS 1.2 for secure connections. If your application calls a secure remote server that is outside of RelativityOne, ensure that the server has TLS 1.2 and that the appropriate algorithms are enabled.

The following code samples illustrates how you can establish a TLS 1.2 connection in your custom code:

1
System.Net.ServicePointManager.SecurityProtocol |= SecurityProtocolType.Tls12;

Customer lockbox and system admin access rights

RelativityOne utilizes a security feature called Customer lockbox to ensure that you have control over users, including Relativity employees, who can access your workspaces and data. Users who are only members of the System Admin group can’t access a workspace unless they are in an additional group that has permissions to that specific workspace. This requirement also applies to operations executing under the current user, when that user is only in the System Admin group. Make sure that your applications execute under a context with access to all required workspaces.

Only RelativityOne has these additional security measures for System Admin group. In Relativity, the members of the System Admin group have access to all workspaces in an environment.

RelativityOne Government

In addition to the RelativityOne considerations described above, Relativity One Government environments have additional considerations for developers:

• An allow-list filters network access for RelativityOne Government environments, including outbound traffic. By default all endpoints are blocked, and only those endpoints explicitly added to an allow-list will be accessible. If you need a particular endpoint added to a RelativityOne Government environment's allow-list, please contact Product Support.

RelativityOne Sandbox

RelativityOne Sandbox refers to reusable RelativityOne environments that allow you to test SQL scripts, event handlers, API based applications, custom pages, and custom agents.

See RelativityOne Sandbox for detailed information about this feature. Review these FAQs for answers to general questions related to RelativityOne Sandbox.

How do I get access to a RelativityOne Sandbox environment?

RelativityOne Sandbox is a service that you must subscribe to. Please contact your Account Manager for more details..

How frequently is RelativityOne Sandbox updated?

Sandbox environments are upgraded one week following end of month RelativityOne primary production upgrades. This upgrade will take place during business hours and can be any day that week, but will be completed Friday at the latest.

There will be a period of a few days following a RelativityOne production upgrade weekend when your RelativityOne production instance will match the version in your EA sandbox environment and your "current release" Sandbox environment will be a version behind your RelativityOne production instance..

What kinds of testing can I perform?

Use the RelativityOne Sandbox only for functional testing. Don't use the environments for performance metrics because these environments use scaled-back resources.

Are there any limitations to tasks I can perform in RelativityOne Sandbox?

As best practice, don't modify any instance or environment settings. While you do have system admin rights, the test environments are configured to use the optimum settings. You can make any necessary changes to your custom applications.

How can I minimize testing costs?

Use these guidelines for minimizing the costs associated with using a testing environment:

• Use automated tests. This approach is also a best practice for custom application development.
• Limit file input/output operations per second (IOPS). They not only increase testing costs, but are also resource intensive.