Locations Management

The Locations Management interface allows administrators to maintain geographic data used throughout AutoLog, including countries, cities, and parking facilities.

Overview

Location management is divided into three main areas:

Countries - Country-level geographic data
Cities - City/municipality information
Parkings - Parking facility locations (future)

This geographic hierarchy ensures consistent location data across user profiles, vehicle assignments, and operational reporting.

Countries Management

Accessing Countries

Navigate to Administration > Locations > Countries to manage country data.

Permissions Required

Action	Permission
View countries	`ver_paises`
Create countries	`crear_paises`
Edit countries	`editar_paises`
Delete countries	`eliminar_paises` or `editar_paises`

Admin users have access to all location management features by default.

Creating a Country

Open Country Form

Click the New Country button in the toolbar

Enter Country Name

nombre

string

required

Country name (2-60 characters)

Examples:

Honduras
Guatemala
El Salvador

Save

Click Save to create the country. The form validates:

Minimum 2 characters
Maximum 60 characters
Required field (cannot be empty)

Validation Schema:

const validationSchema = yup.object({
  nombre: yup
    .string()
    .transform((v) => (typeof v === 'string' ? v.trim() : v))
    .min(2, 'Mínimo 2 caracteres')
    .max(60, 'Máximo 60 caracteres')
    .required('Requerido'),
});

Editing a Country

To modify an existing country:

Click the three-dot menu on the country row
Select Edit
Update the country name
Click Save

The country is updated using:

await updateCountry(countryId, {
  id: countryId,
  nombre: trimmedName
});

Deleting a Country

Deleting a country that is referenced by cities or users may cause data integrity issues. Consider the impact before deletion.

To delete a country:

Click the three-dot menu on the country row
Select Delete (if available in your configuration)
Confirm the deletion

Delete functionality is currently commented out in the UI but can be enabled by uncommenting the delete menu item in /pages/Administration/Locations/Countries.jsx:382-389.

Searching Countries

Use the search bar to filter countries by name:

Real-time filtering as you type
Case-insensitive matching
Click the X icon to clear search

Cities Management

Accessing Cities

Navigate to Administration > Locations > Cities to manage city data.

Permissions Required

Action	Permission
View cities	`ver_ciudades`
Create cities	`crear_ciudades`
Edit cities	`editar_ciudades`
Delete cities	`eliminar_ciudades` or `editar_ciudades`

Creating a City

Cities must be associated with a country.

Open City Form

Click the New City button in the toolbar

Enter City Details

nombre

string

required

City name (minimum 2 characters)

id_pais

select

required

Select the country this city belongs to

Save

Click Save to create the city

Validation Schema:

const validationSchema = yup.object({
  nombre: yup
    .string()
    .transform((v) => (typeof v === 'string' ? v.trim() : v))
    .min(2, 'Mínimo 2 caracteres')
    .required('Requerido'),
  id_pais: yup.string().required('Debes seleccionar un país'),
});

Editing a City

To modify an existing city:

Click the three-dot menu on the city row
Select Edit
Update the city name or country
Click Save

Changing a city’s country association may affect users and vehicles assigned to that city. Verify impact before saving.

Deleting a City

To delete a city:

Click the three-dot menu on the city row
Select Delete
Confirm the action

Deleting a city removes it from user profiles and may affect location-based reports. Ensure no active users or assets are assigned to this city.

Searching Cities

The city search filters by:

City name
Country name (if provided by backend as pais or pais_nombre)

Search is performed in real-time with case-insensitive matching.

Cities Display

Cities are displayed in a table with:

Column	Description
Name	City name
Country	Country name in a soft chip
Actions	Edit/Delete menu

Country information appears as a colored chip for quick visual reference.

Data Loading

Countries Loading

Countries are loaded using:

const data = await getCountries();
setCountries(Array.isArray(data) ? data : []);

Cities Loading

Cities and countries are loaded in parallel for efficiency:

const [citiesData, countriesData] = await Promise.all([
  getCities(),
  getCountries(),
]);

This ensures:

Fast page load times
Country dropdown is immediately available
Reduced waiting time for users

UI States and Error Handling

Loading State

While data is loading:

Circular progress indicator displayed
Table is hidden
User cannot perform actions

Error State

If data loading fails:

Error card displayed with descriptive message
Retry button to reload data
Network errors are detected with regex: /failed to fetch|network/i

