rules-rule-notification

name	rules-rule-notification
description	Schema and authoring guide for Pega notification rules (Rule-Notification), including the value-conditional recipient model (CURRENTPAGE / DATAPAGE / PAGELIST), the three delivery channels (Email, Gadget, MobilePush), data-page parameter mapping, message parameters, and side-by-side examples for each recipient context.

Prerequisite: Load methodology-rule-authoring first

Examples

Skill	Description
Stub Notification	Stub Notification — minimal notification, current-page recipient, gadget channel only. Smallest valid create payload.
Send Status Update	Send Status Update — auto-generated Send Notification step pattern, all three channels, case followers recipient, four linked rules sharing the same base name.
Notify Work Parties	Notify Work Parties — recipients from an embedded page list on the work object, Email and Gadget channels, both operator ID and raw email address mappings, message parameter.
Case Status Details	Case Status Details — all three channels each with their own independent parameter map (message body, email subject, push message), case followers recipient.

Author-minimal examples: the example payloads in this skill show only the fields the author typically supplies. Auto-filled / auto-derived fields such as pxObjClass, pyCategory, and channel scaffolding fields are omitted unless they carry author signal.

Authoring notes

Required identity fields

pyPurpose is the primary key the author must supply (PascalCase or camelCase, no spaces). pyRuleName is auto-derived from pyPurpose by the server — never set it in payloads.

Every entry in pzRecipients[] (or legacy pzRecipientDataPages[]) resolves within a recipient context. The fields the author needs to supply on that entry depend on the value:

pyRecipientContext	Meaning	Additional required fields	Optional fields
CURRENTPAGE	Use the running page as the recipient page	pyRecipientProperties (≥1 entry)	—
DATAPAGE	Fetch recipients from a data page	pyRecipientDataPage, pyDPClass, pyRecipientProperties (≥1 entry)	pzRecipientDataPageParameters, pzRuleParameters
PAGELIST	Iterate an embedded page list / page group	pyRecipientContextPage, pyRecipientProperties (≥1 entry)	pyDPClass, pzRecipientDataPageParameters

The schema enforces this with if/then branches on the recipient $def. When pyRecipientContext is omitted on legacy rules, treat the default as CURRENTPAGE.

pyRecipientProperties is always required

Every recipient entry — regardless of context — needs at least one pyRecipientProperties mapping. Each entry picks an identifier kind and the property reference that holds the value:

pyNotificationRecipientType	Typical pyNotificationRecipientProperty	Drives
Operator	.pyUserIdentifier, .pyUser, .pyOperatorID	Gadget (in-app), MobilePush, Email-by-operator
Email	.pyEmail, .pyEmailAddress	Email-by-address (no operator lookup)

Rules that need both in-app and raw-email delivery declare two pyRecipientProperties entries.

Channels are a page group keyed by subscript

pyChannelsList is an object with up to three subscripts: Email, Gadget, MobilePush. Each has a different pxObjClass:

Channel	pxObjClass	Body source	Content fields to supply
Email	Embed-NotificationChannel-Email	pyCorrespondence (Rule-Obj-Corr)	pyCorrespondence, pySubject
Gadget	Embed-NotificationChannel-Gadget	pyDisplayStream (section rule)	—
MobilePush	Embed-NotificationChannel-MobilePush	pyPushMessage (Rule-Obj-FieldValue)	pyPushMessage

All channels also require pxObjClass, pyChannelName, and pyEnableChannel. If a channel entry is present and pyEnableChannel is omitted, Infinity defaults it to enabled. For channels you do not want active, include that channel entry and explicitly set pyEnableChannel: "false" (see Auto-filled fields).

At least one channel should be enabled. Auto-generated rules from the App Studio Send Notification step always create all three with pxChannelRank Gadget=1, MobilePush=2, Email=3.

pzRecipients vs legacy pzRecipientDataPages

Both arrays have identical item shapes (the RecipientDef $def). Pega 8.4+ and App Studio auto-generated rules use pzRecipients. Older Pega-shipped notifications (Pega-Social, Pega-ProcessEngine) populate pzRecipientDataPages. For new rules, prefer pzRecipients. Do not populate both.

Data page parameter mapping

pzRecipientDataPageParameters is a free-form map of parameter name → source expression:

"pzRecipientDataPageParameters": {
  "WorkObjectID": ".pzInsKey",
  "PostID": "PostMessage.pzInsKey",
  "ReplyTo": "PostMessage.pyReplyTo"
}

The keys must match the parameters declared on the underlying data page (or the named page in PAGELIST mode). pzRuleParameters[] carries the metadata (name, type, required flag) for those parameters; the recipient model on the form derives the metadata from the data page rule.

Message parameters

Top-level pzMessageParameters maps the parameter tokens used in the message stream / correspondence to source expressions on the running page. pzOrderedMessageParams is the value list controlling the binding order. The Email channel has its own subject parameter map (pzCorrSubjectParameters + pzOrderedEmailSubjectParams) and the MobilePush channel has its own push message map (pzPushMessageParameters + pzOrderedPushMessageParams) and optional push title map (pzPushTitleParameters + pzOrderedPushTitleParams).

Each channel's parameter map is independent: every parameter declared on the referenced rule (FieldValue body, Email subject, MobilePush push message) MUST appear as a key in that channel's map with a valid source expression, and MUST be listed in the corresponding ordered array in the same order. A parameter shared across channels must be mapped separately in each map. Missing or mis-ordered parameters fail at runtime token resolution.

