Human Resources — HMX Documentation

What is the Human Resources scope?

The HR scope covers everything about your people: who they are, where they sit in the organisation, what they're skilled at, and how they're performing. It ships in two modules — core_hr for the master records and structure, and core_hr_talent_management for goals, KPI, and competency tracking.

Together they give you a full employee lifecycle backbone: from creating an employee with their full personal & work profile, organising them into departments and job positions, tagging their skills and experience, all the way to setting OKRs, defining KPIs, and building competency frameworks for performance reviews.

The two modules at a glance

👤

core_hr

Employee records, departments, job positions, skills, contract types, work locations, hierarchy charts, organisation configuration. The master data foundation.

🎯

core_hr_talent_management

OKR/Goals library, KPI library, Competency library & templates, performance date ranges. Layered on top of core_hr.

Employee lifecycle in HMX

Hire→ Profile + Contract→ Org Assignment→ Goals + KPI→ Performance Review→ Promotion / Exit

Steps 1–3 are owned by core_hr; steps 4–5 by core_hr_talent_management.

What ships in the HR scope

Capability	Module	Key Models
Employee master + personal/work profile	core_hr	hremployee, hremployeeaddress, hremployeefamily, hremployeeeducation, hremployeebankaccount, hremployeeemergencycontact
Organisation structure	core_hr	hrdepartment, hremployeejob, hrhierarchychart
Reference master data	core_hr	hrcontracttype, hrworklocation, hrskills, hremployeegrade, hrjobclassification, hrjobexperiencelevel, hrrace, hrreligion, hrmaritalstatus, hremployeerelation, hremployeecategory, hrcompanyholiday, hryears
Goals (OKR) library & templates	core_hr_talent_management	hrgoals, hrgoalstemplate
KPI library & templates	core_hr_talent_management	hrkpilibrary, hrkpitemplate
Competency library & templates	core_hr_talent_management	hrcompetencylibrary, hrcompetencytemplate, hrcompetencycategory, hrcompetencylevel
Performance date ranges	core_hr_talent_management	hrperformancedaterange

Prerequisites

base module — provides Companies, Branches, Countries, Currencies that HR records reference.
mail module — provides activity logging on employees, departments, and goals.
webx_widget — used by the org chart, kanban, and several form widgets.
At least one Company set up. HR records default to the active company on creation.

Install & bootstrap

Install core_hr

Install the master module first. It seeds the four HR groups on first install.

hmx update install core_hr --alias=default --noinput

Install talent management (optional)

If you'll use OKR / KPI / Competency tracking, install the talent module too.

hmx update install core_hr_talent_management --alias=default --noinput

Verify HR roles

Open Settings → Users & Companies → Groups, filter "HR" — you should see four roles.

Settings / Groups

Groups (filter: "HR")

Name	Module	Users
HR Super User	core_hr	0
HR Manager	core_hr	0
HR Supervisor	core_hr	0
HR User	core_hr	0

Four HR tiers seeded on install

Seed reference data

Before creating employees, seed the lists they reference: Departments, Job Positions, Contract Types, Work Locations, Skills.

Assign HR roles to people

Open Settings → Users, pick a user, add the appropriate HR role.

Open the HR menu and create your first employee

After refresh, an HR top-level menu appears. Click HR → Employees to start onboarding.

Install order & data seeding