Empty State

When no locations exist:

Icon with “No data” message
Encouragement to create first entry
New button remains available

No Search Results

When search yields no matches:

“No matches found” message in table
Suggestion to clear or modify search
All data preserved, only display filtered

Location Services API

Countries API

import {
  getCountries,
  addCountry,
  updateCountry,
  deleteCountry,
} from '@/services/LocationServices';

Get all countries:

const countries = await getCountries();
// Returns: Array of { id, nombre }

Create country:

const result = await addCountry({ nombre: 'Nicaragua' });

Update country:

const result = await updateCountry(countryId, {
  id: countryId,
  nombre: 'Updated Name'
});

Delete country:

const result = await deleteCountry(countryId);

Cities API

import {
  getCities,
  addCity,
  updateCity,
  deleteCity,
} from '@/services/LocationServices';

Get all cities:

const cities = await getCities();
// Returns: Array of { id, nombre, id_pais, pais_nombre }

Create city:

const result = await addCity({
  nombre: 'Tegucigalpa',
  id_pais: '1'
});

Update city:

const result = await updateCity(cityId, {
  id: cityId,
  nombre: 'Updated Name',
  id_pais: '1'
});

Delete city:

const result = await deleteCity(cityId);

Integration with User Management

Locations integrate with user management:

User City Assignment

When creating or editing users:

Cities are loaded as autocomplete options
User selects city from dropdown
City ID is stored in id_ciudad field
City name is displayed in user table

<Autocomplete
  options={ciudades}
  getOptionLabel={(opt) => opt?.nombre ?? opt?.ciudad ?? ''}
  value={ciudades.find(c => String(c.id) === String(formik.values.ciudad)) || null}
  onChange={(_, opt) => formik.setFieldValue('ciudad', opt ? String(opt.id) : '')}
/>

City Resolution

User city names are resolved using:

const getCiudadNombre = useCallback(
  (id) => ciudades.find(c => String(c.id) === String(id))?.nombre || '',
  [ciudades]
);

Best Practices

Location Data Management

Standardize Names: Use official country and city names
Avoid Duplicates: Check for existing entries before creating new ones
Maintain Hierarchy: Always assign cities to correct countries
Plan Before Deleting: Verify no users or assets depend on location
Regular Audits: Review location data quarterly for accuracy

Data Integrity Warnings

Deleting a country with associated cities will cause orphaned records
Deleting a city assigned to users will break user profiles
Always check dependencies before deletion
Consider deactivation instead of deletion for historical data
Backup location data before bulk changes

Troubleshooting

Countries Not Loading

Verify ver_paises permission
Check network connection
Look for errors in browser console
Ensure LocationServices endpoints are configured
Click Retry button if error state is shown

Cities Not Loading

Verify ver_ciudades permission
Check if countries loaded successfully (cities depend on countries)
Review network tab for failed API calls
Verify backend returns proper format: { id, nombre, id_pais, pais_nombre }

Ensure countries were loaded before opening form
Check countriesList state in component
Verify parallel loading didn’t fail for countries
Reload page to trigger fresh data fetch

Save Operations Failing

Check form validation errors (red text below fields)
Verify required fields are filled
Ensure country is selected for cities
Check backend logs for validation errors
Verify you have create/edit permissions

Search Not Working

Ensure data has loaded (not in loading state)
Try clearing search and re-entering
Check if special characters are causing issues
Verify search term matches actual data

Performance Considerations

Lazy Loading

Location components implement efficient loading patterns:

Data loaded only when page is accessed
Parallel requests for cities and countries
Minimal re-renders with React hooks

Filtering Performance

Search filtering uses useMemo for optimal performance:

const filtered = useMemo(() => {
  const s = search.toLowerCase();
  return cities.filter(c => {
    const cityName = (c.nombre || '').toLowerCase();
    const countryName = (c.pais || '').toLowerCase();
    return cityName.includes(s) || countryName.includes(s);
  });
}, [cities, search]);

Filtering recalculates only when cities or search changes.

Parkings Management

AutoLog includes a complete parking facility management system for tracking vehicle parking locations.

Overview

The Parkings feature (/parkings) allows you to:

Create and manage parking location records
Associate parking spots with cities
Track available parking facilities
Filter and search parking locations
Assign vehicles to specific parking spots

