Relativity aiR developer considerations

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

Relativity aiR architectural overview

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

Even though Relativity and Relativity aiR 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 Relativity aiR infrastructure affect application development:

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

Relativity aiR fundamentals

Most importantly, treat Relativity aiR as a service rather than a collection of servers. The Relativity aiR application itself and our operations team handle the Relativity aiR infrastructure, including installation, upgrades, and infrastructure components, such as servers. The infrastructure of a cloud PaaS service such as Relativity aiR 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 Relativity aiR, which is run in the cloud.

If you run .NET code within a supported extensibility point, your application probably works in Relativity aiR 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 Relativity aiR. 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 Relativity aiR instance, but this setup isn't required. Your application won't have access to the infrastructure in the Relativity aiR environment. For more information, see Relativity aiR developer considerations

SQL server coding considerations

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

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 Relativity aiR as a service rather than a server. Relativity aiR provides applications with a connection string to the appropriate database. Storing and retrieving data, creating tables, and running queries are all safe operations in Relativity aiR. 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 Relativity aiR. 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 Relativity aiR.
In a Relativity aiR 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 Relativity aiR environment are linked. For example, other SQL Servers in your environment may not be linked to the primary SQL Server for Relativity aiR. Invariant servers and their store servers may not be linked to the primary and workspace servers.
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:

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;"

If you are connecting using .NET Core, you must set the MultiSubnetFailover to TRUE.
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

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.

Direct SQL access and location considerations

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

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 Relativity aiR:

Relativity aiR 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 Relativity aiR.
Note that different accounts have varying levels of access to database tables. For more information, see Direct SQL access in Relativity aiR.

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

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.

When creating a user login:

The fields cannot use spaces.
The LoginName must be unique, and it cannot start with “R1”.
tenantSQLLogin and tenantGroup are metadata columns. They do not affect login functionality, and you can use them to organize users into groups or associate other information with the user.

Copy

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.

Copy

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.

Copy

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

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 Relativity aiR environment.

Copy

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.

Copy

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

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

Analytics servers

In Relativity aiR, Analytics services are hosted as a multi-tenant shared service with a single URI endpoint. Authenticating to the Analytics shared service works differently in Relativity aiR 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 Relativity aiR, DataGrid services are hosted as a multi-tenant shared service with a single URI endpoint. Authenticating to the DataGrid shared service works differently in Relativity aiR 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 Relativity aiR 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 Relativity aiR application development.

General best practices for Relativity aiR

The following list contains general best practices for Relativity aiR application development:

Agents run in a cloud compute platform in Relativity aiR. Use the Workload Discovery APIs to horizontally scale your jobs and spin up multiple agent containers in Relativity aiR 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 Relativity aiR as you would for Relativity Server. You can use supported authentication methods when developing custom applications for Relativity aiR; 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 Relativity aiR 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 Relativity aiR 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.
Relativity aiR 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 Relativity aiR 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 Relativity aiR environment may be stored in multiple geographic locations. In Relativity aiR, data storage is like a Relativity Server environment using multiple distributed SQL Servers located in different geographic regions, but linked together.

For any Relativity aiR instance, the data will never be stored outside of the borders of a country. For example, if a Relativity aiR 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 Relativity aiR environment. These configurations are optimum for Relativity aiR environments, and modifying them may have unintended consequences.

Import and store data in Relativity aiR

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

Import options for Relativity aiR

Relativity aiR 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.
You can configure Relativity aiR to provide node-to-node transfers. For example, you can use Aspera servers for a Relativity Server instance of Relativity.

Cloud data storage

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

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

TLS 1.2 support

Relativity aiR 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 Relativity aiR, 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:

Copy

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

Customer lockbox and system admin access rights

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

Relativity aiR Government

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

An allow-list filters network access for Relativity aiR 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 Relativity aiR Government environment's allow-list, please contact Product Support.

Relativity aiR Sandbox

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

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