Skip to content

communication.md

Latest commit

 

History

History
118 lines (97 loc) · 8.94 KB

communication.md

File metadata and controls

118 lines (97 loc) · 8.94 KB

Frappe Core Doctype: Communication

The Communication Doctype is a cornerstone of Frappe's interaction tracking capabilities, designed to log and manage various forms of communication, with a strong emphasis on email. It also supports other mediums like Chat, Phone, SMS, and system events.

Core Purpose

  • To serve as a central repository for all communications sent from or received into the Frappe system.
  • To link communications to relevant documents (e.g., Leads, Sales Orders, Issues) and Contacts.
  • To facilitate email integration, including sending, receiving, replying, forwarding, and tracking email status.
  • To provide a timeline view of interactions related to specific documents.
  • To support features like automated email responses, email templates, and scheduling emails.

Key Files Defining Communication

  • communication.json: Defines the schema (fields, properties, permissions).
  • communication.py: Contains the main server-side Python controller logic.
  • communication.js: Handles client-side JavaScript for the Communication form, providing an email client-like interface.
  • email.py: Likely contains specialized functions for email processing, validation, and interaction with email services (used by communication.py).
  • mixins.py: Probably contains reusable Python classes or methods (mixins) for email functionalities, shared with communication.py.
  • README.md: Provides a brief overview.
  • communication_list.js: Customizes the list view.
  • test_communication.py: Unit tests.

communication.json - Schema Definition

This JSON file outlines the extensive structure for Communication entries.

  • email_append_to: 1: Enables direct creation/linking of Communications from incoming emails.
  • sender_field: "sender", subject_field: "subject": Designated fields for email integration.
  • Key Fields:
    • subject (Small Text, Required): The subject line of the communication.
    • communication_medium (Select): Type like "Email", "Chat", "Phone", "SMS", "Event", "Meeting", "Visit", "Other".
    • content (Text Editor): The main body/message of the communication.
    • sender (Data, Email): Sender's email address.
    • recipients, cc, bcc (Code, Email): Email recipient lists.
    • phone_no (Data): For phone/SMS.
    • status (Select): "Open", "Replied", "Closed", "Linked".
    • sent_or_received (Select, Required): Indicates if the communication was "Sent" or "Received".
    • communication_date (Datetime): Timestamp of the communication.
    • reference_doctype & reference_name (Dynamic Link): Links the communication to a primary Frappe document.
    • timeline_links (Table, child: "Communication Link"): Allows linking a single communication to multiple documents for comprehensive timeline views.
    • email_account (Link to Email Account): The Frappe Email Account used.
    • in_reply_to (Link to Communication): Links to a previous communication in a thread.
    • delivery_status (Select, Hidden): Tracks detailed email delivery events (Sent, Bounced, Opened, Clicked, etc.).
    • email_template (Link to Email Template): If an email template was used.
    • send_after (Datetime): For scheduling future email dispatches.
    • Email inbox fields: message_id, uid (IMAP UID), imap_folder, email_status ("Open", "Spam", "Trash").
  • Permissions:
    • Complex, with different access levels for "System Manager", "Inbox User", and "All" (based on ownership). Permissions are also defined at different permlevels, suggesting field-level security.
  • Other Properties:
    • track_changes: 1, track_seen: 1.
    • row_format: "Compressed" for a compact list view.

communication.py - Server-Side Logic

The Python controller is rich with features for managing communications.

  • Communication(Document, CommunicationEmailMixin) Class:
    • Inherits from CommunicationEmailMixin for shared email functionalities.
    • onload(): Creates "Email Flag Queue" entries for received emails to mark them as read on the IMAP server.
    • validate(): Extensive validation including:
      • Setting defaults for user, subject, sent_or_received.
      • Calling validate_email() (from communication/email.py).
      • Parsing email content/recipients for automatic timeline_links based on doctype+docname@domain patterns.
      • Linking to Contact records.
      • Setting sender's full name.
      • Marking emails as spam if sender is on a spam list.
    • after_insert(): Updates status of replied-to communications; notifies changes for real-time updates.
    • set_signature_in_email_content(): Appends user or default outgoing email signatures.
    • on_update(): Updates the _comments cache on the parent document and calls update_parent_document_on_communication() (or a custom hook on the parent) to update fields like status or response times.
    • notify_change(): Publishes real-time events for UI updates on related documents.
    • set_delivery_status(): Updates the delivery_status field based on "Email Queue" records.
    • Manages timeline_links (add, get, remove, deduplicate).
  • Global Functions:
    • has_permission(): Custom permission logic, allowing read access if the user can read the referenced document.
    • get_permission_query_conditions_for_communication(): Tailors list view visibility based on user roles and their associated "User Email" accounts.
    • Email parsing utilities (get_contacts, get_emails, parse_email, get_email_without_link).
    • update_parent_document_on_communication(): Updates status and response time metrics (e.g., first_response_time, avg_response_time) on linked parent documents like "Issue" or "Support Ticket".

communication.js - Client-Side Logic

Provides a feature-rich interface, especially for emails.

  • onload(frm): Sanitizes HTML content and sets filters for reference_doctype selection.
  • refresh(frm):
    • Sets the content field to read-only.
    • Adds numerous custom buttons for email actions if the communication is a received email:
      • "Reply", "Reply All", "Forward": Opens the frappe.views.CommunicationComposer.
      • "Mark as Unread/Read", "Mark as Spam", "Move To Trash": Trigger server-side actions, often via an email flag queue or inbox management methods.
      • "Move": Opens a dialog to move the email to another configured Email Account.
      • "Contact" (Create): To quickly create a Contact from sender details.
    • Adds "Close"/"Reopen" buttons for managing communication status.
    • Adds a "Relink" button to change the reference_doctype and reference_name.
  • Dialog Handlers (show_relink_dialog, show_move_dialog): Manage UI for relinking and moving emails.
  • Action Handlers (mark_as_read_unread, mark_as_closed_open, reply, reply_all, forward_mail, add_to_contact, mark_as_spam, move_to_trash): Implement the logic for the custom buttons, often by calling server-side methods or opening the composer.
  • get_mail_args(frm): A helper to prepare data for the CommunicationComposer.

email.py and mixins.py

  • These files (not fully analyzed here) would contain more specialized Python code for:
    • email.py: Email validation, parsing, interacting with SMTP/IMAP servers (possibly via EmailAccount Doctype's logic), handling email headers, content types, and attachments.
    • mixins.py: Reusable methods for email functionalities that might be shared across different Doctypes or modules that deal with emails.

README.md Overview

  • Confirms that "Communication" tracks emails/messages.
  • Highlights that receive.py (likely frappe.email.receive) handles incoming mail and creates Communication documents.

How It's Used

  • Sending Emails: Users can compose and send emails from within Frappe (e.g., from a Sales Order, clicking "Email"). This creates a "Sent" Communication.
  • Receiving Emails: Frappe polls configured Email Accounts. Incoming emails are fetched (by frappe.email.receive) and new "Received" Communication documents are created.
  • Document Timeline: Communications linked to a document (e.g., an Issue) appear in its timeline, providing a history of all interactions.
  • Automated Notifications: System notifications (e.g., workflow approvals, alerts) can be sent as emails and logged as Communications of type "Automated Message".
  • Support/CRM: Heavily used in modules like Support (for Issues) and CRM (for Leads, Opportunities) to track all customer interactions.
  • Scheduled Emails: Emails can be scheduled to be sent later using the send_after field.

The Communication Doctype is a critical hub for managing interactions, providing a unified record and interface for emails and other communication channels within the Frappe ecosystem.