Data Structure

Each parking record includes:

{
  id_ubicacion: 5,
  nombre_ubicacion: "Main Office Parking - Building A",
  id_ciudad: 3,
  ciudad: "San Pedro Sula",  // Auto-populated from city relationship
  nombre_ciudad: "San Pedro Sula"
}

Creating a Parking Location

Navigate to Parkings

Go to Administration → Parkings (/parkings)

Click Create

Click the + Add Parking button (requires crear_estacionamiento permission)

Fill Details

Enter the parking information:

Location Name (nombre_ubicacion): Descriptive name (min 2 characters, required)
City (id_ciudad): Select from configured cities (required)

Submit

Click Save to create the parking location

Permissions

Action	Permission	Description
View parkings	`ver_estacionamientos`	View parking list
Create parking	`crear_estacionamiento`	Add new parking locations
Edit parking	`editar_estacionamiento`	Modify existing parkings
Delete parking	`eliminar_estacionamiento`	Remove parking locations

Search and Filter

The parkings list supports real-time search:

Search by parking name
Search by city name
Case-insensitive matching

// Example: Filtering parkings
const filtered = parkings.filter((p) => {
  const name = (p.nombre_ubicacion || "").toLowerCase();
  const cityName = (p.ciudad || p.nombre_ciudad || "").toLowerCase();
  return name.includes(searchTerm) || cityName.includes(searchTerm);
});

API Services

From ParkingServices.jsx: getParkings()

Returns: Array of parking objects
Endpoint: endpoints.getParkings

addParking(parking)

Parameters: { nombre_ubicacion, id_ciudad }
Returns: Created parking object

updateParking(id, parking)

Parameters: Parking ID and updated data
Returns: Updated parking object

deleteParking(id)

Parameters: Parking ID
Returns: Success confirmation

Validation Rules

From the Yup schema:

{
  nombre_ubicacion: yup.string()
    .transform((v) => typeof v === "string" ? v.trim() : v)
    .min(2, "Minimum 2 characters")
    .required("Required"),
  id_ciudad: yup.string()
    .required("Must select a city")
}

Integration with Vehicles

Parkings can be assigned to vehicles through the id_ubicacion_actual field, enabling:

Current vehicle location tracking
Parking utilization reports
Location-based vehicle searches

User Management - Assign users to locations
Permissions - Configure location permissions
Settings - System configuration

Get Started

Core Features

User Guides

Administration

Advanced

​Overview

​Countries Management

​Accessing Countries

​Permissions Required

​Creating a Country

​Editing a Country

​Deleting a Country

​Searching Countries

​Cities Management

​Accessing Cities

​Permissions Required

​Creating a City

​Editing a City

​Deleting a City

​Searching Cities

​Cities Display

​Data Loading

​Countries Loading

​Cities Loading

​UI States and Error Handling

​Loading State

​Error State

​Empty State

​No Search Results

​Location Services API

​Countries API

​Cities API

​Integration with User Management

​User City Assignment

​City Resolution

​Best Practices

​Troubleshooting

​Countries Not Loading

​Cities Not Loading

​Country Dropdown Empty in City Form

​Save Operations Failing

​Search Not Working

​Performance Considerations

​Lazy Loading

​Filtering Performance

​Parkings Management

​Overview

​Data Structure

​Creating a Parking Location

​Permissions

​Search and Filter

​API Services

​Validation Rules

​Integration with Vehicles

​Related Pages

Build docs developers (and LLMs) love

Overview

Countries Management

Accessing Countries

Permissions Required

Creating a Country

Editing a Country

Deleting a Country

Searching Countries

Cities Management

Accessing Cities

Permissions Required

Creating a City

Editing a City

Deleting a City

Searching Cities

Cities Display

Data Loading

Countries Loading

Cities Loading

UI States and Error Handling

Loading State

Error State

Empty State

No Search Results

Location Services API

Countries API

Cities API

Integration with User Management

User City Assignment

City Resolution

Best Practices

Troubleshooting

Countries Not Loading

Cities Not Loading

Country Dropdown Empty in City Form

Save Operations Failing

Search Not Working

Performance Considerations

Lazy Loading

Filtering Performance

Parkings Management

Overview

Data Structure

Creating a Parking Location

Permissions

Search and Filter

API Services

Validation Rules

Integration with Vehicles

Related Pages