Versions Compared

Old Version 69

changes.mady.by.user Amy Truong (Unlicensed)

Saved on

compared with

New Version Current

changes.mady.by.user Bruce Hoff

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

NOTE:

...

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

  1. Log into Synapse as an ACT member.

  2. Go to the dataset of interest.

  3. 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.


Table of Contents

 

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

...

Code Block
# 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)

 

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 add a wiki page to an access requirement:

In the above examples the text of the access requirement was embedded directly in the actContactInfo, ensure that any anchor tags (<a>) include the attribute target="blank", e.g.:

Code Block
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:

Code Block
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.

...

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

Code Block
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:

Code Block
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.:

Code Block
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:

Code Block
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.

Code Block
# 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]]
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 istype an
"ACTsyn2341872" (Tier 3) Access Requirement, then"ENTITY" 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

 

How to list the access requirements for a data object:

Use the following function, which you can cut/paste into your R session:

Code Block
listRequirementsForEntity<-function(entityId) {
	ars<-synRestGET(sprintf("/entity/%s/accessRequirement", entityId))$results
	for (ar in ars) {
		if (ar$concreteType=="org.sagebionetworks.repo.model.ACTAccessRequirement") {
			text<-ar$actContactInfo
		} else {
			text<-ar$termsOfUse
		}
		cat(sprintf("id=%s type=%s text=%s...\n", ar$id, substring(text=ar$concreteType, first=1+nchar("org.sagebionetworks.repo.model.")), substr(text, 1, 50)))
	}
}

 

How to find out who has access to a data object:

Use the following function, which you can cut/paste into your R session:

