Project — HMX Documentation

What is the Project scope?

The Project scope today gives you a simple project register — a place to record initiatives with a name, owner, start & end dates, current progress (%), and a status that tracks the work from Draft through to Done. Useful for tracking high-level engagements, internal projects, or client-facing milestones without the overhead of a full PM tool.

A complete project management workbench (Tasks, Sub-tasks, Gantt charts, Timesheets, Burndowns, dependency management) is on the roadmap but not yet implemented. For now, projects act as a high-level tracker; detailed task management lives outside the system or in another module.

ℹ️

Honest scope note

The Project scope ships one module: project. It contains a single Project model with status workflow (Draft → Pending → Verified → Done). No Tasks, no Gantt, no Timesheets yet — see the Roadmap.

Project lifecycle today

Draft→ Pending→ Verified→ Done

Four-state workflow tracked on the status field. The transition is manual (no auto-rules) — set the status as the project moves through approval & execution.

What ships in the project module

Capability	Source	Notes
Project record (name, dates, owner, progress, status)	project	project.py / Project model
4-state status workflow with tracking	project	tracking=True on status field
Active / archive flag	project	Note: archive blocked via UserError today
Multi-amount fields (decimal_ref to sale)	project	amount, amount2, amount3, amount4 — for budget/value tracking
Bulk-create helper (action_create_project)	project	Generates 10,000 sample records for stress testing

Prerequisites

base module — provides Companies and the Auth User model the project's user_id references.
At least one user with last_name ilike 'admin' — the user_id field domain is filtered to admin-style users today.

Install & first project

Install the project module

Run the install command:

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

Open the Project menu

After refresh, navigate to Project → Projects. The list will be empty until you create your first.

Project / Projects

Name	Owner	Start	End	Progress	Status
No projects yet

Empty Project list — ready for your first record

Create a project (see next chapter)

See the Projects chapter below for the step-by-step.

Module wiring

__hmx__.py declares depends: ["base"]. Loads security/base.model.access.csv + views/projects_views.xml only.
Single model: Project in models/project.py. No additional sequences, ACLs, or wizards.
Signal hooks (post_save, post_delete) are imported but not yet attached — placeholder for future event handling.

What is a Project record?

A Project is a lightweight tracker for a body of work: a name, a date range, an owner (the responsible Auth User), a progress percentage you bump as work advances, and a status. Use it for things like internal initiatives ("ERP rollout phase 2"), client engagements, or compliance projects you want to keep visible without yet having a task system.

How to create a project

Open Projects → click Create

From Project → Projects, click + Create.

Fill in the basics

Enter a Name (max 100 chars, required), pick the Owner (a User), set Start Date and End Date.

New Project

Name

ERP Rollout — Phase 2

Owner

Andi Rahman (admin)

Start Date

22 Apr 2026

End Date

31 Aug 2026

Progress

0.0%

Status

Draft

A new project — Draft status by default

Save

On save, the project appears in the list. Status defaults to Draft; Active defaults to True.

Update progress as work advances

Edit the project, bump Progress from 0 to 100 as you advance. Change the Status as you transition through the workflow (see next chapter).

ERP Rollout — Phase 2 (mid-flight)

Progress

55%

Status

Pending

Progress bar & status updated as work advances

Project rules to know

🔒

Archive is intentionally blocked

Calling action_archive raises a "Testing. Cannot Archive!!" error. To deactivate a project today, set active = False directly via the form (or use the unarchive helper which restores it).

👤

Owner field is admin-only

The user_id domain is [('last_name', 'ilike', 'admin')] — only users whose last name contains "admin" are pickable. This is a placeholder; expand the domain when proper ownership rules land.

💰

Four amount fields available

Three Decimal fields (amount, amount2, amount3) and one Float (amount4) are exposed for tracking budget, actual cost, or other monetary values. Decimal fields use the sale.product_price:digits_amount precision reference.

Project model fields

Field	Type	Notes
name	CharField(100)	Required
user_id	FK → auth.User	CASCADE; domain filtered to admin users
start_date, end_date	DateField	Both nullable
progress	FloatField	Default 0.0
status	CharField (choices)	'dr' \| 'p' \| 'v' \| 'do'; `tracking=True`
active	BooleanField	Default True
amount, amount2, amount3	DecimalField	10 digits, decimal_ref to sale
amount4	FloatField	—

