Agent Feedback & Surveys — Setup & Workflow Guide

Overview

Three distinct collection modes under one module:

• Open-ended feedback — free-text submissions with category, sentiment, related-to context, and anonymous / visible-to-team toggles. Goes through a new → acknowledged → resolved workflow so supervisors can track follow-up.
• Pulse surveys — one-question scaled surveys that recur every N days. One-tap responses with optional comments. Team average is recomputed after every response.
• Assigned surveys — multi-question surveys assigned to all agents or specific roles. Supports text, textarea, radio, checkbox, rating, scale, NPS, matrix question types. Progress saves automatically; completion requires all is_required = 1 questions answered.

What's new in V2

Feedback submission

Agents hit the Feedback tab inside the CRM and see a submit form at the top:

• Feedback text — required, up to 5,000 chars (truncated silently via mb_substr).
• Category — optional dropdown populated from feedback_categories where tenant_id = current and is_active = 1.
• Sentiment — positive / neutral / negative. Agent-declared; V2 doesn't auto-analyze. The Sentiment Analysis module integrates separately if needed.
• Related to — optional context (manager / team / process / tools / training / system / other).
• Submit anonymously — flips is_anonymous. Listing queries substitute "Anonymous" for the submitter name. The submitted_by user_id is still stored for FK integrity.
• Share with team — flips visible_to_team. Non-admin teammates can see it.

Submissions default to status = 'new'. The admin acknowledge/resolve workflow takes over from there.

Pulse surveys

Single-question recurring surveys. Configured by tenant admins in feedback_pulse_surveys:

• question — the prompt, up to 500 chars
• scale_min / scale_max — numeric range (e.g. 1-5, 0-10)
• scale_labels — optional JSON array of labels for each scale point (e.g. ["Poor","Fair","Good","Very good","Excellent"])
• frequency_days — how often agents should respond (e.g. 7 for weekly)
• allow_comments — if true, agents see an optional comment textarea

Agents see pulses in the Team Pulse tab. A "Due" badge shows when their last response is older than frequency_days; "Answered recently" otherwise. One tap on a scale button records the response. Team average is shown alongside the question. The engine validates the value is within [scale_min, scale_max] and strips comments if allow_comments = 0.

After every response, total_responses and average_score on the pulse row are recomputed in the same transaction. No background cron needed for the stats to stay fresh.

Assigned surveys

Multi-question surveys live in feedback_surveys with questions in feedback_survey_questions. V2 supports:

• text / textarea — free-form with optional max_length
• radio — single selection from options JSON array
• checkbox — multiple selections, stored in answer_options JSON
• rating / scale / nps — numeric with min_value / max_value validation
• matrix — multi-dimensional selection (stored as JSON)

Flow: startSurvey(id) creates (or resumes) a response row with status = 'in_progress'. The UNIQUE constraint on (user_id, survey_id) prevents duplicates. submitSurveyAnswer(responseId, questionId, answer) upserts one answer row per question — the agent can revise answers until finalization. finishSurvey(responseId) validates all required questions have answers, flips status to 'completed', and records completion_time_seconds.

Survey creation (the admin side) isn't yet available through a UI in V2 — admins need to INSERT directly into feedback_surveys and feedback_survey_questions. A builder UI is on the V2.1 roadmap.

Admin workflow

Four statuses on feedback_submissions:

1. new — fresh submission
2. acknowledged — admin has seen it and flagged for follow-up (records acknowledged_by + acknowledged_at)
3. in_review — longer-running investigation (optional intermediate state)
4. resolved — closed with optional notes (records resolved_by + resolved_at + resolution_notes)

Admins see all submissions in the Feedback tab with action buttons next to each row: Acknowledge (only shows for status = 'new'), Resolve (any unresolved status → resolved). Both actions go through the engine which enforces admin role_id and tenant scoping.

Action items (feedback_action_items) can be created from feedback to track follow-up work: priority (critical / high / medium / low), assigned_to, due_date. The state viewer surfaces all open items sorted by priority. A UI for creating action items from feedback is on the V2.1 roadmap — today they require direct INSERT.

Quick start ≈ 15 minutes

1. Activate the module at RubiMine. $79.99/mo.
2. Sysadmin verifies schema at /admin/run-feedback-v2-migration.php. All 10 tables should show ✅ exists.
3. Seed categories (if not already present) — the migration ships with 6 defaults per tenant. Customize via direct SQL in feedback_categories.
4. Configure pulse surveys — default install ships 3 pulse questions per tenant. Review them or add your own in feedback_pulse_surveys.
5. Announce the feature to agents — Internal Messaging's admin broadcast is a good channel. Point them at the CRM Feedback tab.
6. Agents start submitting — forms are inline, no training needed.
7. Admins acknowledge + resolve incoming feedback from the same tab.

API endpoints

All endpoints on /crm/api/feedback.php. Session-authenticated, tenant-scoped.

Feedback

POST action=submit_feedback         (feedback_text, category_id?, related_to?, sentiment?, is_anonymous?, visible_to_team?)
POST action=list_feedback           (status?, sentiment?, category_id?)
POST action=list_categories
POST action=acknowledge_feedback    (feedback_id) — admin only
POST action=resolve_feedback        (feedback_id, resolution_notes?) — admin only

Pulse

POST action=list_pulse_surveys
POST action=respond_to_pulse        (pulse_id, value, comment?)

Surveys

POST action=list_my_surveys         → pending + in-progress surveys for current user
GET  action=get_survey              (survey_id) → full questions + current answers
POST action=start_survey            (survey_id) → response_id
POST action=submit_answer           (response_id, question_id, answer)
POST action=finish_survey           (response_id) → {ok, completion_time_seconds} or {missing_question_ids}

Known limitations (V2)

• Survey builder UI — admins need direct SQL to create surveys + questions today. UI coming in V2.1.
• Action item creation UI — the feedback_action_items table exists but creating items from feedback needs direct INSERT. V2.1.
• Sentiment auto-detection — sentiment is agent-declared. Integrates with the Sentiment Analysis module for automatic scoring; V2 doesn't do this inline.
• Exit interview templates — schema supports the 'exit' survey type but no built-in templates. Custom creation via SQL.
• Pulse analytics — state viewer shows 7-day + total counts. Trend charts (month-over-month, by department) planned for V2.1.
• Agent notifications — no email / push notifications when new pulses become "due". V2.1 will integrate with Notifications Engine.
• Feedback export — no CSV export today. Direct SQL works for e-discovery / compliance exports.

Frequently asked questions