| New in v2.12 | What it is |
|---|---|
| Configurator (Configurator, also called "Admin Console") | The web app a city admin uses to set up and configure a city — boundaries, complaint categories, staff, dashboards, notifications. Replaces manual/scripted city setup. |
| digit-ui-esbuild | The rebuilt citizen and employee web app. |
| digit-mcp | An automation toolkit that speeds up onboarding a new city. On by default. |
| Real OTP delivery (otp-publisher) | Sends genuine one-time passwords for login, instead of the earlier test stub. Switched on with enable_otp_services. |
| Notification admin dashboard (novu-dashboard) + novu-bridge-endpoint | Lets a city manage its own notification (SMS/WhatsApp/Email) templates. Switched on with enable_novu. |
| Location search (turbopass) | Address/place auto-complete when setting up city boundaries. Off by default (enable_turbopass). |
| Host monitoring (node-exporter) | Server CPU/memory/disk metrics for the monitoring dashboards. Always on. |
| Single-VM installer (local-setup, Ansible-driven) | Stands up a full deployment from one settings file and one command, with built-in pre-flight checks. |
Performance testing framework (performance/) | k6-based load tests used to validate this release at scale (up to 1M complaints / 500K+ daily transactions). |
| Enable | Nothing to flip — this is the classification model in v2.12. |
| City data | RAINMAKER-PGR.ComplaintHierarchyDefinition (the shape: how many levels, their names), RAINMAKER-PGR.ComplaintHierarchy (the actual category tree; a leaf's code is the complaint's serviceCode). Default: a 2-level tree (Category → Sub-type). Editable in DIGIT Studio. |
| Existing cities | Action required — convert old ServiceDefs rows into the two new records, reusing leaf codes so existing complaints stay valid. Use the validated migration tool (servicedefs-to-complainthierarchy-migration.md) rather than doing this by hand — migration guide Section 2.1. |
| Related | Migration V20260731000000__repoint_grain_mvs_to_complainthierarchy.sql (and, found during later validation, V20260810000000__tenant_business_calendar_grains.sql, which fixes report time-groupings to use each city's own time zone) repoint the reporting views to the new categories — run automatically. |
| Watch out for | Two gaps found during real-world validation of this migration: a complaint whose category hasn't been migrated yet will fail to send notifications on its next workflow action even though it still opens and displays fine; and the reporting views resolve a category's department by comparing across every city in the deployment rather than each city's own, so two cities sharing a default category code with different departments can end up showing one city's department on the other's dashboard tiles. See the migration tool's documentation for exposure-check queries. |
| Enable | On a running deployment: local-setup/scripts/enable-dashboard.sh — registers the dashboard data definitions, loads 39 ready-made statistics + 1 dashboard pack (mapped to the roles that exist on that deployment), grants the menu entry, loads the dashboard's translations for every language, refreshes login tokens, and verifies end-to-end. |
| City data | dss.KpiDefinition, dss.DashboardPack, dss.DashboardConfig (who can see which pages, number formats, department scoping). |
| Service settings | pgr.dashboard.refresh.enabled=true (statistics refresh, on by default), .interval.ms; pgr.analytics.config-cache-ttl-ms. |
| Gateway | Whitelist /v2/dashboard and all of /v2/analytics/_query, _schema, /packs, catalog/_search. |
| Important caveat | The dashboard only shows a supervisor data for their own area and department, and errs on the side of showing nothing: an employee whose HR record has no department will see an empty dashboard. Check department assignments in HR data first; dss.DashboardConfig.departmentScoping=false turns the department restriction off city-wide. |
| Performance telemetry | The dashboard reports its own loading speed by default, which adds two public gateway routes (/otel/v1/metrics, /otel/v1/logs). dashboard_metrics_enabled: false stops the dashboard from sending this telemetry, but the two routes themselves stay in place — they are not removed by this setting. |
| An older dashboard | The pre-catalog dashboard that predates this KPI-catalog-driven Supervisor Dashboard is now hidden by default, kept only as a rollback aid. |
| Enable | City admin turns it on/off via a single toggle in the Admin Console (and gets its shareable URL); backed by dss.DashboardConfig. Which KPIs are exposed is fixed by the shipped public-default KPI pack (MDMS seed data), not a per-KPI admin choice today. |
| Access | Served without a login session, at its own web address. Deliberately excludes the schema-introspection endpoint (_schema) from its gateway whitelist, so a public caller can't discover column/data structure — only /packs, /catalog/_search, and /_query are exposed. |
| Isolation | A public caller cannot escape the curated set of indicators the city admin selected — verified by dedicated isolation tests. |
| Enable | Ships with the complaints service; the policy is per-tenant seed data (a scope-policy record keyed to a specific access-control action, with per-role scopes for jurisdiction and department, each OWN or ALL). |
| What it does | For roles without an explicit scope entry, a default policy applies. If an employee's HR record has no resolvable jurisdiction or department, that axis resolves to a deny-all rather than an unrestricted view — fails closed, not open. |
| Watch out for | An independent review of this feature found real gaps for admin-level roles: tenant-wide admin/supervisor roles can lose unrestricted dashboard access; a cross-tenant authorisation gap lets one tenant's role refresh another tenant's dashboard config cache; the "department scoping disabled" override can be silently skipped; and a fresh/source-less tenant bootstrap can end up with no row-scope policy seeded at all. Verify this specifically for any admin/supervisor role your city relies on before enabling. See Known Issues. |
| Enable | (1) Deployment flag enable_novu: true (starts the notification services); (2) complaints-service setting pgr.notification.config.driven=true (deployment flag pgr_notification_config_driven); or simply run the guided installer local-setup/scripts/enable-notifications.sh on a running system. Verify with local-setup/scripts/drive-test-complaint.py. |
| City data | RAINMAKER-PGR.NotificationRouting (who is notified, on which step, on which channel), .NotificationTemplate (the message wording, with placeholders), .NotificationProviderTemplate (maps each WhatsApp message to the provider's approved template ID). |
| WhatsApp — read this | The sample WhatsApp template IDs shipped with the product belong to the reference demo account and will not work anywhere else. Each city must author its own WhatsApp message templates, get them approved (Meta approval via Twilio), and load its own template IDs — via the Admin Console's Sync WhatsApp templates screen or local-setup/scripts/persist-provider-templates.py. This is the single most common reason WhatsApp messages silently don't arrive. (Do not use the old notif-mdms-seed/seed.sh script — it loads data the current delivery path no longer reads.) |
| Channel defaults | The default channel is now SMS (previously WhatsApp), and WhatsApp is off until explicitly enabled (novu.bridge.channels.enabled defaults to SMS,EMAIL; WhatsApp events log as skipped until added). |
| Split-domain setups | Notification-dashboard URLs default to the city's own domain; if TLS terminates on a different public hostname set novu_public_base_url (per-URL overrides exist for rare cases). |
| Old messages | The previous fixed SMS wording (localisation keys) still works for cities that don't opt in — it is now deprecated. |
| Enable/disable | On by default (pgr.escalation.enabled=true); per-deployment override PGR_ESCALATION_ENABLED. |
| City data | RAINMAKER-PGR.EscalationConfig — how many levels (maxDepth), the time allowed per level, optional per-category overrides. Design default: 3 levels at 1 h / 4 h / 24 h — but as of this validation this master has no live seed path, so a fresh tenant doesn't actually receive it (the scheduler silently falls back to a hardcoded 5-day default when no record exists). |
| Service settings | pgr.escalation.interval.ms, .batch.size, .default.sla.ms, .max.depth, .kafka.topic=pgr-escalation-events — this messaging topic must exist while escalation is on. |
| Prerequisite | Workflow.BusinessServiceMasterConfig must contain a PGR row (active:true, isStatelevel:true). |
| Enable | pgr.visibility.enabled=true (env PGR_VISIBILITY_ENABLED) plus a per-city RAINMAKER-PGR.InboxVisibilityConfig record. Without the record the inbox behaves as before. |
| Service settings | pgr.visibility.hrms.employee.save.topic / .update.topic, .reportee.depth.default, .unassigned.states, .rebuild.cron, .rebuild.batch.size, .team.fanout.max. |
| Endpoints | POST /v2/request/inbox/_search, POST /v2/request/inbox/_count (whitelist if enabling). |
| Data | Uses a local copy of the HR reporting hierarchy (eg_pgr_hrms_projection, created by migration V20260715000000). |
| Phone numbers | common-masters.MobileNumberValidation — one record per country code with the number pattern. Exactly one record must be marked default: true (the shipped record is not); otherwise the app quietly falls back to a built-in single-country pattern. Requires the 2.12 build of the User Service, which reads this record. |
| Postal code / name / email | New record type common-masters.FormValidations — one row per field (postalCode, name, email) with its pattern. This is the primary per-city rule and wins over the deployment-file fallback, in the Admin Console and all complaint forms. A default postal-code row is created for new cities — but the two seed paths that create it currently disagree (one ships a 5-digit pattern, the other a 6-digit pattern); reconcile before relying on a single format across fresh installs. |
| Deployment-file fallback | core_mobile_configs and core_postal_configs.postalCodePattern are used only when the city record is absent. The old postalCodeLength / postalCodeErrorMessage settings are gone — the pattern is the single source, and the translated error message ("enter a valid N-digit postal code") is derived from it. |
| Existing cities | Action required — the old UserValidation record type is removed (migration guide Section 2.2); cities created before v2.12 must add the FormValidations rows themselves. |
| Config | RAINMAKER-PGR.UIConstants.REOPENSLA (milliseconds; shipped default 259200000 = 72 hours) drives the reopen window in the citizen timeline and the employee/counter action bar alike. Edit per city in DIGIT Studio. Cities onboarded before this release keep their existing value. |
| Enforcement | The deadline is also enforced on the server from the same REOPENSLA master, based on the stored complaint (not what the request claims). Deployments must unset time-before-closing-complaint, which used to override it. |
| Fixed after 2026-08-25 | REOPENSLA originally couldn't be edited via the Admin Console/API at all — the master was keyed on the value itself, so any change was rejected outright. A database migration now re-keys it onto a stable identifier the first time a deployment upgrades; no action needed beyond letting that migration run. |
| What | Complaint and workflow changes flow through the persister → audit-service into the eg_audit_logs table. |
| Config | Persister mappings carry isAuditEnabled + module (CMS / Workflow); the audit service reads the local persister configs (EGOV_PERSIST_YML_REPO_PATH) to decide what to audit, and binds PERSISTER_AUDIT_KAFKA_TOPIC=audit-create. Wired by default; no flag. |
| Enable | Ships with the employee UI and complaints service; no flag. |
| Service settings | pgr.employee.context.resolver-role-codes / .citizen-role-codes / .admin-role-codes (env PGR_EMPLOYEE_CONTEXT_*) — which roles the switcher treats as resolver / citizen-facing / admin. Defaults: PGR_LME,GRO,DGRO / CITIZEN / PGR_ADMIN,SUPERUSER,MDMS_ADMIN,HRMS_ADMIN,STADMIN,SUPERVISOR,PGR_SUPERVISOR. |
| Flag | What you get | Notes |
|---|---|---|
enable_search_stack | Faster inbox search (Elasticsearch) | ~3 GB extra RAM |
enable_otp_services | Real one-time passwords for login | Replaces the built-in test OTP entirely; set STATIC_OTP for test environments |
enable_digit_ui_v2 | The new citizen web app at /citizen/ | |
enable_mcp (+ nginx_features.mcp) | City-onboarding automation tools | Uses a ready-built image by default — works outside the internal network; build_mcp: true builds from source |
enable_turbopass / enable_overpass | Address auto-complete / self-hosted boundary maps | |
enable_integration_tests[_runner] | Test dashboards + a run button | |
docker_log_max_size / docker_log_total_size | Caps on container log disk usage | Defaults 100 MB / 1 GB; deployments run outside Ansible get no log rotation |
dashboard_metrics_enabled | Dashboard loading-speed telemetry | Default on; false stops the browser from sending this data, but does not remove the two /otel/v1/* gateway routes themselves |
pgr_pincode_allowlist, login_tenant_allowlist, employee_module_denylist | Service-area and access lists | Leave pgr_pincode_allowlist unset (not []) to accept any postal code |
RAINMAKER-PGR.MapConfig (city data) | Per-city map style, centre, and zoom | Optional; sensible defaults apply without it |
| Web analytics (Matomo) | Citizen-traffic analytics | Kubernetes/Helm chart only, not Compose |
| Record / key | Module | Default provided? | What it controls |
|---|---|---|---|
ComplaintHierarchyDefinition, ComplaintHierarchy | RAINMAKER-PGR | Yes (2-level tree) | Complaint categories (replaces ServiceDefs) |
NotificationRouting, NotificationTemplate, NotificationProviderTemplate | RAINMAKER-PGR | Yes (demo WhatsApp template IDs — replace them!) | Citizen notifications |
EscalationConfig | RAINMAKER-PGR | Yes (3 levels) | Automatic escalation timings |
MapConfig | RAINMAKER-PGR | Schema only | Per-city map settings |
InboxVisibilityConfig | RAINMAKER-PGR | Schema only | My/All inbox tabs |
ComplaintExtendedAttributeSchema, ComplaintRelatedToMap, ComplaintTemplateType | RAINMAKER-PGR | Yes | Confidential/extended complaint fields |
UIConstants.REOPENSLA | RAINMAKER-PGR | Yes (72 hours) | Complaint reopen window (now actually applied, UI + server) |
MobileNumberValidation | common-masters | Yes (default: false — mark one record true) | Phone-number rules per country (replaces UserValidation) |
FormValidations | common-masters | Yes (5-digit postal-code row) | Postal-code / name / email rules |
KpiDefinition, DashboardPack, DashboardConfig | dss | Via enable-dashboard.sh | Supervisor Dashboard |
BusinessServiceMasterConfig (+PGR row) | Workflow | Yes | Prerequisite for escalation & notification routing |
SecurityPolicy (expanded) | DataSecurity | Yes | Who may see personal data (name, phone, address…) — review before applying to live cities |
New role CMS_SCREENING_OFFICER | ACCESSCONTROL | Yes | Screening Officer: reviews and routes incoming complaints |
| # | Area | Fix |
|---|---|---|
| 1 | Employee inbox | Complaint counts no longer stop at the page size; page navigation, column sorting, and time-allowed (SLA) calculations fixed (#1058, #1014, #1212, #1144) |
| 2 | Complaint updates | The chosen department is no longer overwritten on update; masked confidential values no longer wipe real data (#1077, #1092) |
| 3 | Citizen search | Citizens can only see their own complaints in search (#1100) |
| 4 | Dashboard statistics | "Complaints created today" now means the calendar day, not the last 24 hours (#1462, #1483) |
| 5 | Dashboard statistics | Reporting views now follow the new complaint categories; resolution-time targets fixed for city-level complaints (#1494, #1081) |
| 6 | Supervisor Dashboard | Broken header search removed; saved layouts no longer rearrange on refresh; date-filter no longer blanks the page (#1474, #1013) |
| 7 | Admin Console | Complaint-type edits no longer silently discarded; complaint workflow read from the correct city (#521) |
| 8 | Admin Console | City boundaries are saved to the city itself, not the state root |
| 9 | HR data | Employee-update crash fixed (#1056); a start-up race condition removed |
| 10 | Login & security | Admin account gets the correct encryption key after first-time setup (#1042); expired sessions no longer hang the app (#1101) |
| 11 | Complaint reopen | The reopen deadline is enforced on the server and follows the configured window (#925) |
| 12 | Postal codes | One postal-code rule everywhere, with translated error messages; raw browser pop-ups removed (#722, #1315) |
| 13 | Admin Console | A bug that incorrectly blocked legitimate users from editing MDMS roles/actions in the Admin Console is fixed |
| 14 | City/tenant setup | A tenant-setup failure partway through a multi-page data fetch no longer silently drops the master-data rows already fetched |
| 15 | Admin Console | Creating a new complaint category now correctly stamps the metadata it needs (previously could produce a category invisible to the citizen/employee picker) |
| 16 | Search | PGR search stays fully backward-compatible for a tenant that never configured a dashboard access-scope policy, instead of silently defaulting to an overly restrictive scope |
| 17 | Security & bootstrap | New-city bootstrap admin credentials no longer come from a fixed, shared set of environment variables — each bootstrap now uses the deploying session's own credentials |
| 18 | Security & bootstrap | A missing administrator role in the seeded roles master was restored |
| 19 | Security & bootstrap | A stale, unauthenticated gateway route to a decommissioned endpoint was dropped from both the Kong and Kubernetes gateway whitelists |
| 20 | Dashboard statistics | Report time-groupings (day/week/month/hour) now use each city's own time zone instead of one hardcoded zone (found during migration validation) |
| 21 | Complaint reopen | The reopen window (REOPENSLA) can now actually be edited via the Admin Console/API — previously blocked by a technical defect where the value doubled as the record's own identifier, so an edit silently failed to save |
| 22 | Access control | Fixed a severe scope mismatch: an employee with a coarse jurisdiction assignment (e.g. County-level, common for new employees) previously saw zero results in search but nearly the entire tenant on the dashboard, because the two features resolved jurisdiction differently. Both now expand a jurisdiction to itself plus every area beneath it, consistently |
| 23 | Access control | The Grievance Routing Officer role (and the unconfigured-role default) no longer sees every department's complaints regardless of their own assigned department — tightened to their own department, matching other supervisor-level roles |
| 24 | Admin Console | The Dashboard sidebar entry, corrupted in the sample seed data for one tenant, is restored — affected any city bootstrapped from that sample |
| 25 | Login & security | The seeded local admin account is granted the account-administrator permission it needs now that city-bootstrap actions require it; a missing Supervisor role was added to the seed data |
| 26 | Employee profile | A backend authentication/type-handling bug in the new employee working-context switcher is fixed |
| 27 | Notifications | A WhatsApp integration/provider-selection bug fixed |
| 28 | Employee & UI | Profile image visibility fixed; duplicate options removed from a dropdown; employee date-of-birth/date-of-appointment made optional where they shouldn't have been required |
| Area | Issue |
|---|---|
| Notifications | Error while creating the workflow in Novu (#1517) |
| Notifications | Sync WhatsApp templates from Twilio fails for some messages (#1516) |
| Notifications | Configure Notifications: Delete and Recreate features not working as expected (#1501) |
| Notifications | Employees are not yet notified on complaint assignment across email, SMS and WhatsApp (#904) |
| Notifications | TemplateBinding needs an audience selector and body field (blocks SMS work) (#905) |
| Notifications | Notification setup documentation for implementation teams still to be published (#1032) |
| Supervisor Dashboard | Employee dashboard: unable to add KPIs (#1276) |
| Supervisor Dashboard | Portuguese localisation and language dropdown driven by DIGIT-configured languages (#1108, #1169) |
| Supervisor Dashboard | Group-by across complaint hierarchy levels (Category / Sub-Type / Leaf) (#1111) |
| Supervisor Dashboard | Production render-lag instrumentation and load-time benchmarks at 1K / 50K / 100K records (#1110, #1109) |
| Supervisor Dashboard | Data dictionary asset creation for the CMS dashboard (#1575) |
| Complaint lifecycle | Reopen complaint timeline: increase to 72 hours and make it configurable (#1252) |
| Complaint lifecycle | Complaints at Risk: complaint ID click redirects to a wrong URL path (#1249) |
| Complaint lifecycle | Validate complaint types against the tenant master, dropping the state-level fallback (#902) |
| Configuration | Resolve the department master per tenant with state-level fallback (#901) |
| Deployment / operations | Ansible deploy: fixes needed for fresh-box and repeat deploys (#1245) |
| Deployment / operations | Image ↔ DB-migration version skew: floating tags can reintroduce login failures (#1023) |
| Deployment / operations | Default alert thresholds for Grafana (#1538); observability dashboards for operations & maintenance (#541) |
| Deployment / operations | Citizen login on the Docker Compose setup (#453) |
| Deployment / operations | Developer environment setup within an hour (#191); |
| Platform | Rate-limiter configuration (#1253); Matomo analytics enablement (#1254) |
| Quality & security | Vulnerability testing (#1482); testing-suite improvements (#1047) |
| Document | Description |
|---|---|
| Complaints Management roadmap | Product roadmap |
| Changelog | Configuration & infrastructure changelog (city data, service settings, DevOps) |
| Migration Guide | Operator upgrade procedure v2.11 → v2.12 |
| Jurisdiction Access Control | Plain-language explainer: jurisdiction/department access control for complaint search & inbox |
| Windows Quickstart | Validated Windows setup path (via WSL2) |
| Local Setup | City onboarding + add-ons catalogue (every optional flag) |
| Notifications | Notifications setup guide (SMS, WhatsApp, email) |
| Configurator onboarding guide | setup and configure the complaint management system |
| Configurator management guide | manage the complaint management system |
| Dashboard configuration | configure and setup the dashboard |
| Deploy | deploy Complaints Management System |
| Notifications | configure notifications |
| Performance & benchmarking | access the performance and benchmarking test reports |