Solution
From the use cases that listed in this document, we list the summary of the solution below:
- The ACT has a way to manage requests for datasets under ACTAccessRequirement. We need to support the following:
- Ability to view Submitted requests for a particular dataset. Allowing the ACT to see all information and quickly decide if the request contains the required information.
- Ability to approve a request and grant access to all accessors.
- Ability to reject a request, provide the instructions on how to correct/provide the missing information, and send email to requestor.
- The ACT has a way to configure the ACTAccessRequirement to indicate the required information, if the data set requires annual renewal, and if the intended data use statement should be public.
- A requestor has a way to create a request, save it, and submit it to ask for access to a dataset under ACTAccessRequirement.
- A requestor will be able to correct the old request and submit it after the old submission was rejected. They would not need to type/ provide any correct information that they already provided in the old submission.
- A requestor will be able to remove an accessor from his/her approved request. This action takes away the accessor's access to the dataset.
- The system automatically sends annual review reminder emails to accessors.
- An accessor will be able to provide the required information for the annual review process to keep their access to the dataset.
- An accessor will be able to provide the final statement of use when they no longer need to access the controlled data.
- The system will automatically remove AccessApproval from users who have not submitted a renewal request within a year for dataset that requires renewal.
We recognize the needs to support #1 - #7 in the first phase. From the ACT, we haven't had users come back to us with a final statement of use, so #8 would have low priority. We are not very strict about removing access, so not sure if #9 is necessary.
Object Models
| ACTAccessRequirement |
|---|
| (original fields) |
| Boolean isCertifiedUserRequired |
| Boolean isValidatedProfileRequired |
| Boolean isDUCRequired |
| String ducTemplateFileHandleId |
| Boolean isIRBApprovalRequired |
| Boolean areOtherAttachmentsRequired |
| Boolean isAnnualReviewRequired |
| Boolean isIDUPublic |
| ResearchProject |
|---|
| String id |
| String accessRequirementId |
| String institution |
| String projectLead |
| String intendedDataUseStatement |
| String createdBy |
| Long createdOn |
| String modifiedBy |
| Long modifiedOn |
Any user can create a ResearchProject. To create a ResearchProject, the following information are required: accessRequirementId, institution, projectLead, intendedDataUseStatement, ownerId, and createdBy. The following fields: id, createdOn, and modifiedOn are set by the system. A user will not be able to change these values.
After a ResearchProject is created, only the creator can make changes to a ResearchProject. The owner can also change the ownership of a ResearchProject by changing the ownerId value to another userId that has been granted access to the dataset under the same ResearchProject. After taking over the ResearchProject, a user would have the same permissions with the DataAccessRequest's creator.
| DataAccessRequest implements DataAccessRequestInterface |
|---|
| String id |
| String accessRequirementId |
| String createdBy |
| Long createdOn |
| String researchProjectId |
| List<String> accessors |
| String ducFileHandleId |
| String irbFileHandleId |
| List<String> attachments |
| String modifiedBy |
| Long modifiedOn |
Any user can create a DataAccessRequest to a given AccessRequirement. To create a DataAccessRequest, the following fields are required: accessRequirementId, and createdBy. The following fields: id, createdOn, and modifiedOn are set by the system. A user cannot change these values.
Only creator of DataAccessRequest can update, and submit the request. To submit a request, it has to meet the requirements specified in the associated AccessRequirement.
Once a request is submitted, a DataAccessSubmission object is created. While there is an DataAccessSubmission with status SUBMITTED, it's associated DataAccessRequest no longer available for update & submit.
| DataAccessRenewal implements DataAccessRequestInterface extends DataAccessRequest |
|---|
| String publication |
| String summaryOfUse |
Once a DataAccessSubmission is approved and requestor wants to add/ remove accessors, he/she needs to update the request with a DataAccessRenewal, given the publication and summaryOfUse in addition to editing the existing information from the original DataAccessRequest.
Submitting a DataAccessRenewal will also result in a DataAccessSubmission being created with status SUBMITTED.
| DataAccessSubmission |
|---|
| String id |
| String dataAccessRequestId |
| String submittedBy |
| Long submittedOn |
| ResearchProject researchProjectSnapshot |
| List<String> accessors |
| Boolean isRenewalSubmission |
| String ducFileHandleId |
| String irbFileHandleId |
| List<String> attachments |
| String publication |
| String summaryOfUse |
| DataAccessSubmissionState state (SUBMITTED, APPROVED, REJECTED, CANCELED) |
| String reviewerId |
| Long reviewedOn |
| String rejectedReason |
Once a DataAccessSubmission is created, it will have state SUBMITTED until a reviewer (ACT member) review and update its status.
After a submission is Rejected and a reason is provided, the submission is closed for modification.
When an ACT member approves a submission, multiple AccessApproval are created for each accessor.
When a requestor adds/removes a user, he/she will also need to update the request and create a new submission. An ACT member will review the new submission and make decision to grant/revoke access to the accessor.
Services
| Action | Intended User | URI | Method | Request Params | Request Body | Response Body | |
|---|---|---|---|---|---|---|---|
| create or update Research Project | Synapse User | /researchProject | POST | ResearchProject | ResearchProject | ||
| get ResearchProject for update | creator | /accessRequirement/{id}/researchProjectForUpdate | GET | ResearchProject | |||
| 5 | |||||||
| 6 | |||||||
| 7 | asking the server for a suitable request object to start with | creator | /accessRequirement/{id}/dataAccessRequestForUpdate | GET | DataAccessRequestInterface | ||
| create or update DataAccessRequest | Synapse User | /dataAccessRequest | POST | DataAccessRequestInterface | DataAccessRequestInterface | ||
| 9 | submit a DataAccessRequest | creator, | /dataAccessRequest/{id}/submission | POST | etag | ACTAccessRequirementStatus | |
| 11 | cancel a DataAccessSubmission | requestor, | /dataAccessSubmission/{id}/cancellation | PUT | ACTAccessRequirementStatus | ||
| 12 | update a DataAccessSubmission | ACT | /dataAccessSubmission/{id} | PUT | SubmissionStateChangeRequest | DataAccessSubmission | |
| 13 | retrieve a list of DataAccessSubmission | ACT | /accessRequirement/{id}/submissions | GET | nextPageToken, order (DataAccessSubmissionOrder), filter (DataAccessSubmissionState), asc | DataAccessSubmissionPage | |
| 15 | retrieve restriction info for a given entity | Synapse user | /entity/{id}/restrictionInformation | GET | RestrictionInfo | ||
| 16 | retrieve access requirement status | Synapse user | /accessRequirement/{id}/status | GET | AccessRequirementStatus | ||
| 17 | retrieve info about open submissions | ACT | /dataAccessSubmission/openSubmissions | GET | nextPageToken | OpenSubmissionPage | |
| 18 | retrieve approval info for users | ACT | /accessApproval/batch | POST | BatchAccessApprovalRequest | BatchAccessApprovalResult |
| BatchAccessApprovalRequest |
|---|
List<String> userIds String accessRequirementId |
| BatchAccessApprovalResult |
|---|
| List<AccessApprovalResult> results |
| AccessApprovalResult |
|---|
| String userId |
| String accessRequirementId |
| Boolean hasAccessApproval |
| OpenSubmissionPage |
|---|
| List<OpenSubmission> openSubmissionList |
| String nextPageToken |
| OpenSubmission |
|---|
| String accessRequirementId |
| Long numberOfOpenSubmissions |
| ACTAccessRequirementStatus implements AccessRequirementStatus |
|---|
| String accessRequirementId |
| String submittedBy |
| String submissionId |
| DataAccessSubmissionState state |
| String rejectedReason |
| Long reviewedOn |
| SubmissionStateChangeRequest |
|---|
| String submissionId |
| DataAccessSubmissionState newState (only APPROVED and REJECTED are valid) |
| String rejectedReason |
| RestrictionInfo |
|---|
| RestrictionLevel restrictionLevel (OPEN, RESTRICTED_BY_TERMS_OF_USE, CONTROLLED_BY_ACT) |
| boolean hasUnmet |
| TermsOfUseAccessRequirementStatus implements AccessRequirementStatus |
|---|
| String accessRequirementId |
| boolean isApproved |
Compare behaviors of #6 and #7
| GET /accessRequirement/{id}/dataAccessRequestForUpdate | ||
|---|---|---|
| user has not created a request | empty DataAccessRequest | |
| user has a request, zero APPROVED submission | the created DataAccessRequest | |
| user has an APPROVED submission, requires renewal | re-filled DataAccessRenewal | |
| user has an APPROVED submission, renewal not required | the created DataAccessRequest |
Notification
| Condition | Target User | Notes | |
|---|---|---|---|
| 1 | After a new submission is created | ACT member | Includes link to a page that manages the dataset's access requests |
| 2 | After a submission is approved | Requestor | Includes link to view request |
| 3 | After a submission is rejected | Requestor | Includes reason Includes link to create a new request from the rejected one |
May Summary
By May 2017, we have completed #1-4, #7 & #8 under Solution. We have implemented all APIs listed under Services. The feature is under alpha in stack-180.
From user's feeback, we still need to provide the following:
1. Need notifications for ACT when there is a new submission - may only get 1-2 requests a week for old dataset.
2. Revoking access - when user is removed in an updated request, revoke user access. System should send a message to the people removed (Amy to help with messaging).
3. Bundle submission together (like Brian suggested) to see latest + history. May be able to work around if we have ability to sort by institution, and filter by Submitted By.
4. RENEWAL SUPPORT. ACT currently manually revokes user access. We need to help support the existing process in the new system, or automate it.
To help support, they need ability to filter by the date granted access, and ability to get the list of emails. Alternatively, system could automatically send out emails at specific reminder dates, and auto-revoke access after expiration.
As a path moving forward, we decided that when we bring the feature out of alpha, an ACT member can continue managing access outside of Synapse, or switch to use the new system. To be able to achieve this, SWC needs to know if an ACTAccessRequirement was configured to use Synapse to keep track of Submission.
After a discussion, we conclude on:
- Making AccessRequirement version-able.
- An access approval grants a user access to a specific access requirement version.
- On download, if a user have access approval for one version of the access requirement, the user meets the conditions specified by that access requirement.
- A new API need to be added to retrieve a version of an access requirement.
- Retrieving restriction information API needs to be generic (taking an ID and subject type instead of being specific for entity only)
- A submission points to a particular access requirement version.
- Retrieving Access Requirement Status always include information about whether or not a user have met the conditions specified by the access requirement regardless of version.