fw-gear-project-settings 2.2.8

For a given project, clone the permissions and gear rules to a new project, or export the settings for import to another project.

Project Settings

Overview

Summary

For a given project, clone the gear rules and/or permissions to a project, or export the settings for import to another instance/project.

Cite

License: MIT

URL: https://gitlab.com/flywheel-io/scientific-solutions/gears/project-settings

Source: https://gitlab.com/flywheel-io/scientific-solutions/gears/project-settings

Classification

Category: Analysis

Gear Level:

• Project
• Subject
• Session
• Acquisition
• Analysis

---

[[TOC]]

---

Inputs

• Template

  • Name: template
  • Type: json file
  • Optional: true
  • Description: Template json file from source project. If this is provided to this gear at runtime, the template will be applied to this project.

• Fixed Inputs

  • Name: fixed_inputs
  • Type: zip file or json file
  • Optional: true
  • Description: Archive containing fixed input files, or single JSON file. These files will be uploaded to the cloned project and referenced by the gear rules. If this is provided to this gear at runtime, the files will be applied to this project.

Config

• clone_project_path

  • Name: clone_project_path
  • Optional: true
  • Type: string
  • Description: Path for new project to be created. Format should be <group_id>/<project_name>. If <clone_project_path> provided a new project will be created. If the project exists, the 'apply_to_existing_project' option must be used to update the project settings. If this option is omitted settings will be exported.

• data_views

  • Name: data_views
  • Type: boolean
  • Description: Export/Import DataViews.
  • Default: false

• default_group_permissions

  • Name: default_group_permissions
  • Type: boolean
  • Description: Applies the clone project's default group permissions to the clone project. This is done by default and will override permissions within the template. If you wish to use the permissions within the template you must set default_group_permissions to false, and permissions to true.
  • Default: true

• permissions

  • Name: permissions
  • Type: boolean
  • Description: Export/Import Permissions
  • Default: true

• gear_rules

  • Name: gear_rules
  • Type: boolean
  • Description: Export/Import Gear Rules and related fixed inputs (if applicable).
  • Default: true
  • Note: When exporting gear rules, gear will export the latest version of the fixed input file available on the origin project. When importing gear rules to the destination project, the gear will upload the fixed input files and the gear rule will use this latest version of the file available on the destination project. When gear rules with fixed inputs are triggered, the triggered job uses the latest version of the fixed input at runtime.

• apply_to_existing_project

  • Name: apply_to_existing_project
  • Type: boolean
  • Description: If a project already exists, apply settings and rules to that project.
  • Default: true

• existing_rules

  • Name: existing_rules
  • Type: string
  • Description: If a project already has a rule with the same name as a template rule, this option will determine what happens with those rules. Options are: 'REPLACE ALL' (delete ALL existing rules, then add template rules)', 'MATCH' (replace the existing rule with the template rule), 'APPEND' (add template rule - may result in duplicate rules), 'SKIP' (don't add the matching template rule).
  • Default: "MATCH"

• debug

  • Name: debug
  • Type: boolean
  • Description: Log debug messages
  • Default: false

Outputs

Files

• Template

  • Name: project-settings_template
  • Type: json file
  • Description: JSON file containing the permissions and gear rules of the source project, saved as project-settings_template_<source_project_id>.json

• Fixed Inputs

  • Name: fixed_inputs
  • Type: zip file
  • Description: Archive file consisting of any files referenced by the exported gear rules (if applicable), saved as fixed_inputs_<source_project_id>.zip

Metadata

No metadata is created or modified by this gear.

Pre-requisites

A created project is required for this gear to run.

Prerequisite Gear Runs

No prerequisite gear runs are necessary for this gear.

Prerequisite Files

No files are required by this gear. Input files for template and fixed inputs are optional.

Prerequisite Metadata

No prerequisite metadata necessary.

Usage

For new projects it can be difficult to replicate existing project configurations. This Gear will run at the project level and generate a new project (locally or via configuration file for external use) with the appropriate gear rules and user permissions.

Description

This gear utilizes an inputted template or creates a template from the source project to be assist with replicating an existing project configuration. Fixed inputs can also be applied either from an archive (zip) file or from the source project. If clone_project_path is provided, the gear will attempt to locate the specified project; if it is not located, it will attempt to create the project as specified, and if the project already exists and apply_to_existing_project==True it will set the existing project as the target for application. (If the project already exists and apply_to_existing_project==False, the gear will exit.) The gear will then export the template, and if applicable will apply the template to the target project as configured. If permissions==True, permissions will be applied. If gear_rules==True, gear rules will be applied.

Workflow

A picture and description of the workflow

graph LR;
    A[Template - Optional]:::input -.-> E;
    B[Fixed Input Archive - Optional]:::input -.-> E;
    D[Source Project]:::container --> E((Gear));

    E:::gear --> F[Exported Template];
    E -.-> G[Exported Fixed Input Archive - if applicable]
    E -.-> H[Target Project]:::container
    
    classDef container fill:#57d,color:#fff
    classDef input fill:#7a9,color:#fff
    classDef gear fill:#659,color:#fff

Description of workflow

1. Identify existing project to be cloned
2. Optionally, input template and/or fixed inputs
3. Gear outputs template created from source project and a fixed input archive, if applicable.
4. Gear configures target project as specified, if applicable.

Use Cases

Use Case 1: Exporting Project Settings - without Project Creation

To export a project's settings (permissions and gear rules):

1. Run project-settings as a project analysis on the source project without configuring a clone_project_path. This will not create a project, nor apply any settings. It will simply generate the settings output files.

Use Case 2: Exporting Project Settings - with Project Creation

To export a project's settings (permissions and gear rules), create a new project, and apply those settings to the new project

1. Run project-settings as a project analysis on the source project
2. Configure a clone_project_path. This will trigger the creation of a new project.
3. Check permissions and gear_rules configuration options as desired. Default for both is true.

Use Case 3: Import Project Settings to an Existing Project

To import project settings from one project to another:

1. Generate settings files: Run project-settings as a project analysis on the source project without configuring a clone_project_path. This will not create a project, nor apply any settings. It will simply generate the settings output files. Optionally you can use files from an existing run.
2. Upload settings files: Settings files should be uploaded to the target project as project attachments.
3. Run project-settings as a project-level analysis on the target project, where you want the permissions and rules applied.
4. Choose input files from the project attachments as appropriate for input to project-settings.

Logging

This gear provides log statements as it runs to identify where the gear is at within the process. These can be used to understand where a gear run is encountering problems, if any, and what actions the gear is taking.

FAQ

FAQ.md

Contributing

[For more information about how to get started contributing to that gear, checkout CONTRIBUTING.md.]