# 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:*
- [X] 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 `apply_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*
- *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
```mermaid
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
1. Optionally, input template and/or fixed inputs
1. Gear outputs template created from source project and a fixed input archive, if applicable.
1. Gear configures target project as specified, if applicable.
### Use Cases
This section is very gear dependent, and covers a detailed walkthrough of some use cases. Should include Screenshots, example files, etc.
#### 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
1. Configure a `clone_project_path`. This will trigger the creation of a new project.
1. 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._
1. _Upload settings files:_ Settings files should be uploaded to the target project as project attachments.
1. _Run_ project-settings as a project-level analysis on the _target project_, where you want the permissions and rules applied.
1. _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](FAQ.md)
## Contributing
[For more information about how to get started contributing to that gear,
checkout [CONTRIBUTING.md](CONTRIBUTING.md).]
<!-- markdownlint-disable-file -->
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/flywheel-io/scientific-solutions/gears/project-settings",
"name": "fw-gear-project-settings",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.11",
"maintainer_email": null,
"keywords": "Flywheel, Gears",
"author": "Flywheel",
"author_email": "support@flywheel.io",
"download_url": null,
"platform": null,
"description": "# Project Settings\n\n## Overview\n\n### Summary\n\nFor a given project, clone the gear rules and/or permissions to a project, or export the settings for import to another instance/project.\n\n### Cite\n*License:* MIT\n\n*URL:* https://gitlab.com/flywheel-io/scientific-solutions/gears/project-settings\n\n*Source:* https://gitlab.com/flywheel-io/scientific-solutions/gears/project-settings\n\n### Classification\n\n*Category:* Analysis\n\n*Gear Level:* \n\n- [X] Project\n- [ ] Subject\n- [ ] Session\n- [ ] Acquisition\n- [ ] Analysis\n\n----\n\n[[_TOC_]]\n\n----\n\n### Inputs\n\n- *Template*\n - __Name__: *template*\n - __Type__: *json file*\n - __Optional__: *true*\n - __Description__: *Template json file from source project. If this is provided to this gear at runtime, the template will be applied to this project.*\n\n- *Fixed Inputs*\n - __Name__: *fixed_inputs*\n - __Type__: *zip file or json file*\n - __Optional__: *true*\n - __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.*\n\n### Config\n\n- *clone_project_path*\n - __Name__: *clone_project_path*\n - __Optional__: *true*\n - __Type__: *string*\n - __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.*\n\n- *data_views*\n - __Name__: *data_views*\n - __Type__: *boolean*\n - __Description__: *Export/Import DataViews.*\n - __Default__: *false*\n\n- *default_group_permissions*\n - __Name__: *default_group_permissions*\n - __Type__: *boolean*\n - __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 `apply_group_permissions` to `false`, and `permissions` to `true`.*\n - __Default__: *true*\n\n- *permissions*\n - __Name__: *permissions*\n - __Type__: *boolean*\n - __Description__: *Export/Import Permissions*\n - __Default__: *true*\n\n- *gear_rules*\n - __Name__: *gear_rules*\n - __Type__: *boolean*\n - __Description__: *Export/Import Gear Rules and related fixed inputs (if applicable).*\n - __Default__: *true*\n\n- *apply_to_existing_project*\n - __Name__: *apply_to_existing_project*\n - __Type__: *boolean*\n - __Description__: *If a project already exists, apply settings and rules to that project.*\n - __Default__: *true*\n\n- *existing_rules*\n - __Name__: *existing_rules*\n - __Type__: *string*\n - __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).*\n - __Default__: *\"MATCH\"*\n\n- *debug*\n - __Name__: *debug*\n - __Type__: *boolean*\n - __Description__: *Log debug messages*\n - __Default__: *false*\n\n## Outputs\n\n#### Files\n\n- *Template*\n - __Name__: *project-settings_template*\n - __Type__: *json file*\n - __Description__: *JSON file containing the permissions and gear rules of the source project, saved as `project-settings_template_<source_project_id>.json`*\n\n- *Fixed Inputs*\n - __Name__: *fixed_inputs*\n - __Type__: *zip file*\n - __Description__: *Archive file consisting of any files referenced by the exported gear rules (if applicable), saved as `fixed_inputs_<source_project_id>.zip`*\n\n#### Metadata\n\nNo metadata is created or modified by this gear.\n\n### Pre-requisites\n\nA created project is required for this gear to run.\n\n#### Prerequisite Gear Runs\n\nNo prerequisite gear runs are necessary for this gear.\n\n#### Prerequisite Files\n\nNo files are required by this gear. Input files for template and fixed inputs are optional.\n\n#### Prerequisite Metadata\n\nNo prerequisite metadata necessary.\n\n## Usage\n\nFor 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.\n\n### Description\n\nThis 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. \n\n### Workflow\n\nA picture and description of the workflow\n\n```mermaid\ngraph LR;\n A[Template - Optional]:::input -.-> E;\n B[Fixed Input Archive - Optional]:::input -.-> E;\n D[Source Project]:::container --> E((Gear));\n\n E:::gear --> F[Exported Template];\n E -.-> G[Exported Fixed Input Archive - if applicable]\n E -.-> H[Target Project]:::container\n \n classDef container fill:#57d,color:#fff\n classDef input fill:#7a9,color:#fff\n classDef gear fill:#659,color:#fff\n\n```\n\nDescription of workflow\n\n1. Identify existing project to be cloned\n1. Optionally, input template and/or fixed inputs\n1. Gear outputs template created from source project and a fixed input archive, if applicable.\n1. Gear configures target project as specified, if applicable.\n\n### Use Cases\n\nThis section is very gear dependent, and covers a detailed walkthrough of some use cases. Should include Screenshots, example files, etc.\n\n#### Use Case 1: Exporting Project Settings - without Project Creation\n\nTo export a project's settings (permissions and gear rules):\n\n1. 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.\n\n#### Use Case 2: Exporting Project Settings - with Project Creation\n\nTo export a project's settings (permissions and gear rules), create a new project, and apply those settings to the new project\n\n1. Run project-settings as a project analysis on the source project\n1. Configure a `clone_project_path`. This will trigger the creation of a new project.\n1. Check `permissions` and `gear_rules` configuration options as desired. _Default for both is true_.\n\n#### Use Case 3: Import Project Settings to an Existing Project\n\nTo import project settings from one project to another:\n\n1. _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._\n1. _Upload settings files:_ Settings files should be uploaded to the target project as project attachments.\n1. _Run_ project-settings as a project-level analysis on the _target project_, where you want the permissions and rules applied.\n1. _Choose input files_ from the project attachments as appropriate for input to project-settings.\n\n### Logging\n\nThis 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.\n\n## FAQ\n\n[FAQ.md](FAQ.md)\n\n## Contributing\n\n[For more information about how to get started contributing to that gear,\ncheckout [CONTRIBUTING.md](CONTRIBUTING.md).]\n<!-- markdownlint-disable-file -->\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "For a given project, clone the permissions and gear rules to a new project, or export the settings for import to another project.",
"version": "2.2.6",
"project_urls": {
"Homepage": "https://gitlab.com/flywheel-io/scientific-solutions/gears/project-settings",
"Repository": "https://gitlab.com/flywheel-io/scientific-solutions/gears/project-settings"
},
"split_keywords": [
"flywheel",
" gears"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f9d7b4e388da7d6ecfd105dd702debe73ba910deb4ac236ac99a723bdeb0f91",
"md5": "b82539f67d78338d926c4fcf88744f39",
"sha256": "b059528e1c837b3d94ea0b95aec32877c9c8802eba2407aa23f5da7bf2249665"
},
"downloads": -1,
"filename": "fw_gear_project_settings-2.2.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b82539f67d78338d926c4fcf88744f39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 13897,
"upload_time": "2024-12-10T15:32:11",
"upload_time_iso_8601": "2024-12-10T15:32:11.586091Z",
"url": "https://files.pythonhosted.org/packages/8f/9d/7b4e388da7d6ecfd105dd702debe73ba910deb4ac236ac99a723bdeb0f91/fw_gear_project_settings-2.2.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-10 15:32:11",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "flywheel-io",
"gitlab_project": "scientific-solutions",
"lcname": "fw-gear-project-settings"
}
JSON