feat: configurable amended document naming (#21414)

* feat: configurable amendment naming

* patch: set default amend naming

* chore: linters and document filter

* test: amended document naming

* refactor: use set_single_value

* chore: typo, fix copy

* fix(UX): move action button below table

* refactor: Series Counter -> Default Naming

The behaviour in this PR doesn't necessarily mean to apply naming series
it can be:
- Naming Series
- hash
- Naming Rule
- Some code

So the name was misleading.

---------

Co-authored-by: Ankush Menat <ankush@frappe.io>

frappe/core/doctype/amended_document_naming_settings/amended_document_naming_settings.json

@@ -0,0 +1,44 @@
+{
+ "actions": [],
+ "allow_rename": 1,
+ "creation": "2023-06-16 17:57:36.604672",
+ "doctype": "DocType",
+ "editable_grid": 1,
+ "engine": "InnoDB",
+ "field_order": [
+  "document_type",
+  "action"
+ ],
+ "fields": [
+  {
+   "default": "Amend Counter",
+   "fieldname": "action",
+   "fieldtype": "Select",
+   "in_list_view": 1,
+   "label": "Action",
+   "options": "Amend Counter\nDefault Naming",
+   "reqd": 1
+  },
+  {
+   "fieldname": "document_type",
+   "fieldtype": "Link",
+   "in_list_view": 1,
+   "label": "DocType",
+   "options": "DocType",
+   "reqd": 1,
+   "unique": 1
+  }
+ ],
+ "index_web_pages_for_search": 1,
+ "istable": 1,
+ "links": [],
+ "modified": "2023-06-16 18:26:16.247475",
+ "modified_by": "Administrator",
+ "module": "Core",
+ "name": "Amended Document Naming Settings",
+ "owner": "Administrator",
+ "permissions": [],
+ "sort_field": "modified",
+ "sort_order": "DESC",
+ "states": []
+}

frappe/core/doctype/amended_document_naming_settings/amended_document_naming_settings.py

@@ -0,0 +1,9 @@
+# Copyright (c) 2023, Frappe Technologies and contributors
+# For license information, please see license.txt
+
+# import frappe
+from frappe.model.document import Document
+
+
+class AmendedDocumentNamingSettings(Document):
+	pass

frappe/core/doctype/document_naming_settings/document_naming_settings.js

@@ -2,6 +2,16 @@
 // For license information, please see license.txt
 
 frappe.ui.form.on("Document Naming Settings", {
+	setup: function (frm) {
+		frm.set_query("document_type", "amend_naming_override", () => {
+			return {
+				filters: {
+					is_submittable: 1,
+				},
+			};
+		});
+	},
+
 	refresh: function (frm) {
 		frm.trigger("setup_transaction_autocomplete");
 		frm.disable_save();

frappe/core/doctype/document_naming_settings/document_naming_settings.json

@@ -18,7 +18,11 @@
   "update_series",
   "prefix",
   "current_value",
-  "update_series_start"
+  "update_series_start",
+  "amended_documents_section",
+  "default_amend_naming",
+  "amend_naming_override",
+  "update_amendment_naming"
  ],
  "fields": [
   {
@@ -105,13 +109,41 @@
    "fieldtype": "Text",
    "label": "Preview of generated names",
    "read_only": 1
+  },
+  {
+   "collapsible": 1,
+   "description": "Configure how amended documents will be named.<br>\n\nDefault behaviour is to follow an amend counter which adds a number to the end of the original name indicating the amended version. <br>\n\nDefault Naming will make the amended document to behave same as new documents.",
+   "fieldname": "amended_documents_section",
+   "fieldtype": "Section Break",
+   "label": "Amended Documents"
+  },
+  {
+   "default": "Amend Counter",
+   "fieldname": "default_amend_naming",
+   "fieldtype": "Select",
+   "in_list_view": 1,
+   "label": "Default Amendment Naming",
+   "options": "Amend Counter\nDefault Naming",
+   "reqd": 1
+  },
+  {
+   "fieldname": "amend_naming_override",
+   "fieldtype": "Table",
+   "label": "Amendment Naming Override",
+   "options": "Amended Document Naming Settings"
+  },
+  {
+   "fieldname": "update_amendment_naming",
+   "fieldtype": "Button",
+   "label": "Update Amendment Naming",
+   "options": "update_amendment_rule"
   }
  ],
  "hide_toolbar": 1,
  "icon": "fa fa-sort-by-order",
  "issingle": 1,
  "links": [],
- "modified": "2023-02-20 13:11:56.662100",
+ "modified": "2023-06-20 17:47:52.204139",
  "modified_by": "Administrator",
  "module": "Core",
  "name": "Document Naming Settings",

frappe/core/doctype/document_naming_settings/document_naming_settings.py

@@ -169,6 +169,23 @@ class DocumentNamingSettings(Document):
 			self.current_value = NamingSeries(self.prefix).get_current_value()
 		return self.current_value
 
+	@frappe.whitelist()
+	def update_amendment_rule(self):
+		self.db_set("default_amend_naming", self.default_amend_naming)
+
+		existing_overrides = frappe.db.get_all(
+			"Amended Document Naming Settings",
+			filters={"name": ["not in", [d.name for d in self.amend_naming_override]]},
+			pluck="name",
+		)
+		for override in existing_overrides:
+			frappe.delete_doc("Amended Document Naming Settings", override)
+
+		for row in self.amend_naming_override:
+			row.save()
+
+		frappe.msgprint(_("Amendment naming rules updated."), indicator="green", alert=True)
+
 	@frappe.whitelist()
 	def update_series_start(self):
 		frappe.only_for("System Manager")

frappe/core/doctype/document_naming_settings/test_document_naming_settings.py

@@ -26,6 +26,7 @@ class TestNamingSeries(FrappeTestCase):
 					}
 				],
 				autoname="naming_series:",
+				is_submittable=1,
 			)
 			.insert()
 			.name
