Document toolboxDocument toolbox

Synapse Table Data Change Request Process

Owned by Aaron Hayden (Unlicensed)
Last updated: Jul 01, 2021

Effective date: 07/16/2021
Owner: Chief Technology Officer
Available: Sage Intranet/Policies

Version
Summary

6/25/2021

Added versioning and tracking for Quality Program purposes

Changes to some Synapse tables may require strict change control procedures in order to meet agreements with data providers, regulators, or for other change control purposes. This process can be used to ensure that changes to a Synapse table are limited to approved by specific authorities.

Scope

This process covers Synapse objects that can be versioned and annotated by the Synapse application; currently this can be done for tables. This process relies on the security model of Synapse, on versioning to capture changes, and on annotations to record signature of the approval authority. 

Out of scope

  • Changes to the configuration of a Synapse project are beyond the scope of the process; auditing of configuration changes can be done by administrators and audited through reports on the Synapse data warehouse.
  • Projects in a pre-production phase, before a production release, do not need require the full documentation of this procedure. Access control must still be managed according to this procedure, however.

Process Requirements

Requests for ad-hoc data changes start with a Jira issue ticket that serves as a record of the change and approval process.

Important

When a change effects the elements of a Synapse table related to a project governed by GCP controls, the issue ticket must be generated by the Scientific Project Lead of the relevant project who has the Investigator role. A change request may be documented in Jira by any project member, but the issue must also be rendered in PDF form, approved and signed by the Investigator, and attached to the Jira issue. As a record of primary data, changes to Synapse tables are always considered "material" in the sense that the change effects the integrity of the project in the long term.

The issue ticket must include the following elements:

  1. In all cases, the change request must be formally documented and tracked as an issue in Jira to create an audit-able trail of the work to be done. This must include a description of who is performing the data change and the specifics of what the change entails. This should be detailed enough so that someone looking at the data after the fact can determine how the data was changed. A project should have an appropriate data change form template that includes the appropriate elements, such as this example.
    1. For some projects, the authoritative change request must be recorded in a partner's record system, signed by approval authorities, and linked to the Jira issue.
    2. Determine how the change will be made, whether through the web client or programmatically. If the change requires scripting, develop and test the script first.
  2. An administrative user may temporarily assign write permission to the user who will oversee the change. This is to ensure that no user participating in the project can modify participant data unilaterally, and that we have an audit-able record of following this procedure.
  3. Perform the change:
    1. The Investigator or delegate must issue an API call, such as through the web client, to create a snapshot of the table version. The snapshot becomes an immutable record of the state of the table before the change.
      1. A label reflecting the nature of the change and referencing the explanatory Jira ticket should be included in the version snapshot.
      2. The version comment should contain a link to a Jira ticket that includes the signed change request if appropriate for the project.
      3. Query the prior and new table versions to confirm that the difference is as required by the change request. Attach a screenshot of the version history noted on the prior version of the table to the Jira ticket.
    2. The appropriate project staff may apply the change with appropriate supervision as defined by the project requirements.
  4. The project investigator or other approval authority should review and validate prior and changed versions of the data and close the Jira issue that documents the change request.
  5. The administrative user must revert permissions in order to prevent further modification of the table.

Managing Synapse Permissions

Permission control on the Synapse entities should be limited to those with a need to access and modify objects for the duration which requires access. Write access to tables that require this level of control should be limited by Synapse Team. Tables generated through the Bridge export process require BridgeAdmin Team membership, for example, as described in the Bridge Ad Hoc Data Change Process.

Bridge Data Change Request Process