Account Track Category Documentation

Overview

The Account Track Category model (account.track.categ) provides a hierarchical structure for tracking and categorizing financial transactions by cost centers, profit centers, projects, departments, or any other business dimension. It enables multi-dimensional analysis of accounting data.

---

Model Information

Model Name: account.track.categ Display Name: Tracking Category Name Field: name Key Fields: ["code"]

Features

• ❌ Audit logging enabled (_audit_log)
• ❌ Multi-company support (company_id)
• ❌ Full-text content search (_content_search)
• ✅ Hierarchical structure (parent/child)
• ✅ Computed full name with path
• ✅ Balance calculation across hierarchy
• ✅ Active/Inactive status
• ✅ Cycle constraint validation

---

Key Fields Reference

Core Fields

Field	Type	Required	Description
name	Char	✅	Category name
code	Char	✅	Unique category code
description	Text	❌	Category description
type	Selection	✅	Primary (1) or Secondary (2)
active	Boolean	❌	Active status (default: True)

Hierarchy Fields

Field	Type	Description
parent_id	Many2One	Parent tracking category
sub_tracks	One2Many	Child tracking categories
full_name	Char	Computed full path name (stored)

Relationship Fields

Field	Type	Description
track_entries	One2Many	All tracking entries for this category
sale_orders	One2Many	Related sales orders
projects	One2Many	Related projects
documents	One2Many	Attached documents
contact_id	Many2One	Associated contact
currency_id	Many2One	Category currency

Computed Fields

Field	Type	Description
balance	Decimal	Total balance (includes children)
full_name	Char	Full hierarchical name path
self_id	Many2One	Self-reference for UI

---

Default Values

_defaults = {
    "type": "1",        # Primary
    "active": True,
}

---

Default Ordering

Records are ordered by type, code, then full name:

_order = "type,code,full_name"

---

Type Options

Value	Label	Description
1	Primary	Main tracking dimension
2	Secondary	Secondary tracking dimension

---

API Methods

1. Create Track Category

Method: create(vals, **kw)

Creates a new tracking category with validation.

Validation: - Name cannot contain apostrophes (regular or curly) - Code must be unique (key field)

Example:

track_id = get_model("account.track.categ").create({
    "name": "Marketing Department",
    "code": "MKT",
    "type": "1",
    "description": "Marketing and advertising expenses",
})

Raises: - Exception - If name contains apostrophes

---

2. Update Track Category

Method: write(ids, vals, **kw)

Updates tracking category and recalculates full_name for children.

Behavior: 1. Validates name for apostrophes 2. Updates record 3. Updates function store for all children

Example:

get_model("account.track.categ").write([track_id], {
    "name": "Marketing Dept",
})

---

3. Get Full Name

Method: get_full_name(ids, context={})

Computes hierarchical full name by traversing parent chain.

Returns: dict - {id: "Parent / Child / Grandchild"}

Example:

# If hierarchy is: Company > Department > Team
# full_name = "Company / Department / Team"

---

4. Get Balance

Method: get_balance(ids, context={})

Calculates total balance including all child categories.

Behavior: 1. Finds all child category IDs 2. Queries sum of amounts from track entries 3. Recursively aggregates child totals

Returns: dict - {id: total_balance}

Example:

totals = get_model("account.track.categ").get_balance([track_id])
print(f"Total balance: {totals[track_id]}")

---

5. Name Search

Method: name_search(name, condition=[], limit=None, context={})

Searches by name or code.

Example:

results = get_model("account.track.categ").name_search("MKT")
# Finds categories where name or code contains "MKT"

---

6. Name Get

Method: name_get(ids, context={})

Returns display name with code prefix.

Format: [CODE] Name

Example:

names = get_model("account.track.categ").name_get([track_id])
# Returns: [(1, "[MKT] Marketing Department")]

---

Related Models

Model	Relationship	Description
account.track.entry	One2Many	Tracking entries
sale.order	One2Many	Sales orders
project	One2Many	Projects
document	One2Many	Documents
contact	Many2One	Contact
currency	Many2One	Currency

---

Common Use Cases

Use Case 1: Create Department Hierarchy

# Create parent department
parent_id = get_model("account.track.categ").create({
    "name": "Operations",
    "code": "OPS",
    "type": "1",
})

