| Table of Contents |
|---|
Solution
From the use cases that listed in this document, we list the summary of the solution below:
...
| ResearchProject |
|---|
| String id |
| String accessRequirementId |
| String institution |
| String projectLead |
| String intendedDataUseStatement |
| String createdBy |
| Long createdOn |
| String modifiedBy |
| Long modifiedOn |
...
After a ResearchProject is created, only the owner 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 Request implements DataAccessRequestInterfaceRequestInterface |
|---|
| 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 a Request to a given AccessRequirement. To create a DataAccessRequestRequest, 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 Request 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 Submission object is created. While there is an DataAccessSubmission Submission with status SUBMITTED, it's associated DataAccessRequest Request no longer available for update & submit.
| DataAccessRenewal Renewal implements DataAccessRequestInterfaceRequestInterface extends DataAccessRequestRequest |
|---|
| String publication |
| String summaryOfUse |
Once a DataAccessSubmission Submission is approved and requestor wants to add/ remove accessors, he/she needs to update the request with a DataAccessRenewalRenewal, given the publication and summaryOfUse in addition to editing the existing information from the original DataAccessRequestRequest.
Submitting a DataAccessRenewal Renewal will also result in a DataAccessSubmission Submission being created with status SUBMITTED.
| DataAccessSubmissionSubmission |
|---|
| 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 |
| SubmissionState state (SUBMITTED, APPROVED, REJECTED, CANCELED) |
| String reviewerId |
| Long reviewedOn |
| String rejectedReason |
Once a DataAccessSubmission Submission is created, it will have state SUBMITTED until a reviewer (ACT member) review and update its status.
...
| Action | Intended User | URI | Method | Request Params | Request Body | Response Body | |
|---|---|---|---|---|---|---|---|
| owner | |||||||
| owner | |||||||
| owner | |||||||
| 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 | SynapseUsercreator | /accessRequirement/{id}/dataAccessRequestForUpdate | GET | DataAccessRequestInterfaceRequestInterface | ||
| create or update Request | Synapse User | /dataAccessRequest | POST | RequestInterface | RequestInterface | ||
| 9 | submit a DataAccessRequestRequest | creator, | /dataAccessSubmission/dataAccessRequest/{id}/submission | POST | DataAccessRequestInterfaceetag | SubmissionStatus | |
| SubmissionStatus | |||||||
| 11 | cancel a DataAccessSubmissionSubmission | requestor, | /dataAccessSubmission/{id}/cancelcancellation | PUT | SubmissionStatus | ||
| 12 | update a DataAccessSubmissionSubmission | ACT | /dataAccessSubmission/{id} | PUT | SubmissionStatusChangeRequestSubmissionStateChangeRequest | DataAccessSubmissionSubmissionStatus | |
| 13 | retrieve a list of DataAccessSubmissionSubmission | ACT | /accessRequirement/{id}/listSubmissionsubmissions | GET | nextPageToken, order (SubmissionOrder), filter (by statusSubmissionState), DataAccessSubmissionPageasc | SubmissionPage | |
| SubmissionStatus | |||||||
| String submissionId | |||||||
| POST | AccessApprovalStatusRequest | AccessApprovalStatusResults | |||||
| ChangeOwnershipRequest | |||||||
| String researchProjectId | |||||||
| String newOwnerId | |||||||
| retrieve restriction information | Synapse user | /restrictionInformation | POST | RestrictionInformationRequest | RestrictionInformationResponse | ||
| 16 | retrieve access requirement status | Synapse user | /accessRequirement/{id}/status | GET | AccessRequirementStatus | ||
| 17 | retrieve info about open submissions | ACT | /dataAccessSubmission/openSubmissions | GET | nextPageToken | OpenSubmissionPage | |
| 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 |
| Boolean isApproved |
| SubmissionStatus current submissionStatus |
SubmissionStatus |
|---|
| String submittedBy |
| String submissionId |
| SubmissionState state |
| String rejectedReason |
| Long reviewedOn |
| SubmissionStatusChangeRequestSubmissionStateChangeRequest |
|---|
| String submissionId |
| SubmissionState newState (only APPROVED and REJECTED are valid) |
| String rejectedReason |
| AccessApprovalStatusRequest |
| List<String> accessRequirementIdList |
| AccessApprovalStatusResults |
| List<AccessApprovalStatusResult> results |
| AccessApprovalStatusResult |
| String accessRequirementId |
| String accessApprovalId (null if there is no AccessApproval associated with the given access requirement) |
| SubmissionStatus submissionStatus (null if there is no DataAccessSubmission associated with the given access requirement) |
| FailureCode failureCode (UNAUTHORIZED, NOT_FOUND) |
...
| GET /accessRequirement/{id}/dataAccessRequest | GET /accessRequirement/{id}/dataAccessRequestForUpdate | |
|---|---|---|
| user has not created a request | NotFoundException | empty DataAccessRequest |
| user has a request, zero APPROVED submission | the created DataAccessRequest | the created DataAccessRequest |
| user has an APPROVED submission, requires renewal | the created DataAccessRequest | re-filled DataAccessRenewal |
| user has an APPROVED submission, renewal not required | the created DataAccessRequest | the created DataAccessRequest |
| RestrictionInformationRequest | ||
| String objectId | ||
RestrictableObjectType objectType |
| RestrictionInformationResponse |
|---|
| RestrictionLevel restrictionLevel (OPEN, RESTRICTED_BY_TERMS_OF_USE, CONTROLLED_BY_ACT) |
| boolean hasUnmet |
| TermsOfUseAccessRequirementStatus implements AccessRequirementStatus |
|---|
| String accessRequirementId |
| boolean isApproved |
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 feedback, we still need to provide the following:
- Need notifications for ACT when there is a new submission - may only get 1-2 requests a week for old dataset.
- 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).
- 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.
- 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 any 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.