The four states

State	Stored as	When to use
Draft	'dr'	The project is being scoped — name, dates, owner are still being filled in. Default state on create.
Pending	'p'	Submitted for review or actively in progress, awaiting verification of milestones / deliverables.
Verified	'v'	Deliverables verified by the project owner / approver. Final sign-off pending.
Done	'do'	Project is closed — no further work expected. Often paired with progress = 100%.

How to change status

Open the project form

Click into the project from the list view.

Edit the Status field

Pick the new state from the dropdown. There are no rules preventing skipping states (e.g., Draft → Done directly), but conventionally you walk through them in order.

ERP Rollout — Phase 2

Status

Manual transition — no auto-rules today

Save — change is tracked

tracking=True on the status field means every change is logged in the chatter (when mail module is installed). You can review the full transition history per project.

Status field implementation

PROJECT_STATUS = [
    ('dr', 'Draft'),
    ('p', 'Pending'),
    ('v', 'Verified'),
    ('do', 'Done'),
]

status = models.CharField(
    _("Status"),
    max_length=50,
    default='dr',
    choices=PROJECT_STATUS,
    tracking=True,
)

No state-machine logic is enforced; transitions are bare assignments. The 2-letter stored values keep the column small. tracking=True persists every change to the chatter when mail is installed.

Capability status

Capability	Target	Status	Workaround Today
Project register (name, dates, status, progress)	project	Shipping	—
Status workflow with tracking	project	Shipping	—
Tasks & sub-tasks	project (planned)	Planned	External tracker (Jira/Linear) or spreadsheet
Gantt chart	project + webx (planned)	Planned	External Gantt; Project widgets ship test ManyToMany hooks
Timesheets / Time tracking	project_timesheet (planned)	Planned	External tool
Milestones & deliverables	project (planned)	Planned	Use the project's progress + status as a single milestone
Task dependencies / critical path	project (planned)	Backlog	External Gantt with dependency editor
Burndown / velocity reports	project + olap (planned)	Backlog	External BI
Resource allocation & capacity	project + core_hr (planned)	Backlog	Manual planning sheet
Client-portal task visibility	project + core_website (planned)	Backlog	Email status updates

📅

For now, treat the Project record as a high-level tracker. Pair it with the chatter (mail module) for activity logs, and use the four-state workflow as your minimal governance.

Module manifest

{
    "name": "Project",
    "category": "project",
    "version": "1.0",
    "depends": ["base"],
    "data": [
        "security/base.model.access.csv",
        "views/projects_views.xml",
    ],
}

Minimal manifest — single dependency, single security CSV, single view file. No data seeds, no wizards, no API.

Models

Model	Purpose	Notes
Project	The single project record	Default ordering by name; verbose_name "Project"

Notable methods

Method	Behaviour
action_archive()	Raises UserError ("Testing. Cannot Archive!!") — archive disabled by design
action_unarchive()	Sets active = True on selected records
action_create_project()	Bulk-generates 10,000 sample projects with random names — for stress / load testing
default_company	Returns `self.env.company` (current active company)

Signal hooks

post_save and post_delete are imported from django.db.models.signals and the @receiver decorator is wired up — but no actual receiver functions are attached today. Treat these as placeholders for future event-driven behaviour (notifications, cascade updates).

Source files

Path	Role
__hmx__.py	Manifest
apps.py	Django AppConfig
models/project.py	Project model + helpers
views/projects_views.xml	List + form views, menu
security/base.model.access.csv	ACL for the project model

Project Scope

What is the Project scope?

Honest scope note

Project lifecycle today

What ships in the project module

Getting Started

Prerequisites

Install & first project

Install the project module

Open the Project menu

Create a project (see next chapter)

Module wiring

Projects

What is a Project record?

How to create a project

Open Projects → click Create

Fill in the basics

Save

Update progress as work advances

Project rules to know

Archive is intentionally blocked

Owner field is admin-only

Four amount fields available

Project model fields

Status Workflow

The four states

How to change status

Open the project form

Edit the Status field

Save — change is tracked

Status field implementation

Project Roadmap

Capability status

Technical Reference

Module manifest

Models

Notable methods

Signal hooks

Source files