Workflow: OKR Cycle — Planning & Evaluation

Modules involved: OKR (Circulation · OKRs · Key Results · Check-ins · Approval) · Goals · DataPulse
Who uses it: Management · Department Managers · All Employees
Typical duration: One cycle = 1 quarter or 1 year (configured in Circulation)

Overview

The OKR module implements the Objectives & Key Results methodology. A complete cycle covers: defining the period (Circulation), creating objectives with quantifiable key results (OKRs + Key Results), periodic progress check-ins with optional hierarchical approval, and closing the cycle when progress reaches 100%.

Important distinctions:

• OKR = subjective progress on user-defined objectives (periodic check-in)
• Goals = separate module; automatically tracks real CRM metrics (invoices, leads, contracts) against a numerical target — no manual check-in
• DataPulse = read-only analytics dashboard; has no own tables, does not integrate with OKR
• tblhr_checkins from the HR module = physical attendance (start/stop time at workplace) — has no connection to OKR check-ins

Mandatory condition: Without at least one record in tblokr_setting_circulation with valid from_date/to_date, the OKR module does not work correctly. This is the first setting to configure.

Flow diagram

[CYCLE SETUP — admin, once per period]
  │
  ├── Circulation: define period (e.g., Q1 2026: 01.01–31.03)
  ├── Units: units of measure (%, RON, number of items)
  ├── Questions: questions displayed at each check-in
  ├── Evaluation Criteria: evaluation scores per criterion
  └── Approval Setting (optional): who approves check-ins
  │
  ↓
[CREATE OKR]
  │
  ├── Type: Personal (1) · Department (2) · Company (3)
  ├── Display: Public (1) · Private (2)
  ├── Objective + Key Results (target, unit, plan)
  └── approval_status = 0 (draft)
  │
  ↓
[PERIODIC CHECK-IN]
  │
  ├── User opens okr/checkin_detailt/{id}
  ├── Fills in per Key Result: achieved, progress (0–100%), confidence_level
  ├── Fills in: evaluation_criteria (score), comment, answers to Questions
  ├── Sets: recently_checkin (today) + upcoming_checkin (future date)
  └── Submit → approval_status = 3 (Waiting for Approval)
  │
  ↓
[CHECK-IN APPROVAL]
  │
  ├── If NO Approval Setting exists for the relevant department/OKR:
  │     → approval_status = 1 (Auto-approved) ← immediately
  │
  └── If Approval Setting EXISTS:
        ├── System resolves approvers (direct_manager / department_manager / fixed staff)
        ├── Notification sent to first approver
        ├── Approver approves (approve=1) or rejects (approve=-1)
        │     → If all approve: approval_status = 1
        │     → If anyone rejects: approval_status = 2
        └── Creator notified with approved_checkin / rejected_checkin
  │
  ↓
[PROGRESS UPDATED]
  │
  ├── okrs.progress = average of all Key Result progress values
  ├── If progress = 100% → okrs.status = 1 (Finished)
  └── Immutable log in tblokrs_checkin_log (complete snapshot)
  │
  ↓
[CYCLE CLOSURE]
  │
  ├── OKRs with status=1 (Finished) are fully achieved
  ├── Cycle report: progress · confidence levels · check-in history
  └── Admin can view reports (requires reports → view permission)

[CYCLE CLOSED ✓]

Step by step

1. Cycle configuration (admin)

Where: /admin/okr → Settings

1a. Circulation — mandatory

Tab: Settings → Circulation → Add Circulation

The system automatically detects the current cycle via MONTH(NOW()) = month(from_date) AND YEAR(from_date) = YEAR(NOW()). If no cycle exists with from_date in the current month, new OKRs cannot be linked to an active cycle.

1b. Units

Tab: Settings → Units → Add Unit

Examples: %, RON, USD, Items, No. of clients. Units are selectable on each Key Result.

1c. Questions (optional)

Tab: Settings → Questions → Add Question

Questions configured here appear mandatorily on the check-in form for all users. E.g., "What went well?", "What blockers exist?", "What help do you need?".

1d. Evaluation Criteria (optional)

Tab: Settings → Evaluation Criteria → Add Criteria

Numerical scores on defined criteria (e.g., group_criteria=1, name="Output quality", scores=85). At check-in, the user selects a criterion and the system records the score.

1e. Approval Setting (optional)

Tab: Settings → Approval Process → Add Approval

If you do not configure any approval rules, all check-ins are automatically approved (approval_status = 1 immediately after submit).

Approver types in JSON setting:

Note: For direct_manager and department_manager, the team_manage field on staff and manager_id on department must be populated. If missing, resolution fails and the check-in may remain blocked.

2. Creating an OKR

Where: /admin/okr → New OKR

Required permission: okr → view OR okr → view_own OR is_admin(). Users with view_own can only create personal OKRs (type=1) assigned to themselves.

Key Results

Added after OKR creation. Each Key Result has:

3. Periodic check-in

Where: /admin/okr → click OKR → Check-in button

Access condition: approval_status must be 0 (draft) or 1 (approved). If it is 2 (rejected) or 3 (pending), the check-in button is hidden.

At each check-in, the system completely replaces the rows in tblokrs_checkin for that OKR (does not add — overwrites the current state). History is kept in tblokrs_checkin_log (immutable).

Fields filled in per Key Result:

OKR-level fields:

Aggregate progress calculation:

total_progress = (sum of all KR progress values) / (number of KRs × 100) × 100

If total_progress = 100 → okrs.status = 1 (Finished) and complete_okrs = 1.

4. Approval workflow

Without configured approval rules: check-in is automatically approved (approval_status = 1) immediately after submit.

With approval rules:

Submit check-in
  → approval_status = 3 (Waiting)
  → system searches for Approval Setting via FIND_IN_SET(department) or FIND_IN_SET(okrs_id)
  → first approver notified

Approver opens request → approves or rejects
  → all approvers approve → approval_status = 1
  → any rejection → approval_status = 2
  → creator notified

If choose_when_approving = 1, the user doing the check-in manually selects the approver from a dropdown at the time of submit.

5. Goals — separate module

Where: /admin/goals

Goals automatically tracks real CRM metrics against a numerical target. No manual check-in, no approval.

At the end of the period (end_date), if the target was not reached and notify_when_fail=1, the system sends a notification. Similarly for target achievement with notify_when_achieve=1.

6. DataPulse

Where: /admin/datapulse

Read-only analytics dashboard with 16 chart types (payments per agent, clients by county, leads by source, logged time per employee, etc.). Has no own tables — reads directly from core CRM tables. Requires no configuration and has no granular permissions (any authenticated staff can access).

OKR Statuses

Required permissions

Gotchas

Module references

• OKR — module documentation
• Goals — automatic CRM targets
• DataPulse — analytics dashboard
• HR — Staff — team_manage field for direct_manager
• HR — Payroll — bonus_kpi fed from OKR progress