Features & How-To Guides

This document details every major feature in ShahiAssist and provides step-by-step “how-to” instructions for common tasks, admin flows, and frontend usage.

—

Table of Contents

1. Ticketing System Overview
2. Creating & Managing Tickets (Admin)
3. Customer-Facing Workflows (Submit Ticket / My Tickets)
4. Knowledge Base Authoring
5. Custom Fields & Forms
6. Email Notifications
7. Roles & Permissions
8. Export / Import
9. UI Customizations & Shortcodes
10. Troubleshooting Tips (quick links)

—

1. Ticketing System Overview


ShahiAssist provides a full ticket lifecycle with the following components:

• CPT sa_ticket for storing tickets
• Statuses: saopen, sainprogress, sapending, saresolved, saclosed
• Priorities and Categories as taxonomies
• Assignment engine (manual + auto modes)
• Guest ticket submission option
• Threaded replies with attachments and internal notes
• Ticket metadata (customer name/email, product/workspace, SLA tags)

Key admin screens:

• Tickets > All Tickets — listing
• Tickets > Add New — manual creation
• Tickets > Categories / Priorities — taxonomy management

2. Creating & Managing Tickets (Admin)


Create a New Ticket


• WP Admin → Tickets → Add New
• Enter Subject and Description
• Select Customer (optional) — either select a registered user or enter a guest email
• Choose Category and Priority
• Set Assigned Agent (optional)
• Pick Status (defaults to “Open”)
• Add any Custom Fields (if configured)
• Click Publish / Create Ticket

Notes:

• Ticket ID and creation timestamp are auto-generated.
• If guest submission is enabled, a confirmation email will be sent when created manually if the guest email is present.

Change Status & Add Replies


• Open the ticket and use the status dropdown meta box to change status.
• Use the reply composer at the bottom to add a public reply or internal note.
• Attach files via the attachment control; allowed types are configurable in Settings → Advanced.

Bulk Actions


• From Tickets > All Tickets, select checkboxes and choose bulk actions: Change status, Assign to, Delete, Export.
• Bulk assign will evenly distribute to chosen agent(s) by selected mode.

Auto-Assignment Modes


• Disabled: no automatic assignment.
• Round-robin: cycles through available agents.
• Least busy: assigns to agent with fewest open tickets.
• Random: random selection from available agents.

Configure at: ShahiAssist → Settings → Tickets → Auto-Assign

3. Customer-Facing Workflows (Submit Ticket / My Tickets)


Submit Ticket Page ([sasubmitticket])


• Shortcode renders the two-column form (left: form, right: guidance sidebar).
• Fields: Subject, Description, Email (guest), Product (optional), Category, Priority, Custom Fields, Attachments.

How to enable guest submissions:

• Settings → Tickets → General → Guest Submissions → Enable
• Optionally enable captcha or honeypot (Settings → Integrations)

Form validation rules:

• Subject: required (min 5 chars)
• Description: required (min 15 chars)
• Email: required for guest submissions; validated with PHP filter_var

Custom success flow:

• After submission, the plugin shows a success message and an optional link to the My Tickets page
• Optionally redirect to a custom page from Settings → Tickets → Submission Redirect

My Tickets Page ([samytickets])


• Shortcode renders logged-in user’s ticket dashboard
• Features: filter chips, product dropdown, ticket cards, search
• Customers can open tickets, see status, and add replies via frontend composer

Agent limitation and visibility:

• Agents can view any ticket via admin. The frontend My Tickets is scoped to the current user by default unless a role override is set in Settings → Tickets → Frontend Visibility

4. Knowledge Base Authoring


KB uses CPT sakbarticle with categories and tags.

Create an Article


• Admin → KB Articles → Add New
• Title, content (Rich Editor + optional Markdown import)
• Assign KB Category and Tags
• Upload featured image and attachments
• Set SEO meta (if Yoast/Rank Math integrated)
• Publish

Article Settings & Options


