Locations

Manage facilities, sites, and location-based access control

Overview

Locations represent physical facilities, sites, or buildings within your organization. Users, assets, work orders, and other resources can be assigned to locations for organizational and access control purposes.

Managing locations requires locations:full_access. Viewing locations only requires locations:read.

Location Data Model

Field	Type	Description
id	Integer	Unique location identifier
name	String	Location name (e.g., “Edificio Central”)
code	String	Short code for the location (e.g., “EC01”)
description	Text	Optional description
is_active	Boolean	Whether the location is available for use
created_at	Timestamp	Creation date
updated_at	Timestamp	Last modification date
created_by	UUID	User who created the location
updated_by	UUID	User who last updated the location

Location Management Workflows

Creating a Location

1. Navigate to Locations

   Go to Administration → Locations (or use the location management interface).

2. Click 'Crear Ubicación'

   Opens the location creation form.

3. Fill in Location Details

   • Name: Descriptive location name (required)
   • Code: Short identifier code (required, must be unique)
   • Description: Optional detailed description
   • Active: Whether the location is active (default: true)
4. Submit

   Click “Crear”. The location is created and can immediately be assigned to users and resources.

Location codes are often used in filters and dropdowns, so choose concise, meaningful codes (e.g., “HQ”, “WH01”, “FAC-A”).

Editing a Location

1. Locate the Location

   Use the locations list to find the location you want to edit.

2. Click 'Editar'

   Opens the edit form with the location’s current details.

3. Modify Fields

   Update any of the following:

   • Name
   • Code
   • Description
   • Active status
4. Save Changes

   Click “Guardar”. The changes are applied immediately.

Changing a location’s code may affect filters and reports that reference the old code.

Activating/Deactivating a Location

Deactivating a location hides it from dropdowns and filters without deleting it:

1. Locate the Location

   Find the location in the locations list.

2. Toggle Active Status

   Click the “Activar” or “Desactivar” button.

3. Confirm

   Confirm the action if prompted.

Effects of Deactivation:

• Location no longer appears in user assignment dropdowns
• Existing users/resources remain assigned to the location
• Historical data is preserved
• Location can be reactivated at any time

Requires locations:disable permission.

Deleting a Location

Deletion is permanent and may affect users, assets, and work orders assigned to this location. Consider deactivation instead.

1. Check Dependencies

   Verify that no critical resources are assigned to the location:

   • Users
   • Assets
   • Active work orders
2. Initiate Deletion

   Click the “Eliminar” button on the location’s row.

3. Confirm

   Confirm the deletion in the warning dialog.

Requires locations:delete permission.

Using Locations for Access Control

User Location Assignment

Users can be assigned to a location during creation or editing:

1. Open the user creation/edit form
2. Select a location from the “Ubicación” dropdown
3. Save the user

Users with a location assignment can be filtered by location in user management views.

Location-Based Filtering

Many modules support location filtering:

• User Management: Filter users by location
• Work Orders: Filter work orders by location
• Assets: Filter assets by location
• Reports: Generate reports for specific locations

Row-Level Security (RLS) with Locations

Locations can be used in RLS policies to restrict data access:

CREATE POLICY "work_orders_location_rbac" ON work_orders
  FOR SELECT
  USING (
    -- User can see work orders from their assigned location
    location_id = (SELECT location_id FROM users WHERE id = auth.uid())
    OR
    -- OR user has full access permission
    current_user_has_permission('work_orders:read')
  );

Location-based RLS policies must be implemented in the database schema. Consult your database administrator.

Service Layer Reference

Location operations are handled by locationService.ts:

Key Functions

// List all locations (with optional filters)
listLocations({
  includeInactive?: boolean,
  limit?: number
}): Promise<Location[]>

// Get minimal location data for dropdowns
listLocationOptions(): Promise<LocationOption[]>

// Get a single location by ID
getLocationById(id: number): Promise<Location | null>

// Get a location by code
getLocationByCode(code: string): Promise<Location | null>

// Create a new location
createLocation(payload: LocationInsert): Promise<Location>

// Update an existing location
updateLocation(id: number, patch: LocationUpdate): Promise<Location>

// Toggle location active status
toggleLocationActive(id: number, nextActive: boolean): Promise<Location>

// Delete a location
deleteLocation(id: number): Promise<void>

Example: Fetching Active Locations

import { listLocations } from '../services/locationService';

const activeLocations = await listLocations({
  includeInactive: false,
  limit: 500
});

Example: Creating a Location

import { createLocation } from '../services/locationService';

const newLocation = await createLocation({
  name: 'Warehouse A',
  code: 'WH-A',
  description: 'Primary storage facility',
  is_active: true
});

console.log('Created location:', newLocation.id);

Database Schema

locations Table

CREATE TABLE locations (
  id SERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  code TEXT NOT NULL UNIQUE,
  description TEXT,
  is_active BOOLEAN DEFAULT TRUE,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ,
  created_by UUID REFERENCES auth.users(id),
  updated_by UUID REFERENCES auth.users(id)
);

RLS Policies

-- Users can view active locations
CREATE POLICY "locations_select_active" ON locations
  FOR SELECT
  USING (is_active = TRUE OR current_user_has_permission('locations:read'));

-- Full access users can insert/update/delete
CREATE POLICY "locations_insert_rbac" ON locations
  FOR INSERT
  WITH CHECK (current_user_has_permission('locations:full_access'));

CREATE POLICY "locations_update_rbac" ON locations
  FOR UPDATE
  USING (current_user_has_permission('locations:full_access'));

CREATE POLICY "locations_delete_rbac" ON locations
  FOR DELETE
  USING (current_user_has_permission('locations:delete'));

Best Practices

Use Consistent Naming

Adopt a naming convention for location codes (e.g., building prefix + number).

Deactivate Instead of Delete

Preserve historical data by deactivating unused locations rather than deleting them.

Assign Users to Locations

Ensure all users have a location assignment for better filtering and reporting.

Review Location Assignments Regularly

Audit user and asset location assignments to ensure accuracy.

Use Descriptions for Context

Add descriptions to locations to clarify their purpose or physical address.

Limit Location Count

Too many locations can complicate navigation. Group similar locations when possible.

Permissions Required

Action	Permission Code
View locations	locations:read
Create locations	locations:create
Edit locations	locations:update
Activate/deactivate	locations:disable
Delete locations	locations:delete
Full access (all operations)	locations:full_access

Troubleshooting

”Code already exists”

Cause: Location codes must be unique.

Solution: Choose a different code or update the existing location.

Location Not Appearing in Dropdowns

Cause: The location is marked as is_active = false.

Solution: Activate the location or use the “Include inactive” filter.

Cannot Delete Location

Possible causes:

1. Users are assigned to the location → Reassign users first
2. Assets are assigned to the location → Reassign assets
3. Missing locations:delete permission → Request permission from admin

Location Filter Not Working

Cause: The filter may be comparing by name, code, or ID inconsistently.

Solution: Verify that the filter is using the correct field (usually location_id).

Related Topics

• User Management
• Roles & Permissions
• Settings