Job Costing Workflow¶

Overview¶

Job costing is the core feature of the Atlas Construction module. It provides detailed tracking of project costs organized by construction phases and cost categories, comparing actual costs against budgeted amounts to monitor project profitability in real-time.

Important

Permissions Required: Users must have the Job Cost Manager security group to create and edit budget lines. See Security & Permissions for details.

Key Concepts¶

Job Cost Matrix¶

Costs are tracked in a two-dimensional matrix:

                 Labor   Materials   Subcontractors   Equipment   Other
───────────────────────────────────────────────────────────────────────
Site Work          $X        $X            $X             $X         $X
Foundation         $X        $X            $X             $X         $X
Framing            $X        $X            $X             $X         $X
Rough-In           $X        $X            $X             $X         $X
Insulation         $X        $X            $X             $X         $X
Finishes           $X        $X            $X             $X         $X
Final              $X        $X            $X             $X         $X

Each cell is a Job Cost Line with:

Budget amount
Actual cost
Committed cost
Total cost (actual + committed)
Variance (budget - total)

Cost Components¶

Budget Amount

Planned cost for this phase/category combination. Set during project setup.

Actual Cost

Money already spent:

Vendor bills (posted to accounting)
Timesheet labor costs
Expense reports

Updated automatically when bills are posted or timesheets submitted.

Committed Cost

Money obligated but not yet spent:

Confirmed purchase orders not yet received
Shows future costs coming down the pipeline

Prevents budget surprises by tracking commitments.

Total Cost

Actual Cost + Committed Cost

The true picture of budget utilization including future obligations.

Variance

Budget Amount - Total Cost

Positive = Under budget (good)
Negative = Over budget (requires attention)
Near zero = On target

Variance Percentage

(Variance / Budget Amount) × 100%

Helps identify which lines need attention regardless of dollar amount.

Workflow Steps¶

Step 1: Create Project Budget¶

There are three ways to create a project budget:

Option A: Auto-Apply Template on Project Creation¶

If a budget template exists for the project’s job type, it auto-applies:

Navigate to Construction → Projects → Create
Enter project details:
- Name: Project name
- Customer: Select customer
- Contract Amount: Total contract value
- Job Type: Select job type (e.g., “Single Family Home”)
- Check Construction Job
Click Save
Budget lines are automatically created from the template

Option B: Manual Template Application¶

Apply a template to an existing project:

Open the project form
Navigate to Job Costing tab
Click Generate Budget from Template
In the wizard:
- Select Template
- Enter Total Budget (or uses contract amount)
- Click Apply
Budget lines are created with amounts distributed by template percentages

Note

The template button only appears when the project has NO budget lines yet. If you need to reapply, delete existing lines first.

Option C: Manual Budget Entry¶

Create budget lines one at a time:

Open the project form
Navigate to Job Costing tab
Click Add Budget Line
In the form dialog:
- Phase: Select construction phase
- Cost Category: Select cost type
- Description: Enter line description
- Budget Amount: Enter budgeted cost
- Notes: Optional additional information
Click Save & Close or Save & New
Repeat for all budget lines

Or use inline editing:

In the Job Costing tab
Click the + button at the bottom of the list
Fill in fields directly in the list
Click away to save
Repeat for additional lines

Step 2: Edit Budget Lines (Manager Permission Required)¶

Warning

Cannot edit budget lines? Verify you have the Job Cost Manager security group assigned. See Security & Permissions for instructions.

Inline Editing¶

The job costing tab list has editable="bottom" enabled:

Open the project form
Navigate to Job Costing tab
Click any field in a budget line to edit it:
- Phase: Click to change
- Category: Click to change
- Description: Click to edit text
- Budget Amount: Click to change amount
Press Tab or Enter to save
Changes are saved automatically

Drag to Reorder¶

Hover over the ≡ handle on the left of any line
Click and drag to new position
Release to save new order
Sequence is updated automatically

Delete Lines¶

Hover over a budget line
Click the × (delete) icon on the right
Confirm deletion
Line is removed immediately

Warning

Deleting a budget line removes historical tracking for that phase/category. Consider setting budget to $0 instead if you want to preserve history.

Bulk Edit in List View¶

To edit multiple budget lines across projects:

Navigate to Construction → Job Costing → Budget Lines
Use filters to find lines to edit
Select multiple lines (checkboxes)
Use Action menu for bulk operations

Step 3: Link Purchase Orders¶

Connect purchase orders to budget lines to track committed costs:

When Creating PO¶

Navigate to Purchase → Orders → Create
Select Vendor
In the PO line:
- Product: Select product/service
- Quantity: Enter quantity
- Unit Price: Enter price
- Project: Select construction project
- Job Cost Line: Select specific budget line (appears when project selected)
Click Save
When PO is confirmed, committed cost updates on the budget line

From Existing PO¶

Open an existing purchase order
Edit the PO line
Select Project and Job Cost Line
Save the PO
Committed cost updates

Note

Only confirmed POs (state = purchase/done) count toward committed cost. Draft POs do not affect budget calculations.

Step 4: Post Vendor Bills¶

When bills are posted, actual costs update automatically:

Navigate to Purchase → Vendor Bills or Accounting → Vendor Bills
Create or import vendor bill
Match bill to PO (if applicable)
In bill line:
- Product/Service: Description
- Quantity: Amount
- Unit Price: Price
- Project: Select project (if not auto-filled from PO)
- Job Cost Line: Select budget line (if not auto-filled)
Click Post to confirm the bill
Actual cost on the budget line updates immediately
If linked to PO, committed cost decreases

Step 5: Monitor Variance¶

View Budget Status in Project Form¶

The Job Costing tab shows real-time status:

Lines are color-coded by variance:
- Green (decoration-success): On or under budget
- Yellow (decoration-warning): Slightly over budget
- Red (decoration-danger): Significantly over budget
Alert Level field triggers colors based on variance percentage:
- Good: Variance ≥ 0%
- Warning: Variance < 0% but > -10%
- Danger: Variance ≤ -10%
Totals at bottom show:
- Total Budget: Sum of all budget amounts
- Total Actual: Sum of all actual costs
- Total Variance: Budget - Actual

Use Budget Reports¶

Navigate to Construction → Reporting → Job Cost Analysis
Select project(s)
View:
- Budget vs. Actual comparison
- Variance analysis
- Cost trends over time
- Phase/category breakdown

Export to Excel for detailed analysis

Set Up Budget Alerts¶

Configure automatic alerts for budget overruns:

Navigate to Construction → Configuration → Settings
Enable Budget Alerts
Set Warning Threshold (e.g., 90% of budget)
Set Danger Threshold (e.g., 100% of budget)
Configure Alert Recipients
Save settings

When a budget line exceeds thresholds:

Alert indicator appears in project form
Email sent to configured recipients
Dashboard notification created

Step 6: Adjust Budgets via Change Orders¶

When scope changes require budget adjustments:

Create a change order (see Change Orders)
Add line items with cost impacts
Submit for approval
Upon approval:
- Sale order created for customer billing
- Project budget automatically updated
- Variance recalculated

Best Practices¶

Budget Structure¶

Use Consistent Phases
- Define standard phases for your company
- Use same phases across all projects
- Enables comparison and historical analysis
Appropriate Detail Level
- Don’t over-segment (too many lines = management overhead)
- Don’t under-segment (lack of visibility)
- Typical project: 25-50 budget lines
Leverage Templates
- Create templates for common project types
- Speeds up setup
- Ensures consistency
- Update templates based on historical data

Cost Tracking¶

Link All POs to Budget Lines
- Never create POs without linking to cost lines
- Ensures committed cost tracking
- Prevents budget surprises
Post Bills Promptly
- Don’t let bills sit in draft
- Actual costs must be current for accurate tracking
- Set up weekly bill posting routine
Review Variance Weekly
- Don’t wait for problems to escalate
- Weekly review catches issues early
- Use variance reports, not just project forms
Investigate Large Variances
- Any line >10% over budget needs explanation
- Document reasons for variances
- Update forecast if permanent change

Budget Adjustments¶

Use Change Orders for Scope Changes
- Don’t manually adjust budgets for scope changes
- Change orders provide audit trail
- Automatically updates customer billing
Document All Budget Changes
- Add notes explaining why budget changed
- Maintain change log
- Required for audits
Reallocate Between Lines Carefully
- Moving budget between lines can mask problems
- Document rationale
- Consider if change order is more appropriate