core_hr.__hmx__.py declares depends: ["base", "mail", "webx_widget"].
core_hr_talent_management.__hmx__.py depends on core_hr. Seeds two data files (evaluation roles + competency categories).
Both modules ship Vue assets under static/vue/views/*.

What is an Employee record?

An Employee in HMX is the canonical record for a single person working for your organisation. It captures their personal identity (name, gender, photo, contact), work assignment (company, branch, department, job position, manager, work location), contract details, plus pluggable child records for addresses, family, education, skills, and bank accounts.

Most other HR features hang off this record: hierarchy is built from manager references; OKRs, KPI assignments, and competency profiles all reference an hremployee.

How to create an employee

Open the Employee list

Navigate to HR → Employees → Employees. The default list shows name, work email, job title, department, and manager.

HR / Employees

Name	Work Email	Job Title	Department	Manager
Sarah Lim	sarah.lim@acme.co	Senior Engineer	Engineering	Andi Rahman
Andi Rahman	andi@acme.co	Engineering Lead	Engineering	—

Employee list — your team roster

Click Create & fill the basics

Enter Name (required), Work Email (required), Job Title, optional Photo. Company defaults to your active company.

Assign organisational fields

Pick a Branch, Department, Job Position, and Manager. The Manager field accepts another Employee — this builds the hierarchy chart automatically.

New Employee

Name

Sarah Lim

Work Email

sarah.lim@acme.co

Job Title

Senior Engineer

Photo

📷 sarah.jpg

Work Information

Company

Acme HQ

Branch

Jakarta Main

Department

Engineering

Job Position

Backend Engineer

Manager

Andi Rahman

Work Location

Remote — ID

Personal + work assignment — the core of every employee

Add supplementary records (tabs)

The form has tabs for child models: Personal, Skills, Contract, Bank Accounts, Emergency Contact.

PersonalSkillsContractBankEmergency Contact

Skills

Skill	Level	Years
Python	Expert	7
PostgreSQL	Advanced	5
Vue.js	Intermediate	2

Skills tab — pick from the Skill master, set level & years

Save the employee

On save, the Employee record is created. They appear in the org chart and can be assigned KPIs / OKRs from the Talent module.

Employee rules to know

🏷️

Categories (Tags) are computed

The Categories M2M field is auto-computed via _compute_m2m_fields. Don't write to it directly.

🌍

Country phone codes are FK references

Both country_mobile_code and country_phone_code point to basecountry.

🔁

Manager is just another Employee

There is no separate "Manager" model. The hierarchy is built by employees pointing to other employees.

HrEmployee model overview

Field	Type	Notes
name	CharField(255)	Required, indexed via `ordering`
job_title	CharField(255)	Free-text — separate from Job Position FK
work_email	CharField(255)	Required
company	FK → basecompany	Default = active company; SET_NULL on delete
branch	FK → basebranch	Optional
categories	M2M → hremployeecategory	Computed (`_compute_m2m_fields`), stored
country_mobile_code, country_phone_code	FK → basecountry	SET_NULL on delete
+ inherited from imagemixin	—	Adds `image`, `image_small`, etc.

Departments

A Department is a hierarchical group of employees. Departments belong to a Company; the (company, name) pair must be unique. A Department can have a parent Department for nesting and a manager who is an Employee.

How to create a department tree

Open Departments

Navigate to HR → Configuration → Departments. Start with the top-level (no parent), then add children.

Departments

Name	Parent	Manager	Company
Engineering	—	Andi Rahman	Acme HQ
↳ Backend	Engineering	Sarah Lim	Acme HQ
↳ Frontend	Engineering	—	Acme HQ
Sales	—	Maya Putri	Acme HQ

A simple two-level department tree

Set the manager

Pick an existing Employee as Manager. They become the default approver for actions originating from this department.

Save — uniqueness is enforced

A unique constraint on (company, name) prevents duplicate department names within the same company.

Job Positions

A Job Position is the role an employee holds. Positions belong to a Department and Branch — the (name, company, branch) triple must be unique.

How to create a job position

Open Job Positions

Go to HR → Configuration → Job Positions.

Fill in the form

Enter Name, optional Description, pick the Company, Branch, and Department.

New Job Position

Name

Backend Engineer

Department

Engineering / Backend

Branch

Jakarta Main

Company

Acme HQ

Job Position attached to a Department + Branch

Save — assign to employees

Once saved, the position appears in the dropdown on the Employee form.

Hierarchy Chart

The Hierarchy Chart auto-renders an organisational tree from the manager references on Departments and Employees. Configure it via HR → Configuration → Hierarchy Chart Configuration.

Hierarchy Chart — Acme HQ

CEO — Andi Rahman

VP Eng — Sarah Lim

VP Sales — Maya Putri

CFO — Bayu Saputra

Hierarchy Chart — auto-built from manager FKs

Org models reference

Model	Constraint	Key fields
hrdepartment	UniqueConstraint(company, name)	name, parent, manager → hremployee, company
hremployeejob	unique(name, company, branch)	name, description, company, branch, department
hrhierarchychart	—	Configuration model for the chart widget

Why seed reference data?

Most fields on the Employee form are dropdowns into master lists — Skills, Contract Types, Work Locations, Job Classifications. Seeding these once at setup time gives you consistent options to pick from, instead of free-text typos that ruin reports later.

Reference lists shipped with core_hr

List	What it is	Typical entries
Contract Type `hrcontracttype`	Employment relationship classifier	Full-time, Part-time, Contractor, Intern
Work Location `hrworklocation`	Where the employee actually works	HQ Office, Plant Bekasi, Remote — ID, Remote — SG
Skills `hrskills`	Master skill catalogue	Python, Negotiation, AutoCAD, English
Employee Grade `hremployeegrade`	Pay grade or seniority level	G1 — Junior, G2 — Mid, G3 — Senior, G4 — Lead
Job Classification `hrjobclassification`	Functional family classifier	Engineering, Sales, Support, Admin
Job Experience Level `hrjobexperiencelevel`	Years-of-experience banding	Entry, Junior, Mid, Senior, Principal
Employee Category `hremployeecategory`	Tags applied (computed) on employees	High Performer, On Probation, Onsite-only
Employee Relation `hremployeerelation`	Family relation type for emergency contacts	Spouse, Parent, Child, Sibling
Race / Religion / Marital Status	Demographic fields (compliance-driven)	Local terms per regulatory requirement
Company Holiday `hrcompanyholiday`	Public holidays per company / branch	New Year, Idul Fitri, National Day
Years `hryears`	Year master used by Talent date ranges	2025, 2026, 2027

Adding an entry to a reference list

Open the list

Each reference list lives under HR → Configuration → <list name>.

Fill the form

Most lists need just Name. Some have a Code, Description, or Company scope.

New Skill

Name

Python

Skill Type

Technical

Description

Backend programming language

Adding "Python" to the Skills master

Save — it's now pickable on every employee

From this point, when editing an employee, the new entry is in the dropdown for the relevant field.

What is a Goal in HMX?

A Goal (model hrgoals, surfaced as OKR Library) is a reusable objective at three levels: Company, Team, or Individual. Goals can be aligned hierarchically, and the achievement score can be aggregated from sub-goals using a formula (sum / average / max / min / median).

How to create an OKR

Open the OKR Library

Navigate to HR → Talent → OKR Library.

Click Create & pick the goal type

Choose between Company, Team, or Individual. Enter the Goal Title and (optionally) align it with a parent goal.

New Goal

Goal Title

Increase product NPS to 60

Goal Type

Company Goals

Align With

— (top-level)

Objective Type

Percentage

A top-level Company OKR — "Increase NPS to 60"

Enable Sub Goals (optional)

Tick Sub Goals and pick a Formula (Average / Sum / Max / Min / Median). The achievement score auto-aggregates from child goals.

Sub-Goals — Formula: Average

Sub-Goal	Type	Score
Reduce app crashes by 50%	Team	80%
Improve onboarding completion to 90%	Team	65%
Launch in-app feedback widget	Team	100%
Aggregated (avg)		81.7%

Parent score = average of children, computed automatically

Save & assign to people

Once saved, the OKR sits in the library and can be picked when creating Goals Templates or assigning to specific employees.

HrGoals model

Field	Choices / Type
name	CharField(255) — Goal Title
goal_types	'company' \| 'team' \| 'individual'
goals_parent_id	FK → self (alignment)
subgoal_is_active	BooleanField — toggle sub-goal aggregation
formula	'none' \| 'average' \| 'sum' \| 'max' \| 'min' \| 'median'
achievement_score	FloatField — % achieved
objective_type	'percentage' \| 'kpi_based'

KPI Library

A KPI is a measurable indicator with a name, code, computation mode, and a comparison rule (higher is better, or lower is better). KPIs live in a central library so you can reuse them across employees and templates.

How to add a KPI to the library

Open KPI Library

Navigate to HR → Talent → KPI Library, click Create.

Fill in the KPI

Enter Name, Code, optional Description, pick Computation Mode and Comparison.

New KPI

Name

Customer Retention Rate

Code

CRR

Computation Mode

Recorded Manually

Comparison

↑ Higher the better

A retention KPI — manually recorded each quarter

Save & reference from KPI Templates

Once saved, the KPI is available in HR → Talent → KPI Templates for grouping into role-specific scorecards.

Competency Library

Competencies are capabilities with defined levels (Beginner → Expert) grouped under categories. Talent management ships seed data for common categories.

Competency Library

Competency	Category	Levels
Strategic Thinking	Leadership	L1 → L5
Backend Architecture	Technical	L1 → L5
Negotiation	Functional	L1 → L5

Competency Library entries grouped by Category

Talent models

Model	Purpose
hrkpilibrary	Catalogue of KPIs (name, code, computation, comparison)
hrkpitemplate	Group KPIs into role-specific scorecards
hrcompetencylibrary	Catalogue of competencies
hrcompetencytemplate	Group competencies into role-specific frameworks
hrcompetencycategory	Categories (Leadership, Technical, Functional, …)
hrcompetencylevel	Level definitions (L1–L5 by default)
hrjobcompetencydetail	Bridge: Job ↔ Competency requirements
hremployeetalent / hrjobtalent	Per-employee / per-job talent profiles
hrperformancedaterange	Period definitions used by the review cycle

The four HR roles

Role	Who gets it	Typical capability
HR Super User	HR System Owner / IT-HR	Configure modules, override anything, manage roles. Reserved for 1–2 people.
HR Manager	HR Director / HRBP Lead	Read all employees, edit master data, run reports, manage performance cycles.
HR Supervisor	HRBPs / People Ops Specialists	Edit employees in their scope, review goals, manage onboarding flows.
HR User	HR Coordinators / People Ops staff	Day-to-day employee data entry, basic lookups, cannot change master data.

Picking the right role

⚠️

Don't grant Super User widely

HR Super User can override everything in the HR scope. Reserve it for 1–2 people who actually run the system.

📋

Manager ≠ Department Manager

The HR Manager role is about system access, not the manager field on a Department. A Department Manager who isn't part of HR doesn't need this role at all.

Group records (core_hr)

<record id="hr_group_super_user" model="group"><field name="name">HR Super User</field></record>
<record id="hr_group_manager"    model="group"><field name="name">HR Manager</field></record>
<record id="hr_group_supervisor" model="group"><field name="name">HR Supervisor</field></record>
<record id="hr_group_user"       model="group"><field name="name">HR User</field></record>

External XML IDs: core_hr.hr_group_super_user, core_hr.hr_group_manager, core_hr.hr_group_supervisor, core_hr.hr_group_user. core_hr_talent_management ships its own role set.

Module manifests

core_hr

Depends: base, mail, webx_widget
Data: 22 files (security + 20 view XMLs + final menu file)
Assets: CSS + JS + Vue under static/ registered to webx.assets_backend

core_hr_talent_management

Depends: base, core_hr, webx_widget, mail
Data: security + 2 seed XMLs + 11 view files
Assets: Kanban + field widgets (CSS, Vue templates loaded before JS, then JS)

All HR models (37 total)

core_hr (25 models)

Model	Purpose
hremployee	Employee master record
hremployeeaddress	Address records (per-employee)
hremployeefamily	Family / dependent records
hremployeeeducation	Education history
hremployeebankaccount	Bank account info
hremployeeemergencycontact	Emergency contacts
hremployeeskill	Bridge: Employee ↔ Skill
hremployeerelation	Relation type master
hremployeecategory	Tag categories applied to employees
hremployeegrade	Pay grade / seniority
hremployeejob	Job Position master
hrmultiplejob	Multi-job assignment per employee
hrdepartment	Department (hierarchical)
hrjobclassification	Job classification master
hrjobexperiencelevel	Experience level master
hrcontracttype	Contract type master
hrworklocation	Work location master
hrskills	Skill master
hrrace / hrreligion / hrmaritalstatus	Demographic masters
hrcompanyholiday	Public holidays per company
hryears	Year master (used by Talent dates)
hrresumeline	Resume line items
hrorgconfiguration	Organisation chart configuration
authgroup	Extended Auth Group from base

core_hr_talent_management (12 models)

Model	Purpose
hrgoals	OKR Library — reusable goals
hrgoalstemplate	OKR templates
hrkpilibrary	KPI master library
hrkpitemplate	KPI templates
hrcompetencylibrary	Competency master
hrcompetencytemplate	Competency templates
hrcompetencycategory	Competency categorisation
hrcompetencylevel	Level definitions
hrjobcompetencydetail	Bridge: Job ↔ Competency requirement
hremployeetalent	Per-employee talent profile
hrjobtalent	Per-job talent definition
hrperformancedaterange	Performance period date ranges

Human Resources Scope

What is the Human Resources scope?

The two modules at a glance

core_hr

core_hr_talent_management

Employee lifecycle in HMX

What ships in the HR scope

Getting Started

Prerequisites

Install & bootstrap

Install core_hr

Install talent management (optional)

Verify HR roles

Seed reference data

Assign HR roles to people

Open the HR menu and create your first employee

Install order & data seeding

Employees

What is an Employee record?

How to create an employee

Open the Employee list

Click Create & fill the basics

Assign organisational fields

Add supplementary records (tabs)

Save the employee

Employee rules to know

Categories (Tags) are computed

Country phone codes are FK references

Manager is just another Employee

HrEmployee model overview

Organisation Structure

Departments

How to create a department tree

Open Departments

Set the manager

Save — uniqueness is enforced

Job Positions

How to create a job position

Open Job Positions

Fill in the form

Save — assign to employees

Hierarchy Chart

Org models reference

Reference Data

Why seed reference data?

Reference lists shipped with core_hr

Adding an entry to a reference list

Open the list

Fill the form

Save — it's now pickable on every employee

Goals & OKR

What is a Goal in HMX?

How to create an OKR

Open the OKR Library

Click Create & pick the goal type

Enable Sub Goals (optional)

Save & assign to people

HrGoals model

KPI & Competency

KPI Library

How to add a KPI to the library

Open KPI Library

Fill in the KPI

Save & reference from KPI Templates

Competency Library

Talent models

HR Roles

The four HR roles

Picking the right role

Don't grant Super User widely

Manager ≠ Department Manager

Group records (core_hr)

Technical Reference

Module manifests

core_hr

core_hr_talent_management

All HR models (37 total)

core_hr (25 models)

core_hr_talent_management (12 models)