• Featured: checkbox to surface on the KB landing page
• Ratings: toggle to allow helpful/not helpful voting
• View counts: enabled by default (can be disabled in Settings → Knowledge Base)

Importing Content


• Tools → Import → KB Import supports .md, .txt, and a special JSON format exported by ShahiAssist
• Use Export/Import > KB Articles to migrate content between sites

Related Articles


• Related articles are chosen by tag/category similarity. Configure count and algorithm in Settings → Knowledge Base → Related Articles

5. Custom Fields & Forms


ShahiAssist supports custom fields for tickets and KB articles.

Add Custom Fields via Admin


• Settings → Custom Fields → Add New Field
• Define:

– Name (internal key)
– Label (display name)
– Type (text, textarea, select, checkbox, file)
– Options (for select/checkbox; comma-separated)
– Applies to: tickets | kb_articles
– Required: yes/no

• Save field. It will automatically appear on relevant forms and the admin screens.

Programmatic Fields (example)


`php
add_action(‘init’, function() {
$fields = getoption(‘sacustom_fields’, []);
$fields[] = [
‘name’ => ‘environment’,
‘label’ => ‘Environment’,
‘type’ => ‘select’,
‘options’ => ‘production,staging,development’,
‘applies_to’ => ‘tickets’,
‘required’ => true
];
updateoption(‘sacustom_fields’, $fields);
});
`

Displaying Custom Fields in Templates


• Use template tags in your theme overrides or plugin hooks:

`php
$fields = shahiassistgetticketmeta($ticketid, ‘customfields’);
foreach($fields as $k => $v) {
echo ‘

‘ . eschtml($v[‘label’]) . ‘: ‘ . eschtml($v[‘value’]) . ‘

‘;
}
`

6. Email Notifications


Template Variables


• {ticketid}, {customername}, {ticketsubject}, {ticketurl}, {agentname}, {companyname}

Editing Templates


• Admin → Settings → Emails → Click template name → Edit content
• Use HTML or plain text; placeholders are replaced at send time

SMTP & Deliverability


• We recommend using WP Mail SMTP or similar plugin
• Verify From address is from your domain to avoid spam filtering

Event Mapping


• New ticket: customer + admin
• Reply from customer: assigned agent
• Status changed: customer
• Ticket assigned: agent

7. Roles & Permissions


Default custom roles:

• support_agent — view/edit tickets, reply
• support_manager — all agent rights + assign/delete/manage categories

Customize via Settings → Roles or programmatically via filters. Example:
`php
addfilter(‘shahiassistdefaultcapabilities’, function($caps) {
$caps[‘supportagent’][] = ‘exporttickets’;
return $caps;
});
`

8. Export / Import


• Support Export/Import for tickets, KB articles, and settings
• Exports are JSON with metadata; attachments are referenced by URL
• Import maps users by email; unknown users create guest entries

Best practices:

• Export before major upgrades
• Use staging environment for large imports

9. UI Customizations & Shortcodes


Shortcodes:

• [sasubmitticket] — Submit Ticket form
• [samytickets] — Customer dashboard
• [saknowledgebase] — KB landing page
• [saticketdetail id="123"] — Single ticket view (admin-only)

Theme Overrides:

• Copy templates from includes/modules/ticketing-system/views/ into your theme under shahiassist/ to override
• Recommended override pattern: your-theme/shahiassist/tickets/single.php

CSS Customizations:

• Use the .sa- prefixed classes to scope changes (see frontend-dark.css)
• Add custom CSS in your theme or enqueue a small stylesheet via wpenqueuestyle

10. Troubleshooting Tips (Quick Links)


• If emails not sending → check SMTP, test with WP Mail SMTP
• If shortcodes output raw text → ensure page content not filtered/visual editor issues
• If REST API failing → flush permalinks and check authentication

—

If you’d like, I can now add inline code samples or create theme override templates for the most common views (ticket list, ticket single, KB article). Tell me which templates you want next.