Mbirn: XNAT Documentation
XNAT Setup/Tutorial
Prerequisites: Java, PostgreSQL, Tomcat, Maven
1. Unzip the distribution into a local directory.
2. Configure the build.properties file.
SUMMARY: The build.properties file is located in the root directory of the XDAT package. The file contains the location of your Tomcat installation and details about your database connections. The initial XDAT setup will create two projects for you (sample and xnat). Thus, you need to specify the connection information for each database. The connections are preset to reference databases named ‘sample’ and ‘xnat’. You simply need to create these empty databases in your PostgreSQL installation and change the USER_NAME & PASSWORD variables in the build.properties to the appropriate values.
3. run ‘maven xdat:setup’
ACTION: At the command prompt in the root directory of the XDAT package, run ‘maven xdat:setup’.
SUMMARY:This will generate and configure the default projects.
- ** *** THE REST OF THE STEPS TAKE PLACE WITHIN EACH PROJECT DIRECTORY ***
4. Create Database
ACTION: If you haven’t already, create the empty database ‘xnat’ in your PostgreSQL installation.
5. Create Database tables & views.
ACTION: At the command prompt in your XNAT project (XDAT_ROOT/projects/xnat) run the following statement ‘../../bin/CreateSQL –f xnat.sql’.
SUMMARY: This will generate an sql file (xnat.sql) in the projects/xnat directory with the code that will create your database tables. You need to run this sql in your empty XNAT database before continuing.
6. Store initial security settings.
ACTION: At the command prompt in your XNAT project (XDAT_ROOT/projects/xnat) run the following statement ‘../../bin/StoreXML -l security\security.xml’.
SUMMARY: This will create two users (admin & boss) which will be used to insert/view data through XDAT. It also sets some of the default actions and roles for XDAT.
The admin account is your initial account for adding/editing users and setting additional security settings. It has a membership to the ‘Admin’ role which allows it to access the user administration section of the website. The admin user has a default password of ‘admin’ which can be changed through the website.
The boss account is used to authorize changes which are made by ‘Admin’ users. Until user privileges have been authorized by the ‘boss’, the changes will not be in effect. The boss account has a membership to the ‘Bossman’ role which allows it to authenticate users.
7. Store sample investigator.
ACTION: At the command prompt in your XNAT project (XDAT_ROOT/projects/xnat) run the following statement ‘../../bin/StoreXML -l work\sample-investigator.xml -u admin -p admin’. (The –u admin –p admin states the username and password of the admin account , who is inserting the data.)
SUMMARY: Security in XNAT is based on a subject or experiment’s investigator. For each data type, the admin will decide which investigator’s data a given user can access. Thus, in order to setup security in XNAT, there must be an investigator. Running this step, adds a sample investigator which can then be used for security configuration.
8. Deploy the Webapp
ACTION: At the command prompt in your XNAT project (XDAT_ROOT/projects/xnat) run the following statement ‘maven turbine:deploy’.
SUMMARY: This will create an xnat webapp in your Tomcat installation.
9. Start the webapp and login
ACTION: Start your Tomcat server using the startup script in your installation’s bin directory. In your Internet browser, proceed to the xnat webapp on your local host (usually http://localhost:8080/xnat).
Login to the site using the username ‘admin’ and the password ‘admin’. This logs you in as the Admin account.
10. Configure sample security settings.
ACTIONS: Click on the ‘Administration’ link. This will list all of the loaded user accounts.
Click on the ‘admin’ link. This brings up the user report for the admin account.
Click on the ‘Change Permissions’ link. This brings up the edit permissions page.
At the bottom of the screen, the current data types will be listed. Click on the plus signs next to the data types. Check the boxes for Create, Read, and Edit for the investigators. (This will give the admin account Create, Read and Edit privileges for data of this type belonging to this investigator). (Additional data types and investigators can be added through the administration section).
SUMMARY: All security changes must be approved by a boss account. So, either click the ‘Submit for Authorization’ link and an email will be sent to the boss account, asking him/her to authorize these changes… or click ‘Print’ and a printable PDF version will be loaded which can be submitted directly to the boss. For our purposes, click either button to save your changes. (The email addresses default to ‘test@test.com’. You can change these through the website.)
11. Authorize your changes.
ACTION: Logout of the website, and log back in as the boss account (username=boss/password=boss). Proceed to the administration section and click on the admin account again. You will now have the option of authorizing the account’s permissions. Go ahead and click the Authorize link. This will confirm the previous changes.
You can now logout, and log back in as the admin account. You will now have links to MrSession data and Subject data.
12. Insert sample subject data.
ACTION: At the command prompt in your XNAT project (XDAT_ROOT/projects/xnat) run the following statement ‘../../bin/StoreXML -l work\sample.xml -u admin -p admin’.
SUMMARY: This will insert some sample data into XNAT. This information will be visible through the admin account on the website. (Notice: This step must be performed after you configure the security settings. Otherwise the change will not be allowed to proceed.)
Customizations:
ADDITIONAL SCHEMAS:
If you have any additional schemas, which you want to be used in your xnat implementation you will need to place the schema in your xnat project (XDAT_ROOT/projects/xnat/schemas). Also, you will need to add your schema to the InstanceSettings.xml document (XDAT_ROOT/projects/xnat/InstanceSettings.xml). This instructs XDAT to load the schema at runtime. The ordering of the Schema matters. Make sure that your schema is listed after the other schemas.
Once the relevant schemas are added you will need to recreate your database and webapp. Steps 4-12.
ADDITIONAL SECURITY:
You can add users, investigators, data types and roles through the administration section of the websites.
Data Types: Adding data types will allow data to be visible in the website and allow for security settings on the data. Also, in order for listings to be available for a new data type a display document will need to be created which will specify what fields show up in the listing (SEE XDATROOT/Documentation/Display Documents.doc)
Roles: Roles will control the access of users in the website and will dictate what tasks show up in the navigation menus on the website.
ADDING DATA:
The site comes with pre-created screens for adding Subjects and MR Sessions (you need to be logged as a user with the ‘DataManager’ role in order to access them).
Create your own data input screens for your new data types or insert the data from the command prompt using the StoreXML method used in the tutorial.
