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. Both 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 requirements.
...
| 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,
`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_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, `ENTITY_TYPE` varchar(256) CHARACTER SET latin1 COLLATE latin1_bin NOT NULL, `SERIALIZED_ENTITY` mediumblob ) |
...
We introduce JSON schemas for the generic interfaces AccessApproval and AccessRequirement, and schemas for specific types, TermsOfUseAccessRequirement, TermsOfUseAccessApproval (for tier 2 data), ACTAccessRequirement, and ACTAccessApproval (for tier 3 data).
Services
AccessRequirement: Create, Read, Update, Delete
| action | uri | HTTP method | Schema | Action | URI | Method | Request Body | Authorization |
|---|---|---|---|---|---|---|---|---|
| create AccessRequirement | /accessRequirement | POST | extension of AccessRequirement.json | parent Entity's CHANGE_PERMISSION permissionACT 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> | parent Entity's READ permission | retrieve 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. | /unfulfilledAccessRequirementsteam/{entityIdteamId}/accessRequirementUnfulfilled | GET | VariableContentPaginatedResults<AccessRequirement> | parent Entity's READ permissionALL | ||||
| update AccessRequirement | /accessRequirement/{accessRqmtId} | PUT | extension of AccessRequirement.json | ACT membership | ||||
| delete AccessRequirement (along with all approvals granted for the requirement) | /accessRequirement/{accessRqmtId} | DELETE | ---- | parent Entity's CHANGE_PERMISSION permissionACT membership | ||||
| create AccessApproval | /accessApproval | POST | AccessApproval.json | parent Entity's CHANGE_PERMISSION permission | 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 entityevaluation | /evaluation/{evaluationId}/accessApproval | GET | VariableContentPaginatedResults<AccessApproval> | ACT membership | ||||
| read all AccessApproval objects for a given team | /team/{entityIdteamId}/accessApproval | GET | PaginatedResults<AccessApproval> | parent Entity's READ permissionVariableContentPaginatedResults<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.
