DISA (Direct Inward System Access) Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Configuration Fields Reference
Call Flow / Logic Explanation
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary
Suggested UI Improvements

---

1. Module Overview (Technical)

What Is DISA?

DISA (Direct Inward System Access) allows external callers to access the PBX dial tone after authenticating with a PIN. Once authenticated, callers can place outbound calls as if they were calling from within the organization.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    DISA System Architecture                     │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  External caller dials inbound DID → Routed to DISA code       │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              DISA Entry Lookup                           │   │
│  │  SELECT * FROM public.disa_entries                       │   │
│  │  WHERE context = [code] AND enabled = TRUE               │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Authentication                              │   │
│  │                                                          │   │
│  │  1. Play: "Enter your access code"                       │   │
│  │  2. Caller enters PIN: ****#                             │   │
│  │  3. Validate against stored password                     │   │
│  │     ├─ Correct → Continue                               │   │
│  │     └─ Wrong → Play error, retry or hangup              │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Dial Collection                             │   │
│  │                                                          │   │
│  │  1. Play: "Enter the number you wish to call"            │   │
│  │  2. Caller enters: 15551234567#                          │   │
│  │  3. Apply dial prefix if configured                      │   │
│  │  4. Apply CoS restrictions                               │   │
│  │  5. Override caller ID if configured                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼                                                         │
│  Bridge call to destination through internal context            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.disa_entries`	DISA configurations (name, password, settings)
`public.class_of_services`	Referenced for CoS restrictions

Key Files

File	Description
`admin/apps/web/src/modules/disaEntries/`	Frontend module
`admin/apps/web/src/i18n/en/disaEntries.json`	English translations
`telephony/freeswitch/lua/main/xml_handlers/disa/disa.lua`	DISA handler

---

2. Module Overview (Commercial/Business)

Business Value

DISA provides remote PBX access for authorized users:

Without DISA	With DISA
Must be in office to use company phones	Call from anywhere
Personal phone shows personal number	Company caller ID displayed
No access to internal extensions	Full PBX access after authentication
Expensive international from mobile	Use company rates

Use Cases

Remote Workers

- Call clients with company caller ID from home

- Access internal extensions while traveling

Sales Teams on the Road

- Present company number to prospects

- Use company trunk for lower international rates

After-Hours Support

- On-call staff can use PBX from mobile

- Consistent caller ID for customer callbacks

Executive Travel

- Maintain professional presence while abroad

- Access internal directory

Feature Highlights

Feature	Benefit
PIN Authentication	Secure access control
Caller ID Override	Present company number
CoS Restriction	Control call destinations
Call Recording	Compliance and training
Access Logging	Audit trail for security

---

3. Module Overview (End User/Administrator)

What Can You Do?

Create DISA entries with unique PINs
Configure caller ID overrides
Restrict destinations by Class of Service
Set timeouts and retry limits
Enable call recording and access logging
Receive notifications on successful access

Administrator Workflow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 Creating a DISA Entry                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Step 1: General Information                                    │
│  ├─ Name: "Sales DISA"                                         │
│  └─ Access PIN: 4567                                           │
│                                                                 │
│  Step 2: Caller ID Settings                                     │
│  ├─ Caller ID Name: "Sales Team"                               │
│  ├─ Caller ID Number: +1-555-100-0000                          │
│  └─ Inherit Caller ID: Off                                     │
│                                                                 │
│  Step 3: Dial Settings                                          │
│  ├─ Dial Prefix: 9 (for external lines)                        │
│  └─ Class of Service: Standard (restrict international)        │
│                                                                 │
│  Step 4: Timeout Settings                                       │
│  ├─ Response Timeout: 10 seconds                               │
│  ├─ Inter-Digit Timeout: 3 seconds                             │
│  └─ Max Call Duration: 3600 seconds                            │
│                                                                 │
│  Step 5: Security Settings                                      │
│  ├─ Max PIN Attempts: 3                                        │
│  ├─ Hangup on Fail: ✓                                          │
│  ├─ Log Access Attempts: ✓                                     │
│  └─ Notify on Access: security@company.com                     │
│                                                                 │
│  Step 6: Enable and Save                                        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

User Workflow (Using DISA)

Plaintext

1. Call company DISA DID from external phone
2. Hear: "Enter your access code"
3. Enter PIN: 4567#
4. Hear: "Enter the number you wish to call"
5. Enter: 15551234567#
6. Call connects with company caller ID

Quick Tips

TIP

Strong PINs: Use at least 6 digits for security.

TIP

CoS Restriction: Always apply CoS to prevent toll fraud.

CAUTION

DISA Security: DISA is a common target for toll fraud. Monitor access logs regularly.

---

4. Configuration Fields Reference

General Section

Field	Description	Example	Required
Name	Display name	`Sales DISA`	Yes
Access PIN	Authentication code	`456789`	Yes
Class of Service	Dial restrictions	`Standard`	No
Enabled	Active status	On/Off	Yes

Caller ID Settings

Field	Description	Default
Caller ID Name	Outbound name	Original caller
Caller ID Number	Outbound number	Original caller
Inherit Caller ID	Use caller's original ID	Off
Dial Prefix	Prefix before dialed number	(empty)

Timeout Settings

Field	Description	Range	Default
Response Timeout	Time to enter first digit	1-60 sec	10
Inter-Digit Timeout	Time between digits	1-10 sec	3
Max Call Duration	Maximum call length	60-3600 sec	3600

Security Settings

Field	Description	Default
Max PIN Attempts	Retries before hangup	3
Hangup on Fail	Disconnect after max attempts	On
Record Call	Enable recording	Off
Log Access Attempts	Audit logging	On
Allow Local Calls	Permit internal extensions	On
Allow International	Permit international	Off
Retry on Fail	Retry if call fails	Off
Notify on Access	Email/webhook notification	(empty)

Audio Prompts

Field	Description	Default
Greeting Prompt	Initial greeting	(system default)
Invalid PIN Sound	Wrong password audio	ivr/ivr-that_was_an_invalid_entry.wav
Timeout Sound	No input audio	ivr/ivr-time_out.wav

---

5. Call Flow / Logic Explanation

DISA Authentication Flow

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                    DISA Call Flow                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Inbound call arrives at DISA DID                            │
│     │                                                           │
│     ▼                                                           │
│  2. Look up DISA entry by context/code                          │
│     ├─ Found & enabled → Continue                              │
│     └─ Not found → "Feature not available" → Hangup            │
│     │                                                           │
│     ▼                                                           │
│  3. Play greeting (if configured)                               │
│     │                                                           │
│     ▼                                                           │
│  4. Prompt for PIN                                              │
│     │                                                           │
│     ▼                                                           │
│  5. Validate PIN                                                │
│     ├─ Correct → Continue                                      │
│     └─ Wrong → Attempt counter                                 │
│         ├─ Attempts < max → Retry from step 4                  │
│         └─ Attempts >= max → "Invalid" → Hangup                │
│     │                                                           │
│     ▼                                                           │
│  6. Log successful access (if log_access enabled)               │
│     │                                                           │
│     ▼                                                           │
│  7. Send notification (if notify_on_access configured)          │
│     │                                                           │
│     ▼                                                           │
│  8. Prompt for destination number                               │
│     │                                                           │
│     ▼                                                           │
│  9. Apply settings:                                             │
│     ├─ Dial prefix: prepend to number                          │
│     ├─ Caller ID: override name/number                         │
│     ├─ CoS: set class_of_services_id                           │
│     └─ Recording: start if enabled                             │
│     │                                                           │
│     ▼                                                           │
│  10. Bridge call to destination                                 │
│     ├─ Connected → Call in progress                            │
│     └─ Failed → Retry or hangup based on settings              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: Sales Team DISA

Setup:

Setting	Value
Name	Sales DISA
PIN	789456
Caller ID Name	Sales Team
Caller ID Number	+1-555-100-0000
CoS	Standard
Allow International	Off

Result: Sales team can make domestic calls with company caller ID.

Scenario 2: Executive DISA

Setup:

Setting	Value
Name	Executive DISA
PIN	147258 (stronger)
Caller ID	Inherit from Caller
CoS	Executive (full access)
Allow International	On
Notify on Access	security@company.com

Result: Executives can call anywhere, security notified on each use.

Scenario 3: On-Call Support

Setup:

Setting	Value
Name	Support DISA
PIN	369258
Allow Local	On (internal extensions)
Max Call Duration	1800 (30 min)
Record Call	On

Result: Support can access internal extensions, calls are recorded.

---

7. Limitations & Important Notes

Security Warnings

CAUTION

Toll Fraud Risk: DISA is a prime target for hackers. Weak PINs can lead to thousands in fraudulent calls.

CAUTION

PIN Complexity: Use at least 6-digit PINs with no obvious patterns (not 123456).

WARNING

Monitor Access Logs: Review DISA access logs regularly for suspicious activity.

Best Practices

Strong PINs: Minimum 6 digits, no patterns
CoS Restriction: Always limit destinations
Max Attempts: Keep low (3) to prevent brute force
Hangup on Fail: Enable to stop attackers
Notifications: Set up alerts for access
Time Restrictions: Consider schedule windows
Regular Audits: Review usage monthly

Technical Limitations

IMPORTANT

Single PIN per Entry: Each DISA entry has one PIN. Create multiple entries for different users/groups.

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
"Feature not available"	Entry not found/disabled	Check entry exists and is enabled
Wrong caller ID	Override not set	Configure caller_id fields
Call restricted	CoS blocking	Check Class of Service permissions
No dial tone after PIN	Timeout too short	Increase response_timeout
Immediate hangup	Max attempts exceeded	Check attempt counter, reset

Diagnostic SQL

List DISA entries:

Sql

SELECT name, context, password, 
       class_of_services_id, enabled
FROM public.disa_entries
WHERE domain_id = [domain_id];

Check access logs:

Sql

SELECT * FROM public.disa_access_logs
WHERE domain_id = [domain_id]
ORDER BY created_at DESC
LIMIT 50;

---

9. Glossary

Term	Definition
DISA	Direct Inward System Access—remote PBX dial tone access
PIN	Personal Identification Number for authentication
CoS	Class of Service—dial permission restrictions
Dial Prefix	Digits prepended before dialed number (e.g., 9 for outside line)
Response Timeout	Time to wait for first digit input
Inter-Digit Timeout	Time between keypress entries
Toll Fraud	Unauthorized use of phone system for expensive calls
Brute Force	Attempting many PINs to guess correct one

---

10. Suggested UI Improvements

Security Enhancements

PIN Strength Indicator: Show weak/medium/strong for entered PIN
Failed Attempt Alerts: Dashboard widget for failed DISA attempts
IP Restriction UI: Easy interface for whitelisting IPs

UX Enhancements

Usage Statistics: Show call count and duration per entry
Quick Test: "Test DISA" button to verify configuration
Clone with New PIN: Duplicate entry with auto-generated PIN

Lua Script Status ✅

Integration Module

Component	Status	Location
DISA Handler	✅ Active	`app/disa/disa.lua`

--- Documentation last updated: January 2026

DISA (Direct Inward System Access) Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is DISA?

Architecture

Key Tables

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Administrator Workflow

User Workflow (Using DISA)

Quick Tips

4. Configuration Fields Reference

General Section

Caller ID Settings

Timeout Settings

Security Settings

Audio Prompts

5. Call Flow / Logic Explanation

DISA Authentication Flow

6. Common Scenarios & Examples

Scenario 1: Sales Team DISA

Scenario 2: Executive DISA

Scenario 3: On-Call Support

7. Limitations & Important Notes

Security Warnings

Best Practices

Technical Limitations

8. Troubleshooting Tips

Common Issues

Diagnostic SQL

9. Glossary

10. Suggested UI Improvements

Security Enhancements

UX Enhancements

Lua Script Status ✅

Integration Module