Frappe Crm Xt

bench get-app https://github.com/rtCamp/frappe_crm_xt

[![Listed on Frappe Gems](https://frappegems.com/api/method/frappe_gems.seo.badge?app=rtCamp%2Ffrappe_crm_xt)](https://frappegems.com/gems/apps/rtCamp/frappe_crm_xt)

# Frappe CRM XT Extensions for [Frappe CRM](https://github.com/frappe/crm) that add features without forking the core app. - **[Global search bar](#global-search-bar)** — Cmd/Ctrl+K modal backed by [`rtcamp/frappe_search`](https://github.com/rtCamp/frappe_search) *(optional)*. - **[Extensible sidebar](#extensible-sidebar-crm_sidebar-hook)** — any installed Frappe app can inject list views, routes, groups, or separators into the CRM sidebar via the `crm_sidebar` hook. - **[Events tab](#events-tab)** — calendar events tab injected into every Lead and Deal page; create, edit, duplicate, and delete Frappe `Event` records linked to the record. - **[Event notifications](#event-notifications)** — scheduler sends in-browser realtime alerts and optional emails to event owners and participants before their events. - **Gmail thread activities** — activity entries on Lead/Deal records resolve Gmail threads via [`rtcamp/frappe_gmail_thread`](https://github.com/rtCamp/frappe_gmail_thread) *(optional)*. - **[Address management (Deal only)](#address-management)** — add, create, link, and unlink `Address` records directly from Deal forms via an inline HTML panel. - **[Follow button (eye icon)](#follow-button)** — injected into the Lead/Deal header icon row. Toggles `Document Follow` for the current user; filled eye = following, outline eye = not following. - **Quotation auto-items** — opening a `Quotation` from a CRM Deal's "Create Quotation" link auto-populates items, customer, currency, and missing values from the source Deal. - **Public Lead intake API** — guest-allowed `POST` endpoints for creating CRM Leads and uploading files against them; intended for website / external form integrations. - **Gmail Add-on backend** — whitelisted endpoints powering the Gmail sidebar Add-on (contact lookup by email, linked Leads / Deals, latest activity). - **Bundled fixtures** — Lead & Deal field layouts, Property Setters, Custom Fields, CRM Form Scripts, and a curated set of CRM View Settings ship as fixtures and install automatically. (Optional) - **[Project creation on Won](#project-creation-on-won-deal)** — when a Deal is marked Won, dialogs guide the user through updating MSA & Insurance details on the linked Customer and creating an ERPNext `Project` pre-filled from the deal. --- ## Architecture Frappe CRM XT ships a **Vite-built Vue 3 IIFE bundle** (`crm_xt_app.js`) that is loaded into the Frappe CRM SPA alongside the standard Frappe assets. The bundle: - mounts a minimal `App.vue` root component on a `#crm-xt-app` div injected into the page - uses `MutationObserver` to watch the CRM SPA's DOM and inject the sidebar, custom routes, and the Events tab without touching any FCRM source files - ships its own copy of Vue 3 and [frappe-ui](https://github.com/frappe/frappe-ui), so all components use the same design tokens and Tailwind classes as native CRM views ### Frontend components | Component | Purpose | |-----------|---------| | `App.vue` | Root — sidebar injection, route registration, Events tab injection, global search trigger | | `ExtListView.vue` | Full-featured list view (frappe-ui `ListView`, filters, sort, column picker, pagination) | | `InjectedEventsTab.vue` | Events tab timeline and empty state | | `InjectedEventModal.vue` | Create / edit / delete / duplicate Event dialog | | `SearchDialog.vue` | Cmd/Ctrl+K global search modal | | `EventNotifications.vue` | Per-event notification rules editor | | `ListFilterLocal.vue` | Ad-hoc filter panel used inside `ExtListView` | | `Attendee.vue` | Email-tag input for event attendees | | `UserAvatar.vue` | Resolved user avatar with fallback initials | ### Backend modules | Module | Purpose | |--------|---------| | `api/activity.py` | Overrides `crm.api.activities.get_activities`; appends Gmail thread entries | | `api/event.py` | `get_doc_events`, create/save/delete helpers, notification scheduler tasks | | `api/follow.py` | Document Follow toggle endpoint | | `api/contact.py` | Gmail Add-on contact lookup endpoints | | `api/quotation.py` | Quotation auto-populate helper | | `api/search.py` | Global search backend (frappe_search or built-in fallback) | | `api/sidebar.py` | Reads `crm_sidebar` hooks from all installed apps and returns merged item list | --- ## Features ### Global Search Bar Press **Cmd+K** (macOS) or **Ctrl+K** (Linux/Windows) anywhere in Frappe CRM to open a full-screen search modal. Two backends are tried in order: | Priority | Backend | Notes | |----------|---------|-------| | 1 | [`rtcamp/frappe_search`](https://github.com/rtCamp/frappe_search) | Full-text search with `` highlighting. Used when installed. | | 2 | Frappe built-in global search | `frappe.utils.global_search` — always available, no extra install. | --- ### Events Tab Every Lead and Deal page gains an **Events** tab injected at the right end of the tab bar. **Capabilities:** - Timeline feed of all `Event` records linked to the current Lead/Deal via `Event Participants` - **Create** a new event — title, date/time or all-day, color, attendees (email tags), visibility, location, description - **Edit** an existing event — all fields editable; changes saved via `frappe.client.save` - **Delete** an event (with confirmation) - **Duplicate** an event - Color-coded accent bar per event card; color picker shows the active selection - Participant avatar stack on each card (up to 3 + overflow count) Events are stored as standard Frappe `Event` documents and also appear in the Frappe Desk Calendar (`/app/event`). **Permissions note:** Events are fetched via `frappe_crm_xt.api.event.get_doc_events`, which bypasses the child-doctype read permission issue that prevents direct `frappe.client.get_list` calls on `Event Participants`. --- ### Event Notifications Scheduler tasks fire at every interval and send notifications to event owners and participants ahead of their events. Per-event rules can be configured in the `Event Notifications` child table on each Event record. If no per-event rules exist, global defaults from **FCRM Settings** are applied. | Setting | Description | |---------|-------------| | `event_notifications` | Rules for timed events | | `all_day_event_notifications` | Rules for all-day events | Each rule specifies: `type` (Notification / Email), `before` (number), `interval` (minutes / hours / days / weeks), and optionally `time` (for all-day events). --- ### Address Management Every CRM Deal form gains a custom **Addresses** HTML panel (not shown on CRM Lead). It renders all `Address` records linked to the Deal via `Dynamic Link`. **Capabilities:** - **List** all linked addresses with collapsible full-address detail - **Create** a new address and automatically link it to the record - **Link** an existing `Address` record by searching and selecting it - **Unlink** an address (removes the Dynamic Link entry; does not delete the Address document) - **Edit** — each card has a direct link to the address's Frappe Desk form --- ### Follow Button An eye icon is injected into the Lead/Deal header icon row: - **Filled eye** — you are currently following this record - **Outline eye** — you are not following this record Clicking the button calls the `frappe_crm_xt.api.follow.toggle_follow` endpoint and auto-enables `track_changes` on the doctype if needed. --- ### Project Creation on Won Deal When a CRM Deal's status is set to **Won**, two sequential dialogs are shown automatically: 1. **MSA & Insurance Details** — pre-filled from the linked ERPNext `Customer`; saves MSA start/end date, document link, insurance requested flag, insurance start/end date, and insurance document link back to the Customer. 2. **Create Project** — collects Project Manager, Territory, Billing Type, Customer, Currency, Estimated Hours, Service Type, Opportunity Amount, and Project Type; creates an ERPNext `Project` and opens it in a new tab. If a project matching the deal already exists, the creation dialog is skipped and an **Open Project** action is added to the Deal's action menu instead. **Customer custom fields required** (shipped as fixtures in `custom_field.json`): | Field | Type | Description | |-------|------|-------------| | `custom_msa_start_date` | Date | MSA start date | | `custom_msa_end_date` | Date | MSA end date | | `custom_msa_document_link` | Data | Link or path to MSA document | | `custom_insurance_requested` | Check | Whether insurance was requested | | `custom_insurance_start_date` | Date | Insurance start date | | `custom_insurance_end_date` | Date | Insurance end date | | `custom_insurance_document_link` | Data | Link or path to insurance document | --- ### Extensible Sidebar (`crm_sidebar` hook) Any installed Frappe app can add items to the CRM sidebar by defining a `crm_sidebar` list in its `hooks.py`. Items appear below the built-in "Call Logs" entry. Four item types are supported: | `type` | Description | |--------|-------------| | `"list_view"` | Opens the built-in list view at `/xt/list/` | | `"route"` | Navigates to an arbitrary URL (internal or external) | | `"separator"` | Renders a horizontal divider line | | `"group"` | Collapsible section; child items live in the `"items"` key (one level deep) | #### Full Hook Reference ```python # hooks.py (in any installed Frappe app) crm_sidebar = [ { # ── Required ────────────────────────────────────────────────── "label": "Purchase Orders", # Sidebar display label "type": "list_view", # "list_view" | "route" | "separator" | "group" # ── Required for type == "list_view" ────────────────────────── "doctype": "Purchase Order", # ── Required for type == "route" ────────────────────────────── # "url": "/app/purchase-order", # ── Optional ────────────────────────────────────────────────── "icon": "shopping-cart", # Lucide icon name (lucide.dev/icons) # Filters shown in the filter UI — users can see and remove them "default_filters": { "status": ["=", "To Receive and Bill"], }, # Filters always applied but never shown in the filter UI "hidden_filters": { "company": ["=", "My Company"], }, # Columns to display (overrides DocType's in_list_view fields) "fields": ["supplier", "transaction_date", "status", "grand_total"], # Initial sort "default_sort": {"field": "transaction_date", "dir": "desc"}, # Fieldname for the toolbar quick-search input # Type-aware: Link → autocomplete, Select/Check → dropdown, # Date/Datetime → date picker, everything else → text "search_field": "supplier", # URL template opened on row click; {name} is replaced with the record name # Defaults to /app// "row_url": "/desk/query-report/{name}", }, {"type": "separator"}, { "label": "Procurement", "type": "group", "icon": "package", "items": [ { "label": "Suppliers", "type": "list_view", "doctype": "Supplier", "icon": "building", }, { "label": "Support Portal", "type": "route", "url": "https://support.example.com", "icon": "external-link", }, ], }, ] ``` #### Option Reference | Key | Type | Required | Description | |-----|------|----------|-------------| | `label` | `str` | ✅ | Sidebar display text | | `type` | `str` | ✅ | `"list_view"`, `"route"`, `"separator"`, or `"group"` | | `doctype` | `str` | `list_view` only | Frappe DocType to display | | `url` | `str` | `route` only | Destination URL | | `icon` | `str` | — | [Lucide](https://lucide.dev/icons/) icon name (default: `"list"`) | | `default_filters` | `dict` | — | Pre-applied filters; users can see and clear them | | `hidden