Bulk Modification Module Documentation

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

---

1. Module Overview (Technical)

What Is Bulk Modification?

Bulk Modification is an administrative tool that allows applying configuration changes to multiple extensions simultaneously instead of editing each one individually. It provides four flexible selection methods and can modify various extension attributes in a single operation.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                  Bulk Modification System                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │               SELECTION METHODS                          │   │
│  ├──────────────────────────────────────────────────────────┤   │
│  │  1️⃣ Individual  │  2️⃣ Ranges  │  3️⃣ Patterns  │  4️⃣ Filters │   │
│  │  Select by ID   │  1000-1099  │  10*, *00     │  By CoS     │   │
│  └──────────────────────────────────────────────────────────┘   │
│                           │                                     │
│                           ▼                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │               PREVIEW OPERATION                          │   │
│  │  POST /api/telephony/bulk-modification/preview           │   │
│  │  → Returns count of affected extensions                  │   │
│  └──────────────────────────────────────────────────────────┘   │
│                           │                                     │
│                           ▼                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │               APPLY MODIFICATIONS                        │   │
│  │  POST /api/telephony/bulk-modification                   │   │
│  │  → Executes changes in transaction                       │   │
│  └──────────────────────────────────────────────────────────┘   │
│                           │                                     │
│                           ▼                                     │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │               DATABASE UPDATE                            │   │
│  │  UPDATE public.sip_extensions SET ... WHERE id IN (...)  │   │
│  │  → Updates settings, recording config, language, etc.    │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.sip_extensions`	Primary table updated during bulk modifications
`public.class_of_services`	Referenced for Class of Service changes
`public.domains`	Used for multi-tenant domain filtering

API Endpoints

Method	Endpoint	Purpose
`POST`	`/api/telephony/bulk-modification/preview`	Preview which extensions will be affected
`POST`	`/api/telephony/bulk-modification`	Apply the modifications

Key Files

File	Description
`admin/apps/api/src/modules/telephony/bulk-modification/services/bulkModificationService.ts`	Backend service handling preview and apply operations
`admin/apps/web/src/modules/bulkModification/BulkModificationPage.tsx`	Frontend page with selection and modification UI
`admin/apps/web/src/i18n/en/bulkModification.json`	English translation strings

---

2. Module Overview (Commercial/Business)

Business Value

Bulk Modification dramatically reduces administrative overhead:

Manual Approach	With Bulk Modification
Change 100 extensions: ~2 hours	Change 100 extensions: ~2 minutes
High error rate from repetitive work	Consistent changes across all selected
Requires skilled administrators	Simple interface for routine changes

Use Cases

Department Restructuring

- Move all Sales team extensions to new Class of Service

- Change language settings for entire floor

Compliance Updates

- Enable call recording for all customer-facing extensions

- Update account codes for billing changes

System Migration

- Mass update ring times during transition

- Apply new default settings to all extensions

Onboarding/Offboarding

- Configure batch of new hire extensions

- Disable extensions for departing employees

Licensing Considerations

This is typically a System Administrator level feature
Consider restricting access to prevent accidental mass changes
Include in Enterprise tier to justify technical support costs

---

3. Module Overview (End User/Administrator)

What Can You Do?

Bulk Modification allows you to:

Select Extensions using multiple methods:

- Individual: Pick specific extensions from a list

- Ranges: Specify numeric ranges (e.g., 1000-1099)

- Patterns: Use wildcards (e.g., 10 = all starting with 10)

- Filters: Select by properties (Class of Service, status, language)

Preview Before Applying:

- See exactly how many extensions will be affected

- Confirm before making changes

Apply Modifications:

- Class of Service

- Ring Time (call timeout)

- Language

- Account Code

- Call Recording Settings

User Workflow

Plaintext
┌─────────────────────────────────────────────────────────────────┐ │ Administrator Workflow │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Step 1: Choose Selection Method │ │ ├─ Individual → Click extensions from list │ │ ├─ Ranges → Enter 1000-1099 │ │ ├─ Patterns → Enter 10* for "starts with 10" │ │ └─ Filters → Select Class of Service, Status, etc. │ │ │ │ Step 2: Preview Selection │ │ ├─ Click "Preview Selection" button │ │ └─ ✓ "Preview: 47 extension(s) will be modified" │ │ │ │ Step 3: Configure Modifications │ │ ├─ ☐ Class of Service → [Select new CoS] │ │ ├─ ☐ Ring Time → [30 seconds] │ │ ├─ ☐ Language → [Spanish] │ │ ├─ ☐ Account Code → [SALES-2024] │ │ └─ ☐ Call Recording → [Enable incoming/outgoing] │ │ │ │ Step 4: Apply Changes │ │ ├─ Click "Apply Changes" button │ │ └─ ✓ "Successfully modified 47 extension(s)" │ │ │ └─────────────────────────────────────────────────────────────────┘

Quick Tips

TIP
Always Preview First: Use the Preview button to verify your selection before applying changes. This prevents accidental modifications to wrong extensions.

TIP
Use Ranges for Floors/Departments: If extensions are numbered by floor (1000s = Floor 1, 2000s = Floor 2), ranges make selection easy.

CAUTION
Recording Changes Are Immediate: Enabling call recording applies to calls made/received after the change—existing calls are not affected.

---

4. Configuration Fields Reference

Selection Methods

Individual Selection

Feature Description Example
Extension Search Search by number, name, or email Type "John" to find John's extension
Multi-Select Click to toggle selection Click ext 1001, click ext 1005, click ext 1010
Select All Load all domain extensions Click "Select All Extensions" button
Clear All Remove all selected Click "Clear" button
Ranges

Feature Description Example
Start/End Define numeric range bounds Start: 1000, End: 1099
Multiple Ranges Add multiple non-contiguous ranges 1000-1099 + 2050-2099 + 3000-3010
Behavior Includes both start and end values 1000-1005 = extensions 1000, 1001, 1002, 1003, 1004, 1005
Patterns

Pattern Meaning Matches
10 Starts with 10 1000, 1001, 1099, 10
00 Ends with 00 1000, 2000, 9900, 100
35 Starts with 3, ends with 5 305, 3005, 3125, 35
All extensions Every extension in domain
Filters

Filter Options Description
Class of Service Dropdown of available CoS Only extensions with selected CoS
Extension Status Any / Enabled Only / Disabled Only Filter by enabled state
Voicemail Any / Enabled / Disabled Filter by voicemail status
Language Language selector Filter by extension language
Modification Options

Modification Type Description Range/Options
Class of Service Dropdown Change permission level for calls (local, long-distance, international) Available CoS from domain
Ring Time Number Input Seconds before call goes to voicemail 10-120 seconds
Language Dropdown Language for voicemail prompts and IVR menus en-us-emma, es-us-paloma, etc.
Account Code Text Input Billing/reporting code for the extension Any text string
Call Recording Checkboxes Enable/disable recording by direction Incoming, Outgoing, Internal, On-Demand
---
5. Operation Flow / Logic Explanation

Preview Flow

Plaintext
┌─────────────────────────────────────────────────────────────────┐ │ Preview Operation │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. User configures selection (extensionIds, ranges, patterns, │ │ or filters) │ │ │ │ │ ▼ │ │ 2. Frontend sends POST to /api/telephony/bulk-modification/ │ │ preview │ │ │ │ │ ▼ │ │ 3. Backend normalizes payload │ │ ├─ sanitizeSelectionPayload() │ │ └─ Resolves domainId from tenant context │ │ │ │ │ ▼ │ │ 4. Backend generates WHERE clause │ │ ├─ Individual: WHERE id IN (1, 2, 3) │ │ ├─ Ranges: WHERE extension::int BETWEEN 1000 AND 1099 │ │ ├─ Patterns: WHERE extension LIKE '10%' │ │ └─ Filters: WHERE class_of_services_id = 5 AND enabled = t │ │ │ │ │ ▼ │ │ 5. Backend executes COUNT query │ │ │ SELECT COUNT(*) FROM sip_extensions WHERE ... │ │ │ │ │ ▼ │ │ 6. Returns response: { success: true, count: 47 } │ │ │ │ │ ▼ │ │ 7. Frontend displays: "Preview: 47 extension(s) will be │ │ modified" │ │ │ └─────────────────────────────────────────────────────────────────┘

Apply Flow

Plaintext
┌─────────────────────────────────────────────────────────────────┐ │ Apply Operation │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ 1. User clicks "Apply Changes" │ │ │ │ │ ▼ │ │ 2. Frontend validates: │ │ ├─ At least one selection method has values │ │ └─ At least one modification checkbox is enabled │ │ │ │ │ ▼ │ │ 3. Frontend builds payload: │ │ { │ │ extensionIds: [1, 2, 3], // or ranges/patterns/filters │ │ modifications: { │ │ classOfServicesId: 5, │ │ callTimeout: 30, │ │ languageCode: "es-us-paloma", │ │ recording: { recordIncoming: true, ... } │ │ } │ │ } │ │ │ │ │ ▼ │ │ 4. POST /api/telephony/bulk-modification │ │ │ │ │ ▼ │ │ 5. Backend validates and selects target extensions: │ │ SELECT id, extension FROM sip_extensions WHERE ... │ │ │ │ │ ▼ │ │ 6. Backend generates UPDATE query: │ │ generateBulkUpdateQuery(extensionIds, modifications) │ │ │ │ │ ▼ │ │ 7. Executes in transaction: │ │ UPDATE sip_extensions SET │ │ class_of_services_id = 5, │ │ call_timeout = 30, │ │ language_code = 'es-us-paloma', │ │ updated_at = NOW(), │ │ updated_by = 123 │ │ WHERE id IN (1, 2, 3, ...) │ │ │ │ │ ▼ │ │ 8. Returns: { success: true, updatedCount: 47 } │ │ │ │ │ ▼ │ │ 9. Frontend shows success and clears form │ │ │ └─────────────────────────────────────────────────────────────────┘

---

6. Common Scenarios & Examples

Scenario 1: Department Language Change
Context: Marketing department (extensions 2000-2099) needs Spanish prompts.
Plaintext
Selection: Ranges → Start: 2000, End: 2099 Preview: "55 extension(s) will be modified" Modifications: ☑️ Language → es-us-paloma Apply → "Successfully modified 55 extension(s)"

Scenario 2: Enable Recording for Customer Service
Context: All extensions with Class of Service "Customer Service" need call recording.
Plaintext
Selection: Filters → Class of Service: "Customer Service" → Extension Status: Enabled Only Preview: "23 extension(s) will be modified" Modifications: ☑️ Call Recording ☑️ Record Incoming Calls ☑️ Record Outgoing Calls ☐ Record Internal Calls ☐ Record On Demand Apply → "Successfully modified 23 extension(s)"

Scenario 3: Pattern-Based Ring Time Adjustment
Context: All executive extensions (starting with 1) should ring longer.
Plaintext
Selection: Patterns → Pattern: "1*" Preview: "12 extension(s) will be modified" Modifications: ☑️ Ring Time → 45 seconds (from default 30) Apply → "Successfully modified 12 extension(s)"

Scenario 4: Mass Account Code Assignment
Context: Year-end billing requires new account codes for all extensions.
Plaintext
Selection: Individual → Click "Select All Extensions" → 347 extensions selected Modifications: ☑️ Account Code → "FY2026-Q1" Apply → "Successfully modified 347 extension(s)"

---

7. Limitations & Important Notes

Technical Limitations

WARNING
No Undo: Bulk modifications cannot be automatically reversed. Keep a backup or document previous settings before large changes.

WARNING
Domain Scope: Operations are scoped to the currently selected domain. You cannot modify extensions across multiple domains in one operation.

IMPORTANT
XML Regeneration: Some changes (like recording settings) may require XML regeneration for the extension. The system handles this automatically, but very large batches may experience brief delays.

Best Practices

Always Preview First: Never skip the preview step, especially for ranges and patterns

Start Small: Test with a small range before applying to entire departments

Document Changes: Keep a log of bulk modifications for audit purposes

Off-Peak Hours: Run large bulk modifications during low-traffic periods

Verify After: Spot-check a few extensions after bulk changes

Security Considerations

CAUTION
Access Control: Only System Administrators should have access to this module. Misconfigured bulk changes can disrupt service for many users.

CAUTION
Audit Trail: All bulk modifications should be logged with the administrator's user ID and timestamp.

---

8. Troubleshooting Tips

Common Issues

Symptom Possible Cause Solution
"No extensions found" Domain filter mismatch Verify correct domain is selected in header
Preview shows 0 Pattern syntax incorrect Check wildcard usage: not %
"No modifications selected" No checkbox enabled Enable at least one modification checkbox
Partial success Some extensions have constraints Check for unique constraint violations
Slow operation Too many extensions Split into smaller batches (500 max recommended)
Validation Errors

Error Meaning Resolution
"Please select at least one extension" Individual tab empty Search and select extensions
"Please add at least one range" Ranges tab empty Add start/end range values
"Please add at least one pattern" Patterns tab empty Add at least one pattern
"Please select at least one filter" Filters tab, no selections Select at least one filter option
Diagnostic SQL
Check extensions matching a range:
Sql
SELECT extension, name, enabled FROM public.sip_extensions WHERE domain_id = [domain_id] AND extension::int BETWEEN 1000 AND 1099 ORDER BY extension;

Check extensions matching a pattern:
Sql
SELECT extension, name, enabled FROM public.sip_extensions WHERE domain_id = [domain_id] AND extension LIKE '10%' ORDER BY extension;

Verify recent bulk changes:
Sql
SELECT extension, updated_at, updated_by FROM public.sip_extensions WHERE domain_id = [domain_id] AND updated_at > NOW() - INTERVAL '1 hour' ORDER BY updated_at DESC;

---

9. Glossary

Term Definition
Bulk Modification The process of applying the same configuration change to multiple extensions at once
Preview A non-destructive operation that shows how many extensions would be affected before changes are made
Selection Method The technique used to choose which extensions to modify (individual, ranges, patterns, filters)
Range A numeric span of extension numbers (e.g., 1000-1099)
Pattern A wildcard expression to match extensions (e.g., 10 matches 1000, 1001, etc.)
Filter Criteria based on extension properties (Class of Service, enabled status, language)
Class of Service (CoS) Permission level controlling what types of calls an extension can make
Account Code A text identifier used for billing and reporting purposes
Ring Time Duration in seconds before an unanswered call proceeds to voicemail or next action
Transaction Database operation that either completes fully or rolls back entirely—no partial updates
---
10. Suggested UI Improvements

Tooltip Improvements

Field Current Suggested
Ring Time "How long to ring before going to voicemail (10-120 seconds)" "How many seconds the phone rings before proceeding to voicemail or voicemail. Most users prefer 20-30 seconds. Very short times (10s) may frustrate callers."
Patterns N/A "Use as a wildcard: 10 matches 1000-1099, 00 matches 100, 1000, 2000. Patterns are case-sensitive for alphanumeric extensions."
Class of Service N/A "Controls calling permissions. Change carefully—restricting CoS may prevent users from making certain calls."
UX Enhancements

Confirmation Modal: Before applying, show a summary modal:

Plaintext
⚠️ You are about to modify 47 extensions: - Class of Service: Sales Team → Customer Service - Ring Time: (unchanged) → 45 seconds [Cancel] [Apply Changes]

Undo History: Store last 10 bulk operations with ability to revert

Export Before: Add button "Download Current Settings" before applying changes

Progress Indicator: For large batches, show progress bar instead of spinner

Dry Run Mode: Advanced option to generate SQL without executing, for review

Label Changes

Current Suggested Reason
"Ring Time (seconds)" "Ring Duration (seconds)" Clearer terminology
"Configure Modifications" "Changes to Apply" Simpler language
"Preview Selection" "Count Affected Extensions" More descriptive
Filter Enhancements

Add additional filters:

Extension Type (SIP, Hotdesk, Virtual, None)

Billing Enabled (Yes/No)

Agent Profile (for call center extensions)

Date Created (before/after)

Lua Script Status ℹ️

Integration Module

Component Status Notes
Bulk Modification ℹ️ Configuration module Actions applied directly to database records
--- Documentation last updated: January 2026

Feature	Description	Example
Extension Search	Search by number, name, or email	Type "John" to find John's extension
Multi-Select	Click to toggle selection	Click ext 1001, click ext 1005, click ext 1010
Select All	Load all domain extensions	Click "Select All Extensions" button
Clear All	Remove all selected	Click "Clear" button

Feature	Description	Example
Start/End	Define numeric range bounds	Start: 1000, End: 1099
Multiple Ranges	Add multiple non-contiguous ranges	1000-1099 + 2050-2099 + 3000-3010
Behavior	Includes both start and end values	1000-1005 = extensions 1000, 1001, 1002, 1003, 1004, 1005

Pattern	Meaning	Matches
`10`	Starts with 10	1000, 1001, 1099, 10
`00`	Ends with 00	1000, 2000, 9900, 100
`35`	Starts with 3, ends with 5	305, 3005, 3125, 35
	All extensions	Every extension in domain

Filter	Options	Description
Class of Service	Dropdown of available CoS	Only extensions with selected CoS
Extension Status	Any / Enabled Only / Disabled Only	Filter by enabled state
Voicemail	Any / Enabled / Disabled	Filter by voicemail status
Language	Language selector	Filter by extension language

Modification	Type	Description	Range/Options
Class of Service	Dropdown	Change permission level for calls (local, long-distance, international)	Available CoS from domain
Ring Time	Number Input	Seconds before call goes to voicemail	10-120 seconds
Language	Dropdown	Language for voicemail prompts and IVR menus	en-us-emma, es-us-paloma, etc.
Account Code	Text Input	Billing/reporting code for the extension	Any text string
Call Recording	Checkboxes	Enable/disable recording by direction	Incoming, Outgoing, Internal, On-Demand

Symptom	Possible Cause	Solution
"No extensions found"	Domain filter mismatch	Verify correct domain is selected in header
Preview shows 0	Pattern syntax incorrect	Check wildcard usage: not `%`
"No modifications selected"	No checkbox enabled	Enable at least one modification checkbox
Partial success	Some extensions have constraints	Check for unique constraint violations
Slow operation	Too many extensions	Split into smaller batches (500 max recommended)

Error	Meaning	Resolution
"Please select at least one extension"	Individual tab empty	Search and select extensions
"Please add at least one range"	Ranges tab empty	Add start/end range values
"Please add at least one pattern"	Patterns tab empty	Add at least one pattern
"Please select at least one filter"	Filters tab, no selections	Select at least one filter option

Term	Definition
Bulk Modification	The process of applying the same configuration change to multiple extensions at once
Preview	A non-destructive operation that shows how many extensions would be affected before changes are made
Selection Method	The technique used to choose which extensions to modify (individual, ranges, patterns, filters)
Range	A numeric span of extension numbers (e.g., 1000-1099)
Pattern	A wildcard expression to match extensions (e.g., `10` matches 1000, 1001, etc.)
Filter	Criteria based on extension properties (Class of Service, enabled status, language)
Class of Service (CoS)	Permission level controlling what types of calls an extension can make
Account Code	A text identifier used for billing and reporting purposes
Ring Time	Duration in seconds before an unanswered call proceeds to voicemail or next action
Transaction	Database operation that either completes fully or rolls back entirely—no partial updates

Field	Current	Suggested
Ring Time	"How long to ring before going to voicemail (10-120 seconds)"	"How many seconds the phone rings before proceeding to voicemail or voicemail. Most users prefer 20-30 seconds. Very short times (10s) may frustrate callers."
Patterns	N/A	"Use as a wildcard: `10` matches 1000-1099, `00` matches 100, 1000, 2000. Patterns are case-sensitive for alphanumeric extensions."
Class of Service	N/A	"Controls calling permissions. Change carefully—restricting CoS may prevent users from making certain calls."

Current	Suggested	Reason
"Ring Time (seconds)"	"Ring Duration (seconds)"	Clearer terminology
"Configure Modifications"	"Changes to Apply"	Simpler language
"Preview Selection"	"Count Affected Extensions"	More descriptive

Bulk Modification Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is Bulk Modification?

Architecture

Key Tables

API Endpoints

Key Files

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Licensing Considerations

3. Module Overview (End User/Administrator)

What Can You Do?

User Workflow

Quick Tips

4. Configuration Fields Reference

Selection Methods

Individual Selection

Ranges

Patterns

Filters

Modification Options

5. Operation Flow / Logic Explanation

Preview Flow

Apply Flow

6. Common Scenarios & Examples

Scenario 1: Department Language Change

Scenario 2: Enable Recording for Customer Service

Scenario 3: Pattern-Based Ring Time Adjustment

Scenario 4: Mass Account Code Assignment

7. Limitations & Important Notes

Technical Limitations

Best Practices

Security Considerations

8. Troubleshooting Tips

Common Issues

Validation Errors

Diagnostic SQL

9. Glossary

10. Suggested UI Improvements

Tooltip Improvements

UX Enhancements

Label Changes

Filter Enhancements

Lua Script Status ℹ️

Integration Module