The project-management app builds containers within Flywheel for a coordinating center supported study.
A coordinating center supported study is a research activity for which data is being collected at the coordinating center. For NACC this is primarily the ADRC program for which data is captured at Alzheimer’s Disease Research Centers (ADRCs), and then transferred to NACC for harmonization and release.
The name “project-management” is historical and comes from a conversation with the NACC PI, Bud Kukull. He had legitimate reasons not to use “study”, so we started with “project”. However, “project” is used in both Flywheel and REDCap to mean particular things, and having three things called projects started to make communication difficult. And, naively, “study” makes sense.
So, we are using “study” now, but keeping the gear name for continuity.
The gear can be run either via the Flywheel user interface or using a script.
You will need an input file uploaded to Flywheel. The format is described below.
For NACC, access to the gear is restricted to the fw://nacc/project-admin project.
There is a file adrc-program.yaml attached to that project, and a gear rule that will run the gear when the file is updated.
For other scenarios, attach a file to the project, and run the gear as usual.
This app takes a YAML file describing the study and creates containers within Flywheel to support the ingest and curation of the collected data.
The file format is
---
study: <study-name>
study-id: <string-identifier>
study_type: <'primary' or 'affiliated'>
centers: <list of center details>
datatypes: <list of datatype identifiers>
dashboards: <optional list of dashboard configs>
pages: <optional list of page configs>
mode: <whether data should be aggregated or distributed>
published: <whether the data is published>
“Center details” may either be a center identifier or a center-study object.
Center identifiers are Flywheel group IDs created by the center management gear.
A center-study object has a center identifier labeled as center-id, an enrollment-pattern that may be co-enrollment or separate, and a pipeline_adcid that is an optional int.
The pipeline_adcid is an ADCID assigned for the study data pipeline and is required when the enrollment pattern is separate and otherwise should not be given.
In the centers list, a center identifier is assumed to represent a center-study object with the co-enrollment pattern.
The mode is a string that is either aggregation or distribution.
The mode may be omitted for aggregating studies to support older project formats.
The dashboards field is an optional list of dashboard configurations. Each entry can be either a plain string (dashboard name, defaults to center level) or an object with name and level fields. Valid levels are center and study. Center-level dashboards are created for each active center in the study. Study-level dashboards exist at the study scope without a center association. Dashboard projects are used as placeholders for managing access to dashboard pages within the ADRC portal. The portal uses Flywheel project roles to determine what content is shown to users.
The pages field is an optional list of page configurations. Each entry is an object with name and level fields. Valid levels are center, study, and community. Center-level pages are created for each active center. Study-level pages exist at the study scope. Community-level pages exist at the community scope (parent: “nacc”). Page projects are used to manage access to portal pages.
Running on the file will create a group for each center that does not already exist, which includes
metadata project where center-specific metadata can be stored using the project info object.center-portal project where center-level UI extensions for the ADRC portal can be attached.Additional projects will be added if the study is either primary or it is affiliated and the center has separate enrollments:
<pipeline>-<datatype>-<study-id> where <pipeline> is ingest, sandbox or retrospective.
For distributing studies, the pipeline will be named distribution.
For instance, ingest-form-leads.
For the primary study, the study-id is dropped like ingest-form.accepted pipeline project for an aggregating study, where data that has passed QC is accessible.dashboards field is provided) for each dashboard name in the list.
Dashboard projects will have a name of the form dashboard-<dashboard-name>-<study-id>.
For the primary study, the study-id is dropped like dashboard-enrollment.
Dashboard projects are only created for active centers and are used to manage access to portal dashboard pages.pages field is provided) for each page configuration.
Center-level page projects will have a name of the form page-<page-name>-<study-id>.
For the primary study, the study-id is dropped like page-enrollment.
Study-level and community-level pages are not created as Flywheel projects but are registered in the authorization hierarchy.Notes:
Only one study should have primary set to True.
Like with any YAML file, you can include several study definitions separated by a line with ---.
However, it is more pragmatic to have one file per study for large studies.
The tags are strings that will be permissible as tags within the group for the center.
Each tag will also be added to ingest projects within the center’s pipeline(s).
Datatypes are strings used for creating ingest containers, and matching to sets of gear rules needed for handling ingest.
Each project added under a center group will have project.info.adcid set to the ADCID of the center.
---
study: "Project Tau"
study-id: tau
study-type: affiliated
centers:
- alpha
- beta-inactive
datatypes:
- form
- dicom
dashboards:
- name: enrollment
level: center
- name: qc-status
level: center
- name: summary
level: study
pages:
- name: enrollment
level: center
- name: reports
level: study
- name: announcements
level: community
mode: aggregation
published: True
---
study: "Project Zeta"
study-id: zeta
study-type: affiliated
centers:
- alpha
- center-id: gamma-adrc
enrollment-pattern: separate
datatypes:
- form
mode: aggregation
published: False
For testing, see the gear wrangling directions in the development documentation.
When the authorization_path config is set and the API endpoint URL can be read from AWS SSM Parameter Store, the gear seeds the resource hierarchy in the NACC Authorization API.
This establishes parent relationships that enable inherited permissions in the Portal.
For each resource the gear creates or visits, it calls the Authorization API to set parent relationships:
| Resource scope | Parents set |
|---|---|
| Center pipeline (ingest, sandbox, retrospective, distribution, accepted) | parent_study + parent_center |
| Center dashboard | parent_study + parent_center |
| Center page | parent_study + parent_center |
| Study dashboard | parent_study |
| Study page | parent_study |
| Community page | parent_community (id: “nacc”) |
The gear reads the current hierarchy before writing. If the parents already match the desired state, the write is skipped. This makes repeated runs efficient — only resources with changed or missing parents trigger API calls.
Authorization hierarchy seeding is optional and fault-isolated:
authorization_path config is not set or the parameter cannot be read from SSM, seeding is disabled and a warning is logged.The gear manifest includes an authorization_path config field (default: /production/authorization/api-endpoint).
This is the SSM Parameter Store path where the Authorization API endpoint URL is stored.
The integration activates automatically when:
authorization_path contains a url value with the API Gateway endpoint