Push notification editor (scheduling, geofencing, deep links)

CMS · Push notification editor (scheduling, geofencing, deep links)

Composes a push notification: subject and message with personalisation variables, target segment, send frequency (single or recurring), an optional geofence (latitude/longitude for on-location delivery), an image, and an action that either opens the app or deep-links to a specific proposal.

Area	CMS
Routes	cms.push-notifications.new · cms.push-notifications.edit
Centre modules	cms · foreground_location · marketingActivityCampaigns
Staff levels	root · admin · manager · crmmanager · weboperator · content_creator
Models	campaign · proposal · push-notification · segment
UI label	cms.push-notification.general-data
Coverage	5 use cases · 2 happy · 7 failure

Known issues (1)

• 🔵 Low — Push image size failure is swallowed

How it works

Validation is heavily conditional on frequency: endDatetime is only required for non-single sends, and latitude/longitude only for on-location, each with explicit range checks (±90 / ±180). startDatetime must be in the future — a rule that also makes editing a scheduled push fail once its time has passed. actionType: 'proposal' requires actionData.proposal_id, validated both by presence and by a custom rule, with resetActionData clearing it when the type changes. checkImageSize guards the image, and the activity-campaign picker only appears when the centre flag is on, behind a confirmation modal (onAcceptActivityCampaignModal).

Use cases

Why someone opens this (5)

• Announcing an event to a segment the evening before.
• Triggering a geofenced message when customers are near the centre.
• Deep-linking a notification straight to the relevant proposal.
• Setting up a recurring reminder over a date range.
• Personalising the message with the recipient’s name.

Path map

flowchart LR
    F(["Push notification editor scheduling, geofencing…"]):::feat
    F --> H1["Single scheduled push with a deep link"]:::ok
    F --> H2["Geofenced recurring push"]:::ok
    F -.-> X1["Core fields missing"]:::bad
    F -.-> X2["Start datetime not in the future"]:::bad
    F -.-> X3["End before start"]:::bad
    F -.-> X4["Coordinates out of range"]:::bad
    F -.-> X5["Proposal action without a proposal"]:::bad
    F -.-> X6["Image too large"]:::bad
    F -.-> X7["Submit while invalid"]:::bad
    classDef feat fill:#6a4a8f,stroke:#6a4a8f,color:#ffffff,font-weight:bold
    classDef ok fill:#e3f1ea,stroke:#0d6b42,color:#0d4a2e
    classDef bad fill:#f7e6e2,stroke:#9a2d1c,color:#6e1f13

Happy paths

Single scheduled push with a deep link

1. User sets subject, message and a future start datetime.
2. Frequency is single sending, so no end datetime is required.
3. Action type is proposal and a proposal is searched and selected, filling actionData.proposal_id.
4. A segment is chosen and the image passes the size check.
5. submit validates and saves; the push appears as scheduled.

Geofenced recurring push

1. Frequency is set to on-location, requiring latitude and longitude.
2. Coordinates are entered within ±90 / ±180.
3. An end datetime after the start is supplied.
4. The notification saves and fires when matching users are nearby.

Failure paths

Core fields missing

Cause — Subject, message, segment, frequency, action type or start datetime blank.

What happens — required + the relevant label, push-notification.start-datetime, push-notification.end-datetime.

Start datetime not in the future

Cause — startDatetime <= now.

What happens — push-notification.startdate-after-now-error (‘The date and time must be later than the current date and time’). This also blocks re-saving a push whose scheduled time has already arrived.

End before start

Cause — Non-single frequency with endDatetime earlier than startDatetime.

What happens — push-notification.startdate-before-enddate-error and error.push-notification.event-end-date.after-startdate — two overlapping rules for the same condition.

Coordinates out of range

Cause — On-location frequency with latitude outside ±90 or longitude outside ±180.

What happens — push-notification.latitude-range-error / push-notification.longitude-range-error.

Proposal action without a proposal

Cause — actionType === 'proposal' and actionData.proposal_id empty.

What happens — Both a presence and a custom rule fail with required + push-notification.action-data.proposal.

Image too large

Cause — checkImageSize fails.

What happens — Guarded in a bare try/catch {} in the controller, so the failure is swallowed — a silent path worth fixing.

Submit while invalid

Cause — model.validate() false.

What happens — submit returns false early; the field errors are rendered on the tabs.

QA checklist

Tick these off while regression-testing this feature. The boxes are plain Markdown, so progress is visible in git diffs.

• ✅ Single scheduled push with a deep link
• ✅ Geofenced recurring push
• ⛔ Core fields missing
• ⛔ Start datetime not in the future
• ⛔ End before start
• ⛔ Coordinates out of range
• ⛔ Proposal action without a proposal
• ⛔ Image too large
• ⛔ Submit while invalid

Implementation

• app/controllers/cms/push-notifications/new.js
• app/routes/cms/push-notifications/new.js
• app/models/push-notification.js
• app/enums/push-notification-frequencies.js
• app/enums/push-notification-action-types.js
• app/enums/push-engagement-options.js

Translation keys (11)

Key	English
cms.push-notification.general-data	General data
cms.notification.code-params.user-name.description	Add the username
push-notification.start-datetime	Start date is required
push-notification.end-datetime	Ending date is required
push-notification.startdate-after-now-error	The date and time must be later than the current date and time
push-notification.startdate-before-enddate-error	End date cannot be before start date
push-notification.latitude-range-error	The range must be between 90 and -90
push-notification.longitude-range-error	The range must be between 180 and -180
push-notification.action-type.default	Default
push-notification.action-type.proposal	Proposal
error.push-notification.event-end-date.after-startdate	Event end date can not be set before event start date

Related

• Same area — Proposal list & publication workflow · Proposal editor (content, coupon, push, AI images) · Push notification list & publishing · Content categories · App button manager (MOFs) · Multicentre proposals
• Shares data with — Activity editor (loyalty mechanics, rules & targeting) · Activity campaigns (programme grouping) · Customer create & edit · Customer CSV import · Customer receipts tab & ticket-stamp generation · Customer loyalty — raffle tickets · Customer loyalty — cards & stamps · Customer loyalty — rewards
• Behind the same module — Proposal editor (content, coupon, push, AI images) · Social wifi & location services · Activity campaigns (programme grouping)

---

Generated from doc/feature-inventory.json · id cms-push-notification-editor · commit 276788ca6