Understanding Data Sharing in XNAT's Security Structure

Access to data stored in XNAT is governed by the data's relation to (or participation in) a given project. "Project Participation" for subject and experiment data in XNAT is split into two kinds of relationships: Ownership and Sharing.

Shared experiment resource files can now be mounted into containers and Jupyter Notebooks! See below in "How Sharing Impacts Resource Files"

Data Ownership

The first (and most important) relationship between projects and their data instances is ownership. Subjects and experiments are ‘owned’ by a single project (referred to as the primary project). The owners and members of the primary project are the users who control access to, and modification of that data. In practice, the primary project is the project which first inserted the data into XNAT (usually the project which acquired or recruited the data). When the data is added to the primary project (at data insertion) the user has the opportunity to give it a unique identifier (label) which will be used across XNAT to refer to the data.

Project Security

Access to data is governed by the relationships between projects and data instances. The permissions governing access to data are different depending on the nature of that relationship. There are four permission types which control user access/control of data.

Activity / Project Role	Permission	Owner	Member	Collaborator
Create	The ability to create data of this type	C	C
Read	The ability to read, including downloading, data of this type	R	R	R
Update	The ability to modify existing data of this type	U	U
Delete	The ability to remove data of this type	D

However, the permissions available to a user in a project are different depending on the data’s relationship to the project.

Sharing data

The second relationship between projects and their data instances is sharing. When a user decides to use data from Project A in his/her project (Project B), then he can add the data to his project by ‘sharing’ the data into it. Any user who can access a data instance, can add that data to his/her project. The user has the option of defining a project-based identifier (label), which will be used within project-scope to refer to this data.

Shared Data (Read-Only) - Data which is shared into a project cannot be modified or deleted by the users in that project. Modification and deletion can only be performed by members of the data’s primary project.
Owned Data (All/some access) - The permissions which a user has for ‘owned’ data is determined by that user’s role in the project.

Data shared from Project A into Project B is not copied into Project B. It is the same data element, so any changes to the data in Project A are reflected in Project B.

"Project A"

Activity / Role	Project A Owners	Project A Members	Project A Collaborators
Share Data into another Project ("Project B")	S	S	S

"Project B"

Activity / Role	Project B Owners	Project B Members	Project B Collaborators
Read Project A Data in Project B	R	R	R
Update Project A Data in Project B	--	--	--
Delete Project A Data in Project B	--	--	--

As this pair of charts shows, data shared from Project A cannot be modified in Project B, except by people who have the appropriate permissions in Project A. Thus, even though the owner of Project B is a collaborator in Project A, this user does not have the appropriate permission to modify or delete that shared data in Project B.

Data identification

Generic ID

Any data instance (subject or experiment) has a generic ‘ID’ field. This field is used by XNAT to uniquely identify this instance throughout XNAT. This value is usually dynamically created by XNAT, behind the scenes.

Project-based labels

The data instances also have project-based identifiers (labels) which identify the item within a specific project.

XML Specification

The relationship between data and its project is captured at the xml level, in the definition of those data instances. There are four pertinent areas of the xml document (subject or experiment) which identify the data’s projects and identifiers.

XML

<xnat:Subject ID="234234223" label="A_1" project="PROJECT_A">
   <xnat:sharing>
       <xnat:share label="B_1" project="PROJECT_B"/>
   </xnat:sharing>
</xnat:Subject>

The attributes are described in the table below.

Attribute	Description
ID	The generic ID used throughout the database to identify this item. It is the primary key of this item.
Label	The identifier used by the primary project to identify this item. This is used throughout the website and file system to refer to this item.
Project	The ID of the primary project which owns this data.
Sharing/Share	These are the projects into which this item has been shared: The target project is indicated by the project ID in the project attribute. The optional label attribute identifies the shared item within the shared project. In this example, the subject is labeled A_1 in its primary project PROJECT_A, but is labeled B_1 when it's shared into PROJECT_B.

How Sharing Impacts Resource Files

When we talk about sharing “data” in the text above, we are referring to the database record that identifies a subject, experiment, or image assessor. The resource files are not copied into the destination project’s archive space. The only copy of the resource files stay associated with the original project’s archive.

This distinction also affects container outputs. Running a container on a shared entity (say, a shared experiment) will cause the container’s outputs to be stored in new resources created on the original entity in the source project, not the entity in the shared project.

Consider this example. A user will be running the “Debug” container, which creates a simple text file resource on a given subject, experiment, scan, or assessor. Assume we have two projects, Project A and Project B. An Experiment E is created in Project A and shared into Project B. Here is what happens in the following scenarios:

A User with edit permissions in Project A runs the Debug container on Experiment E in Project A: The container succeeds, and a new resource file is created on Experiment E in Project A. Users in both Project A and Project B can see the new resource file.
A User with edit permissions in both Project A and Project B runs the Debug container on Experiment E from the shared Project B: The container succeeds, and a new resource file is created on Experiment E in Project A. Users in both Project A and Project B can see the new resource file.
A User with edit permissions in Project B, but not Project A, runs the Debug container on Experiment E from shared Project B: The container fails, with an error logged in the History table that says: "User does not have sufficient permissions to create the output Resource"

Mounting Shared Data in Containers and Notebooks

For users who are running the Container Service plugin or the JupyterHub Integration plugin and want to have shared data in their projects accessible to their containers or notebooks, XNAT 1.8.10 and above makes this possible. Resource files from shared experiments are added to the read-only file mount used by both containers and notebooks.

The same permissions restrictions as specified above applies to saving resource files back to shared data objects in XNAT from a container or a notebook. Users without write permission in the source data project may experience command failures or failed API calls in notebooks if they attempt to write data back to shared project data.