NOTE: The scripts below are replaced by the tool set now built into Synapse. To access:

Log into Synapse as an ACT member.
Go to the dataset of interest.
Select Tools > Change User Access - or - Manage Access Requirements

If the tools built in to Synapse do not meet your needs, kindly contact the Synapse Engineering Team via JIRA.

This page contains the instructions to be followed by the Access and Compliance team for managing access restrictions on data in Synapse.

The design details for the system are here: https://sagebionetworks.jira.com/wiki/display/PLFM/Data+Access+Control

In the initial release of Data Access Control ("Governance"), restrictions are managed from the command line rather than through the Synapse web interface. Here the commands are presented in the form of "R" commands. In all cases the user performing the Governance tasks must have administrative access to the object being managed.

Update: To implement PLFM-1730, we allow multiple access restrictions to be placed on an entity. Synapse records the order in which you create access restrictions. If there are multiple, unfulfilled restrictions, the Synapse Web interface will display the first of these, along with instructions for the user to seek approval for that restriction. If all restrictions are fulfilled, then Synapse will show the first one created. The data restriction level shown for the Synapse entity is the most restrictive of all the restrictions attached to the entity. For example if one Restricted (Terms of Use) restriction and one Controlled (ACT Approval) restriction are applied to an entity, then the entity will be displayed as Controlled.

How to set up the Synapse R client on your machine:

# these two lines install the R Synapse Client.  You only need do this once
source('http://depot.sagebase.org/CRAN.R')
pkgInstall("synapseClient")

# This has to be done each time you start up R:
library(synapseClient)
 
# one time call: 
synapseLogin("username","password", rememberMe=TRUE) # thereafter you can simply call "synapseLogin()" without typing your credentials

How to remove the 'default' access requirement and create new restrictions

library(synapseClient)
synapseLogin(<your user name>, <your password>, rememberMe=TRUE) # later you can log in with "synapseLogin()"
 
#######################################
#Add Restricted (Tier 2) Access Control to syn1446624
########################################
entityIds<-list("syn1446624")


##########Step 1.  Remove the access requirement set by JIRA when the data owner requested restrictions.
#Automatic restriction is: "Access restricted pending review by Synapse Access and Compliance Team."


#Identify the 'restriction id' for the above restriction
currentRestrictions<-synRestGET(paste("/entity/", entityIds[[1]], "/accessRequirement", sep=""))
#$results[[1]]$id
#[1] 1426942


#remove this restriction
requirementId<-currentRestrictions$results[[1]]$id
synRestDELETE(paste("/accessRequirement/", requirementId, sep=""))


###AT THIS POINT, THE DATA IS COMPLETELY OPEN BECAUSE YOU REMOVED THE FORMER RESTRICTION AND HAVE NOT ADDED THE NEW ONE.


# Step 2. Create the new restriction. 
subjectIds<-lapply(entityIds, function(x){list(id=x,type="ENTITY")})
ar <- list(concreteType="org.sagebionetworks.repo.model.TermsOfUseAccessRequirement",
           subjectIds=subjectIds, accessType="DOWNLOAD",
           termsOfUse="The terms under which this dataset may be accessed require that you agree to use this data only for neuropsychiatric research performed for non-commercial purposes.")
ar<-synRestPOST("/accessRequirement", ar)


#######################################
#Add Controlled (Tier 3) Access Control to syn1446623
########################################
# use the synapse identifier for the data object to be put under access control
entityIds<-list("syn1446623")


##########Step 1.  Remove the access requirement created when the data owner requested restrictions.
#Automatic restriction is: "Access restricted pending review by Synapse Access and Compliance Team."


#Identify the 'restriction id' for the above restriction
currentRestrictions<-synRestGET(paste("/entity/", entityIds[[1]], "/accessRequirement", sep=""))
#$results[[1]]$id
#[1] 1426942


#remove this restriction
requirementId<-currentRestrictions$results[[1]]$id
synRestDELETE(paste("/accessRequirement/", requirementId, sep=""))


###AT THIS POINT, THE DATA IS COMPLETELY OPEN BECAUSE YOU REMOVED THE FORMER RESTRICTION AND HAVE NOT ADDED THE NEW ONE.


# # create the Tier Three access requirement
subjectIds<-lapply(entityIds, function(x){list(id=x,type="ENTITY")})
openJiraIssue<-TRUE # set to true or false to control whether the web portal allows the user to open a JIRA issue 
actContactInfo<-"Access to these data is controlled at the request of the data contributor and due to the sensitive nature of the data. <br/> <br/> Please contact the Access and Compliance Team for instruction, by clicking below, if you are interested in applying for access to these data."
ar <- list(concreteType="org.sagebionetworks.repo.model.ACTAccessRequirement",
           subjectIds=subjectIds, accessType="DOWNLOAD",
           actContactInfo=actContactInfo,
			openJiraIssue=openJiraIssue)