Code Block
whoHasAccess<-function(entityId) {
    moreResults<-T
    aas<-list()
    offset<-0
    pageSize<-25
    while (moreResults) {
        page<-synRestGET(sprintf("/entity/%s/accessApproval?limit=%s&offset=%s", entityId, pageSize, offset))$results
        type 
"syn2319165"if (length(page)==0) moreResults<-F
    "ENTITY"  [[2]]  aas <- append(aas, page)
     id   offset<-offset+pageSize
    }
type  "syn2341872"  ups<-list()
  "ENTITY"

 

How to list the access requirements for a data object:

Use the following function, which you can cut/paste into your R session:

Code Block
listRequirementsForEntity<-function(entityId) {
	ars<-synRestGET(sprintf("/entity/%s/accessRequirement"approvedUsers<-list()
    cat(sprintf("There are %d access approvals for entity %s\n", length(aas), entityId))$results
    	for (araa in arsaas) {
		if (ar$concreteType=="org.sagebionetworks.repo.model.ACTAccessRequirement") { 			text<-ar$actContactInfo 		} else { 			text<-ar$termsOfUse
		}
		 # cat(sprintf("approval id=%s requirement typeid=%s, user textid=%s...\n", ar$idaa$id, substring(text=ar$concreteType, first=1+nchar("org.sagebionetworks.repo.model.")), substr(text, 1, 50)))
	}
}

 

How to find out who has access to a data object:

Use the following function, which you can cut/paste into your R session:

Code Block
whoHasAccess<-function(entityId) {
    aas<-synRestGET(sprintf("/entity/%s/accessApproval", entityId))$results
    ups<-list()
    approvedUsers<-list()
    cat(sprintf("There are %d access approvals for entity %s\n", length(aas), entityIdaa$requirementId, aa$accessorId))
        userId<-aa$accessorId
        reqId<-aa$requirementId
        if (!any(approvedUsers[[userId]]==reqId)) {
            approvedUsers[[userId]]<-append(approvedUsers[[userId]], reqId)
        }
        if (is.null(ups[[userId]])) {
            ups[[userId]]<-synRestGET(sprintf("/userProfile/%s", userId))
    for (aa in aas) {}
        # cat(sprintf("approval id=%s requirement id=%s, user id=%s\n", aa$id, aa$requirementId, aa$accessorId))".")
    }
    cat("\n")
    for (userId in  userId<-aa$accessorIdnames(approvedUsers)) {
        reqId<-aa$requirementIddisplayName<-ups[[userId]]$displayName
        if (!any(approvedUsersuserName<-ups[[userId]]==reqId))$userName
{        if (is.null(displayName)) {
  approvedUsers[[userId]]<-append(approvedUsers[[userId]], reqId)         }
        if (is.null(ups[[userId]])) {cat(sprintf("%s (id=%s) is approved for access requirement(s) %s\n", userName, userId,
                upspaste(approvedUsers[[userId]]<-synRestGET(sprintf("/userProfile/%s", userId, collapse=",")))
        } else     {
  cat(".")     }     cat(sprintf("\n")
   %s (username=%s, id=%s) is approved for (userId in names(approvedUsers)) {
        displayName<-ups[[userId]]$displayName
 access requirement(s) %s\n", displayName, userName, userId,
      userName<-ups[[userId]]$userName         if (is.null(displayNamepaste(approvedUsers[[userId]], collapse=",")))
{        }
    cat(sprintf("%s (id=%s) is approved for access requirement(s) %s\n", userName, userId,}
}


 

How to find out if a specific user has access to a data object:

Use the following function, which you can cut/paste into your R session:

Code Block
doesUserHaveAccess<-function(entityId, principalId) {

    moreResults<-T
    aas<-list()
     paste(approvedUsers[[userId]], collapse=",")))offset<-0
    pageSize<-25
     } elsewhile (moreResults) {
            catpage<-synRestGET(sprintf("%s (username=%s, id=%s) is approved for access requirement(s) %s\n", displayName, userName, userId,
/entity/%s/accessApproval?limit=%s&offset=%s", entityId, pageSize, offset))$results
               paste(approvedUsers[[userId]], collapse=",")))
if (length(page)==0) moreResults<-F
       } aas <- append(aas, page)
}   }

 

How to find out if a specific user has access to a data object:

Use the following function, which you can cut/paste into your R session:

Code Block
doesUserHaveAccess<-function(entityId, principalId) {  offset<-offset+pageSize
  aas<-synRestGET(sprintf("/entity/%s/accessApproval", entityId))$results  }
    approvedRequirements<-list()
    cat(sprintf("There are %d access approvals for entity %s\n", length(aas), entityId))
    for (aa in aas) {
        # cat(sprintf("approval id=%s requirement id=%s, user id=%s\n", aa$id, aa$requirementId, aa$accessorId))
        userId<-aa$accessorId
        reqId<-aa$requirementId
        if (userId==principalId && !any(approvedRequirements==reqId)) {
            approvedRequirements<-append(approvedRequirements, reqId)
           	cat(sprintf("\nuser %s was approved for requirement %s by %s on %s\n", principalId, reqId, aa$createdBy, aa$createdOn))
		}
        cat(".")
    }
    cat("\n")
    allRequirements<-list()
    ars<-synRestGET(sprintf("/entity/%s/accessRequirement", entityId))$results
    for (ar in ars) {
        allRequirements<-append(allRequirements, ar$id)
    }
    if (length(allRequirements)>0) allRequirements<-sort(unlist(allRequirements))
    if (length(approvedRequirements)>0) approvedRequirements<-sort(unlist(approvedRequirements))
    if (identical(allRequirements, approvedRequirements)) {
        message(sprintf("User %s DOES have access approvals for ALL %d access requirement(s) on %s", 
            principalId, length(allRequirements), entityId))
    } else {
        if (length(approvedRequirements>0)) {
            message(sprintf("User %s does NOT have access approvals for all the %d access requirement(s) on %s, only for %s", 
                principalId, length(allRequirements), entityId, paste(approvedRequirements, collapse=","))))
        } else {
            message(sprintf("User %s does NOT have access approvals for ANY of the %d access requirement(s) on %s", 
       } else {       principalId, length(allRequirements), entityId))
   message(sprintf("User %s does NOT have access}
approvals for ANY of the}
%d access requirement(s) on %s", 
}

(TODO:  We can also display the date/time when approval was granted.)

 

How to grant access for a specific access requirement:

Use the following function, which you can cut/paste into your R session:

Code Block
grantAccess<-function(requirementId, principalId) {
    actApproval <- list(concreteType="org.sagebionetworks.repo.model.ACTAccessApproval", requirementId=requirementId, accessorId=principalId, approvalStatus="APPROVED")
     principalId, length(allRequirements), entityId))
        }
    }actApproval<-synRestPOST("/accessApproval", actApproval)
}

(TODO:  We can also display the date/time when approval was granted.)

 

...

How to remove access to a data object:

The following deletes access approvals for all requirements found on the object, for the given user.

Use the following function, which you can cut/paste into your R session:

Code Block
grantAccess<removeAccess<-function(requirementIdentityId, principalId) {

   actApproval <moreResults<-T
    list(concreteType="org.sagebionetworks.repo.model.ACTAccessApproval", requirementId=requirementId, accessorId=principalId, approvalStatus="APPROVED")
    actApproval<-synRestPOST("/accessApproval", actApproval)
}

 

How to remove access to a data object:

The following deletes access approvals for all requirements found on the object, for the given user.

Use the following function, which you can cut/paste into your R session:

Code Block
removeAccess<-function(entityId, principalId) {
    aas<-synRestGET(sprintf("/entity/%s/accessApproval", entityId))$resultsaas<-list()
    offset<-0
    pageSize<-25
    while (moreResults) {
        page<-synRestGET(sprintf("/entity/%s/accessApproval?limit=%s&offset=%s", entityId, pageSize, offset))$results
        if (length(page)==0) moreResults<-F
        aas <- append(aas, page)
        offset<-offset+pageSize
    }
    cat(sprintf("There are %d access approvals for entity %s\n", length(aas), entityId))
    for (aa in aas) {
        # cat(sprintf("approval id=%s requirement id=%s, user id=%s\n", aa$id, aa$requirementId, aa$accessorId))
        userId<-aa$accessorId
        reqId<-aa$requirementId
        if (userId==principalId) {
            synRestDELETE(sprintf("/accessApproval/%s", aa$id))
            cat(sprintf("\nRemoved access approval for access requirement %s.\n", reqId))
        }
        cat(".")
    }
    cat("\n")
}

...

Use the following function, which you can cut/paste into your R session:

Code Block
whoHasAccessToTeam<-function(teamIdwhoHasAccessToTeam<-function(teamId) {

    moreResults<-T
    aas<-list()
    offset<-0
    pageSize<-25
    while (moreResults) {
    aas<    page<-synRestGET(sprintf("/team/%s/accessApproval?limit=%s&offset=%s", teamId, pageSize, offset))$results
        if (length(page)==0) moreResults<-F
        aas <- append(aas, page)
        offset<-offset+pageSize
    }
    ups<-list()
    approvedUsers<-list()
    cat(sprintf("There are %d access approvals for Team %s\n", length(aas), teamId))
    for (aa in aas) {
        userId<-aa$accessorId
        reqId<-aa$requirementId
        if (!any(approvedUsers[[userId]]==reqId)) {
            approvedUsers[[userId]]<-append(approvedUsers[[userId]], reqId)
        }
        if (is.null(ups[[userId]])) {
            ups[[userId]]<-synRestGET(sprintf("/userProfile/%s", userId))
        }
        cat(".")
    }
    cat("\n")
    for (userId in names(approvedUsers)) {
        displayName<-ups[[userId]]$displayNameuserId]]$displayName
        userName<-ups[[userId]]$userName
        if (is.null(displayName)) {
            cat(sprintf("%s (id=%s) is approved for access requirement(s) %s\n", userName, userId,
                userName<-upspaste(approvedUsers[[userId]]$userName, collapse=",")))
        if (is.null(displayName))} else {
            cat(sprintf("%s (username=%s, id=%s) is approved for access requirement(s) %s\n", displayName, userName, userId,
                paste(approvedUsers[[userId]], collapse=",")))
        } else
    }
}

How to find out if a certain user was approved to join a Team:

Use the following function, which you can cut/paste into your R session:

Code Block
isUserApprovedToJoinTeam<-function(teamId, principalId) {

    moreResults<-T
      cat(sprintf("%s (username=%s, id=%s) is approved for access requirement(s) %s\n", displayName, userName, userId,
aas<-list()
    offset<-0
    pageSize<-25
    while (moreResults) {
        paste(approvedUsers[[userId]], collapse=",")))page<-synRestGET(sprintf("/team/%s/accessApproval?limit=%s&offset=%s", teamId, pageSize, offset))$results
        if (length(page)==0) moreResults<-F
  }     } }

How to find out if a certain user was approved to join a Team:

Use the following function, which you can cut/paste into your R session:

Code Block
isUserApprovedToJoinTeam<-function(teamId, principalId) {aas <- append(aas, page)
        aas<-synRestGET(sprintf("/team/%s/accessApproval", teamId))$resultsoffset<-offset+pageSize
    }
    approvedRequirements<-list()
    cat(sprintf("There are %d access approvals for team %s\n", length(aas), teamId))
    for (aa in aas) {
        userId<-aa$accessorId
        reqId<-aa$requirementId
        if (userId==principalId && !any(approvedRequirements==reqId)) {
            approvedRequirements<-append(approvedRequirements, reqId)
           	cat(sprintf("\nuser %s was approved for requirement %s by %s on %s\n", principalId, reqId, aa$createdBy, aa$createdOn))
		}
        cat(".")
    }
    cat("\n")
    allRequirements<-list()
    ars<-synRestGET(sprintf("/team/%s/accessRequirement", teamId))$results
    for (ar in ars) {
        allRequirements<-append(allRequirements, ar$id)
    }
    if (length(allRequirements)>0) allRequirements<-sort(unlist(allRequirements))
    if (length(approvedRequirements)>0) approvedRequirements<-sort(unlist(approvedRequirements))
    if (identical(allRequirements, approvedRequirements)) {
        message(sprintf("User %s DOES have access approvals for ALL %d access requirement(s) on %s", 
            principalId, length(allRequirements), teamId))
    } else {
        if (length(approvedRequirements>0)) {
            message(sprintf("User %s does NOT have access approvals for all the %d access requirement(s) on %s, only for %s", 
                principalId, length(allRequirements), teamId, paste(approvedRequirements, collapse=",")))
        } else {
            message(sprintf("User %s does NOT have access approvals for ANY of the %d access requirement(s) on %s", 
                principalId, length(allRequirements), teamId))
        }
    }
}

...