Class of Services Module Documentation

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

---

1. Module Overview (Technical)

What Is Class of Service?

Class of Service (CoS) is the central permission system that controls what features and calling capabilities are available to extensions. It aggregates three key components:

Feature Code Category → Which dialpad features (XX) are available

Dial Rule Restrictions → Which numbers can/cannot be dialed

ARS Profile → Which outbound routes are used

Table	Purpose
`public.class_of_services`	CoS definitions
`public.sip_extensions`	References CoS via `class_of_services_id`
`public.feature_code_categories`	Feature groupings
`public.dial_rule_restrictions`	Dial restrictions
`public.ars_profiles`	Outbound routing

File	Description
`admin/apps/web/src/modules/classOfServices/`	Frontend module
`admin/apps/web/src/i18n/en/classOfServices.json`	Translations
`telephony/freeswitch/lua/resources/functions/cos_utils.lua`	CoS permission checks

Without CoS	With CoS
Same permissions for all	Role-based access
Per-extension configuration	Template-based configuration
Manual updates everywhere	Update once, apply everywhere
No feature control	Granular feature access

Feature	Benefit
Feature Categories	Control dialpad features
Dial Restrictions	Control destination access
ARS Profiles	Control carrier routing
Default Class	Auto-assign to new extensions
Enable/Disable	Suspend without deletion

Field	Description	Example	Required
Class Name	Unique identifier	`Standard Employee`	Yes
Description	Purpose notes	`Staff calling permissions`	No
Feature Code Category	Which features allowed	`Basic Features`	No
Dial Restriction	Which patterns blocked	`Standard Restrictions`	No
ARS Profile	Which routes used	`Standard Routing`	No
Default Class	Auto-assign to new ext	On/Off	No
Enabled	CoS active status	On/Off	Yes

Field	Null Behavior
Feature Code Category = NULL	All features allowed
Dial Restriction = NULL	No dial restrictions
ARS Profile = NULL	Default routing

CoS	Feature Category	Dial Restrictions	ARS Profile
Executive	All Features	No Restrictions	Premium Routing
Manager	Advanced	International Allowed	Standard Routing
Employee	Basic	Domestic Only	Standard Routing
Lobby	Minimal	Emergency Only	Standard Routing

CoS	Features	Restrictions	Notes
Agent Tier 1	Basic calling	Local only	New agents
Agent Tier 2	+ Transfers	+ Long distance	Experienced
Supervisor	+ Spy modes	Full access	Team leads

CoS	Features	Restrictions	ARS Profile
NYC Office	Standard	-	NYC Carriers
LA Office	Standard	-	LA Carriers
Remote	Standard	Limited	VoIP Only

Symptom	Possible Cause	Solution
Feature not working	Not in Feature Category	Add to category
Call blocked	Dial Restriction triggered	Check pattern rules
Wrong carrier	ARS Profile misconfigured	Review ARS routes
New ext no CoS	No default set	Set default CoS

Term	Definition
Class of Service (CoS)	Permission profile assigned to extensions
Feature Code Category	Group of allowed dialpad features
Dial Rule Restriction	Pattern-based call control
ARS Profile	Outbound route selection rules
Default Class	CoS automatically assigned to new extensions

Architecture

Plaintext
┌─────────────────────────────────────────────────────────────────┐ │ Class of Service System │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Class of Service │ │ │ │ "Executive" │ │ │ ├───────────────────────────────────────────────────────────┤ │ │ │ │ │ │ │ Feature Code Category ─────────► Advanced Features │ │ │ │ (What *XX can they dial?) *67, *69, *72, *92... │ │ │ │ │ │ │ │ Dial Rule Restrictions ─────────► Executive │ │ │ │ (What numbers can they call?) Allow international │ │ │ │ │ │ │ │ ARS Profile ────────────────────► Primary Routing │ │ │ │ (Which carriers/routes?) Best rate routing │ │ │ │ │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Extensions │ │ │ │ │ │ │ │ 101 (CEO) ─────────────────────────► Executive CoS │ │ │ │ 102 (CFO) ─────────────────────────► Executive CoS │ │ │ │ 200 (Sales Manager) ───────────────► Manager CoS │ │ │ │ 201-220 (Sales Team) ──────────────► Standard CoS │ │ │ │ 300-320 (Support Team) ────────────► Standard CoS │ │ │ │ │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘

