This page will provided detailed specifications for new/changed APIs as required by Phase 1 of API Changes to support: Extension of Data Access Management to Users outside of Sage ACT.

Figma: https://www.figma.com/proto/vLusb6uSfhx45OyFx5IHwy/(XDM)-Extensible-Data-Management-Comps?node-id=2679%3A37672&scaling=min-zoom&page-id=2329%3A17842&starting-point-node-id=2679%3A37672&show-proto-sidebar=1

Object Changes

Access Requirement: shortDescription description → name

UI only or do we need a migration plan? We would need to
- Update Synapse Web Client
- Update Synapse React Client
- Update all portals and SWC to use new versions of React Client
Likely cannot enforce uniqueness, but maybe we could warn when a new AR name collides with an existing one in the UI.
Enforce non-null/non-empty? Null/empty names could take on the requirement ID as a name.

...

Endpoint	Parameters/Object	Returns	Notes/Questions	Stories
???			Need a way to identify the caller as a reviewer so we can determine if we should show the navbar item in the web client. This could be Manually enabled/disabled as a profile setting Request to see if any ARs exist with the caller having access via ACL (boolean or return the list of ARs)	As a reviewer, I need an intuitive way to access the ACT/Reviewer dashboard so I can review pending requests, troubleshoot user access, and perform other data access tasks.
POST /accessRequirement/search	AccessRequirementSearchRequest	AccessRequirementSearchResponse	For all services, when to allow array filters? No auth required; ARs are public info Special behavior if the reviewerID is the ACT? Is this good enough for search?	As an ACT member, I want to be able to query for existing access requirements so I can inspect or modify them without having to navigate to a specific entity controlled by the AR. As an ACT member, I want to be able to find an AR ID using the AR name so that I can filter other queries by AR without knowing the AR ID.
POST /dataAccessSubmission/search	DataAccessSubmissionSearchRequest	DataAccessSubmissionSearchResponse	Auth required ACT member will see all submissions. If the caller is not ACT, they will only see submissions on ARs for which they have the “REVIEW_SUBMISSIONS” permission. What to do about https://docs.synapse.org/rest/GET/dataAccessSubmission/openSubmissions.html ? Deprecate?	See https://sagebionetworks.jira.com/wiki/spaces/~557058fa14d697877047ec802a3e459a04898e/pages/edit-v2/2617442828?draftShareId=316dfb35-cc6b-4dc2-9e97-c6a4bf025f02 – need to refine This will support both the “Submissions” tab for all reviewers and the “Access History” tab for ACT
POST /accessApproval/historysearch	AccessApprovalHistoryRequestAccessApprovalSearchRequest	AccessApprovalHistoryResponse	Is POST /accessApproval/group enough? Only difference is no history and sort, but sort could probably be added to that service.AccessApprovalSearchResponse	Status by submitter - (submitter, AR ID) is primary key	As an ACT user, I want to see the entire history of all Access Approvals so I can understand why a user may have gained or lost access on an access requirement.

Objects

AccessRequirementBundleAccessRequirementSearchRequest

Code Block

language	json

