Custom Pages migration checklist

As part of Relativity’s architecture modernization, all custom pages used in RelativityOne will be migrated to run on RelativityOne’s modernized compute platform, starting in mid Q3 2022. In some cases, you may need to prepare custom pages for the migration. This topic describes some of the preparation you may need to perform.

Determining if your Custom Page is affected

There are three potential ways in which Custom Pages may be impacted by this migration:

  1. Changes to JavaScript APIs on Relativity’s main window: If your Custom Page relies on JavaScript APIs which exist on Relativity’s main window in order to interact with Relativity, it may be impacted by updates to this API surface. Alternatively, if your RAP contains all of the JavaScript your Custom Page depends on, these changes will not impact your Custom Page. See JavaScript API changes for more details.
  2. Changes to Relativity-hosted assets: If your Custom Page relies on assets which Relativity hosts by default for all Custom Pages, it may be impacted by a reduction in these standard hosted assets. Alternatively, if your RAP contains all of the assets which your Custom Page depends on, these changes will not impact your Custom Page. See Relativity-hosted asset changes for more details.
  3. New requirements for server-side rendered Custom Pages: If your Custom Page must be rendered server-side (e.g. it contains .NET code), it may be impacted by new requirements for running on RelativityOne Compute. Alternatively, if your Custom Page only serves static content, these new requirements do not apply. See Server-side requirements for more details.

JavaScript API changes

  • The script environment on Relativity's main window has been simplified and fully documented. You will need to be sure that main window JavaScript functionality used by your Custom Pages is still available, or update your Custom Pages to account for these changes. See the Removals topic for a list of removals and mitigation strategies. See the supported JavaScript APIs topic for a description of the supported Relativity JavaScript environment.
  • The method for accessing Relativity’s main window from a popup has been modified. If your Custom Page (or parts of it) can open as a popup, you may need access to the Relativity main window with something other than window.top. See the topic how to find the Relativity main window from your custom page for guidance.
  • Most of the redirections a Custom Page would do to common parts of Relativity (such as error pages) can be easily accomplished via methods on the supported JavaScript APls. See the Redirections topic for a description of route redirections which are now handled by API.

Relativity-hosted assets changes

  • Most hosted assets will no longer be hosted by Relativity by default. This includes but is not limited to images, stylesheets, and JavaScript files. If your Custom Page references a file currently hosted within Relativity, but outside of your own Custom Page, we recommend moving copies of these resources into your Custom Page to ensure it remains available.
  • ASMX services and WebMethods will no longer be hosted by Relativity, instead essential functionality is available in Relativity's Platform APIs and Relativity Applications' Kepler Services.

Server-side requirements

Requirement Notes
Be stateless The current web-server based architecture relies on a "sticky session", which means that once a user logs into Relativity all subsequent web requests are always routed to the same running instance of your Custom Page. Once Custom Pages are hosted in the new compute platform this behavior will no longer occur. Your Custom Page must be stateless because the request to your Custom Page may be served by multiple instances during the same browser session and your application could be terminated during auto-scaling operations, node maintenance, or an underlying infrastructure outage.
Do not rely on ASP.NET Session State ASP.NET session state is no longer supported in the new RelativityOne compute platform. Custom pages should be refactored to remove ASP.NET session state dependencies.
Tolerate cold in-memory cache hits The removal of sticky sessions means that Custom Pages which rely on in-memory caching may have adverse impacts. For example, in-memory caching of items related to the logged in user may result in more cold cache hits since multiple requests from the same user are no longer guaranteed to go to the same instance of the Custom Page. Custom Pages must ensure they continue to function correctly despite the loss of sticky session and an increase in number of cold cache hits. Custom Pages that are negatively impacted should consider an alternative caching solution.
Do not have multiple Custom Page zip files Each application in the new architecture may only have a single zip file of Custom Page code. If your application contains multiple Custom Page zip files, they must be combined into a single zip. This does not prohibit you from having one application contain multiple pages on the Relativity User Interface - it simply means that the code for those pages must exist in a single zip file.
Do not use SignalR SignalR will not be supported in the new RelativityOne compute platform. Custom Pages should be refactored so that they do not rely on SignalR.
Do not assume admin permissions on the container

Custom Pages will be hosted under the Windows user with a reduced number of permissions. If your Custom Page relies on admin permissions in Web Servers, it must be adjusted to cater to the reduced permissions noted below:

Note: This only applies to the permissions of the Custom Page on the container. This does not impact end user permissions accessing the Custom Page.

  • Debug programs
  • Act as part of the operating system
  • Create a page file
  • Impersonate a client after authentication
  • Load and unload device drivers
  • Manage auditing and security log
  • Obtain an impersonation token for another user in the same session
  • Profile single process
  • Replace a process level token
  • Take ownership of files or other objects
  • NTFS permission to read/write directories belonging to other users

Frequently Asked Questions

  • What is the recommended overall workflow for making these updates?
    • Multiple paths exist for developers to make these updates, and, depending on the complexity of your Custom Pages, certain steps may be more significant for you than others. However, below is the general workflow we suggest using to ensure your pages are ready for migration:
      1. Review the requirements listed on this page in detail, and evaluate them against each of your Custom Pages. You should have a good understanding of which Custom Pages will be affected and the approach that you want to use in making them ready for migration.
      2. Make any required changes using your existing development process. Typically, this will be on a DevVM where you can quickly iterate and test. You should also confirm Relativity Logging is implemented and correctly capturing important messages from your agent.

        Note: A new DevVM image with all new JS APIs will be available by early July 2022 – we will update here as soon as it is available.

      3. Fully test the behavior of your Custom Pages to ensure it is working as expected.
      4. Install your Custom Page into an EA Sandbox environment and request for it to be migrated to Kubernetes if it is not already migrated. Fully test your Custom Page running in Kubernetes, especially keeping an eye on logging, performance and functional correctness.

        Note: Sandboxes are scheduled to be available for migrations by early July 2022.

      5. Return to Step 2 as needed, based on your findings while running in Kubernetes.
  • Since ASP.NET Session State is not supported, can we still use MVC?
    • Yes, MVC is still supported and does not require ASP.NET Session State.
  • Will Relativity API Helpers still be available server-side?
    • Yes, these helpers will remain unchanged and may still be used to get information about the user.
  • Are the new JavaScript APIs available on DevVM?
    • Yes, the new APIs will be available on shortly on DevVM – we will update this page once the new image is available. In order to fully test your Custom Page running on RelativityOne Compute, though, you should have your page migrated on an EA Sandbox instance as this is the only way to fully validate functionality with all new changes.
  • How do I get more support if I am stuck? 
    • Our first recommendation is usually to add more Relativity Logging to your Custom Page to pinpoint the error message – without strong logging, it is very difficult for us to provide support. If that does not help identify the issue, though, please contact support for additional help.