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 |