Intro to Relativity Scripting
The content of this blog post was originally posted in the Relativity community by Jarrod Kimmel, Oasis VP of Engineering, in response to a user asking for advice on writing Relativity scripts.
Background
A Relativity script is a combination of XML that defines the properties, inputs, and outputs of the script and SQL logic that defines the actions of the script. You can use custom scripts to extend Relativity’s functionality and modify data sets in workspaces. For example, you can develop scripts to generate custom reports, auto-populate fields, or reformat data based on predetermined parameters.
Foundation
In order to write the SQL logic for Relativity scripts, you will need a basic understanding of relational databases and Microsoft’s T-SQL syntax. You can start without this foundational knowledge (many of us do) but getting a basic understanding upfront will help you avoid a lot of beginner mistakes and questions.
A good place to start is IBM’s course, Introduction to Relational Databases. I also recommend The Manga Guide to Databases—this was my introduction to relational databases and it still holds up today. Microsoft also has a course specifically on T-SQL (which Relativity is built on).
Tooling
You can write Relativity scripts entirely through the Relativity front end. However, it’s kind of like driving on the freeway after pepper spraying yourself directly in the eyes: it’s painful and you can’t see anything.
To work with Relativity scripts more efficiently, it is recommended to use a tool such as SQL Server Management Studio (SSMS). This tool allows you to view the structure of Relativity’s databases and execute queries. SSMS can be daunting if you’ve never seen it before, but this blog series does a great job.
Types of Relativity Databases
It is important to note that Relativity does not maintain a document for its database structure and schema change documentation may not be comprehensive. To fully understand the structure of the Relativity databases, it may be necessary to explore them directly using a tool like SSMS.
Relativity is comprised of several databases:
- EDDS: houses most of the instance-level data related to Relativity. This can be considered the brain of a given Relativity environment and there’s only one of them in use for the environment at any time.
- EDDS#######: There is an EDDS####### for every Relativity workspace and will house information related to the workspace. This is typically where people write their Relativity scripts. The ####### in the database name will equal the workspace’s ArtifactID, which can be found in the EDDS database’s [EDDSDBO].[Case] table.
- EDDSArchiving: Relates to the ARM application, storing ARM job configurations and logging. Some interesting stats can be found in this database if you have enough ARM jobs.
- EDDSLogging: Allows you to configure environment logging and retains everything that was logged. I believe this was deprecated in RelativityOne but is still used for Relativity Server installations. You can read more about how logging is configured here.
- EDDSMetrics: Contains transient data sent to Relativity about your Relativity instance. Unless some customization is done data won’t exist here very long.
- EDDSResource: There is an EDDSResource database for each Relativity SQL server. This database contains transient data for various Relativity purposes. Data won’t exist here very long either.
- Invariant: There exists an Invariant database for every processing queue manager in the environment. Similar to EDDS, this can be considered the brain of a given Processing environment. I think most environments only have one QM but several can exist.
- INV#######: There is an INV####### database for every Relativity workspace that has the Processing application installed and has had a processing job run. This will house processing data related to the workspace. The ####### in the database name will equal the workspace’s ArtifactID.
- SecretStore: Contains encrypted secrets stored by Relativity and an audit log for inserts/updates/reads/deletes of those secrets.
What’s Next?
In order to run Relativity scripts, you will need to have access to the appropriate database and permissions to execute queries. The permissions required for a script will depend on the specific actions it performs and the objects it accesses.
Overall, learning about Relativity scripting will require a combination of foundational knowledge about relational databases and T-SQL syntax, as well as practical experience working with the Relativity databases and writing scripts. It’s possible to dig around the EDDS####### databases to try and become familiar enough with a Relativity workspace’s structure to write the script you’re looking to write.
With the right tools and resources, you can begin to effectively create and run Relativity scripts. If you’re struggling to create a custom script, contact info@oasisdiscovery.com and let’s talk about it!
Jarrod Kimmel
Vice President of Engineering