HR Workflows

This page describes the business process workflows implemented in BonardaHR, covering state machines, permissions, business rules, and side effects for each workflow.

---

Summary

Workflow	Initial State	Terminal States	Approval Required	Key Side Effects
Time Off	PENDING	APPROVED, REJECTED, CANCELLED	Yes (manager)	Balance update, calendar event, email
Timesheet	DRAFT	APPROVED	Yes (manager)	Hours recalculation, email reminders
Document Signing	PENDING	SIGNED, DECLINED	No (self-service)	Forensic audit trail
Employee Lifecycle	ACTIVE	TERMINATED	No (HR action)	Soft delete, cancel time-off

---

1. Time-Off Request Workflow

Status States

Status	Description	Transitions
PENDING	Initial state after creation	Employee can cancel; Manager/HR can approve or reject
APPROVED	Request granted	Employee can cancel
REJECTED	Request denied	Terminal state
CANCELLED	Cancelled by employee	Terminal state

State Diagram

[Employee Creates Request]
          |
          v
      PENDING ──────────────────────────────────────┐
         │                                           │
         ├── [Employee Cancel] ──────────────────> CANCELLED
         │
         ├── [Manager Approve] ──> APPROVED
         │                              │
         │                              └── [Employee Cancel] ──> CANCELLED
         │
         └── [Manager Reject] ───> REJECTED

Permissions

Action	Permission	Roles
Create request	TIME_OFF_REQUEST_CREATE	All employees
View own requests	TIME_OFF_REQUEST_READ_OWN	All employees
View team requests	TIME_OFF_REQUEST_READ_TEAM	MANAGER
View all requests	TIME_OFF_REQUEST_READ_ALL	HR_MANAGER, ADMIN
Approve / Reject	TIME_OFF_REQUEST_APPROVE	MANAGER, HR_MANAGER, ADMIN

Business Rules

Request Creation

• Validates that end_date >= start_date
• Half-day requests must be a single day with a MORNING or AFTERNOON period
• Calculates business days (weekdays only)
• Checks for overlapping PENDING or APPROVED requests
• Validates sufficient balance (unless type is unlimited)
• Deducts from pending balance immediately on creation

Approval

• Reviewer cannot be the requesting employee
• Moves pending balance to used
• Creates Outlook calendar event (if Microsoft integration is enabled)

Rejection

• Returns the pending balance to available

Cancellation

• Only PENDING or APPROVED requests can be cancelled
• Only the requesting employee can cancel
• Returns balance (pending or used) to available
• Deletes the Outlook calendar event if the request was APPROVED

Attachment Requirements

Time-off types can require supporting documents:

Requirement	Behaviour
NEVER	No attachment needed
ALWAYS	Attachment always required
CONDITIONAL	Required if business_days > attachmentRequiredAfterDays

Side Effects

Event	Side Effect
Request created	Manager receives email notification
Request reviewed	Employee receives email with decision
Request approved	Outlook calendar event created
Request cancelled (if approved)	Outlook calendar event deleted

---

2. Timesheet Workflow

Status States

Status	Description	Transitions
DRAFT	Created but not submitted	Employee can edit and submit
SUBMITTED	Awaiting manager review	Manager can approve or reject
APPROVED	Accepted by manager	Terminal state
REJECTED	Returned for corrections	Employee can edit and resubmit

State Diagram

[Employee Creates Timesheet]
          |
          v
        DRAFT
         │
         ├── [Edit Entries / Clock In/Out]
         │
         └── [Submit] ──────> SUBMITTED
                                   │
                                   ├── [Approve] ──> APPROVED
                                   │
                                   └── [Reject] ───> REJECTED
                                                       │
                                                       └── [Edit & Resubmit] ──> SUBMITTED

Permissions

Action	Permission	Roles
Create / Edit / Submit	TIMESHEET_CREATE	All employees
Clock In / Out	TIMESHEET_CREATE	All employees
View own timesheets	TIMESHEET_READ_OWN	All employees
View team timesheets	TIMESHEET_READ_TEAM	MANAGER
View all timesheets	TIMESHEET_READ_ALL	HR_MANAGER, ADMIN
Approve / Reject	TIMESHEET_APPROVE	MANAGER, HR_MANAGER, ADMIN

Business Rules

Edit Window

• Employees can edit the current week and the 2 preceding weeks
• Future timesheets cannot be created
• Timesheets older than 2 weeks are locked

Clock In / Out

• Clock-in records the current timestamp
• Clock-out calculates hours: (clockOut - clockIn) / 60, rounded to nearest 0.5
• Automatically creates a timesheet entry for today if one does not exist

Submission

