# 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
`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
```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
#### 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\nthe 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\n 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\n files will be uploaded to the cloned project and referenced by the gear rules. If\n 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\n <group_id>/<project_name>. If <clone_project_path> provided a new project will be\n created. If the project exists, the 'apply_to_existing_project' option must be used\n 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\n clone project. This is done by default and will override permissions within the\n template. If you wish to use the permissions within the template you must set\n `default_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\n applicable).*\n - __Default__: *true*\n - __Note__: *When exporting gear rules, gear will export the latest version of the\n fixed input file available on the origin project. When importing gear rules to the\n destination project, the gear will upload the fixed input files and the gear rule\n will use this latest version of the file available on the destination project. When\n gear rules with fixed inputs are triggered, the triggered job uses the latest version\n of the fixed input at runtime.*\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\n 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\n rule, this option will determine what happens with those rules. Options are:\n 'REPLACE ALL' (delete ALL existing rules, then add template rules)', 'MATCH'\n (replace the existing rule with the template rule), 'APPEND' (add template rule - may\n 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\n 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\n 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\noptional.\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.\nThis Gear will run at the project level and generate a new project (locally or via\nconfiguration file for external use) with the appropriate gear rules and user\npermissions.\n\n### Description\n\nThis gear utilizes an inputted template or creates a template from the source project\nto be assist with replicating an existing project configuration. Fixed inputs can also\nbe applied either from an archive (zip) file or from the source project. If\n`clone_project_path` is provided, the gear will attempt to locate the specified\nproject; if it is not located, it will attempt to create the project as specified, and\nif the project already exists and `apply_to_existing_project==True` it will set the\nexisting project as the target for application. (If the project already exists and\n`apply_to_existing_project==False`, the gear will exit.) The gear will then export the\ntemplate, and if applicable will apply the template to the target project as\nconfigured. If `permissions==True`, permissions will be applied. If `gear_rules==True`,\ngear 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,\nif applicable.\n1. Gear configures target project as specified, if applicable.\n\n### Use Cases\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\n`clone_project_path`. This will not create a project, nor apply any settings.\nIt 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\napply 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.\n_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\nproject without configuring a `clone_project_path`. This will not create a project, nor\napply any settings. It will simply generate the settings output files. _Optionally you\ncan use files from an existing run._\n1. _Upload settings files:_ Settings files should be uploaded to the target project as\nproject attachments.\n1. _Run_ project-settings as a project-level analysis on the _target project_, where\nyou want the permissions and rules applied.\n1. _Choose input files_ from the project attachments as appropriate for input to\nproject-settings.\n\n### Logging\n\nThis gear provides log statements as it runs to identify where the gear is at within\nthe process. These can be used to understand where a gear run is encountering problems,\nif 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.8",
"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": "ee44a4f40f4b5079a2a7e72aadfea393b9146e30b45cb5b5db2daa0e090fd86a",
"md5": "1c059ce186c7eb4b31e36f9c03787bdd",
"sha256": "b762f3c42fe5aeb04b9187bffa8d7efa5a5145a0b6e5d4536e3ea8761b7ea505"
},
"downloads": -1,
"filename": "fw_gear_project_settings-2.2.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1c059ce186c7eb4b31e36f9c03787bdd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.11",
"size": 14272,
"upload_time": "2025-02-06T23:02:08",
"upload_time_iso_8601": "2025-02-06T23:02:08.382178Z",
"url": "https://files.pythonhosted.org/packages/ee/44/a4f40f4b5079a2a7e72aadfea393b9146e30b45cb5b5db2daa0e090fd86a/fw_gear_project_settings-2.2.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-06 23:02:08",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "flywheel-io",
"gitlab_project": "scientific-solutions",
"lcname": "fw-gear-project-settings"
}
JSON