@@ -82,3 +83,36 @@ class TestNamingSeries(FrappeTestCase):
 			self.dns.update_series_start()
 
 			self.assertEqual(self.dns.get_current(), new_count, f"Incorrect update for {series}")
+
+	def test_amended_naming(self):
+		self.dns.amend_naming_override = []
+		self.dns.default_amend_naming = "Amend Counter"
+		self.dns.update_amendment_rule()
+
+		submittable_doc = frappe.get_doc(
+			dict(doctype=self.ns_doctype, some_fieldname="test doc with submit")
+		).submit()
+		submittable_doc.cancel()
+
+		amended_doc = frappe.get_doc(
+			dict(
+				doctype=self.ns_doctype,
+				some_fieldname="test doc with submit",
+				amended_from=submittable_doc.name,
+			)
+		).insert()
+
+		self.assertIn(submittable_doc.name, amended_doc.name)
+		amended_doc.delete()
+
+		self.dns.default_amend_naming = "Default Naming"
+		self.dns.update_amendment_rule()
+
+		new_amended_doc = frappe.get_doc(
+			dict(
+				doctype=self.ns_doctype,
+				some_fieldname="test doc with submit",
+				amended_from=submittable_doc.name,
+			)
+		).insert()
+		self.assertNotIn(submittable_doc.name, new_amended_doc.name)

frappe/model/naming.py

@@ -151,7 +151,8 @@ def set_new_name(doc):
 
 	if getattr(doc, "amended_from", None):
 		_set_amended_name(doc)
-		return
+		if doc.name:
+			return
 
 	elif getattr(doc.meta, "issingle", False):
 		doc.name = doc.doctype
@@ -506,6 +507,17 @@ def append_number_if_name_exists(doctype, value, fieldname="name", separator="-"
 
 
 def _set_amended_name(doc):
+	amend_naming_rule = frappe.db.get_value(
+		"Amended Document Naming Settings", {"document_type": doc.doctype}, "action", cache=True
+	)
+	if not amend_naming_rule:
+		amend_naming_rule = frappe.db.get_single_value(
+			"Document Naming Settings", "default_amend_naming", cache=True
+		)
+
+	if amend_naming_rule == "Default Naming":
+		return
+
 	am_id = 1
 	am_prefix = doc.amended_from
 	if frappe.db.get_value(doc.doctype, doc.amended_from, "amended_from"):

frappe/patches.txt

@@ -226,3 +226,4 @@ frappe.patches.v14_0.remove_manage_subscriptions_from_navbar
 frappe.patches.v15_0.remove_background_jobs_from_dropdown
 frappe.desk.doctype.form_tour.patches.introduce_ui_tours
 execute:frappe.delete_doc_if_exists("Workspace", "Customization")
+execute:frappe.db.set_single_value("Document Naming Settings", "default_amend_naming", "Amend Counter")