/
Shared Module Library

Shared Module Library

May 04, 2017

Status

Critical

These must be in-place before external developers can start using this.

Non-Critical

Not a blocker for external developers to use this, but should be prioritized high.

Nice to Have

Quality of life improvements.

Future Work

Possible phase 2, pending further requirements and design.

Overview

We want to allow study developers to rapidly bootstrap and develop new studies. A big part of this is setting up surveys and activities and schemas, both server-side and client-side. Frequently, a new study will want to share modules with the another study, examples include Tapping, Walking, Tremor, PHQ8. As such, we want a shared library of modules that study developers can import into their study and their app.

Scenarios

Provisioning and populating a study. Study developer provisions a new study. They go into the Bridge Study Manager UI, sees a list of modules (surveys, schemas), and chooses which modules they want to import into their study. The Researcher Portal automatically populates the study with the schemas and surveys and instructs the developer which code module (Github link? Maven package and version, or equivalent in iOS?) to import into their app and how to configure it.

Customizing Surveys and Schemas. Study developers may want to customize a survey or schema after they import it.

Bootstrapping a new app. Study app developer wants to quickly build their study app. They start with the Template App (aka "Super App", aka Sample App, aka the app that contains all of the publicly available modules), downloads a set of configuration files from Bridge Study Manager UI, and they have a working study app with basic functionality.

Data analysis for shared modules. Multiple researchers are using the same module from the shared module library. They want to run some analysis for basic stats. Bridge provides standard analysis code packages for some of the shared modules. (Examples: Tapping, Walking, Voice.)

Publishing new shared modules. Currently, Sage needs to curate what's available in the shared library. Whether this is promoting a module from an existing study or creating a new "ideal" module in the shared space is still up for discussion. Either way, Sage will need to provide metadata and tagging for the module. Note that module metadata needs to include:

  • copyright and/or licensing restrictions

  • whether they are OS-specific

  • if it requires app code, where to find the app code (repo/code link, specific code version, etc)

  • default schedule that would provision with the module, so the module is accessible and usable right away

Business Development. One customer for the shared module feature is a scientist / funder / patient advocate putting together a study design and evaluating Sage's platform and services.  This person may never actually log into the study manager and do anything with their own account.  But, we may want to make it easy for this sort of person to see all the modules available for use, either in the context of a demo by Sage employees, or by reviewing themselves on their own time.  This scenario implies there might be some functionality visible to a non-logged in user.

Non-Goals

  1. Study developer owns two studies. Study A has a module that they want to use in study B. They want to clone that module from study A to study B. This is currently outside the scope of this particular feature, but is something we still want to do separately. See

  2. Study developer provisions a study from a template, already populated with schemas and surveys and schedules. We don't have a use case for study developers being "clones" of an entire study. Expected use case is more that study developers will pick and choose what they need.

  3. Consents are out of scope, as they will almost always need to be customized, based on what's in the app and based on local requirements. We may want to tackle this at a later date, but it's not included in this project.

  4. Schedules are out of scope, but we may add them in the future.  They're much more likely to be developed from scratch for each study.

  5. Survey and schema metadata in Synapse tables. This is orthogonal to the Shared Module Library and is already being tracked in a separate project Upload Format v2#Subtask1c:ExportSurveyQuestionstoSynapse. Note that this is currently blocked on a Synapse feature request

Open Questions

Do we need to block some modules from being edited? (For example, a copyrighted survey like UPDRS can't be updated, ever.)

Do we need a story to notify local developers of new shared module versions?

Design Details

Shared Module Library

JIRAs:

Shared Study

Create a new reserved study called "shared", in which all the shared modules (shared surveys and schemas) will live. Making this a full-fledged study allows us to re-use a lot of our existing code and UI for managing surveys and schemas. It also allows easy separation of permissions between admins, shared study developers, and local study developers.

  • Only developers in the shared study can create or modify objects in the shared study. Any developer can read surveys and schemas from the shared study.

    • We'll need new APIs to read surveys and schemas from the shared study. This will largely have the same Service and DAO code. Controller code will differ only in permissions and will reference the shared study instead of the local study.

  • Surveys and schemas are copied from the shared study to the local study.

    • This decision was made because "fallback logic" to first check the local study then fallback to the shared study would require touching code in about a dozen different places. This would also add both conceptual and mechanical complexity, which increases development time, maintenance time, and results in more bugs.

    • This logic can live in the Study Manager UI. The Study Manager will read the shared object, then call the create API to create that object in the local study. (We'll need to check that the create APIs can be used to "copy" objects from other studies.)

    • Study Manager will need to annotate the newly created object with references to the original object in the shared study.

    • Bridge APIs for creating and updating surveys and schemas to allow publishing by setting the "published" flag to true. This is to allow Study Manager to create and publish surveys and schemas in a single atomic step.

  • When copying surveys and schemas, you'll need a reference to the shared module the survey or schema was copied from. This means having the shared module ID and version as fields in surveys and schemas.

    • The shared module ID and version will persist even when local developers create a new revision of the survey or schema. This is to track where this object originally came from. There is no need to explicitly track whether the object has been edited from its original form or not.

  • Publish workflow for schemas. We'll need to add a "published" flag to schemas and a publish API. This is to enforce immutability in the shared study and to force a revision bump if a study developer tries to modify a schema copied from the shared study.

    • For testing purposes, we will still allow apps to submit data for unpublished schemas.