Atlas Setup Guide

ATLAS Setup Guide

The following sections detail the process for setting up Atlas and its dependencies.

Prerequisites

WebAPI

The first prerequisite for ATLAS is to Install the OHDSI WebAPI. Installation and configuration information is available on the WebAPI wiki. The ATLAS setup assumes WebAPI is available and configured with one or more patient data sets converted to the OMOP Common Data Model.

Achilles

To use the Data Sources feature within ATLAS you must first setup and execute ACHILLES in your environment. Once you have successfully generated summary statistics, you are ready to configure ATLAS to use this information.

ATLAS Installation

The following sections will detail how to download and ready the ATLAS code base and to configure it for your environment.

Code Deployment

Download the latest release of ATLAS and extract it.

Then copy all of the files from the extracted folder to your web server including the node_modules folder (this is required to resolve all JavaScript dependencies). Set up your webserver such that the application will be reachable via a URL such as:

  http://<your_webserver>/atlas

Atlas Configuration

The default configuration for ATLAS is found in the /js/config/app.js file. To override these application settings, create a new file in /js/config-local.js (example below). Please note: the file /js/config-local.js is not included in the Atlas repository. This is by design so that you may have environment-specific configuration.

define([], function () {
	var configLocal = {};

	configLocal.api = {
		name: 'My Organization Name',
		url: 'https://webapi.server.com/WebAPI/'
	};

	return configLocal;
});

In the example above, the /js/config-local.js overrides the corresponding ".api" property found in /js/config/app.js and allows for custom configuration for your environment. The same pattern can be used to override the other settings in /js/config/app.js.

Once this is complete, you should now be able to navigate to ATLAS from Google Chrome.

  http://<your_webserver>/atlas

(Optional) Shutting off the ability of users to grant READ/WRITE permissions to other users for their artifacts

As of 2.14, there is an optional enhancement that allows read permission to be restricted so that only users with read access to a given artifact can view them. More information can be found on the WebAPI Wiki. There is no configuration change required in Atlas for this feature to work if an organization has enabled it in the WebAPI.

• Note the default behavior Atlas >= 2.14 is to allow users to grant other users READ/WRITE access to artifacts that they own and have WRITE access to using the grant permission feature in Atlas (the lock icon that appears when a user opens a given artifact).
  • The organization may not want users to have this ability. If so, the organization may shut this feature off in Atlas config-local.js by adding the line configLocal.enablePermissionManagement = false;
    • This could be done even if the WebAPI is not configured to restrict read access.

Troubleshooting

If you are having trouble loading ATLAS, we recommend the following troubleshooting steps:

• Open Google Chrome's developer tools (press CTRL+SHIFT+I) to reveal several tools that are useful for debugging. In the developer tools, use the console to inspect any errors reported by ATLAS.
• Ensure that you can reach the OHDSI WebAPI by navigating to: http://<your_webserver>/WebAPI/source/sources. If you are unable to reach this endpoint, ATLAS will be unable to function properly. Additionally, if this endpoint returns an empty array, this indicates that there are no sources configured which will also prevent ATLAS from functioning.
• If there are other issues, please capture as much information as possible using the Google Chrome developer console and post them to the OHDSI Forums or create an issue here on GitHub.