OCMLABS/MODULE-SUPPORT-TICKET · ARCHITECTURE

Database schema, service layer, controllers, and routing for OCMLabs_SupportTicket

  • Magento
  • Adobe Commerce
  • Hyvä

This page documents the internal structure of the OCMLabs_SupportTicket module for developers extending or integrating with it.

Module identity

MODULE NAME
OCMLabs_SupportTicket
COMPOSER PACKAGE
ocmlabs/module-support-ticket
COMMERCE METAPACKAGE
ocmlabs/module-support-ticket-commerce
PHP REQUIREMENT
^8.3
MAGENTO DEPENDENCIES
Magento_Catalog, Magento_Customer, Magento_Email, Magento_Sales, Magento_Store

Database schema

ocmlabs_support_ticket

One row per support ticket.

ColumnTypeNotes
ticket_idint, PK, auto-increment
customer_idintFK customer_entity.entity_id, CASCADE delete
product_idint, nullableFK catalog_product_entity.entity_id, SET NULL on delete
order_idint, nullableFK sales_order.entity_id, SET NULL on delete
subjectvarchar(255)Ticket title
statusvarchar(32), default openopen / pending / in_progress / resolved
priorityvarchar(32), default mediumlow / medium / high / urgent
categoryvarchar(64), nullablebilling / shipping / product_issue / general / other
store_idsmallint, nullableFK store.store_id, SET NULL on delete
created_attimestampSet on insert
updated_attimestampAuto-updated on every save

Indexes: customer_id, product_id, status, store_id.

ocmlabs_support_ticket_comment

One row per message in a ticket thread. The initial customer message and all subsequent replies are stored here.

ColumnTypeNotes
comment_idint, PK, auto-increment
ticket_idintFK ocmlabs_support_ticket.ticket_id, CASCADE delete
author_typevarchar(32)customer or admin
author_idintCustomer entity ID or admin user ID
messagetextFull message body
is_editedsmallint(1), default 0Edit flag (reserved for future use)
created_attimestampSet on insert
updated_attimestampAuto-updated on every save

Index: ticket_id.

Service layer

Repositories

  • TicketRepositoryInterface / TicketRepository - Full CRUD for tickets. Implements save(), getById(), delete(), deleteById(), and getList() with SearchCriteriaInterface. Used by all controllers and the admin data provider.
  • CommentRepositoryInterface / CommentRepository - Full CRUD for comments. Comments are loaded by ticket_id when rendering a ticket thread.

Services

NotificationService Handles all outgoing email. Called from the customer and admin comment controllers and the ticket creation controller. Sends five distinct notification types:

  • New ticket - customer confirmation
  • New ticket - admin alert
  • New comment - customer notification (admin replied)
  • New comment - admin notification (customer replied)
  • Ticket resolved - customer confirmation

PurchaseValidator Queries the sales order tables to confirm a given customer has purchased a given product. Any order that is not canceled or closed counts as a purchase. Used to populate the product dropdown on the ticket creation form with only verified purchases, to decide the product page button state, to look up the order linked to a new ticket, and to reject server-side any attempt to submit a ticket against a product the customer does not own.

Source models

ClassValues
Source\Statusopen, pending, in_progress, resolved
Source\Prioritylow, medium, high, urgent
Source\Categorybilling, shipping, product_issue, general, other
Source\TicketProductThe products that have tickets (options for the grid’s Product filter)

The Status, Priority, and Category source models are used by the listing grid filter and the edit form select.

Admin UI components

Listing (ocmlabs_support_ticket_listing.xml)

Standard Magento UI component listing. The DataSource is backed by Model\ResourceModel\Ticket\Grid\Collection, which adds a customer_name column (customer first and last name) so the grid can filter and sort by name. Other columns:

  • Ui\Component\Listing\Column\ProductName - Loads the product and returns its name from product_id. The column filters with a dropdown from Source\TicketProduct and is not sortable.
  • Ui\Component\Listing\Column\TicketActions - Renders the View action link per row.

Mass actions: four flat Set Status: Open / Pending / In Progress / Resolved entries (each submits to the MassStatus controller with its status value) and Delete (submits to the MassDelete controller after a confirmation).

Form (ocmlabs_support_ticket_form.xml)

Edit form with two fieldsets and three buttons: Save Ticket, Delete Ticket (posts to the Delete controller after a confirmation), and Back. The DataProvider is TicketFormDataProvider, which extends the standard form data provider and enriches the raw row with resolved customer_name and product_name values before handing it to the form.

  • Ticket Details fieldset - subject (editable), status (select), priority (select), category (select), product_name (disabled), plus the Block\Adminhtml\Ticket\Edit\Metadata block, which shows the customer name as a link to the customer account and the Created At and Last Updated timestamps as plain text.
  • Comments fieldset - Renders the Block\Adminhtml\Ticket\Edit\Comments block, which loads all comments for the ticket and outputs the conversation thread as HTML. Messages are labeled Support Team or Customer. The Add Reply textarea and Send Reply button are part of this block, posting to the Ticket\AddComment controller.