Server-validation gotchas

Field	Constraint
pyCategory	Default "Default". Observed values: Default, AssignedToMe, Mention.
pyMessage	Must resolve to an existing Rule-Obj-FieldValue (with pyFieldName = pyNotificationMessage) on the applies-to class hierarchy. There is no free-text fallback; any value that does not resolve to an indexed FieldValue causes save failure. Safe OOTB value: pyAddPulsePost.
pyRecipientContextPage (PAGELIST)	Must resolve to a real PageList/PageGroup property on the applies-to class. Safe Work- value: .pyWorkParty. Arbitrary names like .pyParticipantList are rejected at create time.
pyRuleSet / pyRuleSetVersion	REQUIRED for v1 create. Auto-derived by v2 from ChangeRequest branch context. For branch rulesets, version is always 01-01-01.

Auto-filled fields (omit from payloads unless overriding)

The schema marks auto-derived/auto-defaulted properties with x-pega-autoFill / x-pega-autoDerived. The examples in this skill omit them unless they carry author signal. pyEnableChannel is the main exception: omit it only when you want the channel on by default; set it explicitly to "false" to turn a channel off. Common auto-filled fields: pyCategory, pxChannelRank, pxSubscript, pyChannelName, pyEnableChannel, pyDisplayStream ("pyShowNotificationDefault"; grouped/child notifications use "ShowChildNotificationDefault"; member-join notifications use "pyShowNotificationForMemberJoin"), pyDefaultUserPreference blocks, pyShowInUserPreference, pyDoNotShowInPreference, pyMuteNotification, pyRuleAvailable, pyMethodStatus, pyBaseRule, pySortDateCircumWithinRSMajor, pyRuleName (derived from pyPurpose — never set by the author).

pyShowInUserPreference and pyDoNotShowInPreference

Auto-generated rules set pyShowInUserPreference: "false" and pyDoNotShowInPreference: "true" to keep the notification off the user-preference UI. Hand-authored Pega-shipped rules typically leave both unset (so the notification appears in preferences) unless they are workflow-internal.

pyAdvancedParameters for context tokens

Use this name/value list to pass page references into the notification engine that are not mapped through the recipient data page or message parameters. Typical pattern: PulseKey -> PostMessage.pzInsKey, AttachmentKey -> PostMessage.pyAttachmentKeys. Pair with pyPagesAndClasses to declare the named pages.

MobilePush push title parameters

The MobilePush channel supports a separate title (displayed above the push body) via pyPushTitle — a reference to a Rule-Obj-FieldValue rule. When pyPushTitle is set, its parameters are mapped independently via pzPushTitleParameters and pzOrderedPushTitleParams, following the same pattern as pzPushMessageParameters. This is observed on Social-style notifications (e.g. pyAddUserMentionedPost on @baseclass). Most auto-generated notifications do not set pyPushTitle.

Cross-rule dependencies (the four-rule bundle)

Every Notification step in a flow is backed by four rules that must be in sync:

Rule Type	Naming Convention	Referenced By
Rule-Notification	{Name}	Flow Utility shape (pzNotifyWrapper)
Rule-Obj-Corr	{Name} Email	pyChannelsList.Email.pyCorrespondence (base name only)
Rule-Obj-FieldValue	pyNotificationMessage / {Name}	pyMessage, pyChannelsList.MobilePush.pyPushMessage
Flow Utility shape	N/A	pyCallParams.NotificationName = {Name}

Key invariant: pyCorrespondence on the Email channel holds the base name (e.g. "NotifyReviewers_0"), while the actual Rule-Obj-Corr rule is named "{Name} Email". When a single FieldValue is used for both body and push, pyPurpose = pyMessage = pyChannelsList.MobilePush.pyPushMessage all carry that same base name.

Common Variations

• Gadget-only notification: Infinity treats channels as enabled by default, so explicitly set pyEnableChannel: "false" on MobilePush and Email in pyChannelsList. The FieldValue rule is still required. The Corr rule can be omitted if Email is disabled.
• Additional email recipient: Add a second entry to pzRecipients with pyRecipientContext: "CURRENTPAGE", pyRecipientTypeInAppStudio: "EmailID", and pyNotificationRecipientProperty: "[e-mail]".
• Notifying a specific operator instead of followers: Change pyRecipientDataPage to a data page that returns the target operator, or use pyRecipientContext: "CURRENTPAGE" with a property reference to the operator ID.

Auto-generated Send Notification bundle

App Studio auto-generates all four artifacts aligned on the same base name (e.g. SendStatusUpdate_0). For these rules:

• pyPurpose, pyMessage, pyChannelsList.MobilePush.pyPushMessage, pyChannelsList.Email.pyCorrespondence, and pyChannelsList.Email.pySubject all carry the same base name.
• pzIsAutoGenerated: "true" marks the rule as App Studio-generated.
• All three channels are created (see channel rank order in the Channels section above).
• The recipient row uses pyRecipientContext: "DATAPAGE" against D_pxGetCaseFollowers with pyRecipientTypeInAppStudio: "Followers" and one Operator property pointing at .pyUserIdentifier.
• If the generated FieldValue / Corr backing rules declare parameters, map them via pzMessageParameters / pzOrderedMessageParams and the channel-specific parameter lists. Simple generated messages with no parameters omit those fields entirely.