Nomad Support Desk Free - Implementation Guide

Edition scope

Nomad Support Desk Free is a complete standalone WordPress ticketing foundation. It stores tickets, replies, customers, resources, time entries, billing batches, signatures, email events and AI resources in WordPress database tables created by the plugin.

The embedded Ticket AI engine belongs to Service Desk Free. It does not call, license or require the separate AI Support Agent plugin.

• Admin ticket management and customer records
• Logged-in customer support portal
• Assigned-resource mobile portal
• Inbound email webhook
• Time capture and billing batches
• Customer/job-card signature capture
• CRM status tagging and Accounting Pro invoice integration when those products are detected
• Knowledge-only, web-only or combined Ticket AI analysis

Edition boundaries

Free does not provide Pro attachment management, customer email event notifications, the Outlook-friendly structured email template, quote/onsite workflows or customer analytics PDF downloads. Those are documented in the Pro guides.

Core status and priority model

Runtime and data ownership

The Free plugin owns the active runtime when Pro is not active. It creates and reads its own nsd_ tables, registers the customer and resource shortcodes, schedules the billing task, and loads the embedded AI engine. All operational data remains in the site's WordPress database; the portal is a view over that data rather than a separate hosted service.

When Pro is later installed, Free must remain active as the required foundation, but Pro supplies the combined runtime. This prevents two copies of the same hooks and shortcodes from running at once. Implementers should therefore treat Free as the data foundation and Pro as an extension, not as two independent desks.

Lifecycle timestamps and reporting

The status is more than a label. The first public staff response populates the first-response time; moving to Resolved records the resolution time; moving to Closed records the closure time. Analytics use those timestamps, so testing should include deliberate status changes and a genuine public reply rather than editing records directly in the database.

Technical requirements

Decisions to make

• Who may administer the desk and change settings
• Which WordPress users will become support resources
• Whether customers will self-register or be created by staff
• Which page will contain each shortcode
• Whether inbound email will create unknown customers
• Whether exact email or company-domain matching is allowed
• Whether CRM sync and Accounting time billing will be enabled
• Whether Ticket AI will use local knowledge only or an external API and live web research

Data and privacy planning

Ticket descriptions may contain customer, site or technical information. Decide what may be submitted to an external AI provider before enabling natural-language answers or internet research. Service Desk excludes stored licence-key fields and customer identity fields from prepared AI context and redacts common secrets, but administrators must still set an appropriate internal policy.

Deployment worksheet

• Production URL, staging URL and responsible site administrator
• WordPress and PHP versions, database prefix and backup location
• Customer portal, resource portal and sign-off page URLs
• Support mailbox, sender identity and mail-delivery provider
• Inbound bridge owner, endpoint secret location and retry policy
• Support roles, named resources and escalation owner
• CRM status-tag owner and Accounting billing approver
• AI data policy, API owner, approved models and monthly cost owner
• Acceptance-test date, go-live date and rollback decision maker

Hosting and caching checks

Authenticated portal pages must display live, user-specific information. Exclude the Support Desk, Support Agent Desk and sign-off pages from full-page caching where the cache system does not already bypass logged-in users. On LiteSpeed and QUIC.cloud sites, purge all layers after changing pages or front-end assets and test with two different accounts.

Confirm that Wordfence or another firewall does not block authenticated admin-post actions or the Service Desk REST routes. PHP upload limits do not affect Free ticket creation, but normal request-size, execution-time and database limits still affect large descriptions, AI resource uploads and imports.

Mail readiness

1. Verify the From email belongs to a domain authorised by the site's mail provider.
2. Send a WordPress test message before testing Service Desk.
3. Confirm SPF, DKIM and DMARC alignment with the chosen sender.
4. Create a controlled mailbox for inbound tests and keep its forwarding rules documented.
5. Decide who will monitor failed outbound messages and rejected inbound webhook requests.

Safe installation

1. Take a current database and files backup.
2. In WordPress, open Plugins > Add New > Upload Plugin.
3. Upload nomad-support-desk-v0.2.3-role-access-control.zip.
4. Select Install Now and then Activate.
5. Confirm the Support Desk menu appears and no PHP error is recorded.
6. Open Support Desk > Dashboard and confirm the dashboard loads.

What activation creates