# Create child departments
for dept in [("Sales", "OPS-SALES"), ("Support", "OPS-SUPPORT")]:
    get_model("account.track.categ").create({
        "name": dept[0],
        "code": dept[1],
        "type": "1",
        "parent_id": parent_id,
    })

---

Use Case 2: Get Department Balances

# Get all department balances
depts = get_model("account.track.categ").search_browse([
    ["type", "=", "1"],
    ["parent_id", "=", None],  # Top-level only
])

for dept in depts:
    print(f"{dept.full_name}: {dept.balance:,.2f}")
    for sub in dept.sub_tracks:
        print(f"  {sub.name}: {sub.balance:,.2f}")

---

Use Case 3: Find Categories by Contact

# Find tracking categories for a specific contact
tracks = get_model("account.track.categ").search_browse([
    ["contact_id", "=", contact_id],
    ["active", "=", True],
])

for track in tracks:
    print(f"{track.code}: {track.name} - Balance: {track.balance}")

---

Use Case 4: Create Project Tracking

# Create project-based tracking
project_track_id = get_model("account.track.categ").create({
    "name": "Website Redesign",
    "code": "PRJ-WEB-2024",
    "type": "2",  # Secondary tracking
    "contact_id": client_id,
    "currency_id": currency_id,
    "description": "Q1 2024 website redesign project",
})

---

Hierarchical Structure

Tracking Category Hierarchy:
├── Operations (OPS)
│   ├── Sales (OPS-SALES)
│   │   └── Regional Sales (OPS-SALES-REG)
│   └── Support (OPS-SUPPORT)
├── Administration (ADM)
│   ├── HR (ADM-HR)
│   └── Finance (ADM-FIN)
└── Projects (PRJ)
    ├── Project A (PRJ-A)
    └── Project B (PRJ-B)

Full Names:
- "Operations / Sales / Regional Sales"
- "Administration / HR"
- "Projects / Project A"

---

Best Practices

1. Use Consistent Code Patterns

# Good: Hierarchical codes
codes = [
    ("MKT", "Marketing"),
    ("MKT-DIG", "Digital Marketing"),
    ("MKT-DIG-SEO", "SEO Team"),
]

# Bad: Inconsistent codes
codes = [
    ("MARKETING", "Marketing"),
    ("digital", "Digital Marketing"),
    ("SEO", "SEO Team"),
]

---

2. Avoid Apostrophes in Names

# Good: No apostrophes
name = "Clients Division"

# Bad: Contains apostrophe (will raise exception)
name = "Client's Division"

---

3. Use Primary vs Secondary Appropriately

# Primary (type="1"): Main cost centers
# - Departments, Locations, Business Units

# Secondary (type="2"): Project-based tracking
# - Projects, Campaigns, Initiatives

---

Troubleshooting

"Invalid character: apostrophes are not allowed"

Cause: Name contains apostrophe characters Solution: Remove apostrophes from the name field

"Cycle detected"

Cause: Parent-child relationship creates a loop Solution: Review and fix parent_id assignments

"Balance shows 0"

Cause: No track entries or entries on children only Solution: Verify track entries exist; balance includes children

---

Testing Examples

Unit Test: Track Category Hierarchy

def test_track_hierarchy():
    # Create parent
    parent_id = get_model("account.track.categ").create({
        "name": "Test Parent",
        "code": "TEST-P",
        "type": "1",
    })

    # Create child
    child_id = get_model("account.track.categ").create({
        "name": "Test Child",
        "code": "TEST-C",
        "type": "1",
        "parent_id": parent_id,
    })

    # Verify full name
    child = get_model("account.track.categ").browse([child_id])[0]
    assert child.full_name == "Test Parent / Test Child"

    # Cleanup
    get_model("account.track.categ").delete([child_id, parent_id])

---

Security Considerations

Permission Model

• Read access typically broad for reporting
• Write access restricted to administrators

Data Validation

• Unique code constraint prevents duplicates
• Cycle constraint prevents infinite loops
• Apostrophe validation prevents SQL issues

---

Version History

Last Updated: December 2024 Model Version: account_track_categ.py Framework: Netforce

---

Additional Resources

• Track Entry Documentation: account.track.entry
• Track Distribution Documentation: track.distrib
• Project Documentation: project

---

This documentation is generated for developer onboarding and reference purposes.