• Only DRAFT or REJECTED timesheets can be submitted
• Must have at least one time entry
• Must be within the edit window

Review

• Reviewer cannot be the submitting employee
• REJECTED timesheets return to an editable DRAFT-equivalent state

Side Effects

• Total hours recalculated after each entry change
• Email reminders sent for overdue (unsubmitted) timesheets

---

3. Document Signing Workflow

Status States

Status	Description	Final?
PENDING	Awaiting employee action	No
SIGNED	Employee signed	Yes
DECLINED	Employee declined	Yes

State Diagram

[HR Requests Signatures]
          |
          v
      PENDING
         │
         ├── [Sign] ──────> SIGNED
         │
         └── [Decline] ───> DECLINED

Permissions

Action	Permission	Roles
Share document / request signatures	DOCUMENT_SHARE	HR_MANAGER, ADMIN
Sign own signature request	DOCUMENT_SIGN_OWN	All employees
View signature status	DOCUMENT_SIGN_READ	HR_MANAGER, ADMIN

Business Rules

Requesting Signatures

• The document must have requiresSignature = true
• Creates a document share if the employee does not already have access
• Creates a PENDING signature record for each target employee

Signing

• Only PENDING signatures can be signed
• An employee can only sign their own signature request
• Captures: signature data, timestamp, IP address, user agent

Declining

• Only PENDING signatures can be declined
• Employee must provide a decline reason
• Immutable after declining

Forensic Audit Trail

Each signed or declined record captures:

Field	Description
Signature data	Digital signature content
Timestamp	Exact moment of signing or declining
IP address	Client IP at time of action
User agent	Browser and device info
Decline reason	Mandatory if declined

---

4. Employee Lifecycle Workflow

Status States

Status	Description	System Access
ACTIVE	Currently employed	Full access
ON_LEAVE	Has approved time-off today (computed)	Read-only display state
INACTIVE	Temporarily suspended	No access
TERMINATED	Left company	No access

State Diagram

[Create Employee]
          |
          v
      ACTIVE ◄────────────────────────────────────┐
         │                                         │
         ├── [Approved Time-Off Today] ──> ON_LEAVE ┘
         │                                  (computed, not stored)
         │
         ├── [Deactivate] ────────────────> INACTIVE
         │                                      │
         │   ┌────────── [Reactivate] ──────────┘
         │   │
         └───┴── [Terminate] ─────────────> TERMINATED (soft-deleted)

Effective Status

ON_LEAVE is a computed display state — it is not stored in the database. At runtime:

• If stored status is ACTIVE AND the employee has an approved time-off request covering today → display as ON_LEAVE
• Otherwise, display the stored status

Separation Types

Type	Description
RESIGNATION	Employee voluntarily left
TERMINATION	Employment terminated
LAYOFF	Position eliminated
RETIREMENT	Employee retired
CONTRACT_END	Contract completed

Offboarding Process (terminateEmployee)

When an employee is terminated, the following happen atomically:

1. Set exitDate, separationType, and separationReason
2. Cancel all PENDING time-off requests
3. Cancel APPROVED requests with dates after the exit date; return balances
4. Delete future Outlook calendar events (if calendar sync is enabled)
5. Soft-delete the employee record

HR-Only Fields

The following fields require the EMPLOYEE_EXIT_INFO_READ permission to view:

• exitDate
• separationType
• separationReason

---

5. Field Value Audit Trail

Purpose

Every change to an employee's profile field creates an immutable audit record for compliance and dispute resolution.

Audit Record Structure

Field	Description
employeeId	Which employee was changed
fieldName	Field name (e.g. "Mobile Phone")
sectionName	Section (e.g. "Contact Information")
previousValue	Old value
newValue	New value
changedBy	Employee who made the change
changedAt	Timestamp

note

fieldName and sectionName are stored denormalised at the time of change — if a field or section is later renamed, historical audit records preserve the original names. This is intentional.

Field Editability Rules

EditableBy	Who Can Edit
SYSTEM	No one (auto-generated values)
HR_ONLY	HR Manager and Admin only
EMPLOYEE	Employee (own profile) or HR

---

Cross-Cutting Concerns

Notification Triggers

Trigger	Recipients	Content
Time-off request created	Manager	Request details and dates
Time-off request reviewed	Employee	Decision, reviewer, and notes
Timesheet overdue	Employee	Reminder to submit

Calendar Integration

Trigger	Action
Time-off approved	Create Outlook event
Time-off cancelled (if approved)	Delete Outlook event

Transaction Management

• All workflow state transitions use @Transactional for ACID guarantees
• Pessimistic locking is applied on balance rows during time-off approval to prevent double-deduction
• Read-only transactions are used for all query operations