• Support Agent WordPress role and support capabilities
• Support Desk database tables
• Default settings including NSD numbering and ZAR currency
• Draft Support Desk, Support Agent Desk and ticket sign-off pages when equivalents are not found
• A daily billing event
• AI resource storage and embedded AI defaults

Activation validation

Do not publish the generated pages immediately. First confirm access rules, test accounts, menu placement and the correct shortcode on each page.

Database and file backup procedure

1. Take a database backup that can be restored independently of the plugin ZIP.
2. Back up wp-content/plugins or retain the exact currently installed Service Desk ZIP.
3. Record the current plugin version and active integration versions.
4. Verify that the backup completed successfully and is stored outside the live account.
5. For an update, test the restore process in staging before changing production.

Generated pages and their publication state

Activation looks for compatible existing pages before creating new ones. It can reuse support or support-desk, creates the customer and agent pages as drafts when needed, and ensures the sign-off page is published because secure token links must resolve. Review the content and template of every page; do not assume a generated page is correctly placed in menus or protected by the surrounding theme.

Post-activation smoke test

1. Open every Support Desk admin submenu as an administrator.
2. Create a temporary support-agent user and verify the role exists.
3. Open the generated pages while logged out and confirm no ticket data appears.
4. Create a temporary customer and resource, then create and assign one ticket.
5. Add a public reply, internal note and time entry; resolve and sign the ticket.
6. Delete only the disposable test ticket after confirming the required records and totals.

Permission model

Create a resource login

1. Create or identify the WordPress user.
2. Open Support Desk > Resources.
3. Add or edit the resource.
4. Select the Linked WordPress user.
5. Enter display name, email, phone, role/title, hourly rate, currency and weekly capacity as required.
6. Keep Active selected and save.
7. Assign a test ticket and confirm the user sees only that assigned ticket in the front-end resource portal.

HR integration

If the suite HR module is active, use Sync active HR employees to resources, then review every created or updated resource. HR linkage can supply the employee relationship, while Service Desk still controls support assignment, rate, capacity and portal access.

Capabilities and least privilege

Service Desk adds nsd_view_support and nsd_manage_support to the Support Agent role and administrator. Only administrators receive nsd_manage_settings by default. The front-end resource portal also requires an active resource record linked to the current WordPress user; a capability alone does not grant access to every ticket.

Administrators and users who can manage support may use administrative ticket screens. A linked resource is restricted to tickets assigned through the WordPress owner, primary resource or additional-resource relationship. Customer access is determined from the signed-in user's email and the matched Service Desk customer record.

Account provisioning procedure

1. Create named WordPress accounts; avoid shared technician logins.
2. Assign the Support Agent role only to operational support staff.
3. Create or sync the resource and link the correct WordPress user.
4. Verify display name, email, phone, title, rate, currency and capacity.
5. Assign one test ticket and test permitted and non-permitted access.
6. Document the offboarding owner and the process for reassigning open tickets.

Free 0.2.3 role model

Free provides one internal role only: Service Desk Agent. The role receives every Service Desk capability, including all-ticket access, customer and resource management, analytics, billing, settings, AI resources/settings, Service Desk user management and ticket deletion. WordPress Administrators inherit the same Service Desk capabilities while retaining normal site administration.

A Service Desk Agent is automatically linked to an active Service Desk resource profile. The account can work in the complete Support Desk administration area and can also use the assigned-resource portal where that workflow is preferred.

Create a Free Service Desk user

1. Sign in as a WordPress Administrator or authorised Service Desk Agent.
2. Open Support Desk > Users.
3. Enter a unique username and valid email address.
4. Enter the optional first and last name.
5. Enter a controlled initial password, or leave Password blank to generate a secure password.
6. Leave the login/set-password notification selected when WordPress mail delivery has been tested.
7. Create the user and confirm it appears as Service Desk Agent with an active support resource.
8. Test the account in a private browser: it must land on Support Desk and must not open unrelated WordPress administration pages.

Free access restriction and migration

Non-administrator Service Desk Agents are redirected to the Support Desk dashboard after login. Unrelated top-level WordPress menus are removed, direct requests for unapproved administration pages redirect to Support Desk, and the front-end WordPress admin bar is hidden. Form handlers still enforce capabilities and nonces; menu removal is not the security boundary.

