> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/platform/platform-services/notifications/implementing.md).

# Implementing a send

How a product service sends. After commit, with an allow-listed event key, a payload, and a recipient.

The [connector](https://docs.openg2p.org/platform/platform-services/notifications/connector.md) is the only send API. This page is how a service uses it. The events Registry and AWE already send are listed in [Workflows and payloads](https://docs.openg2p.org/platform/platform-services/notifications/workflows-and-payloads.md).

## Rules

1. Commit the business change first. A rolled-back request must not notify.
2. Put the event key in `NOTIFICATION_WORKFLOWS`. A key that is not in the map is skipped.
3. Pass `event`, `entity_id`, `payload`, and a `Recipient`. Do not pass a channel.
4. Call `send` or `send_bulk` from a thread if you are in an async service (`asyncio.to_thread`).
5. Log failures. Do not fail the business request because the notification provider is down or the package is missing.
6. Keep `send_bulk` at 100 events or fewer. Split a longer list.

Staff `recipient_id` is the Keycloak username (`preferred_username`). Registrant `recipient_id` is `registrant_id(internal_record_id)`, which returns `person:{id}`.

`notification_id` defaults to `{event}:{entity_id}`. Pass your own when one entity must produce more than one notification, for example one per recipient. Registry uses `{event}:{entity_id}:{recipient_id}`. AWE uses `{event}:{request_id}:{ref}:{recipient_id}`.

## Minimal call

```python
import asyncio

from openg2p_notification import NotificationFactory, Recipient, registrant_id

await asyncio.to_thread(
    NotificationFactory.get_notifier().send,
    "change_request.created",
    change_request_id,
    {"record_name": record_name, "change_request_id": change_request_id},
    Recipient(
        recipient_id=registrant_id(internal_record_id),
        recipient_email=email,
        recipient_phone=phone,
        recipient_name=name,
    ),
)
```

Wrap that call in `try` / `except`. If `openg2p_notification` cannot be imported, skip the send.

## Registry pattern

Registry does not call `send` at each business method. [`NotificationHelper`](https://github.com/OpenG2P/registry-platform/blob/develop/core/openg2p-registry-core/src/openg2p_registry_core/helpers/notification.py) builds the payload, resolves the recipient, and sends after commit.

| Helper                                  | Recipient                                                                                                        |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `dispatch_change_request_notification`  | Registrant, via `resolve_contact` on the register domain service                                                 |
| `dispatch_intake_form_notification`     | Registrant. If the domain service has no channel, intake falls back to contact fields on the submission sections |
| `dispatch_register_export_notification` | Staff username in `requested_by`                                                                                 |

`dispatch_notification_registrant` returns without sending when the contact is missing or `has_channel()` is false (no email and no phone). `dispatch_notification_staff` uses `preferred_username` as `recipient_id`.

A failed lookup of register, section, or record display is logged and leaves those payload fields empty. The send still goes out.

## AWE pattern

AWE must not notify for a transaction that later rolls back, and it must not do HTTP inside the engine transaction.

| Function    | When                                                                                                  |
| ----------- | ----------------------------------------------------------------------------------------------------- |
| `collect()` | Inside the transaction, from `emit_event()`. Stashes intents on `session.info`. No HTTP. Never raises |
| `flush()`   | After commit. One Keycloak lookup per username, then `send_bulk` per event. Failures are logged       |
| `discard()` | After rollback. Drops the intents                                                                     |

`collect()` ignores engine events that are not in its map: `request_created` (a `stage_started` follows), `stage_skipped`, a plain `stage_completed`, and observers. It also returns immediately when the event is not in `NOTIFICATION_WORKFLOWS`.

Source: [`awe/src/awe/services/notification.py`](https://github.com/OpenG2P/awe/blob/develop/src/awe/services/notification.py).

## Add an event

1. Choose a dotted event key. On the default notification provider the workflow id is that key with `.` and `_` replaced by `-`.
2. Add the workflow on the notification provider (channels, copy, `{{payload.*}}`). See [Novu](https://docs.openg2p.org/platform/platform-services/notifications/notification-provider/novu.md).
3. Add the key to `NOTIFICATION_WORKFLOWS` on the deployment that should send it.
4. After commit, call `send` with a payload that includes every field the template reads.

Removing the key from `NOTIFICATION_WORKFLOWS` turns the event off without a code change.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.openg2p.org/platform/platform-services/notifications/implementing.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
