notifications/docs/notification-workflow.md

Notification Workflow for an App that sends Notifications

Example story

Let's assume the following example scenario. Our app is the files_sharing app. We want to notify the user when a remote share has to be accepted/declined. If the user has dealt with it, we want to remove the notification again.

Creating a new Notification

1. Grab a new notification object (\OCP\Notification\INotification) from the manager (\OCP\Notification\IManager):

$manager = \OCP\Server::get(\OCP\Notification\IManager::class);
$notification = $manager->createNotification();

2. Set the necessary information for the notification:

$acceptAction = $notification->createAction();
$acceptAction->setLabel('accept')
    ->setLink('remote_shares', 'POST');

$declineAction = $notification->createAction();
$declineAction->setLabel('decline')
    ->setLink('remote_shares', 'DELETE');

$notification->setApp('files_sharing')
    ->setUser('recipient1')
    ->setDateTime(new \DateTime())
    ->setObject('remote', '1337') // $type and $id
    ->setSubject('remote_share', ['name' => '/fancyFolder']) // $subject and $parameters
    ->addAction($acceptAction)
    ->addAction($declineAction)
;

Setting app, user, timestamp, object and subject are mandatory. You should not use a translated subject, message or action label. Use something like a "language key", to avoid length problems with translations in the storage of a notification app. Translation is done via invocation of your notifier by the manager when the notification is prepared for display.

You should also try to avoid setting links and image paths here already, use keys again instead. This allows you to change the image/url of your application and also the admin can move the instance to another domain later, without breaking pending notifications. Also make sure, all your URLs are absolute URLs, so the notification icon and link also work from the desktop and mobile clients.

3. Send the notification back to the manager:

$manager->notify($notification);

Preparing a notification for display

1. In OCA\MyApp\Application::register(IRegistrationContext $context) register your Notifier (implementing the \OCP\Notification\INotifier interface) to the manager, using a \Closure returning the Notifier and a \Closure returning an array of the id and name:

	public function register(IRegistrationContext $context): void {
		$context->registerNotifierService(\OCA\Files_Sharing\Notification\Notifier::class);
	}

2. The manager will execute the closure and then call the prepare() method on your notifier. If the notification is not known by your app, just throw an OCP\Notification\UnknownNotificationException (Added in Nextcloud 30, before throw \InvalidArgumentException), but if it is actually from your app, you must set the parsed subject, message and action labels. If the notification is obsolete by now, e.g. because the share was revoked already, you can throw a OCP\Notification\AlreadyProcessedException which will remove the notification also from the devices.

class Notifier implements \OCP\Notification\INotifier {
	protected $factory;
	protected $url;

	public function __construct(\OCP\L10N\IFactory $factory,
								\OCP\IURLGenerator $urlGenerator) {
		$this->factory = $factory;
		$this->url = $urlGenerator;
	}

	/**
	 * Identifier of the notifier, only use [a-z0-9_]
	 * @return string
	 */
	public function getID(): string {
		return 'files_sharing';
	}

	/**
	 * Human-readable name describing the notifier
	 * @return string
	 */
	public function getName(): string {
		return $this->factory->get('files_sharing')->t('File sharing');
	}

