spp_grm

OpenSPP - Grievance Redress Mechanism

Centralized grievance and complaint management for social protection programs. Receives complaints through multiple channels (email, portal, manual entry), tracks resolution through customizable workflow stages, and monitors service level agreements. Links complaints to individual or group registrants and supports anonymous submissions.

Key Capabilities

• Multi-channel intake: Email alias integration creates tickets from inbound messages, portal form for beneficiaries, manual entry by officers
• Stage-based workflow: Define stages with access control restrictions, approval requirements, and decision enforcement before closure
• SLA tracking: Automatically compute deadlines based on category/subcategory configuration, monitor status (on track, at risk, breached), post notifications on breach
• Team assignment: Organize handlers into teams with geographic area responsibilities, auto-assign based on category defaults
• Appeals and escalation: Reference original tickets for appeals, track escalation history and reasons, mark tickets as escalated
• Hierarchical categorization: Two-level category/subcategory system with inherited defaults for severity, sensitivity, SLA hours, and team assignment
• Decision tracking: Record final decisions (upheld, partially upheld, rejected, withdrawn, redirected, referred to case) with resolution summaries
• Anonymous complaints: Optional contact fields for complainants not in the registry

Key Models

Model	Description
spp.grm.ticket	Main complaint/grievance with SLA tracking and decision fields
spp.grm.ticket.stage	Workflow stage with access control and closure configuration
spp.grm.ticket.category	Primary classification with hierarchical structure
spp.grm.ticket.subcategory	Second-level classification under category
spp.grm.team	Team of handlers with manager and geographic areas
spp.grm.sla.rule	Conditional SLA rules with escalation targets
spp.grm.ticket.tag	Tags for flexible ticket classification
spp.grm.ticket.channel	Communication channel (email, phone, walk-in, portal, etc.)

Configuration

After installing:

1. Navigate to Helpdesk > Configuration > Stages to define workflow stages with closure and approval flags
2. Create categories under Helpdesk > Configuration > Categories with default severity, SLA hours, and team assignments
3. Set up teams under Helpdesk > Configuration > Teams with members and geographic area assignments
4. Configure SLA rules under Helpdesk > Configuration > SLA Rules with conditions and escalation targets
5. Set up email alias under Settings > Technical > Email > Aliases to enable automatic ticket creation from inbound messages

UI Location

• Menu: Helpdesk (top-level menu item)
• Tickets: Helpdesk > Tickets
• Configuration: Helpdesk > Configuration (manager access required)
• Portal: Beneficiaries can view and create tickets at /my/tickets
• Registrant Profile: Stat button shows ticket count and opens related tickets

Security

Group	Access
group_grm_viewer	Read only
group_grm_officer	Read/Write/Create (no delete)
group_grm_manager	Full CRUD including configuration
base.group_portal	Read/Write/Create tickets (no delete)

Stage transitions to approval-required stages are restricted by Python code to users in group_grm_supervisor or higher, but this group has no direct model access entries.

Extension Points

• Override _compute_sla_deadline() on spp.grm.ticket to implement custom SLA calculation logic
• Install spp_grm_cel to provide spp.grm.escalation.rule model, which is automatically invoked when SLA status changes to breached
• Inherit spp.grm.ticket to add domain-specific fields (extended by spp_grm_registry, spp_grm_programs)
• Extend spp.grm.ticket.stage to add workflow state fields
• Override evaluate_ticket() on spp.grm.sla.rule to add custom matching conditions

Dependencies

base, mail, portal, spp_registry, spp_area, spp_user_roles, spp_security

Table of contents

• Changelog

Changelog

19.0.2.0.2

• fix(security): portal users can now only access their OWN grievance tickets. The spp.grm.ticket portal access was read/write/create with no record rule, so any portal user could read and rewrite every grievance in the system over RPC (#380). Added a portal record rule scoping to the user's own partner and reduced the portal access-control entry to read-only (submission is handled by the sudo'd portal controller, which needs no direct model write). The rule covers all four operations, so the scoping also holds if a future access-control change ever re-grants portal write.
• fix: SLA-breach handling (auto-escalation and the breach chatter note) no longer runs inside the stored sla_status compute. It is deferred to the end of the triggering transaction, so the escalation engine's writes, savepoints and flushes never execute mid-computation. Same transaction, same outcome. An unsaved form edit queues nothing: the compute also runs on the pseudo-record of an onchange, whose ids resolve back to the real ticket, which would have escalated it for a change the user never saved.

19.0.2.0.1

• fix(views): gate the "Helpdesk" top-level menu (spp_grm_ticket_main_menu) on group_grm_viewer. Previously the root menu had no groups= attribute and was visible to every logged-in user; the OP#951 menu audit requires several roles to NOT see it (Registry Viewer, Global Finance, Global Program Manager, Program Viewer/Validator/Cycle Approver, Global Registrar, CR roles, Farm User/Manager).

19.0.2.0.0

• Initial migration to OpenSPP2

Bug Tracker

Bugs are tracked on GitHub Issues. In case of trouble, please check there if your issue has already been reported. If you spotted it first, help us to smash it by providing a detailed and welcomed feedback.

Do not contact contributors directly about support or help with technical issues.

Credits

Authors

• OpenSPP.org

Maintainers

Current maintainers:

This module is part of the OpenSPP/OpenSPP2 project on GitHub.

You are welcome to contribute.