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
• Load balancing APIs

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 due to network security groups. 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.

 

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.

Prefix	Use
R1_	Relativity one SQL login
_R1	Relativity contained database prefix
_DBTenantDSA	Tenant CMDSA contained database prefix

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.

USE _DBTenantDSA
EXEC dbo.cdp_CMDSA_TenantLoginMGR
@LoginName =  'Elaine'
, @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.

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.

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.

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.

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 don't have access to the IIS or NT Services in a RelaltivityOne environment. If you want to restart the IIS, contact Client Services for more information.

Load balancing APIs

In RelativityOne, the APIs don't require appending -services to API calls directed at load balancing servers.

The APIs use the same base URL for every API. This eliminates the need to toggle base URLs based on your target endpoint.

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:

• When using supported APIs, follow the same development process for RelativityOne as you would for Relativity Server. You can use supported authentication methods and ARM when developing custom applications for RelativityOne. See Identity (authentication and user accounts) and .
• In RelativityOne environments, use a URL with the following format to access the Relativity Services API endpoint:

  https://<MyURL>-services.relativity.one/Relativity.Services

  For example, if you originally used https://saltandpepper.relativity.one/Relativity.Services, then you must now update it to https://saltandpepper-services.relativity.one/Relativity.Services.

• Use the Relativity API helpers to obtain the DBContext and make SQL calls against the database when developing applications with the APIs. For more information, see Relativity API Helpers.

• Custom Applications in the Repository workspace are prohibited

Applications with external dependencies

As a best practice, design applications to operate entirely within the framework of RelativityOne. Review the following limitations on applications that consume external dependencies:

• Applications that require a custom application server or consume external dependencies must be hosted outside of the RelativityOne ecosystem. They can’t be deployed within the tenant pod.
• The stringent firewall rules used for RelativityOne complicate the connection to extensibility points. A custom server can initiate contact through the firewall to any extensibility point. However, extensibility points can't initiate contact and reach out from RelativityOne through the firewall to consume external services.
• When designing an application that must consume external services, account for the increased time that operations require. Communications passing through the firewall to a custom server travel at significantly slower speeds than those for an internal pod.

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 tha Relativity Server instances. Use multiple agents or workers spread across machines 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. Make sure you are using a proper URL in your code. 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 the following:
  • ARM on the Relativity RelativityOne Documentation site
  •  
• Staging Explorer (in Relativity Desktop Client) - For more information, see Staging Explorer on the Relativity RelativityOne 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 RelativityOne 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. Also, see RelativityOne developer considerations

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 tha 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:

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 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.