{{
    "title":"Access Requirement Search Request",
    "description":"Describes the parameters for searching Access Requirements",
    "properties": {
        "nameContains":{
            "type":"string",
            "description":"A substring used to filter Access Requirements by name"
        },
        "relatedProjectId":{
            "type":"string",
            "description":"A synID used to filter Access Requirements to retrieve only those that have been applied within a particular project."
        },
        "reviewerId":{
            "type":"number",
            "description":"A principal ID used to filter Access Requirements to retrieve only those with the user/ or team on the ACL."
        },
        "nextPageToken": {
            "type": "string",
            "description": "A token used to get the next page of a particular search query."
        }
    }
}

AccessRequirementSearchResult

Code Block

language	json

{
    "$id": "org.sagebionetworks.repo.model.AccessRequirementSearchResult"
    "title":"Access Requirement Search Result Item",
    "description":"Result item of an Access Requirement search"
    "properties": {
        "accessRequirementId":{
            "type": "string"
        },
        "name": {
            "type": "string"
        }
        "reviewerIds":{
           "type": "array",
           "description": "Principal IDs of the reviewers of the AR."
           "items": {
              "type": "number"
           }
        },
        "relatedProjectIds":{
            "type": "array",
            "items": {
              "type": "string"
            }
        },
        "modifiedOn": {
            "type": "string",
			"format":"date-time"
        }
    }
}

AccessRequirementSearchResponse

Code Block

language	json

{
    "title":"Access Requirement Search Response",
    "description":"Describes the response object for an Access Requirement search",
    "properties": {
        "results":{
            "type":"array",
            "items": {
                "$ref": "org.sagebionetworks.repo.model.AccessRequirementSearchResult"
            }
            "description":"The results of an access requirement search"
        },
        "nextPageToken": {
            "type": "string",
            "description": "A token used to get the next page of a particular search query."
        }
    }
}

DataAccessSubmissionSearchRequest

Code Block

language	json

{
    "title":"Access Requirement Search Request",
    "description":"Describes the parameters for searching Data Access Submissions",
    "properties": {
        "accessRequirementId": {
            "type":"string",
            "description": "Filter submissions by their Access Requirement ID"
        },
        "accessorId": {
            "type":"string",
            "description":"A principal ID used to filter submissions by accessors on the submission."
        },
        "reviewerFilter": {
          // TODO: check this field with stakeholders
          "type": "string",
          "enum": [
            "ACT_ONLY",
            "DELEGATED_ONLY"
          ],
          "required": false
        },
        "reviewerId": {
            "titletype":"Access Requirement Bundlenumber",
    "description":"Access Requirement and related objects",     "propertiesdescription":"A {principal ID used to filter Access Requirements to retrieve "accessRequirement":{only those with the specified user or team on     "$ref":"org.sagebionetworks.repo.model.AccessRequirementthe ACL."
        },
        "accessControlListsort": {

           "$reftype": "org.sagebionetworks.repo.model.AccessControlList"object",
          "properties": {
  },          "relatedProjectsfield": {
              "type": "arraystring",
              "const": "CREATED_ON"
         "items": {  }
            "typedirection": "string"{
// synIds             }
"$ref": "org.sagebionetworks.repo.model.SortDirection"
       }     }
}

AccessRequirementSearchRequest

Code Block

language	json

{
    "title":"Access Requirement Search Request",     "description":"Describes the parameters for}
searching Access Requirements",     "properties": { },
        "nameSubstringnextPageToken": {
            "type": "string",
            "description": "A substringtoken used to filter Access Requirements by name" get the next page of a particular search query."
        }
    }
}

DataAccessSubmissionSearchResult

Code Block

language	json

{
   },    "$id": "org.sagebionetworks.repo.model.dataaccess.DataAccessSubmissionSearchResult"
    "relatedProjectIdtitle":{"Data Access Submission Search     Result Item",
    "typedescription": "string",
    "properties": {
        "descriptionsubmissionId":"A synID used to filter Access Requirements to retrieve only those that have been applied within a particular project. {
            "type": "string"
        },
        "reviewerIdaccessRequirementId":{
            "type": "numberstring",
        },
    "description":"A principal ID used to filter Access Requirements to retrieve only those with the user/ or team on the ACL."accessRequirementName": {
            "type": "string"
        },
        "nextPageTokenreviewerIds": {
            "type": "stringarray",
        },
   "description": "A token used to get the next page of a particular search query.""submitterId": {
          "description": "The principal ID of }the person who created  }
}

AccessRequirementSearchResponse

Code Block

language	json

{
 the submission."
  "title":"Access Requirement Search Response",     "descriptiontype": "number"Describes
 the response object for an Access Requirement search"},
    "properties": {         "results"accessorIds": {
 
          "type": "array",
 
          "itemsdescription": {"The principal IDs of the             "$ref": "org.sagebionetworks.repo.model.AccessRequirementBundle"users who are accessors on the submission",
            }"items": {
            "descriptiontype": "number"The
results of an access requirement search"     }
   },     }
}

DataAccessSubmissionSearchRequest

Code Block

language	json

{,
        "titlestate":"Access Requirement Search Request", {
          "description$ref":"Describes the parameters for searching Data Access Submissions", "org.sagebionetworks.repo.model.dataaccess.SubmissionState"
        },
        "propertiescreatedOn": {
        "accessRequirementId": {   "type": "string",
			"format":"date-time"
       "type":"string",
 }
      }
}

DataAccessSubmissionSearchResponse

Code Block

language	json

{
    "descriptiontitle":"Filter submissions by their Access Requirement ID"
        },
   Search Response",
    "accessorIddescription":"Describes {the parameters for searching     Access Requirements",
    "typeproperties":"string", {
           "descriptionresults":"A principal{
ID used to filter submissions by accessors on the submission."     "type":"array",
   },         "reviewerIditems": {
                "type$ref":"number",
  "org.sagebionetworks.repo.model.dataaccess.DataAccessSubmissionSearchResult"
          "description":"A principal ID},
used to filter Access Requirements to retrieve only those with the specified user or team on the ACL. "description":"Submissions matching the search parameters"
        },
        "statusnextPageToken": {
            "type": "arraystring",
            "itemsdescription": {"A token used to get the next           "$ref": "org.sagebionetworks.repo.model.dataaccess.SubmissionStatus"page of a particular search query."
        }
    }
},

AccessApprovalSearchRequest

Code Block

language	json

{
    "title":"Access Approval History Request",
    "description": "FilterDescribes Datathe Accessparameters Submissionsfor tosearching showthrough onlythe thosehistory withof theAccess specifiedApprovals SubmissionStatus."for a particular accessor",
     },"properties": {
        "sortaccessorId": {
            "type": "enumerationnumber",
            "valuesdescription": ["CREATED_ON_ASC"The principal ID of the accessor.",
"CREATED_ON_DESC"],           "default": "CREATED_ON_DESC"
 "required": true
        },
        "nextPageTokenaccessRequirementId": {
            "type": "stringnumber",
            "description": "A token used to get the next page of a particular search query."The access requirement for which access approvals should be shown.",
            "required": false
        },
        "sort": }{
    } }