Key Tables

Table Purpose
public.class_of_services CoS definitions
public.sip_extensions References CoS via class_of_services_id
public.feature_code_categories Feature groupings
public.dial_rule_restrictions Dial restrictions
public.ars_profiles Outbound routing
Key Files

File Description
admin/apps/web/src/modules/classOfServices/ Frontend module
admin/apps/web/src/i18n/en/classOfServices.json Translations
telephony/freeswitch/lua/resources/functions/cos_utils.lua CoS permission checks
Lua Integration

CoS is referenced in 40+ Lua scripts for permission checks:

Lua
-- Example: Check if feature code is allowed local sql = string.format([[ SELECT class_of_services_id FROM public.sip_extensions WHERE extension = '%s' AND domain_id = %s ]], extension, domain_id) dbh:query(sql, function(row) cos_id = row.class_of_services_id end) -- Then check if feature is in allowed category for this CoS

---

2. Module Overview (Commercial/Business)

Business Value

Class of Service enables tiered permission management:

Without CoS With CoS
Same permissions for all Role-based access
Per-extension configuration Template-based configuration
Manual updates everywhere Update once, apply everywhere
No feature control Granular feature access
Use Cases

Role-Based Access

- Executive: Full access

- Manager: Advanced features

- Employee: Standard features

- Lobby/Guest: Basic only

Cost Control

- Block premium numbers by tier

- Limit international to approvers

- Route to cheapest carriers

Compliance

- Restrict call recording by role

- Block spy features to authorized users

- Audit trail per permission level

Feature Highlights

Feature Benefit
Feature Categories Control dialpad features
Dial Restrictions Control destination access
ARS Profiles Control carrier routing
Default Class Auto-assign to new extensions
Enable/Disable Suspend without deletion
---
3. Module Overview (End User/Administrator)

What Can You Do?

Create permission profiles (CoS)

Link Feature Categories for feature access

Link Dial Restrictions for call control

Link ARS Profiles for routing

Set default CoS for new extensions

Assign CoS to extensions

Administrator Workflow

Plaintext
┌─────────────────────────────────────────────────────────────────┐ │ Creating a Class of Service │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Step 1: Basic Information │ │ ├─ Name: "Standard Employee" │ │ ├─ Description: "Standard calling permissions for staff" │ │ └─ Default Class: ✓ (optional - for new extensions) │ │ │ │ Step 2: Permissions & Restrictions │ │ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ Feature Code Category │ │ │ │ └─ "Basic Features" (caller ID, DND, call return) │ │ │ │ │ │ │ │ Dial Rule Restrictions │ │ │ │ └─ "Standard Restrictions" (block premium/intl) │ │ │ │ │ │ │ │ ARS Profile │ │ │ │ └─ "Standard Routing" (default carriers) │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ Step 3: Save and Enable │ │ │ │ Step 4: Assign to Extensions │ │ └─ Edit Extensions → Select CoS: "Standard Employee" │ │ │ └─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP
Default Class: Set one CoS as default for automatic assignment to new extensions.

TIP
Descriptive Names: Use role-based names (Executive, Manager, Standard).

CAUTION
Cascading Changes: Modifying a CoS affects all extensions using it.

---

4. Configuration Fields Reference

CoS Fields

Field Description Example Required
Class Name Unique identifier Standard Employee Yes
Description Purpose notes Staff calling permissions No
Feature Code Category Which features allowed Basic Features No
Dial Restriction Which patterns blocked Standard Restrictions No
ARS Profile Which routes used Standard Routing No
Default Class Auto-assign to new ext On/Off No
Enabled CoS active status On/Off Yes
Field Relationships

Field Null Behavior
Feature Code Category = NULL All features allowed
Dial Restriction = NULL No dial restrictions
ARS Profile = NULL Default routing
---
5. Permission System

Permission Hierarchy