Controllers

Admin (Controller/Adminhtml/Ticket/)

ControllerAction
IndexRenders the ticket listing page
EditLoads a ticket by ID and renders the edit form
NewActionRenders an empty edit form for admin-created tickets
SavePersists ticket field changes (subject, status, priority, category)
DeleteDeletes a single ticket by ID (the Delete Ticket button) and returns to the grid
MassDeleteDeletes multiple tickets from grid selection
MassStatusUpdates status on multiple tickets from grid selection
AddCommentSaves an admin comment, changes an open ticket to in_progress (other statuses are unchanged), and triggers the customer notification email

Frontend (Controller/Ticket/)

ControllerAction
IndexCustomer’s ticket list (requires login; scoped to customer_id)
CreateRenders the ticket creation form with available products (via PurchaseValidator)
CreatePostValidates and saves a new ticket + initial comment; triggers the new-ticket notifications
ViewLoads a ticket and its full comment thread (ownership-checked against the session customer)
AddCommentSaves a customer reply; changes in_progress to pending (other statuses are unchanged); triggers the admin notification. Replies to a resolved ticket are rejected.
ResolveSets ticket status to resolved; triggers the resolved notification to the customer
AjaxCreateAjax endpoint used by the product page popup and the Open a Support Ticket form; creates a ticket without a full page navigation
ProductStateUncached JSON endpoint returning loggedIn and purchased for a product, used by the product page button under full page cache

Frontend blocks and templates

BlockTemplatePurpose
Block\Customer\TicketCreatecustomer/ticket-create.phtmlRenders the create form with the customer’s list of purchased products (filtered by PurchaseValidator) and the category/priority option arrays.
Block\Customer\TicketListcustomer/ticket-list.phtmlLoads the customer’s tickets for the current store, newest first.
Block\Customer\TicketViewcustomer/ticket-view.phtmlLoads a single ticket with its full comment thread. Handles ownership validation and hides the reply form and Mark as Resolved button on resolved tickets.
Block\Product\SupportButtonproduct/support-button.phtmlRenders the support button on product pages. Logged-out visitors get a login link from the cached page; for logged-in customers the button state is fetched from ProductState after load, and buyers submit the popup form to AjaxCreate.

Routing

  • Admin router (etc/adminhtml/routes.xml): frontend name ocmlabs_support, area adminhtml.
  • Frontend router (etc/frontend/routes.xml): frontend name ocmlabs_support, area frontend. All frontend ticket routes require a logged-in customer session. Requests for another customer’s ticket redirect to the ticket list with a “Ticket not found” message.

Email templates

Five templates are registered in etc/email_templates.xml. Default template files live in view/frontend/email/. Every template receives the common variable set; some add extras:

TEMPLATE VARIABLES
all:                ticket_id, ticket_subject, ticket_status, ticket_priority,
                    view_url, account_url
new ticket admin:   + customer_name, customer_email, admin_url
comment customer:   + comment_message
comment admin:      + customer_name, comment_message, admin_url

All sending goes through NotificationService, which returns without sending when general/enabled is set to No.

Templates are configurable per store view under Stores > Configuration > OrangeCollar > Support Tickets > Email Templates. See Email Notifications for the customization procedure.

ACL resources

ACL TREE
Magento_Backend::admin
└── OCMLabs_SupportTicket::support          "Support" - also guards the config section
    ├── OCMLabs_SupportTicket::tickets      "Support Tickets" - menu item and grid
    │   ├── OCMLabs_SupportTicket::tickets_manage  "Edit / Reply" - open, save, reply, Set Status
    │   └── OCMLabs_SupportTicket::tickets_delete  "Delete" - single and bulk delete
    └── OCMLabs_SupportTicket::config       "Support Ticket Configuration" - not checked in 1.0.8

The admin menu item under Stores > Support requires OCMLabs_SupportTicket::tickets. Opening a ticket (Edit), Save, AddComment, and MassStatus require OCMLabs_SupportTicket::tickets_manage; Delete and MassDelete require OCMLabs_SupportTicket::tickets_delete. The configuration section declares OCMLabs_SupportTicket::support as its resource.

System configuration paths

All paths are rooted at ocmlabs_support_ticket/* and rendered under Stores > Configuration > OrangeCollar > Support Tickets.

PathTypeDefault
general/enabledselect (Yes/No); gates notification emails only1
general/admin_emailtext(empty)
general/email_senderselectgeneral
email_templates/new_customer_templateselectdefault
email_templates/new_admin_templateselectdefault
email_templates/comment_customer_templateselectdefault
email_templates/comment_admin_templateselectdefault
email_templates/resolved_templateselectdefault

See also

Related pages

In this module