├── sync_customizations ├── modules.txt ├── config │ └── __init__.py ├── public │ └── .gitkeep ├── www │ └── __init__.py ├── templates │ ├── __init__.py │ └── pages │ │ └── __init__.py ├── __init__.py ├── constants.py ├── patches.txt ├── commands.py ├── hooks.py ├── utils.py └── api.py ├── .gitignore ├── pyproject.toml ├── license.txt └── README.md /sync_customizations/modules.txt: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /sync_customizations/config/__init__.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /sync_customizations/public/.gitkeep: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /sync_customizations/www/__init__.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /sync_customizations/templates/__init__.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /sync_customizations/templates/pages/__init__.py: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /sync_customizations/__init__.py: -------------------------------------------------------------------------------- 1 | __version__ = "0.0.1" 2 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | *.pyc 3 | *.egg-info 4 | *.swp 5 | tags 6 | node_modules 7 | __pycache__ -------------------------------------------------------------------------------- /sync_customizations/constants.py: -------------------------------------------------------------------------------- 1 | EXPORT_DIR_NAME = "customizations" 2 | DOCTYPES_TO_SYNC = ("Custom Field", "Property Setter") 3 | -------------------------------------------------------------------------------- /sync_customizations/patches.txt: -------------------------------------------------------------------------------- 1 | [pre_model_sync] 2 | # Patches added in this section will be executed before doctypes are migrated 3 | # Read docs to understand patches: https://frappeframework.com/docs/v14/user/en/database-migrations 4 | 5 | [post_model_sync] 6 | # Patches added in this section will be executed after doctypes are migrated -------------------------------------------------------------------------------- /sync_customizations/commands.py: -------------------------------------------------------------------------------- 1 | import click 2 | 3 | import frappe 4 | from frappe.commands import get_site, pass_context 5 | 6 | 7 | @click.command("sc-export") 8 | @pass_context 9 | def export_customizations(context): 10 | """Export supported customizations to JSON files""" 11 | 12 | from sync_customizations.api import export_customizations 13 | 14 | site = get_site(context) 15 | frappe.init(site=site) 16 | frappe.connect() 17 | 18 | export_customizations() 19 | print("Customizations exported successfully!") 20 | 21 | 22 | commands = [export_customizations] 23 | -------------------------------------------------------------------------------- /pyproject.toml: -------------------------------------------------------------------------------- 1 | [project] 2 | name = "sync_customizations" 3 | authors = [ 4 | { name = "Resilient Tech", email = "admin@resilient.tech"} 5 | ] 6 | description = "Automatically sync Custom Fields and Property Setters in Frappe sites" 7 | requires-python = ">=3.10" 8 | readme = "README.md" 9 | dynamic = ["version"] 10 | dependencies = [ 11 | # "frappe~=15.0.0" # Installed and managed by bench. 12 | ] 13 | 14 | [build-system] 15 | requires = ["flit_core >=3.4,<4"] 16 | build-backend = "flit_core.buildapi" 17 | 18 | # These dependencies are only installed when developer mode is enabled 19 | [tool.bench.dev-dependencies] 20 | # package_name = "~=1.1.0" 21 | -------------------------------------------------------------------------------- /sync_customizations/hooks.py: -------------------------------------------------------------------------------- 1 | from sync_customizations.constants import DOCTYPES_TO_SYNC 2 | 3 | app_name = "sync_customizations" 4 | app_title = "Sync Customizations" 5 | app_publisher = "Resilient Tech" 6 | app_description = ( 7 | "Automatically sync Custom Fields and Property Setters in Frappe sites" 8 | ) 9 | app_email = "admin@resilient.tech" 10 | app_license = "mit" 11 | 12 | before_migrate = "sync_customizations.api.import_customizations" 13 | 14 | doc_events = { 15 | DOCTYPES_TO_SYNC: { 16 | "on_update": "sync_customizations.api.export_doc", 17 | "on_trash": "sync_customizations.api.delete_doc", 18 | }, 19 | "Customize Form": { 20 | "save_customization": "sync_customizations.api.on_save_customization", 21 | }, 22 | } 23 | -------------------------------------------------------------------------------- /license.txt: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2023 Resilient Tech 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 🔁 Sync Customizations 2 | 3 | Automatically sync Custom Fields and Property Setters in Frappe sites 4 | 5 | 6 | ## Usage 7 | 8 | ### Exporting Customizations 9 | 10 | #### Automatically ✨ 11 | 12 | Create Custom Fields and Property Setters as usual through Customize Form / Form Builder / respective DocTypes. The corresponding files should get auto-created in the following directory by default: 13 | 14 | ``` 15 | [bench-name]/sites/[site-name]/customizations/ 16 | ``` 17 | 18 | You can also specify a custom directory for syncing customizations by setting the path to that directory in a site config called `customizations_dir`. This path must be either absolute or relative to the site's bench directory. For example: 19 | 20 | ```bash 21 | bench --site abc.localhost set-config customizations_dir apps/abc/customizations 22 | ``` 23 | 24 | #### Manually 25 | 26 | Want to export existing customizations? Fret not, you can just run the following command: 27 | 28 | ```bash 29 | bench --site [your-site-name] sc-export 30 | ``` 31 | 32 | 33 | ### Importing Customizations 34 | 35 | Ensure that this app is installed and the customizations directory is present. Customizations should get synced automatically during DB migration. 36 | 37 | ## Sponsors 38 | 39 | Special thanks to [@filtersource](https://github.com/filtersource) and [@rtCamp](https://github.com/rtCamp) for sponsoring the development of this app! 40 | 41 | ## License 42 | 43 | MIT 44 | -------------------------------------------------------------------------------- /sync_customizations/utils.py: -------------------------------------------------------------------------------- 1 | import os 2 | 3 | import frappe 4 | from frappe.modules.export_file import strip_default_fields 5 | from frappe.utils import get_bench_path 6 | 7 | from sync_customizations.constants import EXPORT_DIR_NAME 8 | 9 | 10 | def write_document_file(doc): 11 | doc_export = doc.as_dict(no_nulls=True) 12 | for key in ("idx", "__unsaved"): 13 | doc_export.pop(key, None) 14 | 15 | doc.run_method("before_export", doc_export) 16 | doc_export = strip_default_fields(doc, doc_export) 17 | 18 | with open(get_file_path(doc), "w+") as txtfile: 19 | txtfile.write(frappe.as_json(doc_export)) 20 | 21 | 22 | def get_filters(doctype): 23 | return {"is_system_generated": 0} if doctype == "Custom Field" else {} 24 | 25 | 26 | def get_doctype_field(doctype): 27 | return "dt" if doctype == "Custom Field" else "doc_type" 28 | 29 | 30 | def delete_document_file(doc): 31 | try: 32 | os.remove(get_file_path(doc)) 33 | except OSError: 34 | pass 35 | 36 | 37 | def get_export_dir_path(): 38 | if frappe.conf.customizations_dir: 39 | return os.path.join(get_bench_path(), frappe.conf.customizations_dir) 40 | 41 | return frappe.get_site_path(EXPORT_DIR_NAME) 42 | 43 | def get_folder(doctype): 44 | folder_path = os.path.join(get_export_dir_path(), frappe.scrub(doctype)) 45 | frappe.create_folder(folder_path) 46 | return folder_path 47 | 48 | 49 | def get_file_path(doc): 50 | return os.path.join(get_folder(doc.doctype), get_file_name(doc.name)) 51 | 52 | 53 | def get_file_name(docname): 54 | return f"{docname}.json" 55 | -------------------------------------------------------------------------------- /sync_customizations/api.py: -------------------------------------------------------------------------------- 1 | import os 2 | 3 | import frappe 4 | from frappe.modules.import_file import import_file_by_path 5 | 6 | from sync_customizations.utils import ( 7 | write_document_file, 8 | delete_document_file, 9 | get_folder, 10 | get_filters, 11 | get_doctype_field, 12 | get_file_name, 13 | ) 14 | from sync_customizations.constants import DOCTYPES_TO_SYNC 15 | 16 | 17 | IMPORT_FLAG = "sc_importing_customizations" 18 | 19 | 20 | def export_doc(doc, method=None): 21 | if ( 22 | doc.doctype == "Custom Field" and doc.is_system_generated 23 | ) or frappe.local.flags.get(IMPORT_FLAG, False): 24 | return 25 | 26 | frappe.db.after_commit.add(lambda: write_document_file(doc)) 27 | 28 | 29 | def delete_doc(doc, method=None): 30 | frappe.db.after_commit.add(lambda: delete_document_file(doc)) 31 | 32 | 33 | def on_save_customization(doc, method=None): 34 | frappe.db.after_commit.add( 35 | lambda: export_customizations(filter_by_doctype=doc.doc_type) 36 | ) 37 | 38 | 39 | def export_customizations(filter_by_doctype=None): 40 | for doctype in DOCTYPES_TO_SYNC: 41 | folder = get_folder(doctype) 42 | filters = get_filters(doctype) 43 | files_to_keep = set( 44 | get_file_name(doc.name) for doc in frappe.get_all(doctype, filters=filters) 45 | ) 46 | files_to_delete = [ 47 | fname for fname in os.listdir(folder) if fname not in files_to_keep 48 | ] 49 | 50 | for file_name in files_to_delete: 51 | os.remove(os.path.join(folder, file_name)) 52 | 53 | if filter_by_doctype: 54 | doctype_field = get_doctype_field(doctype) 55 | filters[doctype_field] = filter_by_doctype 56 | 57 | for doc in frappe.get_all(doctype, filters=filters, fields="*"): 58 | doc = frappe.get_doc({"doctype": doctype, **doc}) 59 | write_document_file(doc) 60 | 61 | 62 | def import_customizations(): 63 | flags = frappe.local.flags 64 | try: 65 | flags[IMPORT_FLAG] = True 66 | _import_customizations() 67 | 68 | finally: 69 | flags.pop(IMPORT_FLAG, None) 70 | 71 | 72 | def _import_customizations(): 73 | for doctype in DOCTYPES_TO_SYNC: 74 | docnames = set() 75 | 76 | folder = get_folder(doctype) 77 | 78 | for doc_filename in os.listdir(folder): 79 | if not doc_filename.endswith(".json"): 80 | continue 81 | 82 | import_file_by_path(os.path.join(folder, doc_filename)) 83 | docnames.add(os.path.splitext(doc_filename)[0]) 84 | 85 | frappe.db.commit() 86 | print(f"{doctype}s imported successfully...") 87 | 88 | docs_to_delete = frappe.get_all( 89 | doctype, 90 | filters={"name": ("not in", docnames), **get_filters(doctype)}, 91 | pluck="name", 92 | ) 93 | if docs_to_delete: 94 | print(f"Detected stale {doctype}s:\n{', '.join(docs_to_delete)}") 95 | print("\nDeleting...", end=" ") 96 | 97 | frappe.db.delete(doctype, {"name": ("in", docs_to_delete)}) 98 | frappe.db.commit() 99 | print("Done!\n") 100 | 101 | frappe.clear_cache() 102 | --------------------------------------------------------------------------------