ar<-synRestPOST("/accessRequirement", ar)

How to add a 'restricted' access requirement to a file:

# log in to Synapse
library(synapseClient)
synapseLogin(<your user name>, <your password>)

# use the synapse identifier for the data object to be put under access control
entityIds<-list("syn987654")

# create the Terms of Use access requirement
subjectIds<-lapply(entityIds, function(x){list(id=x,type="ENTITY")})
 ar <- list(concreteType="org.sagebionetworks.repo.model.TermsOfUseAccessRequirement", subjectIds=subjectIds, accessType="DOWNLOAD", termsOfUse="The terms under which this dataset may be accessed require that you agree not to transfer or disclose the Data, in whole or part, or any material derived from the Data, to others, except to persons within your Institution.")

ar<-synRestPOST("/accessRequirement", ar)

When someone tries to download the data from the Web interface, they will be presented with a agreement which they must accept before they are able to complete the download.

How to add a 'restricted' access requirement ('click wrap') to a Team:

Putting access requirements on the team will result in the terms of use being displayed as a click-through when a participant presses a (properly configured) register button.

# log in to Synapse
library(synapseClient)
synapseLogin(<your user name>, <your password>)

# use the synapse identifier for the Team to be put under the 'click wrap'
teamIds<-list("1234567")

# create the access requirement
subjectIds<-lapply(teamIds, function(x){list(id=x,type="TEAM")})
ar <- list(concreteType="org.sagebionetworks.repo.model.TermsOfUseAccessRequirement", subjectIds=subjectIds, accessType="PARTICIPATE", 
termsOfUse="<click wrap goes here>")
ar<-synRestPOST("/accessRequirement", ar)

Here's an example terms of use object that contains the DREAM 10 rules: (But, see SYNR-990)

ar <- list(
  concreteType="org.sagebionetworks.repo.model.TermsOfUseAccessRequirement",
  subjectIds=list(list(id="1234567", type="TEAM")),
  accessType="PARTICIPATE",
  termsOfUse='<div class="markdown" style="margin-left:20px; margin-right:20px;">\t\t<h3>Please read the full <a href="https://www.synapse.org/#!Synapse:syn4294018/wiki/" class="link" target="_blank">DREAM 10 Challenge Rules</a>.</h3>\t\t<h3 style="margin-bottom:10px">These rules cover:</h3>\t\t<div class="row" style="height: 90px;">\t\t\t<div class="col-xs-6">\t\t\t\t<img class="left" src="https://s3.amazonaws.com/static.synapse.org/images/person.png" /><h5 style="padding-top: 25px; text-align:left;">Who can participate</h5>\t\t\t</div>\t\t\t<div class="col-xs-6">\t\t\t\t<img class="left" src="https://s3.amazonaws.com/static.synapse.org/images/certificate.png" /><h5 style="padding-top: 5px; text-align:left;">What you need to submit to be evaluated as a best performer</h5>\t\t\t</div>\t\t</div>\t\t<div class="row" style="height: 110px;">\t\t\t<div class="col-xs-6">\t\t\t\t<img class="left" src="https://s3.amazonaws.com/static.synapse.org/images/people.png" /><h5 style="padding-top: 5px; text-align:left;">How to participate as an individual and on teams</h5>\t\t\t</div>\t\t\t<div class="col-xs-6">\t\t\t\t<img class="left" src="https://s3.amazonaws.com/static.synapse.org/images/anonymous-person.png" style="margin-bottom: 20px;" /><h5 style="text-align:left;">Your right to participate anonymously <small>To participate anonymously, you must update your Synapse username to a pseudonym.</small></h5>\t\t\t</div>\t\t</div>\t\t<div class="row" style="height: 80px;">\t\t\t<div class="col-xs-6">\t\t\t\t<img class="left" src="https://s3.amazonaws.com/static.synapse.org/images/unlock.png" /><h5 style="text-align:left;">That DREAM Challenges are IP-free and open source</h5>\t\t\t</div>\t\t\t<div class="col-xs-6">\t\t\t\t<img class="left" src="https://s3.amazonaws.com/static.synapse.org/images/handshake.png" style="margin-bottom: 20px;" /><h5 style="text-align:left;">How we will resolve disagreements with participants</h5>\t\t\t</div>\t\t</div>\t\t<h5>By clicking "Accept" you confirm that you have read and accept the DREAM 10 Challenge Rules</h5></div>')

ar<-synRestPOST("/accessRequirement", ar)

