Locations

Overview

The Locations feature is a hierarchical location management system that supports up to 4 levels of organizational structure. It provides comprehensive location management including status tracking, provider associations, user permissions, and automated status updates based on dates.

Hierarchical Structure

The system supports flexible organizational hierarchies with 1-4 levels:

• Level 1: Direct locations only
• Level 2: Group → Locations (e.g., Division → Locations)
• Level 3: Group → Group → Locations (e.g., Division → District → Locations)
• Level 4: Group → Group → Group → Locations (e.g., Region → Division → District → Locations)

The depth is configured per tenant via tenantSettingsRow.locationsDepth.

Database Models

Location Model

Primary model for individual locations with fields including:

• Basic info: name, code, description, status
• Address: streetAddressLine1/2, city, stateProvince, postalCode, country
• Contact: phone, email, managerName, managerEmail
• Coordinates: latitude, longitude, timeZone
• Important dates: preSaleStartDate, openingDate, closingDate
• Parent relationships: parentLevel1Id, parentLevel2Id, parentLevel3Id, parentLevel4Id

LocationLevel Model

Represents organizational groups/folders:

• level: Numeric level (1-4)
• type: Type of group (e.g., "division", "district")
• Owner information and parent relationships

Routes

Main Routes

• /app/{tenant}/locations - List all locations and levels
• /app/{tenant}/locations/{id} - Individual location details (tabbed interface)
• /app/{tenant}/locations/levels/{id} - Location level management
• /app/{tenant}/locations/export - CSV export with filters

Key Features

Location Status Management

Locations have automatic status transitions based on configured dates:

• Pre-Sale: When preSaleStartDate is reached
• Open: When openingDate is reached
• Closed: When closingDate is reached
• Temporarily Closed: Manual override (not auto-updated)

Status updates happen automatically via cron job (location-status-update).

Provider Integration

Locations can be associated with providers through LocationProvider junction table:

• Multiple providers per location
• Activation/deactivation tracking
• Provider contracts and types

User Permissions

Two permission models:

1. LocationUser: Direct location access

   • User assigned to specific locations
   • Role-based permissions per location

2. LocationLevelUser: Group-level access

   • User assigned to location levels
   • Inherits access to all child locations

Operating Hours

Flexible operating hours system:

• Daily schedules with open/close times
• Individual 24-hour flags per day
• Stored as JSON in operatingHours field

Format:

[
  { "day": 1, "open": "09:00", "close": "17:00", "is24Hours": false },
  { "day": 2, "open": "09:00", "close": "17:00", "is24Hours": false }
]

Import/Export

• Import: Bulk location creation via CSV
• Export: Full data export with filters
• Maintains data relationships during import
• Validates required fields and formats

Website Configuration

Each location can have its own website settings:

• Custom URL and title
• Template selection
• Social media links
• HTML code injection
• Online booking configuration

Notes and Activity Tracking

• LocationNote: User and system notes
• LocationChangeLog: Detailed audit trail
• Tracks all field changes with before/after values
• User attribution for changes

Cron Jobs

Location Status Update Cron

Automatically updates location statuses based on configured dates:

• Type: location-status-update
• Frequency: Can be scheduled daily
• Process:
  1. Queries all locations with date fields
  2. Calculates correct status using calculateLocationStatus()
  3. Updates mismatched statuses
  4. Creates system notes for changes
  5. Skips "temporarily-closed" locations

Search and Filtering

Locations support comprehensive filtering:

• Text search: Name, code, address fields
• Status filter: Open, closed, pre-sale, etc.
• Level filter: By parent groups
• Provider filter: By associated providers
• User permissions: Automatically applied

Best Practices

1. Hierarchical Design: Choose appropriate depth (1-4) based on organizational structure
2. Status Management: Use date fields for automatic status transitions
3. Permissions: Assign users at appropriate levels for inherited access
4. Audit Trail: All changes are tracked in LocationChangeLog
5. Bulk Operations: Use import/export for large-scale changes
6. Provider Management: Link providers at location level for granular control

Common Operations

Creating a Location

1. Navigate to /app/{tenant}/locations
2. Click "Add Location"
3. Select parent level (if applicable)
4. Fill required fields: name, address, contact
5. Configure optional settings: website, hours, dates
6. Save and location status auto-calculates

Bulk Import

1. Download template from locations page
2. Fill CSV with location data
3. Upload via import dialog
4. System validates and creates locations
5. Maintains parent relationships

Status Override

1. Edit location
2. Go to Blend tab
3. Change status to "temporarily-closed"
4. This prevents automatic updates

Managing Operating Hours

1. Edit location
2. Go to Website tab
3. Set hours for each day
4. Toggle 24-hour operation per day
5. Changes tracked in activity log

Integration Points

• Providers: Via LocationProvider junction
• Employees: Via Employee.locationId
• Users: Via LocationUser and LocationLevelUser
• Apps: Various apps can reference locations
• Contracts: Through provider associations
• Audiences: Location-based audience segmentation