Complete Guide to Install and Use OmniMention for Perfex CRM

OmniMention transforms communication across Perfex CRM by enabling instant @ user tagging and $ or # entity linking directly inside rich text editors, task checklists, and discussion forms. This guide walks you through complete installation, global settings configuration, everyday tagging workflows, and personal activity center management to help your team eliminate communication silos and coordinate projects with maximum velocity.

Prerequisites and Compatibility

Before activating OmniMention, ensure your hosting environment meets the following specifications:

• Perfex CRM: Version 3.0.0 or higher (fully tested on 3.0.x and 3.1.x branches).
• PHP: PHP 7.4 through PHP 8.3+.
• Database Engine: MySQL 5.7+ or MariaDB 10.3+ with InnoDB support.
• Editor Compatibility: TinyMCE 4, TinyMCE 5, and TinyMCE 6 engines, along with standard HTML5 textareas and dynamic modal popups.

Step-by-Step Installation

OmniMention follows standard Perfex CRM modular packaging standards and can be deployed in under two minutes using either the administrative interface or direct directory placement.

Method 1: Administrator Panel Upload (Recommended)

1. Log in to your Perfex CRM Administrator Panel.
2. Navigate to Setup > Modules in the left sidebar menu.
3. Click the Upload Module button located at the top right of the screen.
4. Select the omnimention.zip installation package.
5. Click Install. Once the upload completes, locate OmniMention in your module list and click Activate.
6. The installer will automatically run schema migrations, generate specialized composite index tables (tblomnimention_mentions, tblomnimention_entity_tags), and seed default notification matrix preferences.

Method 2: Manual Directory Placement

1. Extract the downloaded omnimention.zip archive on your local workstation.
2. Upload the extracted omnimention directory directly to your server: perfex_crm/modules/omnimention/
3. Verify that directory permissions are set to 755 and file permissions are set to 644.
4. Open Setup > Modules in your admin panel and click Activate.

Global Configuration & Preferences

Once activated, access administrative controls at Setup > Settings > OmniMention or through the sidebar under @ OmniMention > Settings:

• User Trigger Symbol: Default is @. You can customize this character if your organization follows specialized keyboard conventions.
• Entity Trigger Symbol: Default is $. You can also utilize # to trigger CRM entity lookups across all textareas and editors.
• Client Portal Mentions: Toggle whether authenticated client contacts can mention staff members and tag their related records in tickets and project discussions.
• Show Help Icon ('?'): Attaches an unobtrusive 18px circular help trigger to supported textareas and editor toolbars, providing users with a one-click shortcut guide.
• Notification Matrix: Configure granular delivery channels (In-App Bell alerts and automated email notifications) for each individual CRM entity category.

System Architecture & Data Flow

OmniMention executes event interception and database persistence through a clean, decoupled architecture:

flowchart TD
    subgraph UI["User Interaction Layer"]
        A["TinyMCE Rich Text Editor"] 
        B["Standard Form Textareas"]
        C["Task Todo Items & Notes"]
        D["Smart '?' Guide Button"]
    end

    subgraph SEC["Security & Guard Layer"]
        S1["Staff Authentication Guard"]
        S2["Client Portal Permission Scope"]
        S3["Public Guest Decorator Mode"]
    end

    subgraph FE["OmniMention Frontend Engine"]
        K1["Keyup Interceptor (@, $, #)"]
        K2["Autocomplete Finder Panel"]
        K3["Token Inserter & HTML Badge Decorator"]
    end

    subgraph BE["Backend Controller & Model"]
        M1["Api::get_users() with Avatar Resolution"]
        M2["Api::get_entities() Across 8 Modules"]
        M3["Omnimention_model Parser & Cleaner"]
    end

    subgraph DISPATCH["Notification Dispatch"]
        N1["In-App Bell Alerts"]
        N2["Automated HTML Email Delivery"]
        N3["Notification Matrix Settings"]
    end

    subgraph DB["Composite Indexed Storage"]
        D1[("tblomnimention_mentions")]
        D2[("tblomnimention_entity_tags")]
        D3[("tblomnimention_settings")]
    end

    UI --> K1
    SEC -.-> FE
    K1 --> K2
    K2 --> M1
    K2 --> M2
    K2 --> K3
    K3 --> M3
    M3 --> N1
    M3 --> N2
    M3 --> D1
    M3 --> D2
    DISPATCH -.-> D3

Core Usage Workflows

1. Tagging Users with the @ Trigger

Whenever you need input from a team member or client contact, simply type @ inside any task description, ticket response, or discussion textarea:

