---
title: "Route Selections (ARS) Module Documentation"
description: "Documentation for Route Selections (ARS)"
---

## Table of Contents
1. [Module Overview (Technical)](#1-module-overview-technical)
2. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
3. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
4. [Configuration Fields Reference](#4-configuration-fields-reference)
5. [ARS Routing Logic](#5-ars-routing-logic)
6. [Common Scenarios & Examples](#6-common-scenarios--examples)
7. [Model Context Protocol (MCP) AI Integration](#7-model-context-protocol-mcp-ai-integration)
8. [Limitations & Important Notes](#8-limitations--important-notes)
9. [Troubleshooting Tips](#9-troubleshooting-tips)
10. [Glossary](#10-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

```
┌─────────────────────────────────────────────────────────────────┐
│                    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                     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### 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

1. **Cost Optimization**
   - Use cheapest carrier during business hours
   - Use alternative carrier after hours (better night rates)

2. **Regional Routing**
   - Route US calls via US carrier
   - Route international via international carrier

3. **Holiday Routing**
   - Normal routes on workdays
   - Emergency route on holidays

4. **Failover Configuration**
   - Primary route (Priority 1)
   - Backup route (Priority 2) if primary fails

5. **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

### Navigation

1. Navigate to **PBX Engine → Class of Services → Route Selections** in the main navigation menu.
2. The **list view** displays all configured ARS routing profiles, including Name, Description, and active status.
3. Click the **+ Add** button in the top toolbar to create a new Route Selection profile.
4. Click any profile row or the edit action to manage chained carrier routes, time groups, and failover priorities.

![Route Selections (ARS) List View](/screenshots/pbx/class-of-service/route-selections-list.png)

### Administrator Workflow

```
┌─────────────────────────────────────────────────────────────────┐
│                 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 evaluated first). Use the up/down arrow buttons to easily adjust carrier order.

> [!TIP]
> **Always Add Fallback**: Include a route without a Time Group at the end of the list to act as a 24/7 universal fallback.

> [!CAUTION]
> **Time Group Coverage**: Ensure Time Groups do not leave unhandled time windows without a matching active route.

---

## 4. Configuration Fields Reference

![Route Selection (ARS) Configuration Form](/screenshots/pbx/class-of-service/route-selections-form.png)

### General Information Fields

| Field | Description | User-Friendly Tooltip | Example | Notes |
|-------|-------------|----------------------|---------|-------|
| **Name \*** | Unique identifier for the ARS profile | A descriptive name for this ARS route profile | `Standard Outbound PSTN ARS` | Required. Unique per domain. |
| **Description** | Contextual notes and operational scope | Detailed description of the routing logic | `Primary carrier routing with secondary failover` | Optional. |
| **Enabled \*** | Operational status of the ARS profile | Whether this ARS profile is currently active | `Toggle (On/Off)` | Required. If disabled, calls fail or fallback to system default. |

### Routes Table Fields

| Field | Description | Type / Control | Example | Notes |
|-------|-------------|----------------|---------|-------|
| **Order / Priority** | Execution order of candidate routes | Up / Down arrows | `1, 2, 3...` | Evaluated sequentially until an eligible route connects. |
| **Outbound Route \*** | Outbound trunk route to dispatch call | Dropdown | `Primary VoIP Carrier` | Required for each route item. Links to configured Outbound Routes. |
| **Time Group** | Optional temporal condition filter | Dropdown | `Business Hours (8am-5pm)` | If selected, route is only attempted during specified time frames. |
| **Enabled** | Operational status of this route entry | Toggle (On/Off) | `Enabled` | Temporarily disable a carrier without deleting the configuration. |
| **Actions** | Remove entry | Trash button | `Delete` | Deletes the route entry from the profile chain. |
| ... | Continue down the list |
| Last (no Time Group) | Fallback if nothing else matches |

---

## 5. ARS Routing Logic

### Route Selection Algorithm

```
┌─────────────────────────────────────────────────────────────────┐
│                    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. Model Context Protocol (MCP) AI Integration

Ring2All exposes dedicated Model Context Protocol (MCP) tools for **Route Selections (ARS - Automatic Route Selection)**, allowing autonomous AI agents and Copilots to inspect outbound trunk priority chains, verify Time Group schedules, and provision or adjust carrier failover routing policies with domain-level isolation and dependency protection.

### Available MCP Tools

| Tool Name | Description | Key Parameters |
|:---|:---|:---|
| `list_route_selections` | Lists all Route Selection (ARS) profiles in the domain, including profile names, descriptions, and assigned route counts. | `search` (optional string) |
| `get_route_selection_status` | Retrieves full configuration, ordered outbound trunk routes, priority indices, and bound Time Groups for an ARS profile. | `name` (required) |
| `create_route_selection` | Provisions a new Route Selection (ARS) profile to group and prioritize outbound routes. | `name`, `description`, `enabled` |
| `update_route_selection` | Modifies an existing Route Selection profile name, description, or enabled state. | `name`, `newName`, `description`, `enabled` |
| `delete_route_selection` | Deletes an ARS profile after verifying it is not currently bound to an active Class of Service (`assertCanDeleteRouteSelection`). | `name` (required) |

### Protection Guards & Integrity
When an AI agent executes `delete_route_selection`, Ring2All runs `assertCanDeleteRouteSelection`. The system verifies whether any Class of Service (`public.class_of_services`) is actively using this ARS profile. If linked, deletion is rejected with an explanatory message, preventing routing outages.

### AI Agent Operational Examples

#### Querying ARS Route Selection Chains
```json
{
  "tool": "get_route_selection_status",
  "arguments": {
    "name": "Default Outbound ARS"
  }
}
```

#### Provisioning an International Failover ARS Profile
```json
{
  "tool": "create_route_selection",
  "arguments": {
    "name": "International Premium ARS",
    "description": "Primary Tier-1 SIP trunk with automatic failover to secondary gateway",
    "enabled": true
  }
}
```

### Recommended Natural Language Prompts
- *"List all ARS Route Selection profiles configured on this PBX and show their assigned outbound routes."*
- *"Show me the priority carrier chain for the 'Default Outbound ARS' profile."*
- *"Check if 'International Premium ARS' is assigned to any Class of Service before I modify it."*

---

## 8. 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

1. **Always Add Fallback**: Include route without Time Group
2. **No Time Gaps**: Ensure Time Groups cover all hours
3. **Test Time Groups**: Verify transitions at boundaries
4. **Priority Order**: Most specific first, fallback last
5. **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.

---

## 9. 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;
```

---

## 10. 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 |

---

*Documentation last updated: January 2026*