US-302: Define Custom Employee Fields¶

1. Story Title¶

HR defines custom profile fields with validation

2. Context / Background¶

Employee data needs flexible extension for company-specific attributes.

3. User Persona¶

Primary: Priya – HR Manager Secondary: Mark – Employee (consumer of fields)

4. Problem Statement¶

Static schema cannot accommodate diverse data tracking; leads to off-platform spreadsheets.

5. Desired Outcome¶

HR adds custom fields (label, type, required) and they appear on employee profiles for viewing/edit (based on permissions).

6. Business Value¶

Enables adaptability without engineering intervention; increases platform stickiness.

7. Scope (In / Out)¶

In: text, number, date, dropdown (static options) field types; required flag; simple validation. Out: Nested objects, conditional visibility, formula fields.

8. Acceptance Criteria (BDD)¶

Scenario: Create custom field
  Given HR opens custom field admin
  When she adds field "Shirt Size" type dropdown with options
  Then field is saved
  And appears on employee profile edit form

Scenario: Required field validation
  Given field "Employee Code" is required
  When HR saves profile without value
  Then validation error displayed

Scenario: Delete custom field
  Given a custom field exists
  When HR deletes it
  Then it no longer appears on profile
  And data for that field becomes inaccessible (soft-deleted)

Scenario: Type-specific validation
  Given a number field "Years Experience"
  When HR enters non-numeric text
  Then validation error appears

9. UX Notes / References¶

Admin list with add/edit drawer; field grouping below standard fields in profile.

10. Data / Domain Model Impact¶

CustomField definition entity; EmployeeFieldValue linking employeeId + fieldId + value.

11. NFR Touchpoints¶

Performance: profile load with 10 custom fields < 500ms.
Security: prevent injection via dropdown options sanitation.
Observability: field definition CRUD events.

12. Dependencies¶

Employee base profile (US-301).

13. Risks & Mitigations¶

Risk	Impact	Probability	Mitigation
Field proliferation harming performance	Slow profiles	Medium	Hard limit initial (e.g., 25) + monitoring
Invalid option data causing UI injection	Security	Low	Escape & validate options

14. Estimation Support¶

Definition model CRUD
Value storage
UI admin
Profile integration

15. Analytics / Success Metrics¶

Custom fields per tenant; usage frequency; required field completion rate.

16. Rollout / Release Strategy¶

Limit types to text/number/date first; add dropdown next.

17. Definition of Ready Checklist¶

Allowed types finalized
Limits agreed

18. Definition of Done Checklist¶

CRUD + validation tests
Docs updated

19. Open Questions¶

Need ordering / grouping controls?
Editable by employee or HR-only toggle per field?

Version: 1.0