• Autocomplete Finder Panel: An interactive dropdown immediately appears as you type. Continue typing the person's first name, last name, email address, or department to narrow results.
• Real Profile Avatars: Displays authentic profile avatars directly in the finder modal and on inserted badge pills, providing rapid visual identification.
• Role Distinction: Color-coded badges distinguish Administrators, Staff Members, and Client Contacts.
• Pill Navigation: Clicking any inserted user pill navigates straight to that staff member's administrative profile.

2. Cross-Referencing CRM Records with $ and

Instead of copying long URLs between browser tabs, type $ or # followed by a search keyword to reference 8 core CRM entities:

• Tasks: Display task title, assigned status badge, and priority level.
• Projects: Display project code, title, client company, and milestone deadlines.
• Tickets: Display ticket ID, subject, department, and priority status.
• Invoices: Display invoice number, customer name, and payment status (Paid, Unpaid, Overdue).
• Leads: Display lead name, company name, and current sales pipeline stage.
• Proposals: Display proposal title, client association, and total valuation.
• Estimates: Display estimate reference, client name, and expiration date.
• Contracts: Display contract subject, client, and contract duration.

The diagram below demonstrates the complete sequence from initial keystroke to notification dispatch:

sequenceDiagram
    actor User as Staff Member
    participant Editor as TinyMCE / Textarea
    participant Engine as OmniMention JS Engine
    participant API as Backend API Endpoint
    participant DB as MySQL InnoDB Tables
    participant Notif as Notification Dispatcher
    actor Target as Tagged Colleague

    User->>Editor: Type '@' or '$'
    Editor->>Engine: Trigger Autocomplete Event
    Engine->>API: GET /omnimention/api/users or entities
    API->>DB: Query with Composite Index Lookup
    DB-->>API: Return Ranked Matches (Avatars, Badges)
    API-->>Engine: JSON Response
    Engine->>User: Display Autocomplete Finder Panel
    User->>Engine: Select Target Colleague / Record
    Engine->>Editor: Insert Badge Pill / Markdown Token
    User->>Editor: Submit Comment / Task Note
    Editor->>API: Post Content Payload
    API->>DB: Store Record & Differential Mentions
    API->>Notif: Trigger Notification Matrix
    Notif->>Target: In-App Bell Alert + Contextual Email

3. TinyMCE vs. Plain Textarea Token Handling

OmniMention automatically adapts its insertion strategy depending on the input surface:

• In TinyMCE Editors: Mentions insert as styled HTML badge pills with integrated avatar graphics and click handlers.
• In Plain Textareas & Todo Items: Mentions insert as lightweight Option A Markdown tokens, such as [Alex Smith](staff:12) or [INV-2026-004](invoice:4). When saved and displayed on page reload, the OmniMention decorator automatically converts these tokens into interactive badge pills without corrupting the underlying text column in MySQL.

4. Tracking Discussions in My Mentions

Never lose track of feedback or action items. Open @ OmniMention > My Mentions from the sidebar:

• Real-Time Badge Counter: Displays current unread mention counts directly in your main menu.
• Entity Category Filters: Filter your timeline to view only mentions from Tasks, Tickets, Projects, or Invoices.
• Keyword Search: Instant client-side search across mention snippets and notes.
• UTF-8 and Vietnamese Diacritic Support: Clean text decoding ensures diacritics and special characters render flawlessly without raw markdown artifacts.
• One-Click Read Actions: Mark individual items as read or click "Mark All as Read" with SweetAlert2 confirmation.

High-Performance Database Design

OmniMention is engineered to maintain sub-millisecond query execution even on enterprise Perfex CRM databases with hundreds of thousands of activity records:

• Zero-Filesort Timeline Lookups: Composite index (target_type, target_id, id DESC) allows MySQL to read timeline rows sequentially without sorting files on disk.
• 100% In-Memory Covering Scans: Composite index (rel_type, rel_id, comment_id, target_type, target_id) allows the differential mention scanner to verify existing tags directly in RAM buffer pools without touching disk storage.
• Duplicate Tag Prevention: Unique constraint (source_rel_type, source_rel_id, tagged_entity_type, tagged_entity_id) enforces data integrity at the database engine level.

Security & Public Access Isolation

When external clients view public contracts, proposals, or estimates, OmniMention automatically activates Decorator-Only mode:

• Autocomplete endpoints and search APIs are completely disabled for unauthenticated visitors.
• Floating help icons and finder popups are hidden.
• Internal links are sanitized to ensure confidential organizational data remains protected.

Boost Your CRM Team Collaboration

OmniMention bridges communication gaps across your entire organization. Experience frictionless collaboration, instantaneous record cross-referencing, and real-time team notifications by deploying OmniMention in your Perfex CRM instance today.