During upgrade, legacy users with direct broad Support Desk capabilities are moved to Service Desk Agent and direct per-user overrides are removed. If Pro is no longer active, existing Pro roles are consolidated into Service Desk Agent. Review every converted account because a former narrow Pro role becomes all-access in Free.

Recommended page map

Publishing procedure

1. Open the generated draft page or create a new page.
2. Insert only the intended shortcode in the content area.
3. Apply the marketplace site's normal full-width page template if used by other portal pages.
4. Exclude the agent page from public navigation.
5. Require login for customer and agent pages through the site's normal account flow.
6. Publish, clear LiteSpeed/QUIC.cloud caches and test in a private browser window.

Portal acceptance

• Logged-out users receive a login message rather than customer data
• Customer A cannot see Customer B's tickets
• Resources see only tickets assigned as primary, assigned user or additional resource
• Forms remain usable at 320px mobile width
• Signature drawing survives screen rotation

Page-by-page configuration

Use one primary shortcode per page. A full customer portal already contains analytics, ticket creation and ticket history, so placing the form and analytics shortcodes on the same page again creates duplicate interfaces. The dedicated shortcodes are intended for sites that want those functions on separate pages.

The resource portal is operational rather than promotional. Apply the same authenticated header and account-navigation pattern used by other staff pages, prevent search indexing where appropriate, and do not expose the URL as proof of access—the plugin still verifies the logged-in user, role and resource assignment.

Customer identity test

1. Create Customer A and Customer B with distinct email domains.
2. Create a WordPress login for each customer using the matching primary email.
3. Create at least one ticket for each customer.
4. Sign in as Customer A and verify only Customer A's records and analytics appear.
5. Repeat as Customer B, then test an unrelated logged-in account.
6. If domain association is enabled, test both an approved secondary address and an unrelated address on a public mailbox domain.

Resource portal test

1. Assign a ticket to Resource A as primary and Resource B as an additional resource.
2. Verify both can see the ticket and an unrelated Resource C cannot.
3. Remove Resource B and confirm access is removed after refresh.
4. Test search, filters, sort order, pagination, quick status, notes, time and sign-off at desktop and phone widths.

Email support settings

• Support email address
• From name and From email
• Inbound endpoint and private inbound token
• Allow unknown email customers
• Associate inbound messages by company domain

CRM settings

Enable CRM sync only when the compatible Nomad CRM tables are present. Configure a tag slug for each Service Desk status. When a ticket changes status, the plugin can apply the mapped support tag to the linked CRM contact.

Accounting billing settings

• Enable or disable Accounting time billing
• Choose whether resolved/closed tickets may auto-invoice
• Select the Accounting service product code, normally SUPPORT-TIME
• Set a fallback hourly rate and currency
• Choose the billing increment in minutes

Numbering

Set the ticket prefix and next ticket number before live tickets are created. Do not move the next number backwards after launch because duplicate human-readable ticket numbers may confuse email threading and staff.

Complete settings reference

Safe numbering practice

The plugin checks for an existing number and advances until it finds an unused value, but administrators should still treat the next-number field as controlled configuration. Changing the prefix changes future ticket references only; it does not rename old tickets. Preserve the exact ticket number in email subjects because inbound threading searches for that value.

Settings change-control

1. Export or record the current settings before a major change.
2. Make the change in staging or during an approved maintenance window.
3. Clear relevant caches and repeat the workflow affected by the setting.
4. Record the setting, date, reason, tester and result.
5. Roll back immediately if customer isolation, mail, billing or AI privacy tests fail.

Customer records

1. Open Support Desk > Customers.
2. Add the company name, contact name, primary email and phone.
3. Add each legitimate additional email on its own line.
4. Add company domains only when domain-level association is appropriate.
5. Save and confirm the record appears with expected CRM/Accounting references.

Domain matching caution

Domain matching can associate a new sender with a customer when an exact address is not present. Use it for controlled company domains, not public domains such as gmail.com or outlook.com.

Resource records

• Linked WordPress user
• Optional linked HR employee
• Display name and contact details
• Role/title
• Hourly rate and currency
• Capacity hours per week
• Active status and internal notes

Customer field reference

Resource field reference

Initial data-loading sequence

