Asset Categories

Overview

Asset categories provide a hierarchical classification system for organizing your equipment and infrastructure. Categories help you:

Group similar assets for easier management
Generate reports by asset type
Apply consistent maintenance strategies across asset groups
Simplify asset searches and filtering

Asset categories are defined in the asset_categories table and managed through the assetCategoryService (src/services/assetCategoryService.ts).

Category Data Structure

Each asset category contains the following fields:

Field	Type	Description
`id`	number	Unique category identifier
`name`	string	Category name (e.g., “HVAC Equipment”)
`description`	string \| null	Optional detailed description
`is_active`	boolean	Active status flag
`created_at`	timestamp	Creation timestamp
`updated_at`	timestamp	Last update timestamp

// Type definition from src/types/AssetCategory.ts
export type AssetCategory = {
  id: number;
  name: string;
  description: string | null;
  is_active: boolean;
  created_at?: string;
  updated_at?: string;
};

Managing Categories

Listing All Categories

Retrieve all asset categories, optionally filtering by active status:

import { listAssetCategories } from '@/services/assetCategoryService';

// Get all categories (including inactive)
const allCategories = await listAssetCategories();

// Get only active categories
const activeCategories = await listAssetCategories({ 
  includeInactive: false 
});

console.log(`Found ${allCategories.length} total categories`);
console.log(`Active categories: ${activeCategories.length}`);

The listAssetCategories function (assetCategoryService.ts:8-24) returns categories sorted alphabetically by name.

Getting Active Categories Only

For dropdowns and selection lists, use the dedicated function that returns a lightweight response:

import { listActiveAssetCategories } from '@/services/assetCategoryService';

const categories = await listActiveAssetCategories();
// Returns: Array<{ id: number; name: string; is_active: boolean }>

categories.forEach(cat => {
  console.log(`${cat.id}: ${cat.name}`);
});

This function (assetCategoryService.ts:59-72) only selects id, name, and is_active fields for optimal performance in UI components.

Creating Categories

Prepare Category Data

Define the category name and optional description:

import type { AssetCategoryInsert } from '@/types/AssetCategory';

const newCategory: AssetCategoryInsert = {
  name: 'Electrical Equipment',
  description: 'Electrical panels, transformers, and power distribution equipment',
  is_active: true
};

Create the Category

Use the createAssetCategory function:

import { createAssetCategory } from '@/services/assetCategoryService';

await createAssetCategory(newCategory);
console.log('Category created successfully');

Verify Creation

Reload your category list to confirm the new category appears.

The createAssetCategory function (assetCategoryService.ts:26-29) throws an error if creation fails. Wrap calls in try-catch blocks for proper error handling.

Updating Categories

Modify existing category information:

import { updateAssetCategory } from '@/services/assetCategoryService';
import type { AssetCategoryUpdate } from '@/types/AssetCategory';

const updates: AssetCategoryUpdate = {
  name: 'HVAC & Refrigeration',
  description: 'Updated description with expanded scope'
};

await updateAssetCategory(5, updates);

The updateAssetCategory function (assetCategoryService.ts:31-40) accepts partial updates, so you only need to include fields you want to change.

Update Name
Update Description
Update Multiple Fields

await updateAssetCategory(5, { 
  name: 'Mechanical Equipment' 
});

await updateAssetCategory(5, { 
  description: 'Includes pumps, motors, and conveyors' 
});

await updateAssetCategory(5, {
  name: 'Material Handling',
  description: 'Forklifts, pallet jacks, and conveyor systems',
  is_active: true
});

Activating and Deactivating Categories

Categories use soft deletion to preserve historical data while hiding inactive categories from selection lists.

Toggle Active Status

import { toggleAssetCategoryActive } from '@/services/assetCategoryService';

// Deactivate a category
await toggleAssetCategoryActive(5, false);
console.log('Category deactivated');

// Reactivate a category
await toggleAssetCategoryActive(5, true);
console.log('Category reactivated');

The toggleAssetCategoryActive function (assetCategoryService.ts:42-48) updates only the is_active field.

Impact on Assets

Deactivating a category does NOT affect existing assets assigned to that category. Assets retain their category assignment, but the category won’t appear in new asset creation forms.

When a category is deactivated:

Existing assets keep their category_id reference
Category dropdown lists exclude the inactive category
Asset details still display the category name
Historical data remains intact

Deleting Categories

Categories can be permanently deleted if needed:

import { deleteAssetCategory } from '@/services/assetCategoryService';

await deleteAssetCategory(5);
console.log('Category permanently deleted');

Hard Deletion Alert: The deleteAssetCategory function (assetCategoryService.ts:51-57) permanently removes the category from the database.Before deleting:

Verify no assets are currently using this category
Consider deactivating instead of deleting to preserve historical data
Ensure you have proper backups

Handling Category Dependencies

Before deleting a category, check for dependent assets:

import { getAssets } from '@/services/assetsService';
import { deleteAssetCategory } from '@/services/assetCategoryService';

const categoryId = 5;

// Check for assets using this category
const allAssets = await getAssets();
const dependentAssets = allAssets.filter(
  asset => asset.category_id === categoryId
);

if (dependentAssets.length > 0) {
  console.error(
    `Cannot delete category: ${dependentAssets.length} assets are using it`
  );
  console.log('Dependent assets:', dependentAssets.map(a => a.code));
} else {
  await deleteAssetCategory(categoryId);
  console.log('Category deleted successfully');
}