Plaintext
┌─────────────────────────────────────────────────────────────────┐ │ Permission Check Flow │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ User dials a number/feature code │ │ │ │ │ ▼ │ │ 1. Get user's Class of Service │ │ SELECT class_of_services_id FROM public.sip_extensions │ │ │ │ │ ▼ │ │ 2. Is it a feature code (*XX)? │ │ ├─ YES: Check Feature Code Category │ │ │ └─ Is feature in assigned category? │ │ │ ├─ YES → Allow feature │ │ │ └─ NO → "Feature not allowed" │ │ │ │ │ └─ NO: It's an outbound number │ │ │ │ │ ▼ │ │ 3. Check Dial Rule Restrictions │ │ ├─ Pattern blocked? → Block call │ │ ├─ Pattern allowed with limit? → Allow with duration │ │ └─ Pattern allowed? → Proceed │ │ │ │ │ ▼ │ │ 4. Get ARS Profile for routing │ │ └─ Select carrier/route based on ARS rules │ │ │ └─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: Corporate Hierarchy

CoS Feature Category Dial Restrictions ARS Profile
Executive All Features No Restrictions Premium Routing
Manager Advanced International Allowed Standard Routing
Employee Basic Domestic Only Standard Routing
Lobby Minimal Emergency Only Standard Routing
Scenario 2: Call Center Tiers

CoS Features Restrictions Notes
Agent Tier 1 Basic calling Local only New agents
Agent Tier 2 + Transfers + Long distance Experienced
Supervisor + Spy modes Full access Team leads
Scenario 3: Multi-Location

CoS Features Restrictions ARS Profile
NYC Office Standard - NYC Carriers
LA Office Standard - LA Carriers
Remote Standard Limited VoIP Only
---
7. Limitations & Important Notes

Technical Limitations

WARNING
One CoS Per Extension: Each extension can only have one Class of Service.

WARNING
Cascading Impact: Changes to a CoS affect all assigned extensions.

Best Practices

Plan First: Design CoS structure before creating

Document Purpose: Use clear descriptions

Test Thoroughly: Verify permissions work correctly

Minimize Classes: Use as few as needed

Set Default: Always have a default CoS

Default CoS Rules

IMPORTANT
Only One Default: Only one CoS can be marked as default. Default Must Be Enabled: The default CoS cannot be disabled.

---

8. Troubleshooting Tips

Common Issues

Symptom Possible Cause Solution
Feature not working Not in Feature Category Add to category
Call blocked Dial Restriction triggered Check pattern rules
Wrong carrier ARS Profile misconfigured Review ARS routes
New ext no CoS No default set Set default CoS
Diagnostic SQL
List CoS with assignments:
Sql
SELECT c.id, c.name, c.enabled, c.is_main, fc.name as feature_category, dr.name as dial_restriction, (SELECT COUNT(*) FROM public.sip_extensions WHERE class_of_services_id = c.id) as extension_count FROM public.class_of_services c LEFT JOIN public.feature_code_categories fc ON c.feature_code_cos_id = fc.id LEFT JOIN public.dial_rule_restrictions dr ON c.dial_rule_restriction_id = dr.id WHERE c.domain_id = [domain_id];

Check extension CoS:
Sql
SELECT e.extension, e.name, c.name as class_of_service FROM public.sip_extensions e LEFT JOIN public.class_of_services c ON e.class_of_services_id = c.id WHERE e.domain_id = [domain_id] ORDER BY e.extension;

---

9. Glossary

Term Definition
Class of Service (CoS) Permission profile assigned to extensions
Feature Code Category Group of allowed dialpad features
Dial Rule Restriction Pattern-based call control
ARS Profile Outbound route selection rules
Default Class CoS automatically assigned to new extensions
---
Lua Handler Status

⚡ No Dedicated Handler Required

Class of Services is a configuration module. CoS permissions are checked by individual feature and routing Lua scripts when processing calls. The cos_utils.lua library provides shared functions for permission validation.
Key Lua Files:
resources/functions/cos_utils.lua - Permission check utilities

resources/helpers/feature_access.lua - Feature code validation

---

Documentation last updated: January 2026*

Class of Services Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is Class of Service?

Architecture

Key Tables

Key Files

Lua Integration

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

CoS Fields

Field Relationships

5. Permission System

Permission Hierarchy

6. Common Scenarios & Examples

Scenario 1: Corporate Hierarchy

Scenario 2: Call Center Tiers

Scenario 3: Multi-Location

7. Limitations & Important Notes

Technical Limitations

Best Practices

Default CoS Rules

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

9. Glossary

Lua Handler Status

⚡ No Dedicated Handler Required