How to add a 'controlled' access requirement to a file:

# log in to Synapse
library(synapseClient)
synapseLogin(<your user name>, <your password>)

# use the synapse identifier for the data object to be put under access control
entityIds<-list("syn987654")

# # create the Tier Three access requirement
subjectIds<-lapply(entityIds, function(x){list(id=x,type="ENTITY")})
openJiraIssue<-TRUE # set to true or false to control whether the web portal allows the user to open a JIRA issue 
actContactInfo<-"Please complete the following form and email it to the Access and Compliance Team at act@sagebase.org.<br/>  1) Your name:<br/>  2) Your organization: <br/> 3) Your IRB number: <br/> "
ar <- list(concreteType="org.sagebionetworks.repo.model.ACTAccessRequirement", subjectIds=subjectIds, accessType="DOWNLOAD", actContactInfo=actContactInfo, openJiraIssue=openJiraIssue)

ar<-synRestPOST("/accessRequirement", ar)

How to add a wiki page to an access requirement:

In the above examples the text of the access requirement was embedded directly in the requirement (in the 'termsOfUse' or 'actContactInfo' field). An alternative is to create a wiki page and attach it to the access requirement. Synapse will then show the markdown from the wiki page when the access requirement is displayed. To do this, first create the access requirement as shown above, but omit 'termsOfUse' or 'actContactInfo'. Then issue the following command

wikipage <- list(title="title", markdown="put markdown here", attachmentFileHandleIds=c("101", "102", "103"))
synRestPOST(sprintf("/access_requirement/%s/wiki", ar$id), wikipage)

where you are to replace "title", "markdown" and the list of attachmentFileHandleIds with their actual values. If you have already created a wiki that you wish ot use:

wikipage <- synGetWiki(synGet("syn12345")) # Note: replace "syn12345" with the ID of the project, folder or file that has the wiki page.
wikipage$id<-NULL
wikipage$parentWikiId<-NULL
if (length(wikipage$attachmentFileHandleIds)==1) wikipage$attachmentFileHandleIds<-list(wikipage$attachmentFileHandleIds)
synRestPOST(sprintf("/access_requirement/%s/wiki", ar$id), wikipage)

When someone tries to download the data from the Web interface, they will be presented with instructions for contacting the Access and Compliance Team to request download access.

How to link to an approval form to an access requirement:

In the actContactInfo, ensure that any anchor tags (<a>) include the attribute target="blank", e.g.:

actContactInfo<-"Please complete this form and send to act@sagebase.org:<br/><a href=\"https://staging.synapse.org/#!Synapse:syn2295117\" target=\"_blank\">https://staging.synapse.org/#!Synapse:syn2295117</a>"

This is necessary to make the browser open a new tab to show the approval form.

How to delete an existing access requirement:

If a requirement is deleted, all the approvals for said requirement are deleted as well. To delete from R:

requirementId<-"7"
synRestDELETE(paste("/accessRequirement/", requirementId, sep=""))

How to update an existing access requirement:

An access requirement may be changed after it is created. The main use for this is to add files to an existing requirement. You can also change the displayed text.

# Say there is currently an access restriction on just one file, syn2319165.
> entityIds<-list("syn2319165")
> currentRestrictions<-synRestGET(paste("/entity/", entityIds[[1]], "/accessRequirement", sep="")) 
# Check that there is just one restriction
> currentRestrictions$totalNumberOfResults
[1] 1
# set 'ar' to be the restriction
> ar<-currentRestrictions$results[[1]]
# now verify what is the current entity list for the access restriction
> ar$subjectIds
[[1]]
          id         type 
"syn2319165"     "ENTITY" 
 # Now let's make the restriction apply to two files rather than one.
> entityIds<-list("syn2319165", "syn2341872")
> subjectIds<-lapply(entityIds, function(x){list(id=x,type="ENTITY")})
> ar$subjectIds<-subjectIds
#
#
#
# Optionally change the text of the access requirement
# If the Access Requirement is an "ACT" (Tier 3) Access Requirement, then the field is called "actContactInfo":
ar$actContactInfo<-"new ACT contact info"
#
# -- OR --
#
# If the Access Requirement is a "Terms of use" ("click wrap") Access Requirement, then the field is called "termsOfUse":
ar$termsOfUse<-"new click-wrap text"
#
#
# (The above two fields are the only mutable ones: the list of entities and the displayed text.)
#
# This command sends the modified restriction to Synapse.
> ar<-synRestPUT(paste("/accessRequirement/", ar$id, sep=""), ar)
> ar$subjectIds
[[1]]
          id         type 
"syn2319165"     "ENTITY" 
[[2]]
          id         type 
"syn2341872"     "ENTITY"