1. Create or sync resources before assigning production tickets.
2. Create key customers with verified primary emails.
3. Add only controlled additional addresses and domains.
4. Test CRM and Accounting links with disposable records.
5. Create a ticket for each main customer type and complete the lifecycle.
6. Review duplicates before importing any legacy ticket history.

Endpoint contract

Implementation sequence

1. Create the mailbox or forwarding rule.
2. Choose a mailbox parser, Cloudflare Email Worker, Zapier/Make flow or controlled custom bridge.
3. Copy the endpoint and token from Support Desk > Settings.
4. Store the token as a secret in the bridge.
5. Map the required fields and include message_id.
6. Send a new-ticket test from a known customer.
7. Reply with the ticket number in the subject and confirm the reply attaches to the same ticket.
8. Repeat from an unknown address and confirm behaviour matches the configured policy.

Operational controls

• Rotate the inbound token if it is exposed
• Retain bridge delivery logs without retaining unnecessary message content
• Rate-limit the public bridge
• Reject oversized requests before forwarding to WordPress
• Monitor duplicate and failed deliveries

Bridge behaviour and response handling

The endpoint accepts the token as a posted field or X-NSD-Token header. It requires a valid sender, subject and text body; HTML is stripped only as a fallback. If message_id has already been logged, the endpoint returns a successful duplicate response without creating another reply or ticket. A subject containing the existing ticket number adds a reply; otherwise a new ticket is created.

A 403 response normally means the secret is wrong. A 400 response means required fields are absent. A 200 response can mean a ticket or reply was created, or that a duplicate was safely ignored. Configure the bridge to log the HTTP status and response body without permanently storing unnecessary message content.

Inbound security controls

• Use HTTPS and keep the token outside browser-side code
• Limit the bridge to the endpoint and expected method
• Reject oversized messages before sending them to WordPress
• Sanitise and normalise sender fields in the bridge
• Rate-limit public intake and alert on repeated authentication failures
• Rotate the token immediately after suspected exposure
• Retain message IDs and delivery outcomes, not unnecessary full mailbox content

End-to-end email acceptance test

