doc: Updates regarding the new source integrations

Author: nilmerg

doc/01-About.md

@@ -6,38 +6,32 @@
 
     At the moment, we don't provide any support for this module.
 
-Icinga Notifications is a set of components that processes received events from miscellaneous sources, manages
-incidents and forwards notifications to predefined contacts, consisting of:
+Icinga Notifications is a set of components that processes received events from various sources, manages
+incidents and forwards notifications to predefined contacts. The components are:
 
 * [Icinga Notifications](https://github.com/Icinga/icinga-notifications), which receives events and sends notifications.
-* Icinga Notifications Web, which provides graphical configuration.
+* Icinga Notifications Web, which lets users configure Icinga Notifications and manage incidents.
 
 Icinga 2 itself and other sources propagate state updates and other events to [Icinga Notifications](https://github.com/Icinga/icinga-notifications).
 
 ## Big Picture
 
 ![Icinga Notifications Architecture](res/notifications-architecture.png)
 
-Because Icinga Notifications consists of several components,
-this section tries to help understand how these components relate.
+All configuration of Icinga Notifications is done via Icinga Notifications Web. This includes the setup of sources
+Icinga Notifications will receive events from. To set up a source, an accompanying integration in Icinga Web is
+required. At the moment, compatible integrations are available for:
 
-First, the Icinga Notifications configuration resides in a SQL database.
-It can be conveniently tweaked via Icinga Notifications Web directly from a web browser.
-The Icinga Notifications daemon uses this database to read the current configuration.
+* Icinga 2, by using Icinga DB as backend
 
-As in any Icinga setup, all host and service checks are defined in Icinga 2.
-By querying the Icinga 2 API, the Icinga Notifications daemon retrieves state changes, acknowledgements and other events.
-These events are stored in the database and are available for further inspection in Icinga Notifications Web.
-Next to Icinga 2, other notification sources can be configured.
-
-Depending on its configuration, the daemon will take action on these events.
-This optionally includes escalations that are sent through a channel plugin.
-Each of those channel plugins implements a domain-specific transport, e.g., the `email` channel sends emails via SMTP.
-When configured, Icinga Notifications will use channel plugins to notify end users or talk to other APIs.
+Icinga Notifications receives events from the configured sources and decides whether to open an incident and when to
+forward them to which recipients. Icinga Notifications Web allows configuring these rules and managing incidents. To
+send notifications, Icinga Notifications is able to facilitate various types of channels, e.g., email, Rocket.Chat,
+webhook, etc.
 
 ## Available Channels
 
-Icinga Notifications comes with multiple channels out of the box:
+The following channels are currently available out of the box:
 
 * _email_: Email submission via SMTP
 * _rocketchat_: Rocket.Chat
@@ -48,7 +42,7 @@ following the [channel specification](https://icinga.com/docs/icinga-notificatio
 
 ## Installation
 
-To install Icinga Notifications Web see [Installation](02-Installation.md).
+To install Icinga Notifications Web, see [Installation](02-Installation.md).
 
 ## License
 

doc/03-Configuration.md

@@ -10,11 +10,10 @@ configure Icinga Notifications Web:
 
 ## Module Activation
 
-If you just installed the module, do not forget to activate it on your Icinga Web instance(s) by using your
-preferred way:
+If you just installed Icinga Notifications Web, remember to activate it on your Icinga Web instance(s):
 
 - Use Icinga Web's command-line interface on the webserver(s) and execute `icingacli module enable notifications`.
-- Visit Icinga Web, log in as a privileged user and activate the module under `Configuration →
+- Visit Icinga Web, log in as a privileged user and enable the module under `Configuration →
   Modules → notifications` by switching the state from `disabled` to `enabled`.
 
 <!-- {% endif %} -->
@@ -26,10 +25,10 @@ Connection configuration for the database, which both,
 
 !!! tip
 
-    If not already done, initialize your database by following the [instructions](https://icinga.com/docs/icinga-notifications/latest/doc/02-Installation#setting-up-the-database).
+    If not already done, initialize your database by following these [instructions](https://icinga.com/docs/icinga-notifications/latest/doc/02-Installation#setting-up-the-database).
 
 1. Create a new resource for the Icinga Notifications database via the `Configuration → Application → Resources` menu.
-2. Configure the resource you just created as the database connection for the Icinga Notifications Web module using the
+2. Configure the resource you just created as the database connection for Icinga Notifications Web using the
    `Configuration → Modules → notifications → Database` menu.
 
 ## Channels Configuration
@@ -39,34 +38,34 @@ communication channels.
 
 The currently supported channels can be found [here](01-About.md#available-channels).
 
-They can be configured through `Configuration → Modules → notifications → Channels` and the credentials to be supplied 
-might differ depending on the channel type.
+They can be configured through `Configuration → Modules → notifications → Channels`.
 
-You need to configure at least one valid communication channel to be able to supply your contacts with notifications.
+You need to configure at least one valid communication channel to fully configure Icinga Notifications Web.
 
 ## Sources Configuration
 
-The notifications module operates on data fed by miscellaneous sources and is therefore not restricted to Icinga 2 only.
-Consult the source specific documentation on how to integrate such.
+Sources are the most vital part of Icinga Notifications. Without them, no events will be processed and no notifications
+will be sent. So the next thing to configure is your first source. To be able to configure sources, an integration in
+Icinga Web is required. Consult the source-specific documentation on how to integrate such.
 
-You need to provide at least one valid source for this module to function properly.
+How to integrate Icinga 2 is covered in the next section, for your convenience. :)
 
 ### Adding an Icinga 2 source
 
-!!! tip
-
-    If there is no API user with the required permissions yet, read through [Icinga's API documentation](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#authentication).
-
-    The API user needs the following [permissions](https://icinga.com/docs/icinga-2/latest/doc/12-icinga2-api/#overview):
-
-    - `events/*`  
-    - `objects/query/*`  
-    - `status/query`
-
-If you want the notifications module to process Icinga 2 events, you will need to add it as a source:
+Ensure that you use Icinga DB as the database backend for Icinga 2. If that is the case, you should already have
+Icinga DB Web installed. This is the integration required to configure Icinga 2 as a source.
 
 1. Navigate to `Configuration → Module → notifications → Sources` and add a new source.
-2. Choose type `Icinga` and provide the Icinga 2 API credentials.
-3. (Optional) Disable `Verify API Certificate` if you want
-   [Icinga Notifications](https://icinga.com/docs/icinga-notifications/latest) to skip its check for the certificate
-   validity of the given REST API endpoint.
+2. Choose type `Icinga` and define a name as well as a set of credentials.
+3. Open `/etc/icingadb/config.yml` on the host where Icinga DB is running and add the following lines:  
+   The full documentation can be found [here](https://icinga.com/docs/icinga-db/latest/doc/03-Configuration/#notifications-source-configuration).
+    ```yaml
+    notifications-source:
+      # URL to the API root.
+      api-base-url: http://localhost:5680
+
+      # Use the username and password you just defined for the credentials.
+      username: icingadb
+      password: insecureinsecure
+    ```
+4. Restart Icinga DB.