# 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`):
    ```php
    $manager = \OC::$server->getNotificationManager();
    $notification = $manager->createNotification();
    ```

  2. Set the necessary information for the notification:
    ```php
    $acceptAction = $notification->createAction();
    $acceptAction->setLabel('accept')
        ->setLink('/apps/files_sharing/api/v1/remote_shares/1337', 'POST');

    $declineAction = $notification->createAction();
    $declineAction->setLabel('decline')
        ->setLink('/apps/files_sharing/api/v1/remote_shares/1337', 'DELETE');

    $notification->setApp('files_sharing')
        ->setUser('recipient1')
        ->setDateTime(new DateTime())
        ->setObject('remote', '1337') // $type and $id
        ->setSubject('remote_share', ['/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.

  3. Send the notification back to the manager:
    ```php
    $manager->notify($notification);
    ```

### Preparing a notification for display

  1. In `app.php` register your Notifier (`\OCP\Notification\INotifier`) interface to the manager,
  using a `\Closure`:
    ```php
    $manager = \OC::$server->getNotificationManager();
    $manager->registerNotifier(function() {
        return new \OCA\Files_Sharing\Notifier(
            \OC::$server->getL10NFactory()
        );
    });
    ```

  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 `\InvalidArgumentException`,
  but if it is actually from your app, you must set the parsed subject, message and action labels:
    ```php
    protected $factory;

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

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

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

        switch ($notification->getSubject()) {
            // Deal with known subjects
            case 'remote_share':
                $notification->setParsedSubject(
                    (string) $l->t('You received the remote share "%s"', $notification->getSubjectParameters())
                );
                
                // Deal with the actions for a known subject
                foreach ($notification->getActions() as $action) {
                    switch ($action->getLabel()) {
                        case 'accept':
                            $action->setParsedLabel(
                                (string) $l->t('Accept')
                            );
                        break;
 
                        case 'decline':
                            $action->setParsedLabel(
                                (string) $l->t('Decline')
                            );
                        break;
                    }

                    $notification->addParsedAction($action);
                }
                return $notification;
            break;

            default:
                // Unknown subject => Unknown notification => throw
                throw new \InvalidArgumentException();
        }
    }
    ```

    **Note:** currently no markup is allowed.

### 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 neccessary information on a
notification object:

```php
$manager = \OC::$server->getNotificationManager();
$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":

```php
$manager = \OC::$server->getNotificationManager();
$notification->setApp('files_sharing')
    ->setObject('remote', 1337);
$manager->markProcessed($notification);
```