Reporting¶

Standard Reports
- Run weekly variance reports
- Review monthly cost trends
- Analyze completed projects for estimating
Dashboard Monitoring
- Set up KPI dashboard
- Track key metrics:
  - Projects over budget
  - Average variance percentage
  - Committed cost as % of remaining budget
Historical Analysis
- Compare actual costs to estimates
- Identify patterns (always over/under on certain phases)
- Refine future estimates

Common Issues¶

Issue: Cannot Edit Budget Lines¶

Symptom:

Budget lines appear as read-only text, cannot click to edit.

Cause:

User lacks Job Cost Manager security group.

Solution:

Verify user’s security groups: Settings → Users → Select user
Check Job Costing section shows “Manager” role
If not, assign the role
User must log out and log back in
Clear browser cache if still not working

See Security & Permissions for detailed permission configuration.

Issue: Committed Cost Not Updating¶

Symptom:

Created PO linked to budget line, but committed cost stays at $0.

Cause:

PO is still in draft state.

Solution:

Open the purchase order
Click Confirm Order
Committed cost updates immediately
Only confirmed POs (purchase/done state) affect committed cost

Issue: Actual Cost Not Matching Bills¶

Symptom:

Posted vendor bills but actual cost doesn’t reflect them.

Cause:

Bills not properly linked to job cost line.

Solution:

Open the vendor bill
Check each bill line has:
- Project field filled
- Job Cost Line field filled (this is critical!)
If missing, edit bill and add job cost line
Save bill
Actual cost updates

Note

Just having the Project field is NOT enough - the Job Cost Line field must be set for costs to track properly.

Issue: Budget Totals Don’t Match Contract¶

Symptom:

Sum of budget lines doesn’t equal contract amount.

Cause:

This is usually intentional - budget is for costs, contract is revenue.

Explanation:

Budget = Your expected costs to complete the project
Contract = What customer pays you (should be higher!)
Difference = Your expected profit margin

Example:

Contract Amount: $500,000
Total Budget: $400,000
Expected Profit: $100,000 (20% margin)

If budget equals contract, you have no profit margin!

Issue: Variance Showing Wrong¶

Symptom:

Variance calculation seems incorrect.

Check:

Variance = Budget - (Actual + Committed)
Verify all three components:
- Is budget amount correct?
- Is actual cost including all bills?
- Is committed cost showing all open POs?
Remember: Variance can be negative (over budget)

Recalculate:

If numbers still seem wrong:

Navigate to Construction → Job Costing → Budget Lines
Find the line in question
Click Action → Recompute
System recalculates all computed fields

Advanced Topics¶

Timesheet Integration¶

If using hr_timesheet module:

Employees log time to projects
Timesheets can link to job cost lines
Labor costs auto-calculate:
- Hours × Employee Rate = Labor Cost
- Added to actual cost on budget line
Configure in Construction → Configuration → Settings:
- Enable Timesheet Integration
- Set default labor rate calculation method

Multi-Currency Projects¶

For international projects:

Set project currency on project form
Budget lines use project currency
POs and bills auto-convert to project currency
Variance calculated in project currency
Exchange rate fluctuations tracked

Cost Allocation Rules¶

For complex cost allocations:

Create allocation rules: Construction → Configuration → Allocation Rules
Define how to split costs across multiple:
- Phases
- Projects
- Cost categories
Apply rules when posting bills
System auto-creates multiple accounting entries

Custom Cost Categories¶

Beyond the defaults:

Navigate to Construction → Configuration → Cost Categories
Click Create
Define:
- Name: Category name
- Sequence: Display order
- Code: Optional cost code
- Description: Usage notes
Use in budget lines like default categories

API Integration¶

Access job cost data programmatically:

# Get budget lines for a project
budget_lines = env['atlas.job.cost.line'].search([
    ('project_id', '=', project_id)
])

# Calculate total variance
total_variance = sum(budget_lines.mapped('variance'))

# Get lines over budget
over_budget = budget_lines.filtered(
    lambda l: l.variance < 0
)

See Odoo API documentation for more examples.

Next Steps¶

Change Orders - Learn how to handle scope changes
progress_billing - Bill customers based on completed work
../features/reporting - Advanced cost reports and analytics
../configuration/templates - Create budget templates