---
title: "Time Groups Module Documentation"
description: "Documentation for Time Groups"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [Schedule Types & Modalities](#4-schedule-types--modalities)
7. [Configuration Fields Reference](#5-configuration-fields-reference)
8. [Holiday Presets & Quick Setup](#6-holiday-presets--quick-setup)
9. [Time Conditions Integration](#7-time-conditions-integration)
10. [Common Scenarios & Examples](#8-common-scenarios--examples)
11. [Evaluation Engine & Lua Architecture](#9-evaluation-engine--lua-architecture)
12. [Model Context Protocol (MCP) AI Integration](#10-model-context-protocol-mcp-ai-integration)
13. [Troubleshooting & Diagnostics](#11-troubleshooting--diagnostics)
14. [Glossary](#12-glossary)

---

## Navigation & Access

To access the Time Groups module:
1. Log in to the Ring2All Web Portal.
2. In the left navigation sidebar, expand **PBX Engine**.
3. Under **Incoming Call Tools**, click **Time Groups** (`/pbx/incoming-tools/time-groups`).

---

## Screenshots & Visual Interface

### Time Groups Overview
Displays all defined schedule groups, schedule rules count, status, and edit shortcuts.
![Time Groups List View](/screenshots/pbx/incoming-tools/time-groups-list.png)

### Time Group Configuration Form
Provides configuration for group name, description, status toggle, and the recurring schedule rules builder (weekly intervals, specific dates, or relative holidays).
![Time Group Configuration Form](/screenshots/pbx/incoming-tools/time-groups-form.png)

---

## 1. Module Overview (Technical)

### What Are Time Groups?

Time Groups define **reusable schedules, calendars, and time intervals** used to control **time-based call routing**. They are referenced by **Time Conditions**, which evaluate incoming calls in real time and decide whether to route them to a *Match Destination* (e.g., Main IVR) or a *No-Match Destination* (e.g., After-Hours Voicemail).

### Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Ring2All Time-Based Routing Engine                       │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  Time Group: "Company Holidays & Business Hours"                            │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │ Schedule 1 (Weekly):        Mon-Fri, 09:00 - 17:00                     │ │
│  │ Schedule 2 (Specific Date): "Christmas Day", Dec 25 • All Day          │ │
│  │ Schedule 3 (Relative Date): "Thanksgiving", 4th Thu in Nov • All Day   │ │
│  │ Schedule 4 (Relative Date): "Memorial Day", Last Mon in May • All Day  │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                      │                                      │
│  Referenced by:                      ▼                                      │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │ Time Condition: "Main Office Inbound"                                 │ │
│  │                                                                        │ │
│  │ If MATCH (Within configured hours):                                    │ │
│  │   → Route to Main IVR / Ring Group                                     │ │
│  │                                                                        │ │
│  │ If NO MATCH (After hours / Holiday closure):                           │ │
│  │   → Route to After-Hours Auto-Attendant / Voicemail                    │ │
│  │                                                                        │ │
│  │ Manual Override Feature Code: *81 (Toggle via BLF)                     │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                      │                                      │
│                                      ▼                                      │
│  ┌────────────────────────────────────────────────────────────────────────┐ │
│  │         Telephony Server Lua Engine (routing/time_condition.lua)             │ │
│  │                                                                        │ │
│  │  1. Identify tenant and domain_id                                      │ │
│  │  2. Fetch all schedules for assigned time group                        │ │
│  │  3. Evaluate weekly days, specific dates, or relative holiday rules    │ │
│  │  4. Apply override status (override_on / override_off / default)       │ │
│  │  5. Route call seamlessly with topology hiding and CDR tagging         │ │
│  └────────────────────────────────────────────────────────────────────────┘ │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### Key Database Tables

| Table | Schema | Description |
|---|---|---|
| `public.time_groups` | `ss_telephony` | Time group definitions (domain-scoped) |
| `public.time_group_schedules` | `ss_telephony` | Schedule intervals (Weekly, Specific Dates, Relative Rules) |
| `public.time_conditions` | `ss_telephony` | Routing rules linking Time Groups with Match/No-Match destinations |

### Key Source Files

| Component | Path | Description |
|---|---|---|
| **Frontend Form View** | `ring2all/web/src/modules/timeGroups/TimeGroupFormView.tsx` | Time Group creation & editing form |
| **Schedules Section UI** | `ring2all/web/src/modules/timeGroups/components/SchedulesSection.tsx` | Interactive schedule cards, mode switcher & holiday presets |
| **Backend Service** | `ring2all/api/src/modules/telephony/time-groups/services/timeGroupService.ts` | Multi-tenant database service with transactional integrity |
| **Routing Handler** | `telephony/freeswitch/lua/main/xml_handlers/routing/time_condition.lua` | Real-time call routing handler with mathematical relative date evaluation |
| **Feature Code Handler** | `telephony/freeswitch/lua/main/xml_handlers/time_condition/time_condition.lua` | BLF toggle (*81) & audio prompt playback |

---

## 2. Module Overview (Commercial/Business)

### Business Value

Time Groups empower organizations to automate customer interactions around the clock without manual intervention:

| Challenge Without Time Groups | Solution With Ring2All Time Groups |
|---|---|
| Calls ring unattended outside office hours | Automatically routes after-hours calls to specialized greetings or voicemail |
| Need to reprogram floating holidays (like Thanksgiving) every year | **Relative Date Rules** calculate holidays automatically every year |
| Inability to distinguish individual rules in holiday lists | **Named Schedule Labels** allow admins to easily track and modify holidays |
| Rigid routing requiring manual switchboard toggles | Full automation with manual BLF feature code override (`*81`) |

---

## 3. Module Overview (End User/Administrator)

Administrators can configure sophisticated time profiles with zero programming:

- **Multiple Schedules per Group**: Combine regular weekday hours, weekend hours, and all national holidays inside a single group.
- **Named Intervals**: Tag each entry with a friendly label (e.g. *"Thanksgiving Day"*, *"Summer Friday Hours"*, *"Christmas Closure"*).
- **Natural Language Summary**: Every schedule card displays a real-time badge (e.g., `4th Thursday of November • All Day`).
- **One-Click Holiday Presets**: Preload all US or Mexican federal holidays instantly.
- **All-Day Mode**: 1-click toggle to cover full 24-hour periods without typing times manually.

---

## 4. Schedule Types & Modalities

Each schedule interval inside a Time Group can be configured in one of **three powerful modalities**:

### 1. 🗓️ Weekly Days (`weekly`)
- **Use Case**: Regular business hours, shift rotations, or weekend support.
- **Controls**:
  - Multi-select day buttons: `[Mon] [Tue] [Wed] [Thu] [Fri] [Sat] [Sun]`.
  - Start Time & End Time (or *All Day* toggle).
  - *Optional Seasonal Range*: Set `Valid From` and `Valid Until` dates to apply the weekly pattern only during a specific season (e.g., Summer Hours from June 1 to August 31).

### 2. 📅 Specific Date / Range (`specific_date`)
- **Use Case**: Fixed single-day holidays (e.g. Christmas, Independence Day) or multi-day company closures.
- **Controls**:
  - `Start Date` (e.g. `2026-12-25`).
  - `End Date` (optional, for multi-day periods like `2026-12-24` to `2026-12-26`).
  - Start/End Time or *All Day*.

### 3. 🔄 Relative Date / Floating Holiday Rule (`relative_date`)
- **Use Case**: Floating national holidays that change numeric day every year (e.g., Thanksgiving, Memorial Day, Labor Day, Martin Luther King Jr. Day).
- **Controls**:
  - **Occurrence (Ordinal)**: `1st (First)`, `2nd (Second)`, `3rd (Third)`, `4th (Fourth)`, `5th (Fifth)`, `Last`.
  - **Day of Week**: `Monday`, `Tuesday`, `Wednesday`, `Thursday`, `Friday`, `Saturday`, `Sunday`.
  - **Month**: `January` through `December` (or `Every Month`).
  - **Example**: `4th` `Thursday` of `November` • *All Day* (Thanksgiving).
  - **Advantage**: **Zero yearly maintenance**. The PBX calculates the exact calendar day dynamically year after year.

---

## 5. Configuration Fields Reference

### Time Group Main Settings

| Field | Type | Description | Example |
|---|---|---|---|
| **Group Name** | String (Required) | Unique identifier for the Time Group | `Business Hours & Holidays` |
| **Description** | String (Optional) | Detailed notes about the schedule | `Corporate schedule for HQ offices` |
| **Enabled** | Boolean | Toggles active state of the group | `true` |

### Schedule Interval Fields (`time_group_schedules`)

| Field | Type | Modality | Description |
|---|---|---|---|
| **Schedule Label (`name`)** | String | All | Name of the holiday or interval (e.g. `Thanksgiving`) |
| **Schedule Type (`schedule_type`)** | Enum | All | `weekly` \| `specific_date` \| `relative_date` |
| **Days of Week (`day_of_week`)** | Array | `weekly` | `['mon', 'tue', 'wed', 'thu', 'fri']` |
| **Start Date (`start_date`)** | Date | `specific_date` / `weekly` | Start date boundary (`YYYY-MM-DD`) |
| **End Date (`end_date`)** | Date | `specific_date` / `weekly` | End date boundary (`YYYY-MM-DD`) |
| **Occurrence (`ordinal_position`)** | Enum | `relative_date` | `first` \| `second` \| `third` \| `fourth` \| `fifth` \| `last` |
| **Relative Weekday (`relative_day_of_week`)** | Enum | `relative_date` | `mon` \| `tue` \| `wed` \| `thu` \| `fri` \| `sat` \| `sun` |
| **Month of Year (`month_of_year`)** | Integer | `relative_date` | `1` (January) to `12` (December), or `0` for all months |
| **All Day (`is_all_day`)** | Boolean | All | Sets active period to `00:00:00 - 23:59:59` |
| **Start Time (`start_time`)** | Time | All (if not All Day) | Beginning of active period (`HH:MM:SS`) |
| **End Time (`end_time`)** | Time | All (if not All Day) | End of active period (`HH:MM:SS`) |

---

## 6. Holiday Presets & Quick Setup

The interface includes a quick-load menu **"Add Preset..."** to insert preconfigured national holidays with a single click:

### 🇺🇸 US Federal Holidays Preset
1. **New Year's Day**: Jan 1 (Specific Date • All Day)
2. **Martin Luther King Jr. Day**: 3rd Monday in January (Relative Date • All Day)
3. **Presidents' Day**: 3rd Monday in February (Relative Date • All Day)
4. **Memorial Day**: Last Monday in May (Relative Date • All Day)
5. **Juneteenth**: June 19 (Specific Date • All Day)
6. **Independence Day**: July 4 (Specific Date • All Day)
7. **Labor Day**: 1st Monday in September (Relative Date • All Day)
8. **Columbus Day**: 2nd Monday in October (Relative Date • All Day)
9. **Veterans Day**: November 11 (Specific Date • All Day)
10. **Thanksgiving Day**: 4th Thursday in November (Relative Date • All Day)
11. **Christmas Day**: December 25 (Specific Date • All Day)

### 🇲🇽 Mexican National Holidays Preset
1. **Año Nuevo**: 1 de Enero (Fecha Específica • Todo el Día)
2. **Día de la Constitución**: 1er Lunes de Febrero (Fecha Relativa • Todo el Día)
3. **Natalicio de Benito Juárez**: 3er Lunes de Marzo (Fecha Relativa • Todo el Día)
4. **Día del Trabajo**: 1 de Mayo (Fecha Específica • Todo el Día)
5. **Día de la Independencia**: 16 de Septiembre (Fecha Específica • Todo el Día)
6. **Día de la Revolución**: 3er Lunes de Noviembre (Fecha Relativa • Todo el Día)
7. **Navidad**: 25 de Diciembre (Fecha Específica • Todo el Día)

---

## 7. Time Conditions Integration

To activate a Time Group, link it to a **Time Condition** under **Incoming Tools → Time Conditions**:

```
[Inbound Call on DID +1-800-555-0199]
                 │
                 ▼
     [Time Condition: "HQ Main"]
                 │
      Is Current Time within
     Time Group "Business Hours"?
              ╱     ╲
            YES      NO (or Holiday)
            ╱         ╲
           ▼           ▼
   [Main IVR Menu]   [After-Hours Voicemail]
```

### Manual Override & Busy Lamp Field (BLF)
- Dial the assigned feature code (e.g. `*81`) from any phone to toggle between **Normal Mode**, **Override ON** (force match), and **Override OFF** (force no-match).
- The BLF LED on the physical desk phone illuminates accordingly (Green = Normal, Red = Override Active).

---

## 8. Common Scenarios & Examples

### Scenario 1: Standard Corporate Office with Floating Holidays

**Time Group: "HQ Schedule & Holidays"**
- **Interval 1**: `Weekly` • Mon-Fri 09:00 - 17:00
- **Interval 2**: `Relative Date` • "Thanksgiving" • 4th Thursday in November • All Day
- **Interval 3**: `Relative Date` • "Memorial Day" • Last Monday in May • All Day
- **Interval 4**: `Specific Date` • "Christmas" • 2026-12-25 • All Day

### Scenario 2: Weekend Technical Support On-Call

**Time Group: "Weekend Emergency Support"**
- **Interval 1**: `Weekly` • Saturday & Sunday • 08:00 - 20:00
- **Time Condition Match**: Route directly to Mobile Ring Group.
- **Time Condition No-Match**: Route to Emergency Ticket Dispatcher IVR.

---

## 9. Evaluation Engine & Lua Architecture

The Telephony Server Lua handler (`telephony/freeswitch/lua/main/xml_handlers/routing/time_condition.lua`) executes an optimized, sub-millisecond evaluation algorithm:

### Relative Date Mathematical Logic

```lua
-- For N-th Occurrence (1st, 2nd, 3rd, 4th, 5th):
-- In any month, the N-th occurrence of a weekday falls in strict 7-day windows:
if ordinal == "first"  then date_matched = (mday >= 1  and mday <= 7)  end
if ordinal == "second" then date_matched = (mday >= 8  and mday <= 14) end
if ordinal == "third"  then date_matched = (mday >= 15 and mday <= 21) end
if ordinal == "fourth" then date_matched = (mday >= 22 and mday <= 28) end -- e.g. 4th Thursday
if ordinal == "fifth"  then date_matched = (mday >= 29 and mday <= 31) end

-- For Last Occurrence (e.g. Last Monday in May):
if ordinal == "last" then
  local days_in_month = get_days_in_month(current_month, current_year)
  date_matched = ((mday + 7) > days_in_month)
end
```

---

## 10. Model Context Protocol (MCP) AI Integration

Ring2All exposes native Model Context Protocol (MCP) tools for **Time Groups**, enabling AI agents, Copilots, and scheduling systems to inspect business hours, query active holiday calendars, manage schedule rules (weekly intervals, fixed calendar dates, and relative floating holiday rules), and import national holiday presets programmatically with domain isolation and dependency protection.

### Available MCP Tools

| Tool Name | Description | Key Parameters |
|:---|:---|:---|
| `list_time_groups` | Lists all Time Groups in the domain, displaying schedule intervals summary, rule counts, and enabled state. | `search` (optional string) |
| `get_time_group_status` | Retrieves full configuration and structured schedule intervals (weekly hours, specific dates, floating relative holiday rules like 4th Thursday in November) of a Time Group. | `name` (required string) |
| `create_time_group` | Provisions a new Time Group with schedule intervals. Strictly validates name uniqueness per domain and interval structure. | `name`, `schedules` (array of schedule objects), `description` |
| `update_time_group` | Updates Time Group metadata, enabled status, or replaces its schedule intervals. | `name`, `newName`, `description`, `enabled`, `schedules` |
| `list_holiday_presets` | Lists available country codes and country names for automated national holiday calendar imports. | None |
| `import_country_holidays_to_time_group` | Fetches verified national public holidays for a specified country and year, and appends or imports them directly as schedule intervals into the Time Group. | `timeGroupName`, `countryCode` (e.g. "US", "MX", "CR", "ES"), `year` (number) |
| `delete_time_group` | Safely removes a Time Group after verifying via `assertCanDeleteTimeGroup` that no active Time Conditions or ARS Route Selections reference it. | `name` (required string) |

### Protection Guards & Integrity
- **Name Uniqueness**: Time group names must be unique within each tenant domain.
- **Relational Integrity Guard (`assertCanDeleteTimeGroup`)**: If a Time Group is referenced by any Time Condition or Class of Service ARS route selection, deletion is blocked and a detailed error identifies the referencing telephony rules.
- **Dialplan Hot Reload**: Changes trigger Telephony Server XML reload (`reloadxml`) so modified schedules evaluate immediately on subsequent calls.

### AI Agent Operational Examples

#### Auditing Time Group Schedules and Rules
```json
{
  "tool": "get_time_group_status",
  "arguments": {
    "name": "Standard Business Hours"
  }
}
```

#### Importing National Holidays into a Holiday Calendar
```json
{
  "tool": "import_country_holidays_to_time_group",
  "arguments": {
    "timeGroupName": "Company Holidays 2026",
    "countryCode": "US",
    "year": 2026
  }
}
```

### Recommended Natural Language Prompts
- *"List all Time Groups and show their configured schedule intervals."*
- *"Import the 2026 national public holidays for the United States into the 'US Holidays' Time Group."*
- *"Check if any Time Conditions are using the 'Weekend Support' Time Group before I delete it."*
- *"Add a weekly schedule from Monday to Friday, 08:00 to 17:00, to the 'Sales Office Hours' Time Group."*

---

## 11. Troubleshooting & Diagnostics

### Diagnostic SQL Queries

**Inspect all schedules configured for a domain:**
```sql
SELECT 
    tg.name AS group_name,
    tgs.name AS schedule_label,
    tgs.schedule_type,
    tgs.day_of_week,
    tgs.start_time,
    tgs.end_time,
    tgs.start_date,
    tgs.end_date,
    tgs.ordinal_position,
    tgs.relative_day_of_week,
    tgs.month_of_year,
    tgs.is_all_day
FROM public.time_groups tg
JOIN public.time_group_schedules tgs ON tgs.group_id = tg.id
WHERE tg.domain_id = [YOUR_DOMAIN_ID]
ORDER BY tg.name, tgs.id ASC;
```

**Check active Time Condition status:**
```sql
SELECT id, name, status, destination_match_value, destination_nomatch_value
FROM public.time_conditions
WHERE domain_id = [YOUR_DOMAIN_ID];
```

### Telephony Server Live Logs
```bash
# Filter time condition decisions in real time:
tail -f /var/log/freeswitch/freeswitch.log | grep -E "Time condition|time_condition.lua|Evaluating schedule"
```

---

## 12. Glossary

| Term | Definition |
|---|---|
| **Time Group** | Named collection of one or more active time intervals and calendar rules. |
| **Schedule Modality** | The rule type for an interval: Weekly Days, Specific Date, or Relative Date. |
| **Floating Holiday** | A holiday that falls on a variable date each year based on a rule (e.g., 4th Thursday of November). |
| **Time Condition** | Inbound call routing policy that branches based on Time Group evaluation. |
| **BLF Override** | Dialable feature code (*81) to manually override scheduled routing from a phone button. |
| **All Day Mode** | Flag that evaluates an interval as active for the complete 24-hour cycle (`00:00:00 - 23:59:59`). |

---

*Documentation updated: August 2026 • Ring2All Platform Documentation Subsystem*