Route Selections (ARS) Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
ARS Routing Logic
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Is ARS?

ARS (Automatic Route Selection) enables time-based and priority-based outbound route selection. It creates profiles that link Outbound Routes with optional Time Groups, allowing the system to automatically select the best route based on time of day and priority.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    ARS System Architecture                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Outbound call request                                          │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              ARS Profile Lookup                          │   │
│  │  (Assigned to Class of Service or Extension)            │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Evaluate Routes (by priority)               │   │
│  │                                                          │   │
│  │  Priority 1: Route A + Time Group "Business Hours"       │   │
│  │    └─ Check: Is current time within Business Hours?     │   │
│  │       ├─ YES → Use Route A                              │   │
│  │       └─ NO → Check next route                          │   │
│  │                                                          │   │
│  │  Priority 2: Route B + Time Group "After Hours"          │   │
│  │    └─ Check: Is current time within After Hours?        │   │
│  │       ├─ YES → Use Route B                              │   │
│  │       └─ NO → Check next route                          │   │
│  │                                                          │   │
│  │  Priority 3: Route C (No Time Group = Always)            │   │
│  │    └─ Use as fallback                                   │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  Route call through selected Outbound Route                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.ars_profiles`	ARS profile definitions
`public.ars_routes`	Route associations within profiles
`public.outbound_routes`	Referenced outbound routes
`public.time_groups`	Optional time-based restrictions

Key Files

File	Description
`admin/apps/web/src/modules/ars/`	Frontend module
`admin/apps/web/src/i18n/en/ars.json`	English translations

Integration Points

ARS profiles are assigned via:

Class of Service: All extensions with that CoS use the profile
Extension-level override: Specific extension settings

---

2. Module Overview (Commercial/Business)

Business Value

ARS enables intelligent, time-aware routing:

Without ARS	With ARS
Same route all day	Different routes by time
No cost optimization	Cheapest route by time
Manual route changes	Automatic selection
Single route fallback	Multiple route failover

Use Cases

Cost Optimization

- Use cheapest carrier during business hours

- Use alternative carrier after hours (better night rates)

Regional Routing

- Route US calls via US carrier

- Route international via international carrier

Holiday Routing

- Normal routes on workdays

- Emergency route on holidays

Failover Configuration

- Primary route (Priority 1)

- Backup route (Priority 2) if primary fails

Load Balancing

- Split traffic across multiple carriers

- Time-based distribution

Feature Highlights

Feature	Benefit
Multiple Routes	Chain routes with priorities
Time Groups	Time-based route activation
Priority Ordering	Control route evaluation order
Enable/Disable	Toggle routes without deletion
Profile Assignment	Apply to CoS or extensions

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create ARS profiles with multiple routes
Assign Time Groups to routes for time-based selection
Set priorities for route evaluation order
Enable/disable individual routes within profiles
Assign profiles to Class of Service or extensions

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 Creating an ARS Profile                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: Profile Information                                    │
│  ├─ Name: "Standard Outbound"                                  │
│  ├─ Description: "Default routing with time-based selection"  │
│  └─ Enabled: ✓                                                 │
│                                                                 │
│  Step 2: Add Routes                                             │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Route 1 (Priority 1)                                      │  │
│  │ ├─ Outbound Route: Primary Carrier                        │  │
│  │ ├─ Time Group: Business Hours (8am-6pm)                   │  │
│  │ └─ Enabled: ✓                                             │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Route 2 (Priority 2)                                      │  │
│  │ ├─ Outbound Route: Night Carrier                          │  │
│  │ ├─ Time Group: After Hours (6pm-8am)                      │  │
│  │ └─ Enabled: ✓                                             │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Route 3 (Priority 3) - FALLBACK                           │  │
│  │ ├─ Outbound Route: Backup Carrier                         │  │
│  │ ├─ Time Group: (none - always available)                  │  │
│  │ └─ Enabled: ✓                                             │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Step 3: Save Profile                                           │
│                                                                 │
│  Step 4: Assign to Class of Service                             │
│  └─ Edit CoS → Select ARS Profile: "Standard Outbound"        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP

Priority Order: Lower numbers = higher priority (1 is first).

TIP

Always Add Fallback: Include a route without Time Group as final fallback.

CAUTION

Time Group Coverage: Ensure Time Groups don't leave gaps, or add fallback route.

---

4. Configuration Fields Reference

Profile Fields

Field	Description	Example	Required
Profile Name	Unique identifier	`Standard Outbound`	Yes
Description	Purpose notes	`Default routing`	No
Enabled	Profile active status	On/Off	Yes

Route Fields

Field	Description	Example	Required
Outbound Route	The route to use	`Primary Carrier`	Yes
Time Group	When route is active	`Business Hours`	No
Priority	Evaluation order	1, 2, 3...	Yes
Enabled	Route active status	On/Off	Yes

Priority Explanation

Priority	Meaning
1	Checked first
2	Checked if Priority 1 doesn't match
3	Checked if Priority 1 & 2 don't match
...	Continue down the list
Last (no Time Group)	Fallback if nothing else matches

---

5. ARS Routing Logic

Route Selection Algorithm

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    ARS Route Selection                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Get ARS Profile for caller (via CoS or extension)           │
│     │                                                           │
│     ▼                                                           │
│  2. Load all enabled routes, sorted by priority                 │
│     │                                                           │
│     ▼                                                           │
│  3. For each route (in priority order):                         │
│     │                                                           │
│     ├─ Has Time Group?                                         │
│     │   ├─ YES: Check if current time is within Time Group    │
│     │   │   ├─ Within time → SELECT THIS ROUTE                │
│     │   │   └─ Outside time → Continue to next route          │
│     │   │                                                      │
│     │   └─ NO: SELECT THIS ROUTE (always matches)             │
│     │                                                           │
│     ▼                                                           │
│  4. If no route selected → Use system default route             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Time Group Matching

Time Groups define when a route is active:

Within Time Group: Route is available
Outside Time Group: Route is skipped
No Time Group: Route is always available (fallback)

---

6. Common Scenarios & Examples

Scenario 1: Business Hours vs. After Hours

Profile: "Time-Based Routing"

Priority	Outbound Route	Time Group	Purpose
1	Primary Carrier	Business Hours (8am-6pm)	Cheapest daytime
2	Night Carrier	After Hours (6pm-8am)	Night rate savings
3	Backup Carrier	(none)	Fallback if both fail

Scenario 2: Regional Carrier Selection

Profile: "Geographic Routing"

Priority	Outbound Route	Time Group	Purpose
1	US Carrier	(none)	Handles US numbers
2	International Carrier	(none)	Handles international

Note: Route pattern matching happens at Outbound Route level

Scenario 3: Weekend/Holiday Routing

Profile: "Holiday Aware"

Priority	Outbound Route	Time Group	Purpose
1	Holiday Route	Holidays	Special holiday routing
2	Weekend Route	Weekends	Weekend carrier
3	Primary Carrier	Business Hours	Normal business
4	Backup Carrier	(none)	Fallback

Scenario 4: Cost-Based Failover

Profile: "Primary + Backup"

Priority	Outbound Route	Time Group	Purpose
1	Cheapest Carrier	(none)	Try cheapest first
2	Premium Carrier	(none)	If cheapest fails

---

7. Limitations & Important Notes

Technical Limitations

WARNING

Time Group Gaps: If no Time Group matches current time and no fallback exists, calls may fail.

WARNING

Profile Required: Extensions/CoS must have ARS profile assigned to use time-based selection.

Best Practices

Always Add Fallback: Include route without Time Group
No Time Gaps: Ensure Time Groups cover all hours
Test Time Groups: Verify transitions at boundaries
Priority Order: Most specific first, fallback last
Monitor Failures: Track which routes are used

Route Selection Notes

IMPORTANT

Pattern Matching: Pattern matching (e.g., 011 for international) is handled at the Outbound Route level, not ARS.

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
Wrong route selected	Priority order incorrect	Adjust priorities
Calls failing at certain times	Time Group gap	Add fallback route
ARS not being used	Profile not assigned	Check CoS/extension
Always uses fallback	Time Groups misconfigured	Verify time ranges

Diagnostic SQL

List ARS profiles:

Sql

SELECT p.id, p.name, p.enabled,
       (SELECT COUNT(*) FROM public.ars_routes 
        WHERE ars_profile_id = p.id) as route_count
FROM public.ars_profiles p
WHERE p.domain_id = [domain_id];

Check profile routes:

Sql

SELECT r.priority, r.enabled,
       o.name as outbound_route,
       t.name as time_group
FROM public.ars_routes r
JOIN public.outbound_routes o ON r.outbound_route_id = o.id
LEFT JOIN public.time_groups t ON r.time_group_id = t.id
WHERE r.ars_profile_id = [profile_id]
ORDER BY r.priority;

---

9. Glossary

Term	Definition
ARS	Automatic Route Selection—time/priority-based routing
ARS Profile	Collection of routes with priorities
Outbound Route	Carrier/trunk configuration for outbound calls
Time Group	Schedule defining when a route is active
Priority	Order in which routes are evaluated (lower = first)
Fallback Route	Route without Time Group (always available)
Class of Service	Permission group that can have ARS profile assigned

---

Lua Handler Status

⚡ No Dedicated Handler Required

ARS is a configuration module. The ARS profile data is consumed by the main outbound routing engine (route_with_fallback.lua) when processing outbound calls. No dedicated ARS Lua handler exists or is needed.

---

Documentation last updated: January 2026

Route Selections (ARS) Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is ARS?

Architecture

Key Tables

Key Files

Integration Points

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Administrator Workflow

Quick Tips

4. Configuration Fields Reference

Profile Fields

Route Fields

Priority Explanation

5. ARS Routing Logic

Route Selection Algorithm

Time Group Matching

6. Common Scenarios & Examples

Scenario 1: Business Hours vs. After Hours

Scenario 2: Regional Carrier Selection

Scenario 3: Weekend/Holiday Routing

Scenario 4: Cost-Based Failover

7. Limitations & Important Notes

Technical Limitations

Best Practices

Route Selection Notes

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

9. Glossary

Lua Handler Status

⚡ No Dedicated Handler Required