diff --git a/hrms/controllers/employee_boarding_controller.py b/hrms/controllers/employee_boarding_controller.py
index f9578b2b472..18a8857f82b 100644
--- a/hrms/controllers/employee_boarding_controller.py
+++ b/hrms/controllers/employee_boarding_controller.py
@@ -27,7 +27,7 @@ def on_submit(self):
# create the project for the given employee onboarding
project_name = _(self.doctype) + " : "
if self.doctype == "Employee Onboarding":
- project_name += self.job_applicant
+ project_name += self.job_applicant or self.employee_name
else:
project_name += self.employee
diff --git a/hrms/hooks.py b/hrms/hooks.py
index fdfd4f8a773..ec9f5184545 100644
--- a/hrms/hooks.py
+++ b/hrms/hooks.py
@@ -101,8 +101,12 @@
after_install = "hrms.install.after_install"
after_migrate = "hrms.setup.update_select_perm_after_install"
+setup_wizard_requires = "assets/hrms/js/setup_wizard.js"
+setup_wizard_stages = "hrms.setup_wizard.get_setup_stages"
setup_wizard_complete = "hrms.subscription_utils.update_erpnext_access"
+extend_bootinfo = "hrms.utils.extend_bootinfo"
+
# Uninstallation
# ------------
diff --git a/hrms/hr/doctype/employee_onboarding/employee_onboarding.js b/hrms/hr/doctype/employee_onboarding/employee_onboarding.js
index 89d8343ffdb..d30119caad1 100644
--- a/hrms/hr/doctype/employee_onboarding/employee_onboarding.js
+++ b/hrms/hr/doctype/employee_onboarding/employee_onboarding.js
@@ -3,18 +3,10 @@
frappe.ui.form.on("Employee Onboarding", {
setup: function (frm) {
- frm.set_query("job_applicant", function () {
- return {
- filters: {
- status: "Accepted",
- },
- };
- });
-
frm.set_query("job_offer", function () {
return {
filters: {
- job_applicant: frm.doc.job_applicant,
+ status: "Accepted",
docstatus: 1,
},
};
@@ -91,20 +83,11 @@ frappe.ui.form.on("Employee Onboarding", {
}
},
- job_applicant: function (frm) {
- if (frm.doc.job_applicant) {
- frappe.db.get_value(
- "Employee",
- { job_applicant: frm.doc.job_applicant },
- "name",
- (r) => {
- if (r.name) {
- frm.set_value("employee", r.name);
- } else {
- frm.set_value("employee", "");
- }
- },
- );
+ job_offer: function (frm) {
+ if (frm.doc.job_offer) {
+ frappe.db.get_value("Employee", { job_offer: frm.doc.job_offer }, "name", (r) => {
+ frm.set_value("employee", r && r.name ? r.name : "");
+ });
} else {
frm.set_value("employee", "");
}
diff --git a/hrms/hr/doctype/employee_onboarding/employee_onboarding.json b/hrms/hr/doctype/employee_onboarding/employee_onboarding.json
index 48292e22c17..457ec41fc9a 100644
--- a/hrms/hr/doctype/employee_onboarding/employee_onboarding.json
+++ b/hrms/hr/doctype/employee_onboarding/employee_onboarding.json
@@ -6,8 +6,8 @@
"editable_grid": 1,
"engine": "InnoDB",
"field_order": [
- "job_applicant",
"job_offer",
+ "job_applicant",
"employee_onboarding_template",
"column_break_7",
"company",
@@ -29,13 +29,6 @@
"amended_from"
],
"fields": [
- {
- "fieldname": "job_applicant",
- "fieldtype": "Link",
- "label": "Job Applicant",
- "options": "Job Applicant",
- "reqd": 1
- },
{
"fieldname": "job_offer",
"fieldtype": "Link",
@@ -44,7 +37,15 @@
"reqd": 1
},
{
- "fetch_from": "job_applicant.applicant_name",
+ "depends_on": "eval:doc.job_applicant",
+ "fetch_from": "job_offer.job_applicant",
+ "fieldname": "job_applicant",
+ "fieldtype": "Link",
+ "label": "Job Applicant",
+ "options": "Job Applicant"
+ },
+ {
+ "fetch_from": "job_offer.applicant_name",
"fieldname": "employee_name",
"fieldtype": "Data",
"in_list_view": 1,
diff --git a/hrms/hr/doctype/employee_onboarding/employee_onboarding.py b/hrms/hr/doctype/employee_onboarding/employee_onboarding.py
index caf431f80dc..486da2d1b32 100644
--- a/hrms/hr/doctype/employee_onboarding/employee_onboarding.py
+++ b/hrms/hr/doctype/employee_onboarding/employee_onboarding.py
@@ -40,7 +40,7 @@ class EmployeeOnboarding(EmployeeBoardingController):
employee_name: DF.Data
employee_onboarding_template: DF.Link | None
holiday_list: DF.Link | None
- job_applicant: DF.Link
+ job_applicant: DF.Link | None
job_offer: DF.Link
notify_users_by_email: DF.Check
project: DF.Link | None
@@ -53,16 +53,16 @@ def validate(self):
def set_employee(self):
if not self.employee:
- self.employee = frappe.db.get_value("Employee", {"job_applicant": self.job_applicant}, "name")
+ self.employee = frappe.db.get_value("Employee", {"job_offer": self.job_offer}, "name")
def validate_duplicate_employee_onboarding(self):
emp_onboarding = frappe.db.exists(
- "Employee Onboarding", {"job_applicant": self.job_applicant, "docstatus": ("!=", 2)}
+ "Employee Onboarding", {"job_offer": self.job_offer, "docstatus": ("!=", 2)}
)
if emp_onboarding and emp_onboarding != self.name:
frappe.throw(
- _("Employee Onboarding: {0} already exists for Job Applicant: {1}").format(
- frappe.bold(emp_onboarding), frappe.bold(self.job_applicant)
+ _("Employee Onboarding: {0} already exists for Job Offer: {1}").format(
+ frappe.bold(emp_onboarding), frappe.bold(self.job_offer)
)
)
@@ -106,7 +106,8 @@ def make_employee(source_name: str, target_doc: str | Document | None = None) ->
doc.validate_employee_creation()
def set_missing_values(source, target):
- target.personal_email = frappe.db.get_value("Job Applicant", source.job_applicant, "email_id")
+ target.personal_email = frappe.db.get_value("Job Offer", source.job_offer, "applicant_email")
+ target.job_offer = source.job_offer
target.status = "Active"
doc = get_mapped_doc(
diff --git a/hrms/hr/doctype/job_offer/job_offer.json b/hrms/hr/doctype/job_offer/job_offer.json
index 6d7107e6e35..880dd2bcaeb 100644
--- a/hrms/hr/doctype/job_offer/job_offer.json
+++ b/hrms/hr/doctype/job_offer/job_offer.json
@@ -11,10 +11,10 @@
"applicant_name",
"applicant_email",
"column_break_3",
- "status",
"offer_date",
"designation",
"company",
+ "status",
"section_break_4",
"job_offer_term_template",
"offer_terms",
@@ -29,13 +29,13 @@
],
"fields": [
{
+ "depends_on": "eval:doc.job_applicant",
"fieldname": "job_applicant",
"fieldtype": "Link",
"label": "Job Applicant",
"link_filters": "[[\"Job Applicant\",\"status\",\"!=\",\"Rejected\"]]",
"options": "Job Applicant",
- "print_hide": 1,
- "reqd": 1
+ "print_hide": 1
},
{
"fetch_from": "job_applicant.applicant_name",
@@ -44,7 +44,6 @@
"in_global_search": 1,
"in_list_view": 1,
"label": "Applicant Name",
- "read_only": 1,
"reqd": 1
},
{
@@ -54,7 +53,7 @@
"in_global_search": 1,
"label": "Applicant Email Address",
"options": "Email",
- "read_only": 1
+ "reqd": 1
},
{
"fieldname": "column_break_3",
diff --git a/hrms/hr/doctype/job_offer/job_offer.py b/hrms/hr/doctype/job_offer/job_offer.py
index 92bb589cf05..815ddb226c1 100644
--- a/hrms/hr/doctype/job_offer/job_offer.py
+++ b/hrms/hr/doctype/job_offer/job_offer.py
@@ -22,11 +22,11 @@ class JobOffer(Document):
from hrms.hr.doctype.job_offer_term.job_offer_term import JobOfferTerm
amended_from: DF.Link | None
- applicant_email: DF.Data | None
+ applicant_email: DF.Data
applicant_name: DF.Data
company: DF.Link
designation: DF.Link
- job_applicant: DF.Link
+ job_applicant: DF.Link | None
job_offer_term_template: DF.Link | None
letter_head: DF.Link | None
offer_date: DF.Date
@@ -38,18 +38,27 @@ class JobOffer(Document):
# end: auto-generated types
def onload(self):
- employee = frappe.db.get_value("Employee", {"job_applicant": self.job_applicant}, "name") or ""
+ employee = frappe.db.get_value("Employee", {"job_offer": self.name}, "name") or ""
self.set_onload("employee", employee)
def validate(self):
self.validate_vacancies()
- job_offer = frappe.db.exists(
- "Job Offer", {"job_applicant": self.job_applicant, "docstatus": ["!=", 2]}
+ self.validate_duplicate_job_offer()
+
+ def validate_duplicate_job_offer(self):
+ duplicate = frappe.db.exists(
+ "Job Offer",
+ {
+ "applicant_email": self.applicant_email,
+ "docstatus": ["!=", 2],
+ "status": ["not in", ["Rejected", "Cancelled"]],
+ "name": ["!=", self.name],
+ },
)
- if job_offer and job_offer != self.name:
+ if duplicate:
frappe.throw(
- _("Job Offer: {0} is already for Job Applicant: {1}").format(
- frappe.bold(job_offer), frappe.bold(self.job_applicant)
+ _("Job Offer {0} already exists for {1}").format(
+ get_link_to_form("Job Offer", duplicate), frappe.bold(self.applicant_email)
)
)
@@ -86,7 +95,7 @@ def on_discard(self):
def update_job_applicant(status, job_applicant):
- if status in ("Accepted", "Rejected"):
+ if job_applicant and status in ("Accepted", "Rejected"):
frappe.set_value("Job Applicant", job_applicant, "status", status)
@@ -123,9 +132,9 @@ def get_staffing_plan_detail(designation, company, offer_date):
@frappe.whitelist()
def make_employee(source_name: str, target_doc: str | Document | None = None):
def set_missing_values(source, target):
- target.personal_email, target.first_name = frappe.db.get_value(
- "Job Applicant", source.job_applicant, ["email_id", "applicant_name"]
- )
+ target.personal_email = source.applicant_email
+ target.first_name = source.applicant_name
+ target.job_offer = source.name
doc = get_mapped_doc(
"Job Offer",
diff --git a/hrms/hr/doctype/job_offer/test_job_offer.py b/hrms/hr/doctype/job_offer/test_job_offer.py
index 408427a3637..41dd52e92cc 100644
--- a/hrms/hr/doctype/job_offer/test_job_offer.py
+++ b/hrms/hr/doctype/job_offer/test_job_offer.py
@@ -7,8 +7,9 @@
from erpnext.setup.doctype.designation.test_designation import create_designation
from hrms.hr.doctype.job_applicant.job_applicant import get_applicant_to_hire_percentage
-from hrms.hr.doctype.job_offer.job_offer import get_offer_acceptance_rate
+from hrms.hr.doctype.job_offer.job_offer import get_offer_acceptance_rate, make_employee
from hrms.hr.doctype.staffing_plan.test_staffing_plan import make_company
+from hrms.overrides.employee_master import update_job_applicant_and_offer
from hrms.tests.test_utils import create_job_applicant
from hrms.tests.utils import HRMSTestSuite
@@ -68,17 +69,151 @@ def test_recruitment_metrics(self):
self.assertEqual(get_offer_acceptance_rate().get("value"), 50)
def test_status_on_save(self):
- job_offer = create_job_offer()
+ job_applicant = create_job_applicant(email_id="test_job_offer_status@example.com")
+ job_offer = create_job_offer(job_applicant=job_applicant.name)
job_offer.save()
job_offer.discard()
job_offer.reload()
self.assertEqual(job_offer.status, "Cancelled")
+ def test_job_offer_without_job_applicant(self):
+ frappe.db.set_single_value("HR Settings", "check_vacancies", 0)
+ job_offer = create_job_offer(
+ applicant_name="Walk In Candidate",
+ applicant_email="walk_in_candidate@example.com",
+ status="Awaiting Response",
+ )
+ job_offer.submit()
+
+ job_offer.reload()
+ self.assertFalse(job_offer.job_applicant)
+ self.assertEqual(job_offer.applicant_name, "Walk In Candidate")
+
+ def test_duplicate_job_offer_for_same_email(self):
+ frappe.db.set_single_value("HR Settings", "check_vacancies", 0)
+ create_job_offer(
+ applicant_name="Duplicate Candidate",
+ applicant_email="duplicate_candidate@example.com",
+ status="Awaiting Response",
+ ).submit()
+
+ duplicate = create_job_offer(
+ applicant_name="Duplicate Candidate",
+ applicant_email="duplicate_candidate@example.com",
+ status="Awaiting Response",
+ )
+ self.assertRaises(frappe.ValidationError, duplicate.save)
+
+ # a different email is not a duplicate
+ create_job_offer(
+ applicant_name="Another Candidate",
+ applicant_email="another_candidate@example.com",
+ status="Awaiting Response",
+ ).save()
+
+ def test_duplicate_job_offer_allowed_after_rejection(self):
+ frappe.db.set_single_value("HR Settings", "check_vacancies", 0)
+ rejected = create_job_offer(
+ applicant_name="Reoffered Candidate",
+ applicant_email="reoffered_candidate@example.com",
+ status="Rejected",
+ )
+ rejected.submit()
+
+ create_job_offer(
+ applicant_name="Reoffered Candidate",
+ applicant_email="reoffered_candidate@example.com",
+ status="Awaiting Response",
+ ).save()
+
+ def test_make_employee_without_job_applicant(self):
+ frappe.db.set_single_value("HR Settings", "check_vacancies", 0)
+ job_offer = create_job_offer(
+ applicant_name="Intern Candidate",
+ applicant_email="intern_candidate@example.com",
+ status="Awaiting Response",
+ )
+ job_offer.submit()
+
+ employee = make_employee(job_offer.name)
+ self.assertEqual(employee.first_name, "Intern Candidate")
+ self.assertEqual(employee.personal_email, "intern_candidate@example.com")
+ self.assertEqual(employee.job_offer, job_offer.name)
+
+ employee.date_of_birth = "1990-05-08"
+ employee.date_of_joining = nowdate()
+ employee.gender = "Female"
+ employee.insert()
+
+ job_offer.reload()
+ self.assertEqual(job_offer.status, "Accepted")
+
+ job_offer.run_method("onload")
+ self.assertEqual(job_offer.get_onload("employee"), employee.name)
+
+ def test_onload_employee_ignores_unrelated_offers(self):
+ frappe.db.set_single_value("HR Settings", "check_vacancies", 0)
+ unrelated = create_job_offer(
+ applicant_name="Unrelated Candidate",
+ applicant_email="unrelated_candidate@example.com",
+ status="Awaiting Response",
+ )
+ unrelated.save()
+ unrelated.run_method("onload")
+ self.assertFalse(unrelated.get_onload("employee"))
+
+ def test_rejected_job_offer_not_accepted_on_employee_creation(self):
+ frappe.db.set_single_value("HR Settings", "check_vacancies", 0)
+ job_offer = create_job_offer(
+ applicant_name="Rejected Candidate",
+ applicant_email="rejected_candidate@example.com",
+ status="Rejected",
+ )
+ job_offer.submit()
+
+ employee = make_employee(job_offer.name)
+ employee.date_of_birth = "1990-05-08"
+ employee.date_of_joining = nowdate()
+ employee.gender = "Female"
+ employee.insert()
+
+ job_offer.reload()
+ self.assertEqual(job_offer.status, "Rejected")
+
+ def test_rejected_job_offer_does_not_accept_job_applicant(self):
+ frappe.db.set_single_value("HR Settings", "check_vacancies", 0)
+ job_applicant = create_job_applicant(email_id="rejected_sync@example.com")
+ job_offer = create_job_offer(job_applicant=job_applicant.name, status="Rejected")
+ job_offer.submit()
+
+ update_job_applicant_and_offer(frappe._dict({"job_applicant": job_applicant.name}))
+
+ job_applicant.reload()
+ job_offer.reload()
+ self.assertEqual(job_offer.status, "Rejected")
+ self.assertEqual(job_applicant.status, "Rejected")
+
+ def test_reoffered_applicant_accepts_live_job_offer(self):
+ frappe.db.set_single_value("HR Settings", "check_vacancies", 0)
+ job_applicant = create_job_applicant(email_id="reoffered_pick@example.com")
+
+ rejected = create_job_offer(job_applicant=job_applicant.name, status="Rejected")
+ rejected.submit()
+ live = create_job_offer(job_applicant=job_applicant.name, status="Awaiting Response")
+ live.save()
+
+ update_job_applicant_and_offer(frappe._dict({"job_applicant": job_applicant.name}))
+
+ live.reload()
+ rejected.reload()
+ self.assertEqual(live.status, "Accepted")
+ self.assertEqual(rejected.status, "Rejected")
+
def create_job_offer(**args):
args = frappe._dict(args)
- if not args.job_applicant:
- job_applicant = create_job_applicant()
+ if not args.job_applicant and not args.applicant_email:
+ args.job_applicant = create_job_applicant().name
if not frappe.db.exists("Designation", args.designation):
create_designation(designation_name=args.designation)
@@ -86,7 +221,7 @@ def create_job_offer(**args):
job_offer = frappe.get_doc(
{
"doctype": "Job Offer",
- "job_applicant": args.job_applicant or job_applicant.name,
+ "job_applicant": args.job_applicant,
"offer_date": args.offer_date or nowdate(),
"designation": args.designation or "Researcher",
"status": args.status or "Accepted",
diff --git a/hrms/overrides/employee_master.py b/hrms/overrides/employee_master.py
index 067a42e07ac..2e0e65f4761 100644
--- a/hrms/overrides/employee_master.py
+++ b/hrms/overrides/employee_master.py
@@ -30,17 +30,18 @@ def autoname(self):
def validate_onboarding_process(doc, method=None):
"""Validates Employee Creation for linked Employee Onboarding"""
- if not doc.job_applicant:
+ job_applicant = doc.get("job_applicant")
+ job_offer = doc.get("job_offer")
+
+ filters = {"docstatus": 1, "boarding_status": ("!=", "Completed")}
+ if job_offer:
+ filters["job_offer"] = job_offer
+ elif job_applicant:
+ filters["job_applicant"] = job_applicant
+ else:
return
- employee_onboarding = frappe.get_all(
- "Employee Onboarding",
- filters={
- "job_applicant": doc.job_applicant,
- "docstatus": 1,
- "boarding_status": ("!=", "Completed"),
- },
- )
+ employee_onboarding = frappe.get_all("Employee Onboarding", filters=filters)
if employee_onboarding:
onboarding = frappe.get_doc("Employee Onboarding", employee_onboarding[0].name)
onboarding.validate_employee_creation()
@@ -55,36 +56,59 @@ def publish_update(doc, method=None):
def update_job_applicant_and_offer(doc, method=None):
"""Updates Job Applicant and Job Offer status as 'Accepted' and submits them"""
- if not doc.job_applicant:
- return
+ job_applicant = doc.get("job_applicant")
+ job_offer = get_linked_job_offer(doc, job_applicant)
- applicant_status_before_change = frappe.db.get_value("Job Applicant", doc.job_applicant, "status")
- if applicant_status_before_change != "Accepted":
- frappe.db.set_value("Job Applicant", doc.job_applicant, "status", "Accepted")
+ if job_offer and job_offer.status in ("Rejected", "Cancelled"):
frappe.msgprint(
- _("Updated the status of linked Job Applicant {0} to {1}").format(
- get_link_to_form("Job Applicant", doc.job_applicant), frappe.bold(_("Accepted"))
- )
+ _(
+ "Linked Job Offer {0} was {1}. Please update the Job Offer status if this hire was intended."
+ ).format(get_link_to_form("Job Offer", job_offer.name), frappe.bold(_(job_offer.status))),
+ title=_("Job Offer Status Not Updated"),
+ indicator="orange",
)
- offer_status_before_change = frappe.db.get_value(
- "Job Offer", {"job_applicant": doc.job_applicant, "docstatus": ["!=", 2]}, "status"
+ return
+
+ if job_applicant:
+ applicant_status_before_change = frappe.db.get_value("Job Applicant", job_applicant, "status")
+ if applicant_status_before_change != "Accepted":
+ frappe.db.set_value("Job Applicant", job_applicant, "status", "Accepted")
+ frappe.msgprint(
+ _("Updated the status of linked Job Applicant {0} to {1}").format(
+ get_link_to_form("Job Applicant", job_applicant), frappe.bold(_("Accepted"))
+ )
+ )
+
+ if not job_offer or job_offer.status == "Accepted":
+ return
+
+ job_offer.status = "Accepted"
+ job_offer.flags.ignore_mandatory = True
+ job_offer.flags.ignore_permissions = True
+ job_offer.save()
+
+ msg = _("Updated the status of Job Offer {0} for {1} to {2}").format(
+ get_link_to_form("Job Offer", job_offer.name),
+ frappe.bold(job_offer.applicant_name),
+ frappe.bold(_("Accepted")),
)
- if offer_status_before_change and offer_status_before_change != "Accepted":
- job_offer = frappe.get_last_doc("Job Offer", filters={"job_applicant": doc.job_applicant})
- job_offer.status = "Accepted"
- job_offer.flags.ignore_mandatory = True
- job_offer.flags.ignore_permissions = True
- job_offer.save()
-
- msg = _("Updated the status of Job Offer {0} for the linked Job Applicant {1} to {2}").format(
- get_link_to_form("Job Offer", job_offer.name),
- frappe.bold(doc.job_applicant),
- frappe.bold(_("Accepted")),
+ if job_offer.docstatus == 0:
+ msg += "
" + _("You may add additional details, if any, and submit the offer.")
+
+ frappe.msgprint(msg)
+
+
+def get_linked_job_offer(doc, job_applicant: str | None):
+ offer_name = doc.get("job_offer")
+ if not offer_name and job_applicant:
+ offer_name = frappe.db.get_value(
+ "Job Offer", {"job_applicant": job_applicant, "docstatus": ["!=", 2]}, "name"
)
- if job_offer.docstatus == 0:
- msg += "
" + _("You may add additional details, if any, and submit the offer.")
+ if not offer_name:
+ return None
- frappe.msgprint(msg)
+ job_offer = frappe.get_doc("Job Offer", offer_name)
+ return None if job_offer.docstatus == 2 else job_offer
def update_approver_role(doc, method=None):
diff --git a/hrms/patches.txt b/hrms/patches.txt
index 87f17d1d54d..0446b7d0de4 100644
--- a/hrms/patches.txt
+++ b/hrms/patches.txt
@@ -51,3 +51,4 @@ hrms.patches.v16_0.update_partially_paid_employee_advance_status
hrms.patches.v16_0.delete_upload_attendance_doctype #2026-07-16
hrms.patches.v16_0.set_leave_approver_name_in_leave_application #2026-08-05
hrms.patches.v16_0.set_job_applicant_kanban_column_indicators #2026-08-12
+hrms.patches.v16_0.set_job_offer_in_employee
diff --git a/hrms/patches/v16_0/set_job_offer_in_employee.py b/hrms/patches/v16_0/set_job_offer_in_employee.py
new file mode 100644
index 00000000000..839dc9f66c1
--- /dev/null
+++ b/hrms/patches/v16_0/set_job_offer_in_employee.py
@@ -0,0 +1,45 @@
+import frappe
+from frappe import _
+from frappe.custom.doctype.custom_field.custom_field import create_custom_fields
+
+
+def execute():
+ create_custom_fields(
+ {
+ "Employee": [
+ {
+ "fieldname": "job_applicant",
+ "fieldtype": "Link",
+ "label": _("Job Applicant"),
+ "options": "Job Applicant",
+ "insert_after": "employment_details",
+ "depends_on": "eval:doc.job_applicant",
+ "read_only": 1,
+ },
+ {
+ "fieldname": "job_offer",
+ "fieldtype": "Link",
+ "label": _("Job Offer"),
+ "options": "Job Offer",
+ "insert_after": "job_applicant",
+ "depends_on": "eval:doc.job_offer",
+ "read_only": 1,
+ },
+ ]
+ }
+ )
+
+ set_job_offer_in_employee()
+
+
+def set_job_offer_in_employee():
+ employees = frappe.get_all(
+ "Employee", filters={"job_applicant": ["is", "set"]}, fields=["name", "job_applicant"]
+ )
+
+ for employee in employees:
+ job_offer = frappe.db.get_value(
+ "Job Offer", {"job_applicant": employee.job_applicant, "docstatus": ["!=", 2]}, "name"
+ )
+ if job_offer:
+ frappe.db.set_value("Employee", employee.name, "job_offer", job_offer, update_modified=False)
diff --git a/hrms/public/js/setup_wizard.js b/hrms/public/js/setup_wizard.js
new file mode 100644
index 00000000000..65aea4c9f6e
--- /dev/null
+++ b/hrms/public/js/setup_wizard.js
@@ -0,0 +1,145 @@
+frappe.provide("hrms.setup");
+
+frappe.setup.on("before_load", function () {
+ if (
+ frappe.boot.setup_wizard_completed_apps?.length &&
+ frappe.boot.setup_wizard_completed_apps.includes("hrms")
+ ) {
+ return;
+ }
+
+ if (!frappe.boot.hr_only_setup) return;
+
+ // HR-only site: show the HR persona in place of the ERPNext one
+ const persona_index = frappe.setup.slides.findIndex((slide) => slide.name === "persona");
+ if (persona_index >= 0) {
+ frappe.setup.slides.splice(persona_index, 1, ...hrms.setup.slides_settings);
+ } else {
+ hrms.setup.slides_settings.map(frappe.setup.add_slide);
+ }
+});
+
+hrms.setup.slides_settings = [
+ {
+ // Persona — help us tailor the setup
+ name: "hr_persona",
+ title: __("A little about you"),
+ // subtitle shown under the title
+ help: __("A few quick questions so we can set things up the way you work."),
+ fields: [
+ {
+ fieldname: "persona_implementing_for",
+ label: __("Who are you setting this up for?"),
+ fieldtype: "Select",
+ options: [
+ "",
+ "My own business",
+ "A company I work for",
+ "A client I'm consulting for",
+ ].join("\n"),
+ reqd: 1,
+ },
+ {
+ fieldname: "persona_company_size",
+ label: __("How many employees do you have?"),
+ fieldtype: "Select",
+ options: ["", "1–10", "11–50", "51–200", "201–1,000", "1,000+"].join("\n"),
+ reqd: 1,
+ },
+ {
+ fieldname: "persona_industry",
+ label: __("What kind of work do you do?"),
+ fieldtype: "Select",
+ options: [
+ "",
+ "Manufacturing",
+ "Retail",
+ "Wholesale / Distribution",
+ "E-commerce",
+ "Services / Consulting",
+ "Construction / Real Estate",
+ "Technology / Software",
+ "Healthcare",
+ "Education",
+ "Agriculture",
+ "Food & Beverage",
+ "Non Profit",
+ "Other",
+ ].join("\n"),
+ reqd: 1,
+ },
+ {
+ fieldname: "persona_current_system",
+ label: __("What do you use for HR today?"),
+ fieldtype: "Select",
+ options: [
+ "",
+ "Keka",
+ "GreytHR",
+ "Zoho People",
+ "Darwinbox",
+ "BambooHR",
+ "Workday",
+ "SAP SuccessFactors",
+ "Excel / Spreadsheets",
+ "Nothing yet - starting fresh",
+ "Other",
+ ].join("\n"),
+ reqd: 1,
+ },
+ {
+ fieldtype: "Section Break",
+ description: __("Select the modules that you plan to implement"),
+ },
+ {
+ fieldname: "module_leave_attendance",
+ label: __("Leave & Attendance"),
+ fieldtype: "Check",
+ },
+ { fieldname: "module_payroll", label: __("Payroll"), fieldtype: "Check" },
+ { fieldtype: "Column Break" },
+ { fieldname: "module_recruitment", label: __("Recruitment"), fieldtype: "Check" },
+ {
+ fieldname: "module_performance",
+ label: __("Performance Management"),
+ fieldtype: "Check",
+ },
+ ],
+
+ onload: function (slide) {
+ this.bind_company_size_modules(slide);
+ },
+
+ bind_company_size_modules: function (slide) {
+ let me = this;
+ slide.get_input("persona_company_size").on("change", function () {
+ me.apply_company_size_modules(slide);
+ });
+ },
+
+ apply_company_size_modules: function (slide) {
+ let company_size = slide.get_field("persona_company_size").get_value();
+ let modules = hrms.setup.company_size_modules[company_size] || [
+ "leave_attendance",
+ "payroll",
+ ];
+ ["leave_attendance", "payroll", "recruitment", "performance"].forEach(
+ function (module) {
+ slide
+ .get_field("module_" + module)
+ .set_value(modules.includes(module) ? 1 : 0);
+ },
+ );
+ },
+ },
+];
+
+// Modules pre-selected on the persona slide based on the team size.
+// Keys must match the persona_company_size option values. Leave & Attendance and Payroll are always on.
+hrms.setup.company_size_modules = {
+ "1–10": ["leave_attendance", "payroll"],
+ "11–50": ["leave_attendance", "payroll", "recruitment"],
+ "51–200": ["leave_attendance", "payroll", "recruitment", "performance"],
+ "201–1,000": ["leave_attendance", "payroll", "recruitment", "performance"],
+ "1,000+": ["leave_attendance", "payroll", "recruitment", "performance"],
+};
diff --git a/hrms/setup.py b/hrms/setup.py
index 37d36068718..3140a326074 100644
--- a/hrms/setup.py
+++ b/hrms/setup.py
@@ -251,6 +251,17 @@ def get_custom_fields():
"label": _("Job Applicant"),
"options": "Job Applicant",
"insert_after": "employment_details",
+ "depends_on": "eval:doc.job_applicant",
+ "read_only": 1,
+ },
+ {
+ "fieldname": "job_offer",
+ "fieldtype": "Link",
+ "label": _("Job Offer"),
+ "options": "Job Offer",
+ "insert_after": "job_applicant",
+ "depends_on": "eval:doc.job_offer",
+ "read_only": 1,
},
{
"fieldname": "grade",
diff --git a/hrms/setup_wizard.py b/hrms/setup_wizard.py
new file mode 100644
index 00000000000..0ee9d17dd26
--- /dev/null
+++ b/hrms/setup_wizard.py
@@ -0,0 +1,71 @@
+import frappe
+from frappe import _
+from frappe.utils.telemetry import capture
+
+
+def get_setup_stages(wizard_args=None):
+ if not frappe.conf.sk_hrms:
+ return []
+
+ return [
+ {
+ "status": _("Personalizing your setup"),
+ "fail_msg": _("Failed to personalize your setup"),
+ "tasks": [
+ {
+ "fn": capture_user_persona,
+ "args": persona_from_wizard_args(wizard_args) if wizard_args else None,
+ "fail_msg": _("Failed to personalize your setup"),
+ }
+ ],
+ }
+ ]
+
+
+# The exact property set of the `user_persona_submitted` event. The wizard
+# runner mutates task args on resumed setups (`set_missing_values`), so the
+# event is pinned to these fields instead of whatever the payload accumulates.
+PERSONA_FIELDS = (
+ "implementing_for",
+ "company_size",
+ "industry",
+ "current_system",
+ "module_leave_attendance",
+ "module_payroll",
+ "module_recruitment",
+ "module_performance",
+ "country",
+ "language",
+)
+
+
+def persona_from_wizard_args(wizard_args: dict) -> dict:
+ """Narrow the raw wizard payload to the fields the persona event reports."""
+ return {
+ "implementing_for": wizard_args.get("persona_implementing_for"),
+ "company_size": wizard_args.get("persona_company_size"),
+ "industry": wizard_args.get("persona_industry"),
+ "current_system": wizard_args.get("persona_current_system"),
+ "module_leave_attendance": bool(wizard_args.get("module_leave_attendance")),
+ "module_payroll": bool(wizard_args.get("module_payroll")),
+ "module_recruitment": bool(wizard_args.get("module_recruitment")),
+ "module_performance": bool(wizard_args.get("module_performance")),
+ "country": wizard_args.get("country"),
+ "language": wizard_args.get("language"),
+ }
+
+
+def capture_user_persona(persona: dict | None):
+ """Send the persona answers captured on the setup slide to telemetry.
+
+ The wizard runner calls every task as ``fn(task["args"])``, so this takes the
+ narrowed payload from ``persona_from_wizard_args``, never the raw wizard args.
+ """
+ if not persona:
+ return
+
+ capture(
+ "user_persona_submitted",
+ "hrms",
+ properties={field: persona.get(field) for field in PERSONA_FIELDS},
+ )
diff --git a/hrms/telemetry.py b/hrms/telemetry.py
index fe0f7e27b53..15f93556da6 100644
--- a/hrms/telemetry.py
+++ b/hrms/telemetry.py
@@ -26,6 +26,7 @@ def capture(event: str, properties: dict | None = None) -> None:
return
_capture(event, APP, properties=properties or {})
+ _track_conversion()
MILESTONE_DOCTYPE = "HR Telemetry Milestone"
@@ -55,6 +56,40 @@ def capture_first(event: str, properties: dict | None = None) -> None:
capture(event, {"day_since_install": age, **(properties or {})})
+# ---- Conversion --------------------------------------------------------------
+# A site counts as converted once it is still producing usage events more than
+# 14 days after its first capture. The `first_capture` milestone is pure
+# bookkeeping (never sent), its creation timestamp starts the clock.
+
+CONVERSION_WINDOW_DAYS = 14
+FIRST_CAPTURE_MILESTONE = "first_capture"
+CONVERSION_EVENT = "site_converted"
+
+
+def _track_conversion() -> None:
+ if frappe.db.exists(MILESTONE_DOCTYPE, CONVERSION_EVENT):
+ return
+
+ first_capture = frappe.db.get_value(MILESTONE_DOCTYPE, FIRST_CAPTURE_MILESTONE, "creation")
+ if not first_capture:
+ _claim_milestone(FIRST_CAPTURE_MILESTONE)
+ return
+
+ days_since_first_capture = date_diff(today(), first_capture)
+ if days_since_first_capture <= CONVERSION_WINDOW_DAYS:
+ return
+
+ if _claim_milestone(CONVERSION_EVENT):
+ _capture(
+ CONVERSION_EVENT,
+ APP,
+ properties={
+ "days_since_first_capture": days_since_first_capture,
+ "day_since_install": site_age(),
+ },
+ )
+
+
def _duration_days(from_date, to_date) -> int | None:
if not (from_date and to_date):
return None
@@ -242,9 +277,11 @@ def capture_daily_attendance_pulse():
def rate(n):
return round(n / active_employees, 3)
- capture(
+ # Scheduler output, not usage: bypass `capture` so it never drives conversion.
+ _capture(
"attendance_daily_summary",
- {
+ APP,
+ properties={
"active_employees": active_employees,
"checkins": checkins,
"employees_checked_in": employees_checked_in,
diff --git a/hrms/tests/test_telemetry.py b/hrms/tests/test_telemetry.py
index c991e1a4282..a366a9538ea 100644
--- a/hrms/tests/test_telemetry.py
+++ b/hrms/tests/test_telemetry.py
@@ -3,7 +3,14 @@
import frappe
from frappe.utils import add_days, getdate
-from hrms.telemetry import MILESTONE_DOCTYPE, _claim_milestone, capture_daily_attendance_pulse
+from hrms.telemetry import (
+ CONVERSION_EVENT,
+ FIRST_CAPTURE_MILESTONE,
+ MILESTONE_DOCTYPE,
+ _claim_milestone,
+ capture,
+ capture_daily_attendance_pulse,
+)
from hrms.tests.utils import HRMSTestSuite
# A fixed Wednesday. The daily pulse reads the clock and summarises the day
@@ -75,6 +82,18 @@ def telemetry_enabled(self):
def release_milestone(self, event: str):
frappe.db.delete(MILESTONE_DOCTYPE, {"event": event})
+ def start_conversion_clock(self, days_ago: int):
+ """Reset both conversion milestones and backdate `first_capture`."""
+ self.release_milestone(CONVERSION_EVENT)
+ self.release_milestone(FIRST_CAPTURE_MILESTONE)
+ frappe.get_doc({"doctype": MILESTONE_DOCTYPE, "event": FIRST_CAPTURE_MILESTONE}).insert()
+ frappe.db.set_value(
+ MILESTONE_DOCTYPE,
+ FIRST_CAPTURE_MILESTONE,
+ "creation",
+ f"{add_days(FROZEN_TODAY, -days_ago)} 10:00:00",
+ )
+
def reset_checkins(self):
"""The pulse counts site-wide, so leftover rows on the frozen dates would
let a wrong day coincidentally match the right one."""
@@ -180,6 +199,67 @@ def test_milestone_skipped_outside_activation_window(self):
self.assertEqual(self.events("leave_type_configured"), [])
+ # ---- conversion ----
+
+ def test_first_capture_starts_the_clock_without_firing_an_event(self):
+ self.release_milestone(CONVERSION_EVENT)
+ self.release_milestone(FIRST_CAPTURE_MILESTONE)
+
+ capture("_test_usage")
+
+ self.assertTrue(frappe.db.exists(MILESTONE_DOCTYPE, FIRST_CAPTURE_MILESTONE))
+ self.assertEqual(self.events(CONVERSION_EVENT), [])
+ self.assertEqual(self.events(FIRST_CAPTURE_MILESTONE), [])
+
+ def test_no_conversion_within_fourteen_days_of_first_capture(self):
+ self.start_conversion_clock(days_ago=14)
+
+ capture("_test_usage")
+
+ self.assertEqual(self.events(CONVERSION_EVENT), [])
+
+ def test_usage_beyond_fourteen_days_converts_the_site(self):
+ self.start_conversion_clock(days_ago=15)
+
+ capture("_test_usage")
+
+ conversions = self.events(CONVERSION_EVENT)
+ self.assertEqual(len(conversions), 1)
+ self.assertEqual(conversions[0]["days_since_first_capture"], 15)
+ self.assertEqual(conversions[0]["day_since_install"], 3)
+
+ def test_conversion_fires_only_once_per_site(self):
+ self.start_conversion_clock(days_ago=30)
+
+ for _ in range(3):
+ capture("_test_usage")
+
+ self.assertEqual(len(self.events(CONVERSION_EVENT)), 1)
+
+ def test_daily_pulse_does_not_start_the_conversion_clock(self):
+ """The pulse is scheduler output, not usage: a site that set up employees
+ and walked away would otherwise convert on cron activity alone."""
+ # Created first: the Employee insert hook is itself usage and would
+ # stamp `first_capture` before the pulse gets a chance to.
+ create_employee(f"_Test Pulse {frappe.generate_hash(length=8)}")
+ self.release_milestone(CONVERSION_EVENT)
+ self.release_milestone(FIRST_CAPTURE_MILESTONE)
+
+ with self.telemetry_enabled():
+ capture_daily_attendance_pulse()
+
+ self.assertEqual(len(self.events("attendance_daily_summary")), 1)
+ self.assertFalse(frappe.db.exists(MILESTONE_DOCTYPE, FIRST_CAPTURE_MILESTONE))
+
+ def test_daily_pulse_does_not_convert_the_site(self):
+ create_employee(f"_Test Pulse {frappe.generate_hash(length=8)}")
+ self.start_conversion_clock(days_ago=15)
+
+ with self.telemetry_enabled():
+ capture_daily_attendance_pulse()
+
+ self.assertEqual(self.events(CONVERSION_EVENT), [])
+
# ---- the claim is atomic ----
def test_claim_is_exclusive(self):
diff --git a/hrms/utils/__init__.py b/hrms/utils/__init__.py
index e053c3d552e..d2cf58f3964 100644
--- a/hrms/utils/__init__.py
+++ b/hrms/utils/__init__.py
@@ -60,3 +60,7 @@ def get_employee_email(employee_id: str) -> str | None:
or employee_emails.company_email
or employee_emails.personal_email
)
+
+
+def extend_bootinfo(bootinfo):
+ bootinfo.hr_only_setup = bool(frappe.conf.sk_hrms)