	/**
	 * @param INotification $notification
	 * @param string $languageCode The code of the language that should be used to prepare the notification
	 */
	public function prepare(INotification $notification, string $languageCode): INotification {
		if ($notification->getApp() !== 'files_sharing') {
			// Not my app => throw
			throw new \OCP\Notification\UnknownNotificationException();
		}

		// Read the language from the notification
		$l = $this->factory->get('files_sharing', $languageCode);

		switch ($notification->getSubject()) {
			// Deal with known subjects
			case 'remote_share':
				try {
					$this->shareManager->getShareById($notification->getObjectId(), $notification->getUser());
				} catch (ShareNotFound $e) {
					// Throw AlreadyProcessedException exception when the notification has already been solved and can be removed.
					throw new \OCP\Notification\AlreadyProcessedException();
				}

				$notification->setIcon($this->url->getAbsoluteURL($this->url->imagePath('core', 'actions/share.svg')))
					->setLink($this->url->linkToRouteAbsolute('files_sharing.RemoteShare.overview', ['id' => $notification->getObjectId()]));

				// Set rich subject, see https://github.com/nextcloud/server/issues/1706 for more information
				// and https://github.com/nextcloud/server/blob/master/lib/public/RichObjectStrings/Definitions.php
				// for a list of defined objects and their parameters.
				$parameters = $notification->getSubjectParameters();
				$notification->setRichSubject($l->t('You received the remote share "{share}"'), [
					'share' => [
						'type' => 'pending-federated-share',
						'id' => $notification->getObjectId(),
						'name' => $parameters['name'],
					]
				]);

				// Deal with the actions for a known subject
				foreach ($notification->getActions() as $action) {
					switch ($action->getLabel()) {
						case 'accept':
							$action->setParsedLabel($l->t('Accept'))
								->setLink($this->url->linkToRouteAbsolute('files_sharing.RemoteShare.accept', ['id' => $notification->getObjectId()]), 'POST');
							break;

						case 'decline':
							$action->setParsedLabel($l->t('Decline'))
								->setLink($this->url->linkToRouteAbsolute('files_sharing.RemoteShare.decline', ['id' => $notification->getObjectId()]), 'DELETE');
							break;
					}

					$notification->addParsedAction($action);
				}

				// Set the plain text subject automatically
				$this->setParsedSubjectFromRichSubject($notification);
				return $notification;

			default:
				// Unknown subject => Unknown notification => throw
				throw new \OCP\Notification\UnknownNotificationException();
		}
	}

	/**
	 * This is a little helper function which automatically sets the simple parsed subject
	 * based on the rich subject you set. This is also the default behaviour of the API
	 * since Nextcloud 26, but in case you would like to return simpler or other strings,
	 * this function allows you to take over.
	 *
	 * @param INotification $notification
	 */
	protected function setParsedSubjectFromRichSubject(INotification $notification): void {
		$placeholders = $replacements = [];
		foreach ($notification->getRichSubjectParameters() as $placeholder => $parameter) {
			$placeholders[] = '{' . $placeholder . '}';
			if ($parameter['type'] === 'file') {
				$replacements[] = $parameter['path'];
			} else {
				$replacements[] = $parameter['name'];
			}
		}

		$notification->setParsedSubject(str_replace($placeholders, $replacements, $notification->getRichSubject()));
	}
}

Marking a notification as read/deleted/processed/obsoleted

If the user accepted the share or the share was removed/unshared, we want to remove the notification, because no user action is needed anymore. To do this, we simply have to call the markProcessed() method on the manager with the necessary information on a notification object:

$manager = \OCP\Server::get(\OCP\Notification\IManager::class);
$notification->setApp('files_sharing')
    ->setObject('remote', 1337)
    ->setUser('recipient1');
$manager->markProcessed($notification);

Only the app name is mandatory: so if you don't set the user, the notification will be marked as processed for all users that have it. So the following example will remove all notifications for the app files_sharing on the object "remote #1337":

$manager = \OCP\Server::get(\OCP\Notification\IManager::class);
$notification->setApp('files_sharing')
    ->setObject('remote', 1337);
$manager->markProcessed($notification);

Defer and flush

Sometimes you might send multiple notifications in one request. In that case it makes sense to defer the sending, so in the end only one connection is done to the push server instead of 1 per notification.

$manager = \OCP\Server::get(\OCP\Notification\IManager::class);
$shouldFlush = $manager->defer();

// Your application code generating notifications …

if ($shouldFlush) {
	// Only flush when defer() returned true, otherwise another app is already deferring
	$manager->flush();
}