1. Send a new plain-text message from a known customer and verify customer matching.
2. Reply to the support response without removing [NSD-####] and verify one reply is added.
3. Resend the same message_id and confirm no duplicate appears.
4. Test an unknown sender with the allow/deny setting in both states.
5. Test a secondary address and a domain match independently.
6. Confirm internal notes are never emitted as customer email replies.

AI modes

Configure AI Settings

1. Open Support Desk > AI Settings and enable Support Desk AI features.
2. Choose whether the API should generate natural-language answers.
3. Confirm the API base URL and enter the API key; leave the key field blank on later saves to retain it.
4. Set the supported model, temperature and maximum matched resources.
5. Choose whether to show Ask Support AI before the customer form and enable live internet research only after privacy approval.
6. Select Save and Test API and confirm the connection result.

Build the resource library

1. Open Support Desk > AI Resources > Add New.
2. Choose manual content, approved URL or supported file upload.
3. Use a clear title and status, then upload or paste only reviewed material.
4. Save and confirm the resource is indexed; use Re-index after replacing source material.
5. Run a known-answer ticket test and inspect returned sources.

Supported knowledge content

• Manual troubleshooting notes
• Approved public URLs
• PDF manuals
• Text and code files
• Plugin ZIP packages

AI settings field reference

Resource ingestion and maintenance

AI Resources can contain manual notes, a website URL, or an uploaded file/ZIP. Use descriptive titles and set obsolete material inactive rather than leaving contradictory instructions searchable. URL resources depend on the current retrieved content. Supported text-oriented files and code inside ZIP packages are extracted for indexing; image resources retain metadata and need written notes to explain the support knowledge they represent.

1. Classify the source as approved, internal or public before adding it.
2. Remove credentials, customer data and obsolete instructions.
3. Add a title that includes product and version where relevant.
4. Save and confirm the indexed word count or extracted content is plausible.
5. Ask a known question and inspect both the answer and cited source.
6. After replacing material, re-index and repeat the known-answer test.

AI access, rate limits and audit

Pre-ticket queries require a logged-in user. Ticket analysis requires an administrator, support manager or assigned active resource with access to that specific ticket. Requests are rate-limited, and completed ticket analyses are recorded as Service Desk events. Generated text is inserted only when the user selects an action; it remains editable before the reply or work note is saved.

CRM integration test

1. Enable CRM sync.
2. Create or update a Service Desk customer.
3. Confirm the related CRM contact/company mapping is populated when supported.
4. Create a ticket and change its status.
5. Confirm the mapped CRM support-status tag is applied.
6. Disable the test tag mapping if it conflicts with an existing CRM taxonomy.

Accounting time billing test

1. Confirm Accounting Pro is active and the configured service product exists.
2. Set the service product code or fallback hourly rate.
3. Log billable time on a test ticket.
4. Open Support Desk > Billing and generate a batch for the customer and period.
5. Review minutes, amount and currency.
6. Create the Accounting invoice and confirm the invoice/customer/item linkage.

Auto-invoice caution

Leave automatic invoice on close disabled until manual billing batches have passed acceptance testing. A resolved or closed ticket can trigger invoicing only when unbilled billable time exists and the Accounting integration is ready.

CRM record matching and tags

The integration checks for compatible CRM tables and columns before writing. A Service Desk customer can link to an existing CRM contact by email or create the appropriate contact record when supported. Company information may also be synchronised. Each status can map to a CRM tag slug, allowing CRM lists and automation to reflect the support state.

Use distinctive support tag slugs and test them in a non-production contact first. If the CRM already uses similar tags for another workflow, agree ownership before enabling Service Desk mapping. A status change should add the current support tag without corrupting unrelated CRM classification.

Accounting billing flow

A time entry stores minutes, rate, amount, currency, billable choice, user/resource and note. The configured billing increment influences the calculated amount. Billing groups eligible unbilled entries into a draft customer batch; creating an Accounting invoice links the batch and entries to the resulting invoice so they are not selected again.

Integration failure policy

• Keep Service Desk usable when CRM or Accounting is unavailable
• Do not retry invoice creation blindly after an uncertain response
• Check whether a customer or invoice was created before repeating an action
• Correct mapping in the application screens rather than editing IDs directly
• Record the affected customer, batch, ticket and timestamp for escalation

Sign-off flow

1. Ensure the sign-off page contains [nomad_support_ticket_signoff].
2. Open a test ticket as authorised staff or resource.
3. Generate or use the secure sign-off link.
4. Open the link in a separate browser context.
5. Enter signer name/email, draw the signature and confirm consent.
6. Submit and verify the signature record appears on the ticket.
7. Confirm the internal timeline note and optional ticket closure behaviour.

Evidence retained

• Signer name and email
• Signature image data and integrity hash
• Consent text
• Source, date and time
• IP address and browser user-agent
• Internal timeline event

Implementation policy

Define what sign-off means for the business, who may sign, whether closure is automatic and how long the evidence must be retained. The plugin captures evidence but does not replace the organisation's legal or record-retention policy.

Sign-off access and evidence

A sign-off link contains the ticket ID and an HMAC token derived from site secrets and ticket data. The page can also be used by the authorised logged-in customer, assigned resource or support manager. The record stores the signer name and email, signature image, integrity hash, consent text, source, time, IP address and browser user-agent. Submitting again creates another record; it does not overwrite the earlier signature.

Business process design

• Define which ticket states make sign-off appropriate
• Decide whether the default Mark ticket as closed option should be used operationally
• Write an approved consent statement for the business context
• Tell technicians what the customer must review before signing
• Define how corrections, disputed work and repeat signatures are handled
• Set retention, export and access rules for signature evidence

Sign-off acceptance test

1. Open the secure link while logged out and confirm it resolves only with the correct token.
2. Alter the token and confirm access is denied.
3. Draw with a mouse and then on a phone or tablet.
4. Rotate the mobile screen and verify the drawing is preserved.
5. Submit with and without closure selected and verify the resulting status.
6. Confirm the internal timeline entry and stored signature are attached to the correct ticket.

Minimum functional test matrix

Performance and cache checks

• Exclude authenticated support portal pages from full-page caching
• Purge LiteSpeed and QUIC.cloud after page or CSS changes
• Confirm REST requests are not blocked by Wordfence or another firewall
• Check Site Health and PHP logs after representative portal use

Acceptance record

Record the tested WordPress/PHP versions, test accounts, test cases, results, open defects, responsible owner and go-live approval. Keep this record outside the plugin so it survives updates.

Role-based acceptance accounts

Create separate test accounts for administrator, support manager, Resource A, Resource B, Customer A and Customer B. Do not perform the entire test as an administrator because administrator access can hide permission defects. Keep a test matrix that records the account, action, expected result, actual result, tester and evidence.

Detailed acceptance scenarios

Non-functional acceptance

• No PHP warnings or fatal errors in the tested workflows
• No cross-customer or unassigned-resource data exposure
• Usable controls at 320px, tablet and desktop widths
• Keyboard-visible focus and labelled controls
• Reasonable response time with representative ticket volume
• Working outbound mail and documented failed-mail monitoring
• Current backup and tested rollback procedure

Role and user acceptance tests

Go-live checklist

• Backups verified
• Portal URLs published and correctly linked
• Agent portal kept out of public menus
• Support email and outbound delivery tested
• Inbound token protected
• Customer and resource access tested
• AI privacy and cost settings approved
• CRM and billing settings confirmed
• First-line staff trained
• Rollback owner identified

Routine maintenance

• Apply WordPress and plugin updates in staging first
• Review inactive resources and customer domains
• Rotate exposed inbound or API credentials
• Re-index changed AI resources
• Review failed mail and bridge events
• Audit unbilled time and old billing batches
• Export or back up before major configuration changes

Rollback

1. Pause inbound forwarding and customer announcements.
2. Take a diagnostic backup of the affected state.
3. Deactivate the changed build without deleting data.
4. Restore the last verified plugin files or site backup.
5. Save permalinks and clear caches.
6. Re-run the minimum acceptance tests before reopening the service.

Controlled launch sequence

1. Freeze configuration and approve the final acceptance record.
2. Take a verified database and files backup.
3. Publish the customer and resource pages in their intended navigation contexts.
4. Enable inbound forwarding and verify the first message.
5. Invite a small pilot group before opening access broadly.
6. Monitor the first tickets, mail events, time entries and AI requests in real time.
7. Enable optional CRM, billing automation and web research one at a time after the core desk is stable.

Maintenance calendar

Rollback decision and procedure

Rollback is appropriate when the new build causes a reproducible security, access, data-integrity or critical workflow failure that cannot be corrected safely within the maintenance window. Deactivate or replace plugin files only after capturing diagnostic evidence. Do not delete Service Desk tables as part of a normal rollback; the data must remain available to the restored version.

Common issues

Escalation evidence

• Exact page and role
• Ticket number without private secrets
• WordPress and PHP versions
• Service Desk version
• Browser/device
• Relevant Site Health or PHP log excerpt
• Steps to reproduce
• Whether the issue occurs with caching/security plugins temporarily isolated in staging

Diagnostic method

1. Reproduce the issue with the exact affected role in a private browser session.
2. Record the page, ticket, action, time and full on-screen message.
3. Check Site Health, PHP logs, browser console/network and mail or bridge logs as applicable.
4. Confirm WordPress, PHP, theme and plugin versions.
5. Repeat in staging with caching/security interference isolated one control at a time.
6. Compare the result with a second account or known-good ticket.
7. Apply the smallest reversible correction and repeat the acceptance test.

Failure-to-owner map

Evidence privacy

Remove or mask passwords, tokens, full licence keys, customer personal data and confidential file content before sharing diagnostic evidence. Ticket numbers, timestamps and non-sensitive record IDs usually provide enough correlation without exposing the underlying content.

Handover pack

• Installed Free version and source ZIP checksum
• Production, staging and portal URLs
• Named business owner, technical owner, queue manager and billing approver
• Role and resource assignment list
• Settings export or controlled configuration record
• Inbound bridge diagram, secret owner and rotation procedure
• Mail sender configuration and failed-delivery monitoring
• CRM tag map and Accounting product/rate map
• AI policy, model, API owner and approved resources
• Acceptance record, known limitations, open defects and rollback steps

Database table reference

Shortcode and route reference

Final ownership checklist

1. Obtain written operational acceptance from the service owner.
2. Confirm administrators know where settings and AI resources are managed.
3. Confirm queue staff understand status, reply visibility and time rules.
4. Confirm customers and resources have the correct portal links.
5. Schedule the first weekly and monthly reviews.
6. Store the handover pack and backup locations where authorised owners can retrieve them.