# Nocobase Notification Manage

> NocoBase 2 only; never use in a NocoBase 3 project. Use when users need to configure, inspect, test, or troubleshoot NocoBase notification management, including in-app message channels, email SMTP channels, workflow notification nodes, and notification send logs.

- Skill: `nocobase/nocobase-notification-manage` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds add nocobase/nocobase-notification-manage`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nocobase/nocobase-notification-manage/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: nocobase (https://skillmd.com/u/nocobase)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/nocobase/nocobase-notification-manage

---


# Goal

Guide NocoBase notification management work end-to-end: inspect notification plugins and channels, configure in-app message or email channels, wire workflow notification nodes, test delivery, and diagnose send logs.

# Scope

- Handle: notification manager usage, including channels in `notificationChannels` and send logs in `notificationSendLogs`.
- Handle: in-app message channels (`notificationType: in-app-message`) and their workflow message fields.
- Handle: email channels (`notificationType: email`) using SMTP transport.
- Handle: workflow notification node guidance for node type `notification`.
- Handle: delivery diagnosis using send logs, workflow job results, and channel configuration readback.

# Non-Goals

- Do not install, enable, or disable plugins directly. Use `nocobase-plugin-manage` for plugin state changes.
- Do not design a complete workflow from scratch. Use `nocobase-workflow-manage` for trigger and node-chain authoring.
- Do not create new notification channel types. Use plugin development guidance for custom providers.
- Do not send real external email tests without explicit confirmation of recipients.
- Do not expose or echo SMTP passwords, app passwords, or other channel secrets.

# Input Contract

| Input | Required | Default | Validation | Clarification Question |
|---|---|---|---|---|
| `action` | yes | `inspect` | one of `inspect/configure-channel/test-channel/configure-workflow/diagnose` | "Which action should I run: inspect, configure-channel, test-channel, configure-workflow, or diagnose?" |
| `channel` | configure/test: yes | none | existing channel name or one of `in-app-message/email` | "Which channel name or channel type should I use?" |
| `env` | no | current CLI env | configured `nb` env name | "Which NocoBase CLI env should I target?" |
| `workflow` | configure-workflow/diagnose: sometimes | none | workflow id/key/title resolved uniquely | "Which workflow or notification node should I inspect?" |
| `recipients` | test-channel: yes | none | explicit user ids or email addresses | "Which safe test recipients should receive the notification?" |
| `mode` | no | `safe` | one of `safe/fast` | "Use safe mode with readback, or fast mode?" |

Rules:

- If any required input is missing, stop mutation and ask clarification.
- If user says "you decide", use documented defaults.
- Resolve channel names from `notificationChannels`; do not guess generated `s_` names.
- A notification channel must exist in `notificationChannels` before any workflow node or send operation uses it. Never invent or fill in a non-existent `channelName`; create the channel first, then read it back and use the real `name`.
- Prefer safe mode for all configuration and test work.

# Mandatory Clarification Gate

- Max clarification rounds: `2`
- Max questions per round: `3`
- Mutation preconditions:
- `action` is confirmed.
- `nb` CLI reachability and authentication are confirmed for application operations.
- For channel writes, channel type and required provider fields are known.
- For tests, recipients are explicit and approved.
- For workflow edits, exact workflow or node ownership is resolved.
- If preconditions are not met, stop and report missing inputs/capabilities.

# Workflow

1. Confirm `nb` CLI reachability and plugin state; if plugin enablement is required, hand off to `nocobase-plugin-manage`.
2. Inspect `notificationChannels` and registered channel types before changing anything.
3. Select the correct path:
- `inspect`: list channels and recent `notificationSendLogs`.
- `configure-channel`: create or update only the requested channel type.
- `test-channel`: send to explicit safe recipients, then read logs.
- `configure-workflow`: guide or delegate workflow node edits for type `notification`.
- `diagnose`: correlate channel config, send logs, workflow jobs, and server logs.
4. Read the relevant reference file before producing field-level guidance.
5. For mutations, execute one write at a time and read back `notificationChannels`.
6. For delivery tests, inspect `notificationSendLogs.status`, `reason`, `message`, `triggerFrom`, and `channelName`.
7. For workflow notification nodes, use only a read-back `notificationChannels.name`; if no suitable channel exists, create/configure the channel first or stop and report the missing channel.
8. Report the final state, evidence, and any remaining risk.

# Reference Loading Map

Use this section to prevent vague reference usage. Each entry should say exactly when to read it.

| Reference | Use When | Notes |
|---|---|---|
| [Channel configuration](references/channel-configuration.md) | Creating, updating, or reviewing in-app message and email channels. | Includes channel types, fields, and secret handling. |
| [Workflow notifications](references/workflow-notification.md) | Adding or reviewing workflow notification nodes. | Includes node type and per-channel message fields. |
| [Diagnostics](references/diagnostics.md) | Investigating failed or missing notifications. | Includes collections, status fields, and common failure causes. |

Reference rules:

- Use relative Markdown links for local files.
- Use `/` path separators in links.
- Keep references one hop from `SKILL.md` where possible.
- If a reference file exceeds 100 lines, add a TOC in that file.

# Safety Gate

- High-risk actions require secondary confirmation before execution.
- High-risk actions include:
- sending real email to external recipients
- changing SMTP host/account/password/from values
- deleting notification channels or send logs
- changing workflow notification nodes in an enabled or previously executed workflow
- enabling/disabling notification-related plugins

Secondary confirmation template:

- "Confirm execution: `{{action}}` for notification channel `{{channel}}`. Expected impact: {{impact}}. Type `confirm` to continue."

Rollback guidance:

- Trigger rollback when readback does not match the requested channel or workflow configuration.
- Rollback steps:
- restore the previous `notificationChannels` record values
- restore the previous workflow revision or node config through `nocobase-workflow-manage`
- verify by readback and a safe test send when appropriate

# Verification Checklist

- Target channel or workflow node exists and is uniquely resolved.
- `nb` authentication state is valid.
- Required notification plugins are enabled or a handoff is made.
- Input values pass validation rules.
- Every write has immediate readback verification.
- Channel `notificationType` matches the intended provider.
- Email channel has SMTP `host`, `port`, `secure`, `account`, `password`, and `from` configured without printing secrets.
- In-app message channel has a display title and can be selected by workflow notifications.
- Workflow notification node uses type `notification` and a real `channelName`.
- Workflow in-app message `receivers` constants use integer user IDs, not string values such as `"1"`.
- Send logs show expected `status`, `triggerFrom`, `channelName`, and `reason` when failed.
- Errors and partial successes are reported separately.
- Final output includes CLI env and app context used.

# Minimal Test Scenarios

1. Inspect-only: list notification channels and recent send logs.
2. Configure in-app message channel and verify it appears in `notificationChannels`.
3. Configure email SMTP channel, redact secrets in output, and verify readback.
4. Test channel with explicit recipients and verify `notificationSendLogs`.
5. Missing recipient for a real test blocks sending.
6. Workflow node change on an executed workflow hands off to `nocobase-workflow-manage` revision rules.

# Output Contract

Final response must include:

- What was requested.
- What was executed.
- What was verified.
- What failed or remains unclear.
- Which defaults/assumptions were applied.
- Notification channel name/type and CLI env used.
- Exact next actions for user if blocked.

# References

- [Channel configuration](references/channel-configuration.md): use for notification channel configuration fields and provider rules.
- [Workflow notifications](references/workflow-notification.md): use for workflow notification node behavior and message fields.
- [Diagnostics](references/diagnostics.md): use for logs, failure reasons, and troubleshooting sequence.