Background
Update: The API has been extended to apply to Evaluations as well as Entities.
Update: The API has been extended to apply to Teams. See Teams
Update: We allow updating of Access Requirements by the ACT. We allow Access Requirements to apply to Folders as well as Files. Entities inherit any access restrictions applies to Folders which contain them.
Update: We add inheritance of access requirements: Each entity inherits the access requirements of its ancestors (e.g. the Folder(s) containing a given File).
IRB-approved versions of all of the 'data access documents' :
...
- Data layer access in Synapse requires one or more approval steps.
- In Synapse granting data access is synonymous with providing the URL to the stored data.
(This URL may have an embedded access token.)
- Currently (i.e. as of Jan. 2012), the backend Prior to this work, the back end has a representation of EULAs and of Agreements (i.e. that a particular user agrees to a EULA)
- The work flow logic for creating the agreement is embedded in the Web client, so other clients would have to maintain duplicate logic. Specifically, the web client has the following logic:
1) When a user tries to download a layer, the Web client checks whether the parent dataset has an associate EULA;
2) If there is an EULA, the web client checks whether there is an Agreement, owned by the User and referencing the dataset and EULA;
3) If there is a EULA but no Agreement, the web client prompts the User to sign the EULA, creates the Agreement, then allows the download.
...
Tier 3: (Tier 1) + (Tier 2) + User access must be requested/approved through an Access and Compliance Team (ACT).
Design
Database
We have two tables , one for Requirements and Approvals: ACCESS_REQUIREMENT , with a foreign key to a node (object) and one for ACCESS_APPROVAL, having contains the requirement information, while NODE_ACCESS_REQUIREMENT 'joins' it to the JDONODE table, saying what entities are affected by the requirement. ACCESS_APPROVAL has foreign keys to ACCESS_REQUIREMENT and principal. The first imposes a requirement for access to the node. The second fulfills the requirement, for a given principal. ACCESS_REQUIREMENT has a 'REQUIREMENT_TYPE' field along with a variable 'REQUIREMENT_PARAMETERS' blob, allowing it to be used for Tier 2 or Tier 3 requirements. (The 'parameters' field could be a Eula, a form to be filled out, or something else.) The ACCESS_APPROVAL table has an APPROVAL_TYPE and an APPROVAL_PARAMETERS blob, allowing it to The requirement and approval tables have an "ENTITY_TYPE" field (populated from an ENUM) and a "SERIALIZED_ENTITY" field, a BLOB, allowing them to have variable content, so they can be used for Tier 2 or Tier 3 approval. (The 'parameters' field could be some form contents, user's IRB information, information from the ACT, or something else.)requirements.
Below we omit the primary key and foreign key constraints for simplicity.
| Code Block |
|---|
CREATE TABLE `ACCESS_REQUIREMENT` ( `ID` bigint(20) NOT NULL AUTO_INCREMENT, `ETAG` bigint(20) NOT NULL, `CREATED_BY` bigint(20) NOT NULL, `CREATED_ON` bigint(20) NOT NULL, `MODIFIED_BY` bigint(20) NOT NULL, `MODIFIED_ON` bigint(20) NOT NULL, `NODE_ID` bigint(20) NOT NULL, `ACCESS_TYPE` varchar(256) CHARACTER SET latin1 COLLATE latin1_bin NOT NULL, `REQUIREMENT`ENTITY_TYPE` varchar(256) CHARACTER SET latin1 COLLATE latin1_bin NOT NULL, `SERIALIZED_ENTITY` mediumblob ) CREATE TABLE `NODE_ACCESS_REQUIREMENT` ( `NODE_ID` bigint(20) NOT NULL, `REQUIREMENT_PARAMETERS` mediumblob, ) ID` bigint(20) NOT NULL, PRIMARY KEY (`NODE_ID`, `REQUIREMENT_ID`) ) CREATE TABLE `EVALAUTION_ACCESS_REQUIREMENT` ( `EVALUATION_ID` bigint(20) NOT NULL, `REQUIREMENT_ID` bigint(20) NOT NULL, PRIMARY KEY (`NODE_ID`, `REQUIREMENT_ID`) ) |
| Code Block |
|---|
CREATE TABLE `ACCESS_APPROVAL` ( `ID` bigint(20) NOT NULL AUTO_INCREMENT, `ETAG` bigint(20) NOT NULL, `CREATED_BY` bigint(20) NOT NULL, `CREATED_ON` bigint(20) NOT NULL, `MODIFIED_BY` bigint(20) NOT NULL, `MODIFIED_ON` bigint(20) NOT NULL, `REQUIREMENT_ID` bigint(20) NOT NULL, `ACCESSOR_ID` bigint(20) NOT NULL, `APPROVAL`ENTITY_TYPE` varchar(256) CHARACTER SET latin1 COLLATE latin1_bin NOT NULL, `APPROVAL`SERIALIZED_PARAMETERS`ENTITY` mediumblob ) |
Data Access Object (DAO)
...
- AccessRequirementDAO.getForNode(), which returns all the AccessRequirements associated with a Node/Entity
- AccessApprovalDAO.getForNode(), which returns all the AccessApprovals associatd with a Node/Entity. This allows us to find all the users who have been given access to an entity via a single database query.
- AccessApprovalDAO.getForAccessRequirementsAndPrincipals() which returns the AccessApprovals for a given list of AccessRequirements and Principals. This method allows us to look up the approval of all the access requirements for a given node (focussing on user of interest) with a single database query.
...
We introduce JSON schemas for the generic interfaces AccessApproval and AccessRequirement, mirroring the tables above, BUT omitting the variable fields. This is because the json schema cannot know the a priori the schema of such variable fields, which are managed separately. We intoduce ENUMs for AccessRequirementType and AccessApprovalType (e.g. ("TOU_Agreement", "ACT_Approval").
We introduce TermsOfUseRequirementParameters to hold the Terms of Use document for an AccessRequirement whose type is TOU_Agreement.
Services
AccessRequirement: Create, Read, Update, Delete
...
and schemas for specific types, TermsOfUseAccessRequirement, TermsOfUseAccessApproval (for tier 2 data), ACTAccessRequirement, and ACTAccessApproval (for tier 3 data).
Services
| Action | URI | Method | Request Body | Authorization | |
| create AccessRequirement | /accessRequirement/ | POST | extension of AccessRequirement.json | parent Entity's UPDATE permission or CHANGE_PERMISSION permission ??? | |
| read AccessRequirement | /accessRequirement/{accessRqmtId} | GET | AccessRequirement.json | parent Entity's READ permission | |
| retrieve paginated list of unfufilled access requirements | /unfulfilledAccessRequirements/{entityId} | GET | PaginatedResults<AccessRequirement> | parent Entity's READ permission | ACT membership |
| create 'lock' Access Requirement | /entity/{id}/lockAccessRequirement | POST | N/A | CREATE or UPDATE access to the entity | |
| read paginated list of all AccessRequirement objects for an entity. This includes both requirements applied directly to the entity and those applied to its ancestors. | /entity/{entityId}/accessRequirement | GET | VariableContentPaginatedResults<AccessRequirement> | ALL | |
| read paginated list of all AccessRequirement objects for an evaluation | /evaluation/{evaluationId}/accessRequirement | GET | VariableContentPaginatedResults<AccessRequirement> | ALL | |
| read paginated list of all AccessRequirement objects for a team | /team/{teamId}/accessRequirement | GET | VariableContentPaginatedResults<AccessRequirement> | ALL | |
| Retrieve paginated list of unfufilled access requirements (of type DOWNLOAD) for an entity. This includes both requirements applied directly to the entity and those applied to its ancestors. | /entity/{entityId}/accessRequirementUnfulfilled | GET | VariableContentPaginatedResults<AccessRequirement> | ALL | |
| Retrieve paginated list of unfufilled access requirements (of type DOWNLOAD or PARTICIPATE) for an evaluation. | /evaluation/{evaluationId}/accessRequirementUnfulfilled | GET | VariableContentPaginatedResults<AccessRequirement> | ALL | |
| Retrieve paginated list of unfufilled access requirements (of type DOWNLOAD or PARTICIPATE) for a Team. | /team/{teamId}/accessRequirementUnfulfilled | GET | VariableContentPaginatedResults<AccessRequirement> | ALL | |
| update AccessRequirement | /accessRequirement/{accessRqmtId} | PUT | extension of AccessRequirement.json | parent Entity's UPDATE permission or CHANGE_PERMISSION permission ???ACT membership | |
| delete AccessRequirement (along with all approvals granted for the requirement) | /accessRequirement/{accessRqmtId} | DELETE | ---- | parent Entity's UPDATE permission or CHANGE_PERMISSION permission ??? | |
| read TermsOfUseRequirementParameters | /termsOfUseRequirementParameters/{accessRqmtId} | GET | TermsOfUseRequirementParameters.json | parent Entity's READ permission | |
| set TermsOfUseRequirementParameters | /termsOfUseRequirementParameters/{accessRqmtId} | PUT | TermsOfUseRequirementParameters.json | parent Entity's UPDATE permission or CHANGE_PERMISSION permission ??? | |
| create AccessApproval | /accessApproval | POST | AccessApproval.json | parent Entity's CHANGE_PERMISSION permission ??? | |
| read AccessApproval | /accessApproval/{accessApprovalid} | GET | AccessApproval.json | parent Entity's READ permission | |
| update AccessApproval | /accessApproval/{accessApprovalid} | PUT | AccessApproval.json | parent Entity's CHANGE_PERMISSION permission ???ACT membership | |
| create AccessApproval | /accessApproval | POST | extension of SelfSignAccessApproval.json | ALL | |
| ACTAccessApproval.json | ACT membership | ||||
| Read all AccessApproval objects for a given entity. This includes the approvals both for the access requirements applied directly to the entity and those applies to the entity's ancestors. | /entity/{entityId}/accessApproval | GET | VariableContentPaginatedResults<AccessApproval> | ACT membership | |
| read all AccessApproval objects for a given evaluation | /evaluation/{evaluationId}/accessApproval | GET | VariableContentPaginatedResults<AccessApproval> | ACT membership | |
| read all AccessApproval objects for a given team | /team/{teamId}/accessApproval | GET | VariableContentPaginatedResults<AccessApproval> | ACT membership | |
| delete AccessApproval | /accessApproval/{accessApprovalid} | DELETE | --parent Entity's CHANGE_PERMISSION permission ??? | ACT membership
|
Web UI
TBD
...
When a user clicks Download on the page for a Data object having a Terms of Use access requirement, they are presented with a dialog showing the text from the access requirement, as shown below. If they accept the terms, then an access approval is created and the Download link is presented.
When a user clicks Download on the page for a Data object having an ACT access requirement, they are presented with a dialog showing the text from the access requirement, as shown below. Once they contact the ACT team, someone from the team may create the approval object on their behalf, after which they may download the Data without encountering the dialog.