Common Category Examples

Here are typical asset categories used in CMMS implementations:

HVAC Equipment

Air conditioners, chillers, boilers, air handlers, cooling towers

Electrical Equipment

Transformers, switchgear, panels, generators, UPS systems

Mechanical Equipment

Pumps, motors, compressors, fans, blowers

Plumbing Systems

Water heaters, pumps, valves, piping systems

Building Infrastructure

Elevators, fire suppression, security systems, doors

Production Equipment

Manufacturing machinery, assembly lines, quality control equipment

Material Handling

Forklifts, conveyors, cranes, pallet jacks

Instrumentation

Sensors, meters, monitoring devices, control systems

Category-Based Reporting

Asset categories enable powerful reporting capabilities:

Assets by Category Count

import { getAssets } from '@/services/assetsService';
import { listAssetCategories } from '@/services/assetCategoryService';

const assets = await getAssets();
const categories = await listAssetCategories();

// Count assets per category
const categoryStats = categories.map(category => {
  const count = assets.filter(
    asset => asset.category_id === category.id
  ).length;
  
  return {
    categoryId: category.id,
    categoryName: category.name,
    assetCount: count
  };
});

categoryStats
  .sort((a, b) => b.assetCount - a.assetCount)
  .forEach(stat => {
    console.log(`${stat.categoryName}: ${stat.assetCount} assets`);
  });

Maintenance Cost by Category

import { getAssets } from '@/services/assetsService';
import { getAssetMaintenanceLog } from '@/services/assetsService';

const assets = await getAssets();

// Group maintenance costs by category
const costByCategory = new Map();

for (const asset of assets) {
  if (!asset.category_name) continue;
  
  const logs = await getAssetMaintenanceLog(asset.id);
  
  const totalCost = logs.reduce((sum, log) => {
    return sum + log.labor_cost + log.parts_cost + log.other_cost;
  }, 0);
  
  const current = costByCategory.get(asset.category_name) || 0;
  costByCategory.set(asset.category_name, current + totalCost);
}

// Display results
costByCategory.forEach((cost, categoryName) => {
  console.log(`${categoryName}: $${cost.toFixed(2)}`);
});

Best Practices

Use Descriptive Names

Choose clear, consistent category names that make sense to all users. Avoid abbreviations unless they’re universally understood.✅ Good: “HVAC Equipment”, “Electrical Distribution”
❌ Bad: “EQ1”, “MISC”

Add Detailed Descriptions

Include descriptions that explain what types of assets belong in each category. This helps maintain consistency across teams.

Deactivate Instead of Delete

Use the is_active flag to hide categories rather than deleting them. This preserves historical data and relationships.

Plan Your Hierarchy

Design your category structure before creating many assets. Changing categories later requires updating multiple asset records.

Review Periodically

Regularly review your category list to identify unused or redundant categories that can be consolidated.

Integration with Asset Views

The v_assets view automatically includes category information:

import { getAssets } from '@/services/assetsService';

const assets = await getAssets();
// Each asset includes category_name from the joined table

assets.forEach(asset => {
  console.log(`Asset: ${asset.code}`);
  console.log(`Category: ${asset.category_name ?? 'Uncategorized'}`);
});

The join happens in the database view definition, providing optimal performance for category filtering and display (assetsService.ts:47-53).

Getting Started

Core Features

Inventory Management

Asset Management

Reporting & Analytics

Administration

Overview

Category Data Structure

Managing Categories

Listing All Categories

Getting Active Categories Only

Creating Categories

Updating Categories

Activating and Deactivating Categories

Toggle Active Status

Impact on Assets

Deleting Categories

Handling Category Dependencies

Common Category Examples

HVAC Equipment

Electrical Equipment

Mechanical Equipment

Plumbing Systems

Building Infrastructure

Production Equipment

Material Handling

Instrumentation

Category-Based Reporting

Assets by Category Count

Maintenance Cost by Category

Best Practices

Integration with Asset Views

Next Steps

Create Assets

Asset Overview

Build docs developers (and LLMs) love

Getting Started

Core Features

Inventory Management

Asset Management

Reporting & Analytics

Administration

Documentation Index

​Overview

​Category Data Structure

​Managing Categories

​Listing All Categories

​Getting Active Categories Only

​Creating Categories

​Updating Categories

​Activating and Deactivating Categories

​Toggle Active Status

​Impact on Assets

​Deleting Categories

​Handling Category Dependencies

​Common Category Examples

HVAC Equipment

Electrical Equipment

Mechanical Equipment

Plumbing Systems

Building Infrastructure

Production Equipment

Material Handling

Instrumentation

​Category-Based Reporting

​Assets by Category Count

​Maintenance Cost by Category

​Best Practices

​Integration with Asset Views

​Next Steps

Create Assets

Asset Overview

Build docs developers (and LLMs) love

Overview

Category Data Structure

Managing Categories

Listing All Categories

Getting Active Categories Only

Creating Categories

Updating Categories

Activating and Deactivating Categories

Toggle Active Status

Impact on Assets

Deleting Categories

Handling Category Dependencies

Common Category Examples

Category-Based Reporting

Assets by Category Count

Maintenance Cost by Category

Best Practices

Integration with Asset Views

Next Steps