Electronic Data Use Certificates (eDUCs)
Today data requesters collect signatures on data use certificates (DUCs) manually, by downloading a .pdf file from Synapse, routing the document and uploading the signed version. This design provides the ability for Synapse to route a document for signature itself, building on DocuSign.
Governance workflow, Part I:
If there the required DUC does not already exist:
Create document with hooks. (Detail below.)
Export as .pdf
Upload to Docusign as a template
Once the DUC Docusign template exists:
Create an Access Requirement referencing the Docusign template
Send a request with test emails and verify that it looks correct
Requester workflow:
In the Synapse UI: Create data access request (DAR), filling in collaborators (other Synapse users who will be data accessors), and signing official and principal investigator information. At this point the signature process has not yet begun.
In the Synapse UI: Preview the eDUC, verifying that it looks correct before sending out, i.e. that the information entered in the previous step appears in the eDUC and in the correct places.
In the Synapse UI: Kick off the signature process. The document is routed for signatures by DocuSign.
In the Synapse UI: Add or remove signers to the DAR: If the document is in a state which allows signers to change, the changes are applied. Otherwise an error is returned, indicating that changes are locked out. (Note the user would complete two steps, 1. update the DAR, 2. apply the changes to the in-flight eDUC. The client can compare the “modifiedOn” of the DAR and the signature status to determine whether to present the user with a button to update the eDUC.)
In the Synapse UI: Cancel the routed document. (They no longer want to request access.)
In the Synapse UI: Check the status of the signing, including who has signed, which addresses have ‘bounced’, and also who has declined to sign.
In the Synapse UI: Switch from eDUC to traditional DUC. (Download, fill-in, and upload the completed document, then proceed to the next step.)
In the Synapse UI: Submit request (Can only happen if the DUC signing is complete. Signed pdf is attached to the submission.)
Governance workflow, Part II:
Nothing is changed from the current process: The Governance team sees the submitted request/renewal as a signed .pdf document.
Creating the eDUC Template
The document can be created in Google Doc’s and exported as a .pdf. The document should include the following ‘hooks’ for DocuSign to use, with the text color converted to white to make them invisible. Each “[collaboratorX:name]” will be filled with username and full name. If the user doesn’t provide their full name then the system will create a space for the signer to enter their name. The maximum number of collaborators is 98.
[collaborator1:name] [collaborator1:signature]
[collaborator2:name] [collaborator2:signature]
[collaborator3:name] [collaborator3:signature]
…
[collaborator98:name] [collaborator98:signature]
[pi:name]
[pi:email]
[pi:username]
[pi:signature]
[institution]
[so:name]
[so:email]
[so:signature]
In addition to these fields, the eDUC creator can add tags of the form:
[pi:<label>]
[so:<label>]
[collaborator<n>:<label>]
The eDUC will prompt the appropriate signer to fill in the field. Note: The value chosen for <label> must not be one of the pre-defined values listed above (like “email” or “name”).
Filling eDUC fields
Information that ultimately goes in the eDUC comes from a number of sources and some sources can override others. E.g. the DAR creator can enter the Signing Official’s name, but the Signing Official can override if their name is incorrect. The following table lists the fields of the DAR along with the source of the information.
Note that “Collaborators” here omits the PI, though they will be data “accessors.”
Note that “YES” and “(selected)” in the “Entered in Synapse DAR by DAR creator” column also means the value is REQUIRED to be entered before kicking off Docusign routing.
Field | Entered in Synapse user profile by Synapse account owner | Entered in Synapse DAR by DAR creator | Entered in DocuSign eDUC by Synapse | Entered in DocuSign eDUC by signer | Entered in DocuSign eDUC by DocuSign |
|---|---|---|---|---|---|
Collaborator User-name | YES | (selected) | YES | -- | -- |
Collaborator Full Name | YES (optionally) | -- | YES | YES (override) | -- |
Collaborator Signature | -- | -- | -- | YES | -- |
Collaborator Signature Date | -- | -- | -- | -- | YES |
Signing Official Full Name | -- | YES | YES | YES (override) | -- |
Institution Name | -- | YES | YES | YES (override) | -- |
Signing Official Institutional Email | -- | YES | YES | YES (override) | -- |
Signing Official Signature | -- | -- | -- | YES | -- |
Signing Official Signature Date | -- | -- | -- | -- | YES |
PI Full Name | YES (optionally) | YES (override) | YES | YES (override) | -- |
PI Institutional Email | -- | YES | YES | YES (override) | -- |
PI User-name | YES | (selected) | YES | -- | -- |
PI Signature | -- | -- | -- | YES | -- |
PI Signature Date | -- | -- | -- | -- | YES |
Objects and Services
API | Request | Response | Description |
|---|---|---|---|
GET /duc/template/list | N/A | DucTemplateList | returns a list of IDs and metadata (template name, created on, etc.) for templates created in DocuSign. |
GET /accessRequirement/{requirementId}/dataAccessRequest | N/A | AccessRequestList | List of access requests that the user has created, under this Access Requirement ID. |
POST /dataAccessRequest (and other services for DARs) | RequestInterface | RequestInterface | Add fields for PI and signing official, as seen in the eDUC template, above. Maximum number of collaborators is 97. DAR is in ‘trad DUC’ mode until signature process is initiated. Can’t update with a finalized DUC .pdf file if the eDUC is still in flight or is in a failed state. |
GET /dataAccessRequest/{requestId}/preview | N/A | DucFileHandleId | Preview of the eDUC before initiating the signature process |
GET /dataAccessRequest/{requestId}/signature/quota |
| SignatureQuota | Return the user’s signature quota, which is 10 per user per access requirement and per month. |
POST /dataAccessRequest/{requestId}/signature | N/A | SignatureQuota | Initiates the signature process*. Puts DAR into ‘eDUC’ mode. For renewals when the template has not changed, then route only to new signers (Docusign reportedly can create a new envelope from an old, document, already signed.) Fails if Access Requirement does not have isDUCRequired=true. Fails if there is already a routing in process (since there can be only one). Fails if the required fields are not filled in the DAR. Fails if user has exceeded their quota. When complete or failed, email notification is sent. |
GET /dataAccessRequest/{requestId}/signature/status | N/A | DucSignatureStatus | Returns the status for the current routing and for each signer. |
GET /dataAccessRequest/{requestId}/signature/precheck | N/A | SignaturePrecheckResponse | Returns true iff the modified DAR can be applied to the existing signature. |
PUT /dataAccessRequest/{requestId}/signature |
|
| If signers in DAR differ from signers in eDUC, updates the signers in the eDUC, but if someone who has been removed from the DAR has already signed, just leave them in the Docusign eDUC.
If the update is not possible then an error is returned. |
DELETE /dataAccessRequest/{requestId}/signature | N/A | N/A | Voids the routed eDUC. Puts DAR back into ‘trad-DUC’ mode. |
GET /dataAccessRequest/{requestId}/signature/filehandleId | N/A | DucFileHandleId | Returns the file handle id for the signed document. If signing is still in progress or if the trad-eDUC flow is being used, an error is returned. |
DucTemplateList
{
"description": "A DUC template",
"properties": {
"id": {
"type": "string",
"description": "The ID of the template"
},
"name": {
"type": "string",
"description": "The name of the template"
},
"description": {
"type": "string",
"description": "The description of the template"
},
"createdOn": {
"type": "timestamp",
"format": "date-time",
"description": "The timestamp when the template was created"
},
"modifiedOn": {
"type": "timestamp",
"format": "date-time",
"description": "The timestamp when the template was last modified"
}
}
}ManagedAccessRequirement
{
"title": "Managed ACT Access Requirement",
"description": "JSON schema for in-Synapse 'Access Control Team' controlled Access Requirement, a 'tier 3' Access Requirement. This access requirement allows the ACT managing the detail requirements, and submissions within Synapse.",
"implements": [
{
"$ref": "org.sagebionetworks.repo.model.ACTAccessRequirementInterface"
},
{
"$ref": "org.sagebionetworks.repo.model.HasAccessorRequirement"
}
],
"properties": {
...
"eDucTemplateId": {
"type":"string",
"description": "The ID of the eDUC template in the electronic document signing system"
},
...
}
}AccessRequestList
{
"description": "List of data access requests",
"properties": {
"results":{
"type": "array",
"items":{
"$ref": "org.sagebionetworks.repo.model.dataaccess.AccessRequestSummary"
}
},
"nextPageToken": {
"type": "string",
"description": "The token to get the next page of results."
}
}
}
AccessRequestSummary
{
"description": "Summary of data access request",
"properties": {
"requestId": {
"type": "string",
"description": "Id of the data access request"
},
"accessRequirementName": {
"type": "string",
"description": "name of the related access requirement"
},
"eDUCStatus": {
"type": "string",
"enum": [
{
"name": "created",
"description": "Created but not yet routed for signatures"
},
{
"name": "routed",
"description": "Routed for signatures"
},
{
"name": "signed",
"description": "eDUC signed but not yet submitted"
},
{
"name": "terminated",
"description": "eDUC terminated without completing signatures"
},
{
"name": "submitted",
"description": "request submitted, pending Governance review"
},
{
"name": "approved",
"description": "submission approved by Governance team"
},
{
"name": "rejected",
"description": "submission rejected by Governance team"
}
]
},
"isEDuc": {
"type": "boolean",
"description": "true if the request uses the eDuc flow"
}
"signaturesRequested": {
"type": "integer",
"description": "The number of signers requested for the eDUC, or null of using non-eDUC flow"
},
"signaturesAcquired": {
"type": "integer",
"description": "The number of signers who have signed the eDUC, or null of using non-eDUC flow"
},
"submittedOn": {
"type": "string",
"format":"date-time",
"description": "Date/time the request was submitted, or null if not yet submitted"
},
"modifiedOn": {
"type": "string",
"format":"date-time",
"description": "Date/time the request was modified"
},
"expiresOn": {
"type": "string",
"format":"date-time",
"description": "Date/time the approval expires, or null if the request is not yet submitted and approved"
}
}
}RequestInterface
{
"description": "This is the base interface that all Request implements.",
"type": "interface",
"properties": {
...
"insitution": {
"type": "string",
"description": "Collaborators' institution"
},
"signingOfficialName": {
"type": "string",
"description": "Signing Official Name"
},
"signingOfficialEmail": {
"type": "string",
"description": "Signing Official Institutional Email"
},
"principalInvestigatorName": {
"type": "string",
"description": "Name of the Principal Investigator"
},
"principalInvestigatorUserId": {
"type": "string",
"description": "Synapse user id of the Principal Investigator"
},
"principalInvestigatorInsitutionalEmail": {
"type": "string",
"description": "Principal Investigator Institutional Email"
},
"isEDuc": {
"type": "boolean",
"description": "access request uses eDUC flow"
},
...
"accessorChanges": {
"type": "array",
"description": "List of user changes. A user can gain access, renew access or have access revoked. Max number of accessors is 100.",
"items": {
"$ref":"org.sagebionetworks.repo.model.dataaccess.AccessorChange"
}
},
...
}
}
SignatureQuota
{
"description": "Signature Quota",
"properties": {
"quota": {
"type":"integer",
"description": "the total number of eDUC routings allowed"
},
"remaining": {
"type": "integer",
"description": "the number of eDUC routings remaining"
}
}
}SignaturePrecheckResponse
{
"description:" "Check whether DAR changes can be applied to in-flight signature",
"properties": {
"allowed": {
"type": "boolean",
"description": "true if and only if the DAR changes can be applied"
},
"message": {
"type": "string",
"description": "if allowed is false, a message explaining why"
}
}
}DucSignatureStatus
{
"description": "Status of a signature task",
"properties": {
"dataAccessRequestId": {
"type": "string",
"description": "The ID of the data access request who's DUC is to be signed."
},
"createdOn": {
"type": "timestamp",
"format": "date-time",
"description": "The timestamp when the signature process was initiated"
},
"modifiedOn": {
"type": "timestamp",
"format": "date-time",
"description": "The timestamp when the signature process was last updated"
},
"ducStatus": {
"type": "string",
"enum": [
{
"name": "sent",
"description": "email notification with a link has been sent to at least one recipient, and it stays in this state until recipients have at least viewed it"
},
{
"name": "delivered",
"description": "all recipients have viewed the documents in the signing experience"
},
{
"name": "completed",
"description": "signing is finished"
},
{
"name": "declined",
"description": "a recipient has explicitly declined to sign; signing will never be completed"
},
{
"name": "voided",
"description": "the sender has voided the DUC or it has expired"
}
]
},
"includesRequestChanges": {
"type": "boolean",
"description": "true if all changes to request have been applied to routed document"
},
"signerStatus": {
"type": "array",
"$ref" : "org.sagebionetworks.model.duc.DucSignerStatus"
}
}
}
DucSignerStatus
{
"description": "Status of a signature within a DUC",
"properties": {
"name": {
"type": "string",
"description"; "name of the signer"
},
"userid": {
"type": "string",
"description"; "Synapse user id of the signer, if any"
},
"email": {
"type": "string",
"description"; "email of the signer"
},
"status": {
"type": "string",
"description"; "status of the signer",
"enum": [
{
"name": "pending",
"description": "Signature is pending"
},
"name": "done",
"description": "Signer has signed the document"
},
"name": "declined",
"description": "Signer has declined to sign the document"
},
"name": "bounced",
"description": "Signing request email bounced"
}
]
}
}
}
DucFileHandleId
{
"description": "File handle for eDUC",
"properties": {
"fileHandleId": {
"description": "The ID of the file handle for the eDUC",
"type": "string"
}
}
}
Optional: Send an email notification when the envelop reaches a terminal state (completed, declined or voided). Either configure Docusign to do this or add a Synapse worker for this purpose.
Treatment of existing content
Existing access requirements
This work will introduce a new field into the ManagedDataAccessRequest (AR) for the ID of an eDUC template. Existing ARs will be treated as having null values for the template and so will only work for the trad-DUC flow. Existing ARs can be updated to have an eDUC template id, after which they will work with the eDUC flow.
Existing data access requests
Existing data access requests (DARs) will be treated as ones for which the user has opted for the traditional-DUC flow. They will have the option of ‘switching’ to the eDUC flow, but must update the DAR with required fields including PI and SO information before initiating the eDUC flow.
Source for Mermaid diagram
classDiagram
ACCESS_REQUIREMENT "1"--"0..1" DocuSign_Template
ACCESS_REQUIREMENT "1"--"*" DATA_ACCESS_REQUEST
DATA_ACCESS_REQUEST <|-- RENEWAL
DATA_ACCESS_REQUEST: SIGNED_PDF_FHID
DATA_ACCESS_REQUEST "1"--"0..1" SIGNATURE
DATA_ACCESS_REQUEST "1"--"0..1" ACCESS_REQUEST_SUBMISSION
ACCESS_REQUEST_SUBMISSION: SIGNED_PDF_FHID
SIGNATURE "1"--"1" SIGNATURE_STATUS