DataAccessSubmissionSearchResponse

Code Block

language	json

{     "titletype":"Access Requirement Search Response", "enumeration",
          "descriptionvalues":"Describes the parameters for searching Access Requirements",
    "properties": { ["MODIFIED_ON_ASC", "MODIFIED_ON_DESC", "EXPIRED_ON_ASC", "EXPIRED_ON_DESC"],
          "resultsdefault": {"MODIFIED_ON_DESC"
            "type":"array",
   },
        "itemsnextPageToken": {
   
            "$reftype": "org.sagebionetworks.repo.model.dataaccess.Submission"string",
            },
            "description":"Submissions matching the search parameters"
  "description": "A token used to get the next page of a particular search query."
        }
    }
},

AccessApprovalSearchResult

Code Block

language	json

{
    "$id": "org.sagebionetworks.repo.model.AccessApprovalSearchResult"
       "nextPageTokentitle":"Access {Approval Search Result Item",
         "typedescription": "string",The result item in an Access Approval  search",
    "descriptionproperties": "A token used to get the next page of a particular search query."
    {
        "id": {
   }     } }

AccessApprovalHistoryRequest

Code Block

language	json

{
    "titledescription": "The ID of the Access Approval History Request",
    "description":"Describes the parameters for searching through the history of Access Approvals for a particular accessor","type": "string"
       "properties": { },
        "accessorIdrequirementId": {
            "type": "numberstring",
        },
   "description": "The principal ID of the accessor.","requirementName": {
            "requiredtype": true"string"
        },
        "accessRequirementIdreviewerIds": {

           "type": "array"
        },
        "numbersubmitterId",: {
           "description": "The accessprincipal requirementID forof whichthe accessperson approvalswho shouldcreated bethe shownsubmission.",
 
          "requiredtype": false"number"
        },
        "sortstate": {
 
			"$ref": "org.sagebionetworks.repo.model.ApprovalState"
        },
        "typemodifiedOn": "enumeration",{
          "values": ["MODIFIED_ON_ASC", "MODIFIED_ON_DESC", "EXPIRED_ON_ASCtype": "string",
"EXPIRED_ON_DESC"],
          "default": "MODIFIED_ON_DESC			"format":"date-time"
        },
        "nextPageTokenexpiredOn": {
            	"type": "string",
			"format":            "date-time",
			"description": "AThe tokendate usedthis toobject getwill the next page of a particular search query."
be expired.",
			"title": "Expired On",
			"transient": true
        }
    }
}

AccessApprovalHistoryResponseAccessApprovalSearchResponse

Code Block

language	json

{
    "title":"Access Approval HistorySearch Response",
    "description":"The results of an Access Approval History Request",
    "properties": {
        "results": {
            "type":"array",
            "items": {
                "$ref": "org.sagebionetworks.repo.model.AccessApprovalAccessApprovalSearchResult"
            },
            "description":"The matching historyAccess ofApproval Accessinformation Approvalscorresponding matchingto the search parameters"
        },
        "nextPageToken": {
            "type": "string",
            "description": "A token used to get the next page of a particular search query."
        }
    }
}

Deprecations

...

Versions Compared

Old Version 1

New Version Current

Key

Object Changes

Objects

Deprecations

Page Comparison

Versions Compared

Old Version 1

New Version Current

Key

Object Changes

Objects

Deprecations