I’m considering the next feature for frappe_hr_self_service: employee self-enrollment leading into first login.
The interesting part is that organizations may already have partial data:
neither Employee nor User exists
Employee exists, but User does not
User exists, but Employee does not
both exist but are not linked
both already exist and are linked
existing records conflict or are ambiguous
Rather than treating this as simple “self-registration”, I’m proposing a staged flow:
HR invitation
↓
Employee registration
↓
HR review
↓
Reconcile existing Employee/User records
↓
Create or link only what is missing
↓
First login
Ambiguous cases would stop for HR review rather than automatically creating or relinking records.
I’ve written up the proposed state matrix, trust boundary and first milestone in GitHub Issue #6:
opened 06:26AM - 08 Oct 26 UTC
## Goal
Add a generic employee enrollment and account-provisioning workflow to … `frappe_hr_self_service`.
The target user is a real employee who may not yet have a usable Frappe self-service identity. Depending on the organization's existing data, any of these states may already exist:
- neither Employee nor User exists;
- Employee exists but User does not;
- User exists but Employee does not;
- Employee and User both exist but are not linked;
- Employee and User already exist and are linked;
- existing records conflict or are ambiguous.
The feature should safely reconcile those states instead of assuming that every registrant starts from zero.
## Design direction
The first version should use a staged workflow rather than allowing an unauthenticated person to create an `Employee` directly.
```text
HR invitation
↓
Employee registration
↓
HR review / approval
↓
Identity-state classification
↓
Create or link Employee and User
↓
First login
```
The registration record is a staging record. Frappe HR remains authoritative for the Employee master, and Frappe remains authoritative for User authentication.
## Identity-state matrix
| Existing Employee | Existing User | Expected action |
| --- | --- | --- |
| No | No | Create Employee and User, then link them |
| Yes | No | Use existing Employee, create User, then link |
| No | Yes | Use existing User, create Employee, then link |
| Yes | Yes, not linked | Reconcile and link after HR verification |
| Yes | Yes, already linked | Do not create duplicates; optionally update approved profile fields |
| Ambiguous/conflicting | Any | Stop and require HR review |
Automatic provisioning must be idempotent: repeating an approval or provisioning action must not create duplicate Employee or User records.
## Trust boundary
Employee-provided information may include fields such as:
- first / middle / last name;
- date of birth;
- gender;
- mobile number;
- address;
- emergency contact.
Trusted organizational fields should come from the invitation or HR review, not from an unauthenticated browser. Examples include:
- Company;
- employee number;
- department;
- designation;
- date of joining;
- employment type;
- reports-to relationship;
- leave approver;
- roles and permissions.
Email may be used to locate candidate records, but email alone should not be sufficient evidence to automatically link an existing Employee and User when identity is uncertain.
## Proposed states
Enrollment status:
```text
Invited
Submitted
Under Review
Approved
Rejected
Expired
```
Provisioning result:
```text
Not Started
Employee and User Created
Existing Employee - User Created
Existing User - Employee Created
Existing Records Linked
Already Provisioned
Requires Review
Failed
```
The registration should retain references to the resulting `Employee` and `User` records for auditability.
## Suggested internal separation
Keep enrollment/provisioning independent of the existing leave implementation so it can be extracted later if needed.
A possible module boundary:
```text
employee_enrollment/
invitation.py
registration.py
identity.py
provisioning.py
permissions.py
```
Conceptually, the provisioning layer should expose operations such as:
```text
resolve_employee()
resolve_user()
classify_identity_state()
provision()
```
with outcomes such as:
```text
CREATE_BOTH
CREATE_USER
CREATE_EMPLOYEE
LINK_EXISTING
ALREADY_LINKED
REQUIRES_REVIEW
```
## First milestone
Keep the first vertical slice intentionally small:
1. HR creates an invitation.
2. Recipient submits a registration form.
3. HR reviews and approves it.
4. The system classifies the existing Employee/User state.
5. The system creates or links only the missing records.
6. The resulting User can complete first login and use self-service.
Explicitly defer, for now:
- document uploads;
- bank details;
- government-ID fields;
- employee profile self-editing after provisioning;
- complex onboarding checklists;
- organization-specific approval policy.
## Questions for design review
- Should invitation and registration be separate DocTypes, or should one registration record carry the invitation token/state?
- Should the first implementation use Frappe Web Form Request for the invitation link?
- Which Employee fields are safe to let the registrant propose, and which must remain HR-controlled?
- What exact matching rules should be used before a case is classified as `REQUIRES_REVIEW`?
- Which standard Frappe mechanisms should be used for User creation, password setup, roles and first-login routing?
- Which parts should remain extensible so organization-specific rules can stay outside the reusable core?
## Acceptance direction
The feature should never silently create duplicate Employee or User records and should never automatically relink an Employee from one User to another when there is a conflict. Ambiguous identity cases must stop for HR review.
The reusable app should provide the generic enrollment/reconciliation/provisioning machinery. Organization-specific fields, business rules, branding and approval policy should remain in the organization's own custom app.
Employee self-enrollment and account provisioning
I’d particularly appreciate feedback from people who have implemented something similar:
How are you currently handling Employee ↔ User provisioning and reconciliation?
Are there existing Frappe/HRMS mechanisms we should reuse instead of building new ones?
Would an invitation-based flow be useful in your deployments, or do you generally need completely open self-registration?
Feedback on edge cases we haven’t considered would be especially useful.
Reviving this thread because our team is currently tackling this exact onboarding challenge. Did the core team make any headway on integrating Microsoft 365 or Google Workspace for automated email provisioning? Also, I would love to know how others handle document rejection loops without completely stalling the process. Any updates from recent releases or custom setups would be super helpful.