diff --git a/docs/user-guide/020-manager-ui/10-manager-ui.md b/docs/user-guide/020-manager-ui/10-manager-ui.md index e95f7f63..c174c4ac 100644 --- a/docs/user-guide/020-manager-ui/10-manager-ui.md +++ b/docs/user-guide/020-manager-ui/10-manager-ui.md @@ -188,6 +188,18 @@ The alarms functionality (top right) allows you to automatically generate alarms ![](img/alarms-overview.png) _Figure 13. The alarms page with an overview of all alarms._ +## Notifications + +The notifications page (top right, under the dots menu) shows all email and push notifications sent within the selected realm, and lets you send new ones. These features are supported: +* Overview of sent notifications: see what was sent by rules, the platform itself, or clients using the [Manager APIs](#manager-apis), and whether it was sent or failed. +* Filtering by source and by period, ordering by column, and paging. +* Send a notification: write an email or push notification and send it to users, users linked to assets, or all users in a realm. + +Viewing notifications requires the `read:notifications` role, sending them the `write:notifications` role. See [Notifications](./50-notifications.md) for more details. + +![](img/notifications-overview.png) +_Figure 14. The notifications page with an overview of all sent notifications._ + ## Settings and access Admin users of the 'Master' realm see the Realm selector on the top right to switch between Realms. Next to that the dots give you access to a series of general settings as well as account access related settings. We will explain these here: @@ -198,17 +210,17 @@ You can link multiple instances of OpenRemote (as Gateways) to a single Central See the [Edge Gateway documentation](../080-gateways-and-devices/10-edge-gateway.md) for more details. ![](img/manager-interconnect.png) -_Figure 14. Several OpenRemote instances can be interconnected, e.g. connecting multiple instances on edge gateways to one central cloud hosted instance. The Manager Interconnect page, used at the edge instances (left) uses the keys which are created on the central instance by adding Edge gateway Assets (right)._ +_Figure 15. Several OpenRemote instances can be interconnected, e.g. connecting multiple instances on edge gateways to one central cloud hosted instance. The Manager Interconnect page, used at the edge instances (left) uses the keys which are created on the central instance by adding Edge gateway Assets (right)._ ![](img/manager-interconnect-rate-limiting.png) -_Figure 15. Next to interconnecting you can choose which asset attributes are actually linked as well as the rate at which data is exchanged._ +_Figure 16. Next to interconnecting you can choose which asset attributes are actually linked as well as the rate at which data is exchanged._ ### Gateway tunnels On top of the 'Manager Interconnect' functionality, you can remotely access the full Manager UI of the Gateway instances of OpenRemote, by creating Gateway tunnels. See the [Edge Gateway documentation](../080-gateways-and-devices/10-edge-gateway.md) for more details. ![](img/create-gateway-tunnel.png) -_Figure 16. Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ +_Figure 17. Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ ### Languages @@ -219,14 +231,14 @@ OpenRemote currently supports 9 languages: English, German, French, Spanish, Por The logs page shows information, warnings and errors of the different activities of OpenRemote. You can use it to understand the behaviour of the whole platform or debug issues, e.g. errors connecting agent with device. ![](img/logs-page.png) -_Figure 17. The Logs page to evaluate system behaviour._ +_Figure 18. The Logs page to evaluate system behaviour._ ### Account On the Account page you can (re)set you personal information or password. You can also monitor your past sessions or enable 2FA via an Authenticator (default disabled). ![](img/edit-account-change-password.png) -_Figure 18. The account page with contact details (left) and reset passwords (right)._ +_Figure 19. The account page with contact details (left) and reset passwords (right)._ ### Users and access configuration @@ -241,14 +253,14 @@ By linking assets to users, the system will understand which users are connected When, next to linking an asset to a user, you also set the Realm role to 'Restricted User', users will only have access to the assets they are linked to. Note that you additionally have to indicate on the assets which attributes of the asset they have access to. To do that, set the configuration item 'Access restricted user read/write' on the attribute ([see 'Configure attributes'](#configure-attributes)). ![](img/creating-users.png) -_Figure 19. Creating users for a selected realm, assigning roles. In this example, the user is made a 'restricted user' linked to only 6 assets._ +_Figure 20. Creating users for a selected realm, assigning roles. In this example, the user is made a 'restricted user' linked to only 6 assets._ ### Roles With the correct permissions, you can create and edit roles. These roles define which parts of the system a user is allowed to Read or Write, e.g. system settings, assets, attributes, map, or rules. Also see the userguide: [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md). ![](img/role-with-permissions.png) -_Figure 20. Roles are made of a set of permissions_ +_Figure 21. Roles are made of a set of permissions_ ### Realms @@ -257,16 +269,16 @@ Only the Master realm Admin user can create `Realms` by accessing the master rea You can create a realm by adding a `realmname` name (single word, lower case letters), and a `Friendly name`. You can (temporarily) disable realms, which blocks access for any user. ![](img/realms.png) -_Figure 21. Realms can be created to manage multiple independent projects within one OpenRemote instance_ +_Figure 22. Realms can be created to manage multiple independent projects within one OpenRemote instance_ Also see the userguide: [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md). ### Auto provisioning of devices -If you are an OEM, developing and producing your own hardware, you can provision your devices and OpenRemote to automatically have your devices connecting, once they get online. Using certificates (we currently support X.509) your devices will register and automatically generate and connect to an asset of a defined type in the OpenRemote Manager (see figure 22). For details, check out the documentation about ['Auto provisioning'](../080-gateways-and-devices/20-auto-provisioning.md). +If you are an OEM, developing and producing your own hardware, you can provision your devices and OpenRemote to automatically have your devices connecting, once they get online. Using certificates (we currently support X.509) your devices will register and automatically generate and connect to an asset of a defined type in the OpenRemote Manager (see figure 23). For details, check out the documentation about ['Auto provisioning'](../080-gateways-and-devices/20-auto-provisioning.md). ![](img/auto-provisioning-of-devices.png) -_Figure 22. Auto provisioning of devices_ +_Figure 23. Auto provisioning of devices_ ### Appearance @@ -277,7 +289,7 @@ You can change the logo's, use different colours, change the title and default l For adding map layers you can add GeoJSON files (created e.g. with https://geojson.io/). More advanced settings like visible asset and agent types on the asset and rules page, can be configured directly in a JSON file. For the options available in the JSON file and an example, check out [Configuring the Manager UI](../010-deploying/20-configuring-the-manager-ui.md). For the maps you can set the center point, zoom levels and boundaries. ![](img/appearance-settings.png) -_Figure 23. Appearance settings allow white labeling of your OpenRemote manager_ +_Figure 24. Appearance settings allow white labeling of your OpenRemote manager_ ## Manager APIs @@ -285,10 +297,10 @@ The Manager APIs let you interact with OpenRemote without using the UI. This can ### Service users -Service users can be created on the `Users` page, and selecting `Add user` in the `Service user` panel (see figure 24). The `Username` (ClientID) can be set using letters, dashes, and numbers, while the `Secret` will be generated automatically once saved. Note that you also need to select the role(s). +Service users can be created on the `Users` page, and selecting `Add user` in the `Service user` panel (see figure 25). The `Username` (ClientID) can be set using letters, dashes, and numbers, while the `Secret` will be generated automatically once saved. Note that you also need to select the role(s). ![](img/creating-service-users.png) -_Figure 24. Creating service users, with Username, Secret and Roles for a selected Realm_ +_Figure 25. Creating service users, with Username, Secret and Roles for a selected Realm_ ### HTTP, MQTT, and WebSocket diff --git a/docs/user-guide/020-manager-ui/50-notifications.md b/docs/user-guide/020-manager-ui/50-notifications.md new file mode 100644 index 00000000..cb9b2464 --- /dev/null +++ b/docs/user-guide/020-manager-ui/50-notifications.md @@ -0,0 +1,259 @@ +# Notifications + +The Notifications page gives you an overview of all email and push notifications sent within a realm, and lets you send new ones directly from the Manager UI. You can find it in the settings menu (the dots on the top right) under `Notifications`. The page shows the notifications of the realm that is currently selected in the realm picker. + +The Notifications page provides three capabilities: +- **Overview** — browse, filter and sort all notifications that were sent, whether they came from rules, the platform itself, or an API client +- **Send** — write an email or push notification and send it to users, users linked to assets, or all users in a realm +- **Details** — look at the full content, recipient and delivery status of a single notification + +![](img/notifications-overview.png) +_Figure 1. The Notifications page with an overview of all sent notifications._ + +## Before you start + +Notifications are only delivered when the matching channel is configured for your deployment: + +| Channel | Requirements | +| :------ | :----------- | +| **Email** | An SMTP server, configured using the `OR_EMAIL_HOST`, `OR_EMAIL_USER`, `OR_EMAIL_PASSWORD` and `OR_EMAIL_FROM` environment variables. See [setting environment variables](../010-deploying/10-custom-deployment.md#setting-environment-variables-and-docker-volume-mappings-for-services). Recipients need an email address. | +| **Push** | A Firebase Cloud Messaging configuration file, set using the `OR_FIREBASE_CONFIG_FILE` environment variable. See [Push Notifications / FCM setup](../../developer-guide/140-working-on-the-mobile-consoles.md#push-notifications--fcm-setup). Recipients need the [OpenRemote app](./20-on-mobile.md) (or your own console app) with push notifications enabled. | + +:::note + +If a channel is not configured, sending a notification of that type fails and nothing is added to the overview. When you run the manager in dev mode without this configuration, notifications are recorded in the overview and written to the log instead of being sent. + +::: + +### Required roles + +Access to the page is controlled by two roles, which you can assign on the [Roles](./10-manager-ui.md#roles) page: + +| Role | Description | +| :--- | :---------- | +| `read:notifications` | View the Notifications page and the notifications sent within the realm | +| `write:notifications` | Send notifications, using the `Send new` button or the [API](#using-the-api) | + +The admin roles don't give access to this page: users with `read:admin` or `write:admin` still need the notification roles above. Some parts of the page need additional roles: +- **Recipients** — to select users you need `read:users`, and to select assets you need `read:assets`; `read:admin` works for both. Without these roles, the recipients of users or assets are shown as `-` in the overview. The `Send new` button only appears if you have `write:notifications`, and is disabled if you can't select any recipients. +- **All users in a realm** — only superusers can send a notification to every user in a realm. +- **Restricted users** — a [restricted user](../070-identity-and-security/10-realms-users-and-roles.md#restricted-user-realm-role) only sees notifications they sent themselves, notifications sent to them, and notifications sent to their whole realm. They can only send notifications to users linked to the assets they are linked to. + +:::warning + +When you upgrade an existing installation, `read:notifications` and `write:notifications` are automatically added to the default `read` and `write` roles in every realm. Custom roles that you created yourself do not get them, so add the roles there if needed. + +Sending a notification through the API now requires the `write:notifications` role as well. Give this role to any [service user](./10-manager-ui.md#service-users) that sends notifications. + +::: + +## Viewing sent notifications + +The overview shows one row per recipient that was reached: a user or asset for an email, or a device with the app for a push notification. A user with two phones gets two rows for one push notification, and recipients that can't be reached get no row. By default, you see the notifications sent today, with the newest first. + +| Column | Description | +| :----- | :---------- | +| **Title** | The title of a push notification or the subject of an email. The icon in front shows whether it was a push notification or an email | +| **Body** | The message of the notification. For emails this is the HTML that was sent | +| **Status** | Whether the notification was sent or failed. See [Status](#status) | +| **Source** | What sent the notification. See [Source](#source) | +| **Recipient** | The user, asset or realm that received the notification. Users and assets link to their page in the Manager UI | +| **Sent on** | The moment the notification was sent | +| **Delivered on** | The moment a console app confirmed that it received the notification (push notifications only) | + +:::note + +Delivery confirmation does not work at the moment. The `Delivered on` column stays empty, and push notifications keep the `Sent` status, even when they arrived on the device. + +::: + +Click a column header to sort by that column; click again to reverse the order. You can sort by Title, Status, Source, Sent on and Delivered on. Sorting is applied to all notifications, not just the current page. Use the controls at the bottom of the table to change the number of rows per page and to move between pages. + +### Status + +| Status | Description | +| :----- | :---------- | +| `Sent` | The notification left the platform: it was accepted by the email server or by Firebase | +| `Delivered` | A console app confirmed that it received the push notification. Emails never get this status. Not set at the moment, see the note above | +| `Error` | Sending failed. Hover over the status to see the reason | + +### Source + +| Source | Description | +| :----- | :---------- | +| **Internal** | Sent by the platform itself, for example by a service or by custom code running in the manager | +| **Client** | Sent through the [API](#using-the-api) by a user or service user. Notifications you send with `Send new` also get this source | +| **Global ruleset** | Sent by a global rule, such as a [When-Then rule](../060-rules-and-forecasting/20-when-then-rules.md#supported-actions) or [Groovy rule](../060-rules-and-forecasting/40-groovy-rules.md) | +| **Realm ruleset** | Sent by a rule in the realm | + + + +### Filtering notifications + +Use the controls at the top of the page to narrow down the overview: + +| Filter | Description | +| :----- | :---------- | +| **Source** | Only show notifications from one source. The default is `All sources` | +| **From** / **To** | Only show notifications sent within this period. The default is today, from 00:00 to 23:59 | + +To see the notifications of another realm, select that realm in the realm picker. A notification is listed in the realm of its recipient, so a notification sent from the master realm to a user in another realm shows up in that other realm. If the recipient's realm cannot be determined, the notification is listed in the realm of the sender. For global rules and internal notifications, that is the master realm. + +## Sending a notification + +To send a notification, you need the `write:notifications` role. + +1. Click `Send new` on the top right of the page. +2. Select the recipients: choose a **Recipient type** and select one or more recipients. +3. Choose the **Type** of notification, `Push` or `Email`, and enter its content. +4. For push notifications, optionally configure the **Actions**. +5. Click `Create`. + +The `Create` button is only enabled when you have selected at least one recipient, filled in the title or subject and the body, and entered a valid website URL (if you entered one). After the notification is sent, the overview reloads and shows the new notification with the source `Client`. + +### Recipients + +| Recipient type | Who receives the notification | Availability | +| :------------- | :---------------------------- | :----------- | +| **Users** | The selected users of the current realm | Requires `read:users`. Not available for restricted users | +| **Users linked to assets** | The users linked to the assets you select in the asset tree | Requires `read:assets`. Restricted users can only select assets they are linked to | +| **All users in realms** | Every user in the selected realms | Superusers only | + +How recipients are reached depends on the type of notification: +- **Email** — sent to the email address of each user. For `Users linked to assets`, the email is also sent to the address in the `email` attribute of the asset, if it has one. +- **Push** — sent to the console apps (for example the OpenRemote app on a phone) that are registered by the users. For push notifications the recipient in the overview is therefore the console asset, one row per device. + +Service users, users without an email address (for email), users without a registered console app (for push), and users who turned off that type of notification never receive it. + +### Content + +| Field | Description | +| :---- | :---------- | +| **Type** | `Push` for a notification on a mobile device, or `Email` | +| **Title** / **Subject** | The title of the push notification or the subject of the email. Required | +| **Body** | The message. Required. Emails are sent as HTML, so use tags such as `

`, `
` or `` for formatting; line breaks are not kept otherwise | + +### Actions + +Push notifications can include an action and buttons. All fields are optional. + +| Field | Description | +| :---- | :---------- | +| **Website to be opened** | The URL opened when the recipient taps the notification. The URL must include a scheme, such as `https://example.com` | +| **Open in browser (for external websites)** | Opens the website in the browser of the device instead of inside the app | +| **Text for action button** | Adds a button with this text. The button opens the website | +| **Text for decline button** | Adds a button with this text that dismisses the notification | +| **Priority** | `Normal` or `High`. Only applies to Android devices, where high priority notifications are delivered immediately, even when the device is idle. iOS devices always receive push notifications with high priority | + +### When sending fails + +If sending fails, you will see the message `Failed to send notification.` This happens when: +- none of the selected recipients can be reached, for example because the users have no email address or no console app with push notifications +- you are not allowed to send to one of the selected recipients +- the email or push channel is not [configured](#before-you-start) + +If the notification was sent to some recipients but failed for others, rows with the `Error` status are added to the overview for the recipients that failed. Close the dialog to see them. + +## Examples + +The examples below show which fields to fill in for common situations. See [Sending a notification](#sending-a-notification) for a description of all fields. + +### Send an urgent push notification to specific users + +1. Click `Send new`. +2. Set **Recipient type** to `Users` and select the users. +3. Set **Type** to `Push` and enter a **Title** and **Body**. +4. Under **Actions**, set **Priority** to `High`. This makes a difference on Android devices only; iOS devices always receive push notifications with high priority. +5. Click `Create`. + +### Open a website from a push notification + +1. Click `Send new`, select the recipients, and set **Type** to `Push` with a **Title** and **Body**. +2. Under **Actions**, enter the address in **Website to be opened**, including the scheme, such as `https://`. +3. Turn on **Open in browser (for external websites)** to open the website in the browser of the device. Leave it off to open the website inside the app. +4. Click `Create`. + +Recipients open the website by tapping the notification. + +### Add buttons to a push notification + +Buttons let recipients respond directly from the notification, for example to view more details or to dismiss the message. + +1. Click `Send new`, select the recipients, and set **Type** to `Push` with a **Title** and **Body**. +2. Under **Actions**, enter the **Website to be opened**. The action button opens this website. +3. Enter the **Text for action button**, for example `View details`. +4. Enter the **Text for decline button**, for example `Dismiss`. +5. Click `Create`. + +:::tip + +Always fill in the **Text for action button** when you add a decline button. If you enter a website but only a text for the decline button, that button opens the website instead. + +::: + +### Email the users linked to an asset + +Use this, for example, to inform the users responsible for a building or a machine. First make sure these users are [linked to the asset](./10-manager-ui.md#link-assets-to-users) and have an email address. + +1. Click `Send new`. +2. Set **Recipient type** to `Users linked to assets` and check the assets in the asset tree. +3. Set **Type** to `Email` and enter a **Subject**. +4. Enter the **Body** as HTML, for example `

The heating will be serviced on Monday.

`. +5. Click `Create`. + +If an asset has an `email` attribute, the email is also sent to that address. + +### Send an announcement to all users in a realm + +Only superusers can send a notification to every user in a realm. + +1. Click `Send new`. +2. Set **Recipient type** to `All users in realms` and check one or more realms. +3. Choose the **Type** and enter the content. +4. Click `Create`. + +A push announcement reaches every console app with push notifications enabled in the selected realms. An email announcement reaches every user with an email address. Each user (for email) or device (for push) gets its own row in the overview. + +### Check whether a rule sent its notifications + +When a rule should have sent a notification but nobody received it, use the overview to find out what happened. + +1. In the realm picker, select the realm of the recipients. +2. Set **Source** to `Realm ruleset` or `Global ruleset`, depending on where the rule is defined. +3. Set **From** and **To** to the period in which the rule should have triggered. +4. Find the notification by its title and check the **Status**: + - `Sent` — the notification left the platform. If it did not arrive, check the recipient's email or the notification settings of the app. + - `Error` — hover over the status to see why sending failed. + +If there is no row at all, either the rule did not trigger, or none of its recipients could be reached, for example because they have no email address or no app with push notifications enabled. + +## Viewing notification details + +Click a row in the overview to open the notification details. The details are read-only and show: +- **Recipient** — the recipient type and the ID of the recipient +- **Content** — the type, title or subject, and body +- **Actions** — the website, button texts and priority (push notifications only) +- **Properties** — the source, status, and the moments it was sent and delivered. If you have the `read:users` role, the source also shows the ID of the sender, such as the user for `Client` or the realm for `Realm ruleset` + +The IDs of users and assets are only shown when you have the `read:users` or `read:assets` role. Push device tokens are never shown. + +## Using the API + +You can also retrieve and send notifications through the HTTP API, for example to send notifications from an external application. Notifications sent this way get the source `Client` and require the same roles as the Notifications page: + +| Operation | Endpoint | Required role | +| :-------- | :------- | :------------ | +| [Retrieve notifications](../../rest-api/get-notifications.api.mdx) | `GET /api/{realm}/notification` | `read:notifications` | +| [Count notifications](../../rest-api/get-notifications-count.api.mdx) | `GET /api/{realm}/notification/count` | `read:notifications` | +| [Send a notification](../../rest-api/send-notification.api.mdx) | `POST /api/{realm}/notification/alert` | `write:notifications` | + +The linked REST API pages describe the parameters and request bodies. For authentication, see [Manager APIs](../050-manager-apis.md). + +## See Also + +- [Manager UI — Notifications](./10-manager-ui.md#notifications) +- [When-Then rules — Supported actions](../060-rules-and-forecasting/20-when-then-rules.md#supported-actions) +- [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md) +- [On mobile](./20-on-mobile.md) +- [Working on the mobile consoles — Push Notifications / FCM setup](../../developer-guide/140-working-on-the-mobile-consoles.md#push-notifications--fcm-setup) +- [Custom deployment — Setting environment variables](../010-deploying/10-custom-deployment.md#setting-environment-variables-and-docker-volume-mappings-for-services) diff --git a/docs/user-guide/020-manager-ui/img/notifications-overview.png b/docs/user-guide/020-manager-ui/img/notifications-overview.png new file mode 100644 index 00000000..35603f3e Binary files /dev/null and b/docs/user-guide/020-manager-ui/img/notifications-overview.png differ diff --git a/versioned_docs/version-1.28.0/user-guide/020-manager-ui/10-manager-ui.md b/versioned_docs/version-1.28.0/user-guide/020-manager-ui/10-manager-ui.md index e6c90a02..2fff0f52 100644 --- a/versioned_docs/version-1.28.0/user-guide/020-manager-ui/10-manager-ui.md +++ b/versioned_docs/version-1.28.0/user-guide/020-manager-ui/10-manager-ui.md @@ -188,6 +188,18 @@ The alarms functionality (top right) allows you to automatically generate alarms ![](img/alarms-overview.png) _Figure 13. The alarms page with an overview of all alarms._ +## Notifications + +The notifications page (top right, under the dots menu) shows all email and push notifications sent within the selected realm, and lets you send new ones. These features are supported: +* Overview of sent notifications: see what was sent by rules, the platform itself, or clients using the [Manager APIs](#manager-apis), and whether it was sent or failed. +* Filtering by source and by period, ordering by column, and paging. +* Send a notification: write an email or push notification and send it to users, users linked to assets, or all users in a realm. + +Viewing notifications requires the `read:notifications` role, sending them the `write:notifications` role. See [Notifications](./50-notifications.md) for more details. + +![](img/notifications-overview.png) +_Figure 14. The notifications page with an overview of all sent notifications._ + ## Settings and access Admin users of the 'Master' realm see the Realm selector on the top right to switch between Realms. Next to that the dots give you access to a series of general settings as well as account access related settings. We will explain these here: @@ -198,17 +210,17 @@ You can link multiple instances of OpenRemote (as Gateways) to a single Central See the [Edge Gateway documentation](../080-gateways-and-devices/10-edge-gateway.md) for more details. ![](img/manager-interconnect.png) -_Figure 14. Several OpenRemote instances can be interconnected, e.g. connecting multiple instances on edge gateways to one central cloud hosted instance. The Manager Interconnect page, used at the edge instances (left) uses the keys which are created on the central instance by adding Edge gateway Assets (right)._ +_Figure 15. Several OpenRemote instances can be interconnected, e.g. connecting multiple instances on edge gateways to one central cloud hosted instance. The Manager Interconnect page, used at the edge instances (left) uses the keys which are created on the central instance by adding Edge gateway Assets (right)._ ![](img/manager-interconnect-rate-limiting.png) -_Figure 15. Next to interconnecting you can choose which asset attributes are actually linked as well as the rate at which data is exchanged._ +_Figure 16. Next to interconnecting you can choose which asset attributes are actually linked as well as the rate at which data is exchanged._ ### Gateway tunnels On top of the 'Manager Interconnect' functionality, you can remotely access the full Manager UI of the Gateway instances of OpenRemote, by creating Gateway tunnels. See the [Edge Gateway documentation](../080-gateways-and-devices/10-edge-gateway.md) for more details. ![](img/create-gateway-tunnel.png) -_Figure 16. Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ +_Figure 17. Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ ### Languages @@ -219,14 +231,14 @@ OpenRemote currently supports 9 languages: English, German, French, Spanish, Por The logs page shows information, warnings and errors of the different activities of OpenRemote. You can use it to understand the behaviour of the whole platform or debug issues, e.g. errors connecting agent with device. ![](img/logs-page.png) -_Figure 17. The Logs page to evaluate system behaviour._ +_Figure 18. The Logs page to evaluate system behaviour._ ### Account On the Account page you can (re)set you personal information or password. You can also monitor your past sessions or enable 2FA via an Authenticator (default disabled). ![](img/edit-account-change-password.png) -_Figure 18. The account page with contact details (left) and reset passwords (right)._ +_Figure 19. The account page with contact details (left) and reset passwords (right)._ ### Users and access configuration @@ -241,14 +253,14 @@ By linking assets to users, the system will understand which users are connected When, next to linking an asset to a user, you also set the Realm role to 'Restricted User', users will only have access to the assets they are linked to. Note that you additionally have to indicate on the assets which attributes of the asset they have access to. To do that, set the configuration item 'Access restricted user read/write' on the attribute ([see 'Configure attributes'](#configure-attributes)). ![](img/creating-users.png) -_Figure 19. Creating users for a selected realm, assigning roles. In this example, the user is made a 'restricted user' linked to only 6 assets._ +_Figure 20. Creating users for a selected realm, assigning roles. In this example, the user is made a 'restricted user' linked to only 6 assets._ ### Roles With the correct permissions, you can create and edit roles. These roles define which parts of the system a user is allowed to Read or Write, e.g. system settings, assets, attributes, map, or rules. Also see the userguide: [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md). ![](img/role-with-permissions.png) -_Figure 20. Roles are made of a set of permissions_ +_Figure 21. Roles are made of a set of permissions_ ### Realms @@ -257,16 +269,16 @@ Only the Master realm Admin user can create `Realms` by accessing the master rea You can create a realm by adding a `realmname` name (single word, lower case letters), and a `Friendly name`. You can (temporarily) disable realms, which blocks access for any user. ![](img/realms.png) -_Figure 21. Realms can be created to manage multiple independent projects within one OpenRemote instance_ +_Figure 22. Realms can be created to manage multiple independent projects within one OpenRemote instance_ Also see the userguide: [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md). ### Auto provisioning of devices -If you are an OEM, developing and producing your own hardware, you can provision your devices and OpenRemote to automatically have your devices connecting, once they get online. Using certificates (we currently support X.509) your devices will register and automatically generate and connect to an asset of a defined type in the OpenRemote Manager (see figure 22). For details, check out the documentation about ['Auto provisioning'](../080-gateways-and-devices/20-auto-provisioning.md). +If you are an OEM, developing and producing your own hardware, you can provision your devices and OpenRemote to automatically have your devices connecting, once they get online. Using certificates (we currently support X.509) your devices will register and automatically generate and connect to an asset of a defined type in the OpenRemote Manager (see figure 23). For details, check out the documentation about ['Auto provisioning'](../080-gateways-and-devices/20-auto-provisioning.md). ![](img/auto-provisioning-of-devices.png) -_Figure 22. Auto provisioning of devices_ +_Figure 23. Auto provisioning of devices_ ### Appearance @@ -277,7 +289,7 @@ You can change the logo's, use different colours, change the title and default l For adding map layers you can add GeoJSON files (created e.g. with https://geojson.io/). More advanced settings like visible asset and agent types on the asset and rules page, can be configured directly in a JSON file. For the options available in the JSON file and an example, check out [Configuring the Manager UI](../010-deploying/20-configuring-the-manager-ui.md). For the maps you can set the center point, zoom levels and boundaries. ![](img/appearance-settings.png) -_Figure 23. Appearance settings allow white labeling of your OpenRemote manager_ +_Figure 24. Appearance settings allow white labeling of your OpenRemote manager_ ## Manager APIs @@ -285,10 +297,10 @@ The Manager APIs let you interact with OpenRemote without using the UI. This can ### Service users -Service users can be created on the `Users` page, and selecting `Add user` in the `Service user` panel (see figure 24). The `Username` (ClientID) can be set using letters, dashes, and numbers, while the `Secret` will be generated automatically once saved. Note that you also need to select the role(s). +Service users can be created on the `Users` page, and selecting `Add user` in the `Service user` panel (see figure 25). The `Username` (ClientID) can be set using letters, dashes, and numbers, while the `Secret` will be generated automatically once saved. Note that you also need to select the role(s). ![](img/creating-service-users.png) -_Figure 24. Creating service users, with Username, Secret and Roles for a selected Realm_ +_Figure 25. Creating service users, with Username, Secret and Roles for a selected Realm_ ### HTTP, MQTT, and WebSocket diff --git a/versioned_docs/version-1.28.0/user-guide/020-manager-ui/50-notifications.md b/versioned_docs/version-1.28.0/user-guide/020-manager-ui/50-notifications.md new file mode 100644 index 00000000..cb9b2464 --- /dev/null +++ b/versioned_docs/version-1.28.0/user-guide/020-manager-ui/50-notifications.md @@ -0,0 +1,259 @@ +# Notifications + +The Notifications page gives you an overview of all email and push notifications sent within a realm, and lets you send new ones directly from the Manager UI. You can find it in the settings menu (the dots on the top right) under `Notifications`. The page shows the notifications of the realm that is currently selected in the realm picker. + +The Notifications page provides three capabilities: +- **Overview** — browse, filter and sort all notifications that were sent, whether they came from rules, the platform itself, or an API client +- **Send** — write an email or push notification and send it to users, users linked to assets, or all users in a realm +- **Details** — look at the full content, recipient and delivery status of a single notification + +![](img/notifications-overview.png) +_Figure 1. The Notifications page with an overview of all sent notifications._ + +## Before you start + +Notifications are only delivered when the matching channel is configured for your deployment: + +| Channel | Requirements | +| :------ | :----------- | +| **Email** | An SMTP server, configured using the `OR_EMAIL_HOST`, `OR_EMAIL_USER`, `OR_EMAIL_PASSWORD` and `OR_EMAIL_FROM` environment variables. See [setting environment variables](../010-deploying/10-custom-deployment.md#setting-environment-variables-and-docker-volume-mappings-for-services). Recipients need an email address. | +| **Push** | A Firebase Cloud Messaging configuration file, set using the `OR_FIREBASE_CONFIG_FILE` environment variable. See [Push Notifications / FCM setup](../../developer-guide/140-working-on-the-mobile-consoles.md#push-notifications--fcm-setup). Recipients need the [OpenRemote app](./20-on-mobile.md) (or your own console app) with push notifications enabled. | + +:::note + +If a channel is not configured, sending a notification of that type fails and nothing is added to the overview. When you run the manager in dev mode without this configuration, notifications are recorded in the overview and written to the log instead of being sent. + +::: + +### Required roles + +Access to the page is controlled by two roles, which you can assign on the [Roles](./10-manager-ui.md#roles) page: + +| Role | Description | +| :--- | :---------- | +| `read:notifications` | View the Notifications page and the notifications sent within the realm | +| `write:notifications` | Send notifications, using the `Send new` button or the [API](#using-the-api) | + +The admin roles don't give access to this page: users with `read:admin` or `write:admin` still need the notification roles above. Some parts of the page need additional roles: +- **Recipients** — to select users you need `read:users`, and to select assets you need `read:assets`; `read:admin` works for both. Without these roles, the recipients of users or assets are shown as `-` in the overview. The `Send new` button only appears if you have `write:notifications`, and is disabled if you can't select any recipients. +- **All users in a realm** — only superusers can send a notification to every user in a realm. +- **Restricted users** — a [restricted user](../070-identity-and-security/10-realms-users-and-roles.md#restricted-user-realm-role) only sees notifications they sent themselves, notifications sent to them, and notifications sent to their whole realm. They can only send notifications to users linked to the assets they are linked to. + +:::warning + +When you upgrade an existing installation, `read:notifications` and `write:notifications` are automatically added to the default `read` and `write` roles in every realm. Custom roles that you created yourself do not get them, so add the roles there if needed. + +Sending a notification through the API now requires the `write:notifications` role as well. Give this role to any [service user](./10-manager-ui.md#service-users) that sends notifications. + +::: + +## Viewing sent notifications + +The overview shows one row per recipient that was reached: a user or asset for an email, or a device with the app for a push notification. A user with two phones gets two rows for one push notification, and recipients that can't be reached get no row. By default, you see the notifications sent today, with the newest first. + +| Column | Description | +| :----- | :---------- | +| **Title** | The title of a push notification or the subject of an email. The icon in front shows whether it was a push notification or an email | +| **Body** | The message of the notification. For emails this is the HTML that was sent | +| **Status** | Whether the notification was sent or failed. See [Status](#status) | +| **Source** | What sent the notification. See [Source](#source) | +| **Recipient** | The user, asset or realm that received the notification. Users and assets link to their page in the Manager UI | +| **Sent on** | The moment the notification was sent | +| **Delivered on** | The moment a console app confirmed that it received the notification (push notifications only) | + +:::note + +Delivery confirmation does not work at the moment. The `Delivered on` column stays empty, and push notifications keep the `Sent` status, even when they arrived on the device. + +::: + +Click a column header to sort by that column; click again to reverse the order. You can sort by Title, Status, Source, Sent on and Delivered on. Sorting is applied to all notifications, not just the current page. Use the controls at the bottom of the table to change the number of rows per page and to move between pages. + +### Status + +| Status | Description | +| :----- | :---------- | +| `Sent` | The notification left the platform: it was accepted by the email server or by Firebase | +| `Delivered` | A console app confirmed that it received the push notification. Emails never get this status. Not set at the moment, see the note above | +| `Error` | Sending failed. Hover over the status to see the reason | + +### Source + +| Source | Description | +| :----- | :---------- | +| **Internal** | Sent by the platform itself, for example by a service or by custom code running in the manager | +| **Client** | Sent through the [API](#using-the-api) by a user or service user. Notifications you send with `Send new` also get this source | +| **Global ruleset** | Sent by a global rule, such as a [When-Then rule](../060-rules-and-forecasting/20-when-then-rules.md#supported-actions) or [Groovy rule](../060-rules-and-forecasting/40-groovy-rules.md) | +| **Realm ruleset** | Sent by a rule in the realm | + + + +### Filtering notifications + +Use the controls at the top of the page to narrow down the overview: + +| Filter | Description | +| :----- | :---------- | +| **Source** | Only show notifications from one source. The default is `All sources` | +| **From** / **To** | Only show notifications sent within this period. The default is today, from 00:00 to 23:59 | + +To see the notifications of another realm, select that realm in the realm picker. A notification is listed in the realm of its recipient, so a notification sent from the master realm to a user in another realm shows up in that other realm. If the recipient's realm cannot be determined, the notification is listed in the realm of the sender. For global rules and internal notifications, that is the master realm. + +## Sending a notification + +To send a notification, you need the `write:notifications` role. + +1. Click `Send new` on the top right of the page. +2. Select the recipients: choose a **Recipient type** and select one or more recipients. +3. Choose the **Type** of notification, `Push` or `Email`, and enter its content. +4. For push notifications, optionally configure the **Actions**. +5. Click `Create`. + +The `Create` button is only enabled when you have selected at least one recipient, filled in the title or subject and the body, and entered a valid website URL (if you entered one). After the notification is sent, the overview reloads and shows the new notification with the source `Client`. + +### Recipients + +| Recipient type | Who receives the notification | Availability | +| :------------- | :---------------------------- | :----------- | +| **Users** | The selected users of the current realm | Requires `read:users`. Not available for restricted users | +| **Users linked to assets** | The users linked to the assets you select in the asset tree | Requires `read:assets`. Restricted users can only select assets they are linked to | +| **All users in realms** | Every user in the selected realms | Superusers only | + +How recipients are reached depends on the type of notification: +- **Email** — sent to the email address of each user. For `Users linked to assets`, the email is also sent to the address in the `email` attribute of the asset, if it has one. +- **Push** — sent to the console apps (for example the OpenRemote app on a phone) that are registered by the users. For push notifications the recipient in the overview is therefore the console asset, one row per device. + +Service users, users without an email address (for email), users without a registered console app (for push), and users who turned off that type of notification never receive it. + +### Content + +| Field | Description | +| :---- | :---------- | +| **Type** | `Push` for a notification on a mobile device, or `Email` | +| **Title** / **Subject** | The title of the push notification or the subject of the email. Required | +| **Body** | The message. Required. Emails are sent as HTML, so use tags such as `

`, `
` or `` for formatting; line breaks are not kept otherwise | + +### Actions + +Push notifications can include an action and buttons. All fields are optional. + +| Field | Description | +| :---- | :---------- | +| **Website to be opened** | The URL opened when the recipient taps the notification. The URL must include a scheme, such as `https://example.com` | +| **Open in browser (for external websites)** | Opens the website in the browser of the device instead of inside the app | +| **Text for action button** | Adds a button with this text. The button opens the website | +| **Text for decline button** | Adds a button with this text that dismisses the notification | +| **Priority** | `Normal` or `High`. Only applies to Android devices, where high priority notifications are delivered immediately, even when the device is idle. iOS devices always receive push notifications with high priority | + +### When sending fails + +If sending fails, you will see the message `Failed to send notification.` This happens when: +- none of the selected recipients can be reached, for example because the users have no email address or no console app with push notifications +- you are not allowed to send to one of the selected recipients +- the email or push channel is not [configured](#before-you-start) + +If the notification was sent to some recipients but failed for others, rows with the `Error` status are added to the overview for the recipients that failed. Close the dialog to see them. + +## Examples + +The examples below show which fields to fill in for common situations. See [Sending a notification](#sending-a-notification) for a description of all fields. + +### Send an urgent push notification to specific users + +1. Click `Send new`. +2. Set **Recipient type** to `Users` and select the users. +3. Set **Type** to `Push` and enter a **Title** and **Body**. +4. Under **Actions**, set **Priority** to `High`. This makes a difference on Android devices only; iOS devices always receive push notifications with high priority. +5. Click `Create`. + +### Open a website from a push notification + +1. Click `Send new`, select the recipients, and set **Type** to `Push` with a **Title** and **Body**. +2. Under **Actions**, enter the address in **Website to be opened**, including the scheme, such as `https://`. +3. Turn on **Open in browser (for external websites)** to open the website in the browser of the device. Leave it off to open the website inside the app. +4. Click `Create`. + +Recipients open the website by tapping the notification. + +### Add buttons to a push notification + +Buttons let recipients respond directly from the notification, for example to view more details or to dismiss the message. + +1. Click `Send new`, select the recipients, and set **Type** to `Push` with a **Title** and **Body**. +2. Under **Actions**, enter the **Website to be opened**. The action button opens this website. +3. Enter the **Text for action button**, for example `View details`. +4. Enter the **Text for decline button**, for example `Dismiss`. +5. Click `Create`. + +:::tip + +Always fill in the **Text for action button** when you add a decline button. If you enter a website but only a text for the decline button, that button opens the website instead. + +::: + +### Email the users linked to an asset + +Use this, for example, to inform the users responsible for a building or a machine. First make sure these users are [linked to the asset](./10-manager-ui.md#link-assets-to-users) and have an email address. + +1. Click `Send new`. +2. Set **Recipient type** to `Users linked to assets` and check the assets in the asset tree. +3. Set **Type** to `Email` and enter a **Subject**. +4. Enter the **Body** as HTML, for example `

The heating will be serviced on Monday.

`. +5. Click `Create`. + +If an asset has an `email` attribute, the email is also sent to that address. + +### Send an announcement to all users in a realm + +Only superusers can send a notification to every user in a realm. + +1. Click `Send new`. +2. Set **Recipient type** to `All users in realms` and check one or more realms. +3. Choose the **Type** and enter the content. +4. Click `Create`. + +A push announcement reaches every console app with push notifications enabled in the selected realms. An email announcement reaches every user with an email address. Each user (for email) or device (for push) gets its own row in the overview. + +### Check whether a rule sent its notifications + +When a rule should have sent a notification but nobody received it, use the overview to find out what happened. + +1. In the realm picker, select the realm of the recipients. +2. Set **Source** to `Realm ruleset` or `Global ruleset`, depending on where the rule is defined. +3. Set **From** and **To** to the period in which the rule should have triggered. +4. Find the notification by its title and check the **Status**: + - `Sent` — the notification left the platform. If it did not arrive, check the recipient's email or the notification settings of the app. + - `Error` — hover over the status to see why sending failed. + +If there is no row at all, either the rule did not trigger, or none of its recipients could be reached, for example because they have no email address or no app with push notifications enabled. + +## Viewing notification details + +Click a row in the overview to open the notification details. The details are read-only and show: +- **Recipient** — the recipient type and the ID of the recipient +- **Content** — the type, title or subject, and body +- **Actions** — the website, button texts and priority (push notifications only) +- **Properties** — the source, status, and the moments it was sent and delivered. If you have the `read:users` role, the source also shows the ID of the sender, such as the user for `Client` or the realm for `Realm ruleset` + +The IDs of users and assets are only shown when you have the `read:users` or `read:assets` role. Push device tokens are never shown. + +## Using the API + +You can also retrieve and send notifications through the HTTP API, for example to send notifications from an external application. Notifications sent this way get the source `Client` and require the same roles as the Notifications page: + +| Operation | Endpoint | Required role | +| :-------- | :------- | :------------ | +| [Retrieve notifications](../../rest-api/get-notifications.api.mdx) | `GET /api/{realm}/notification` | `read:notifications` | +| [Count notifications](../../rest-api/get-notifications-count.api.mdx) | `GET /api/{realm}/notification/count` | `read:notifications` | +| [Send a notification](../../rest-api/send-notification.api.mdx) | `POST /api/{realm}/notification/alert` | `write:notifications` | + +The linked REST API pages describe the parameters and request bodies. For authentication, see [Manager APIs](../050-manager-apis.md). + +## See Also + +- [Manager UI — Notifications](./10-manager-ui.md#notifications) +- [When-Then rules — Supported actions](../060-rules-and-forecasting/20-when-then-rules.md#supported-actions) +- [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md) +- [On mobile](./20-on-mobile.md) +- [Working on the mobile consoles — Push Notifications / FCM setup](../../developer-guide/140-working-on-the-mobile-consoles.md#push-notifications--fcm-setup) +- [Custom deployment — Setting environment variables](../010-deploying/10-custom-deployment.md#setting-environment-variables-and-docker-volume-mappings-for-services) diff --git a/versioned_docs/version-1.28.0/user-guide/020-manager-ui/img/notifications-overview.png b/versioned_docs/version-1.28.0/user-guide/020-manager-ui/img/notifications-overview.png new file mode 100644 index 00000000..35603f3e Binary files /dev/null and b/versioned_docs/version-1.28.0/user-guide/020-manager-ui/img/notifications-overview.png differ diff --git a/versioned_docs/version-1.29.0/user-guide/020-manager-ui/10-manager-ui.md b/versioned_docs/version-1.29.0/user-guide/020-manager-ui/10-manager-ui.md index e95f7f63..c174c4ac 100644 --- a/versioned_docs/version-1.29.0/user-guide/020-manager-ui/10-manager-ui.md +++ b/versioned_docs/version-1.29.0/user-guide/020-manager-ui/10-manager-ui.md @@ -188,6 +188,18 @@ The alarms functionality (top right) allows you to automatically generate alarms ![](img/alarms-overview.png) _Figure 13. The alarms page with an overview of all alarms._ +## Notifications + +The notifications page (top right, under the dots menu) shows all email and push notifications sent within the selected realm, and lets you send new ones. These features are supported: +* Overview of sent notifications: see what was sent by rules, the platform itself, or clients using the [Manager APIs](#manager-apis), and whether it was sent or failed. +* Filtering by source and by period, ordering by column, and paging. +* Send a notification: write an email or push notification and send it to users, users linked to assets, or all users in a realm. + +Viewing notifications requires the `read:notifications` role, sending them the `write:notifications` role. See [Notifications](./50-notifications.md) for more details. + +![](img/notifications-overview.png) +_Figure 14. The notifications page with an overview of all sent notifications._ + ## Settings and access Admin users of the 'Master' realm see the Realm selector on the top right to switch between Realms. Next to that the dots give you access to a series of general settings as well as account access related settings. We will explain these here: @@ -198,17 +210,17 @@ You can link multiple instances of OpenRemote (as Gateways) to a single Central See the [Edge Gateway documentation](../080-gateways-and-devices/10-edge-gateway.md) for more details. ![](img/manager-interconnect.png) -_Figure 14. Several OpenRemote instances can be interconnected, e.g. connecting multiple instances on edge gateways to one central cloud hosted instance. The Manager Interconnect page, used at the edge instances (left) uses the keys which are created on the central instance by adding Edge gateway Assets (right)._ +_Figure 15. Several OpenRemote instances can be interconnected, e.g. connecting multiple instances on edge gateways to one central cloud hosted instance. The Manager Interconnect page, used at the edge instances (left) uses the keys which are created on the central instance by adding Edge gateway Assets (right)._ ![](img/manager-interconnect-rate-limiting.png) -_Figure 15. Next to interconnecting you can choose which asset attributes are actually linked as well as the rate at which data is exchanged._ +_Figure 16. Next to interconnecting you can choose which asset attributes are actually linked as well as the rate at which data is exchanged._ ### Gateway tunnels On top of the 'Manager Interconnect' functionality, you can remotely access the full Manager UI of the Gateway instances of OpenRemote, by creating Gateway tunnels. See the [Edge Gateway documentation](../080-gateways-and-devices/10-edge-gateway.md) for more details. ![](img/create-gateway-tunnel.png) -_Figure 16. Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ +_Figure 17. Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ ### Languages @@ -219,14 +231,14 @@ OpenRemote currently supports 9 languages: English, German, French, Spanish, Por The logs page shows information, warnings and errors of the different activities of OpenRemote. You can use it to understand the behaviour of the whole platform or debug issues, e.g. errors connecting agent with device. ![](img/logs-page.png) -_Figure 17. The Logs page to evaluate system behaviour._ +_Figure 18. The Logs page to evaluate system behaviour._ ### Account On the Account page you can (re)set you personal information or password. You can also monitor your past sessions or enable 2FA via an Authenticator (default disabled). ![](img/edit-account-change-password.png) -_Figure 18. The account page with contact details (left) and reset passwords (right)._ +_Figure 19. The account page with contact details (left) and reset passwords (right)._ ### Users and access configuration @@ -241,14 +253,14 @@ By linking assets to users, the system will understand which users are connected When, next to linking an asset to a user, you also set the Realm role to 'Restricted User', users will only have access to the assets they are linked to. Note that you additionally have to indicate on the assets which attributes of the asset they have access to. To do that, set the configuration item 'Access restricted user read/write' on the attribute ([see 'Configure attributes'](#configure-attributes)). ![](img/creating-users.png) -_Figure 19. Creating users for a selected realm, assigning roles. In this example, the user is made a 'restricted user' linked to only 6 assets._ +_Figure 20. Creating users for a selected realm, assigning roles. In this example, the user is made a 'restricted user' linked to only 6 assets._ ### Roles With the correct permissions, you can create and edit roles. These roles define which parts of the system a user is allowed to Read or Write, e.g. system settings, assets, attributes, map, or rules. Also see the userguide: [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md). ![](img/role-with-permissions.png) -_Figure 20. Roles are made of a set of permissions_ +_Figure 21. Roles are made of a set of permissions_ ### Realms @@ -257,16 +269,16 @@ Only the Master realm Admin user can create `Realms` by accessing the master rea You can create a realm by adding a `realmname` name (single word, lower case letters), and a `Friendly name`. You can (temporarily) disable realms, which blocks access for any user. ![](img/realms.png) -_Figure 21. Realms can be created to manage multiple independent projects within one OpenRemote instance_ +_Figure 22. Realms can be created to manage multiple independent projects within one OpenRemote instance_ Also see the userguide: [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md). ### Auto provisioning of devices -If you are an OEM, developing and producing your own hardware, you can provision your devices and OpenRemote to automatically have your devices connecting, once they get online. Using certificates (we currently support X.509) your devices will register and automatically generate and connect to an asset of a defined type in the OpenRemote Manager (see figure 22). For details, check out the documentation about ['Auto provisioning'](../080-gateways-and-devices/20-auto-provisioning.md). +If you are an OEM, developing and producing your own hardware, you can provision your devices and OpenRemote to automatically have your devices connecting, once they get online. Using certificates (we currently support X.509) your devices will register and automatically generate and connect to an asset of a defined type in the OpenRemote Manager (see figure 23). For details, check out the documentation about ['Auto provisioning'](../080-gateways-and-devices/20-auto-provisioning.md). ![](img/auto-provisioning-of-devices.png) -_Figure 22. Auto provisioning of devices_ +_Figure 23. Auto provisioning of devices_ ### Appearance @@ -277,7 +289,7 @@ You can change the logo's, use different colours, change the title and default l For adding map layers you can add GeoJSON files (created e.g. with https://geojson.io/). More advanced settings like visible asset and agent types on the asset and rules page, can be configured directly in a JSON file. For the options available in the JSON file and an example, check out [Configuring the Manager UI](../010-deploying/20-configuring-the-manager-ui.md). For the maps you can set the center point, zoom levels and boundaries. ![](img/appearance-settings.png) -_Figure 23. Appearance settings allow white labeling of your OpenRemote manager_ +_Figure 24. Appearance settings allow white labeling of your OpenRemote manager_ ## Manager APIs @@ -285,10 +297,10 @@ The Manager APIs let you interact with OpenRemote without using the UI. This can ### Service users -Service users can be created on the `Users` page, and selecting `Add user` in the `Service user` panel (see figure 24). The `Username` (ClientID) can be set using letters, dashes, and numbers, while the `Secret` will be generated automatically once saved. Note that you also need to select the role(s). +Service users can be created on the `Users` page, and selecting `Add user` in the `Service user` panel (see figure 25). The `Username` (ClientID) can be set using letters, dashes, and numbers, while the `Secret` will be generated automatically once saved. Note that you also need to select the role(s). ![](img/creating-service-users.png) -_Figure 24. Creating service users, with Username, Secret and Roles for a selected Realm_ +_Figure 25. Creating service users, with Username, Secret and Roles for a selected Realm_ ### HTTP, MQTT, and WebSocket diff --git a/versioned_docs/version-1.29.0/user-guide/020-manager-ui/50-notifications.md b/versioned_docs/version-1.29.0/user-guide/020-manager-ui/50-notifications.md new file mode 100644 index 00000000..cb9b2464 --- /dev/null +++ b/versioned_docs/version-1.29.0/user-guide/020-manager-ui/50-notifications.md @@ -0,0 +1,259 @@ +# Notifications + +The Notifications page gives you an overview of all email and push notifications sent within a realm, and lets you send new ones directly from the Manager UI. You can find it in the settings menu (the dots on the top right) under `Notifications`. The page shows the notifications of the realm that is currently selected in the realm picker. + +The Notifications page provides three capabilities: +- **Overview** — browse, filter and sort all notifications that were sent, whether they came from rules, the platform itself, or an API client +- **Send** — write an email or push notification and send it to users, users linked to assets, or all users in a realm +- **Details** — look at the full content, recipient and delivery status of a single notification + +![](img/notifications-overview.png) +_Figure 1. The Notifications page with an overview of all sent notifications._ + +## Before you start + +Notifications are only delivered when the matching channel is configured for your deployment: + +| Channel | Requirements | +| :------ | :----------- | +| **Email** | An SMTP server, configured using the `OR_EMAIL_HOST`, `OR_EMAIL_USER`, `OR_EMAIL_PASSWORD` and `OR_EMAIL_FROM` environment variables. See [setting environment variables](../010-deploying/10-custom-deployment.md#setting-environment-variables-and-docker-volume-mappings-for-services). Recipients need an email address. | +| **Push** | A Firebase Cloud Messaging configuration file, set using the `OR_FIREBASE_CONFIG_FILE` environment variable. See [Push Notifications / FCM setup](../../developer-guide/140-working-on-the-mobile-consoles.md#push-notifications--fcm-setup). Recipients need the [OpenRemote app](./20-on-mobile.md) (or your own console app) with push notifications enabled. | + +:::note + +If a channel is not configured, sending a notification of that type fails and nothing is added to the overview. When you run the manager in dev mode without this configuration, notifications are recorded in the overview and written to the log instead of being sent. + +::: + +### Required roles + +Access to the page is controlled by two roles, which you can assign on the [Roles](./10-manager-ui.md#roles) page: + +| Role | Description | +| :--- | :---------- | +| `read:notifications` | View the Notifications page and the notifications sent within the realm | +| `write:notifications` | Send notifications, using the `Send new` button or the [API](#using-the-api) | + +The admin roles don't give access to this page: users with `read:admin` or `write:admin` still need the notification roles above. Some parts of the page need additional roles: +- **Recipients** — to select users you need `read:users`, and to select assets you need `read:assets`; `read:admin` works for both. Without these roles, the recipients of users or assets are shown as `-` in the overview. The `Send new` button only appears if you have `write:notifications`, and is disabled if you can't select any recipients. +- **All users in a realm** — only superusers can send a notification to every user in a realm. +- **Restricted users** — a [restricted user](../070-identity-and-security/10-realms-users-and-roles.md#restricted-user-realm-role) only sees notifications they sent themselves, notifications sent to them, and notifications sent to their whole realm. They can only send notifications to users linked to the assets they are linked to. + +:::warning + +When you upgrade an existing installation, `read:notifications` and `write:notifications` are automatically added to the default `read` and `write` roles in every realm. Custom roles that you created yourself do not get them, so add the roles there if needed. + +Sending a notification through the API now requires the `write:notifications` role as well. Give this role to any [service user](./10-manager-ui.md#service-users) that sends notifications. + +::: + +## Viewing sent notifications + +The overview shows one row per recipient that was reached: a user or asset for an email, or a device with the app for a push notification. A user with two phones gets two rows for one push notification, and recipients that can't be reached get no row. By default, you see the notifications sent today, with the newest first. + +| Column | Description | +| :----- | :---------- | +| **Title** | The title of a push notification or the subject of an email. The icon in front shows whether it was a push notification or an email | +| **Body** | The message of the notification. For emails this is the HTML that was sent | +| **Status** | Whether the notification was sent or failed. See [Status](#status) | +| **Source** | What sent the notification. See [Source](#source) | +| **Recipient** | The user, asset or realm that received the notification. Users and assets link to their page in the Manager UI | +| **Sent on** | The moment the notification was sent | +| **Delivered on** | The moment a console app confirmed that it received the notification (push notifications only) | + +:::note + +Delivery confirmation does not work at the moment. The `Delivered on` column stays empty, and push notifications keep the `Sent` status, even when they arrived on the device. + +::: + +Click a column header to sort by that column; click again to reverse the order. You can sort by Title, Status, Source, Sent on and Delivered on. Sorting is applied to all notifications, not just the current page. Use the controls at the bottom of the table to change the number of rows per page and to move between pages. + +### Status + +| Status | Description | +| :----- | :---------- | +| `Sent` | The notification left the platform: it was accepted by the email server or by Firebase | +| `Delivered` | A console app confirmed that it received the push notification. Emails never get this status. Not set at the moment, see the note above | +| `Error` | Sending failed. Hover over the status to see the reason | + +### Source + +| Source | Description | +| :----- | :---------- | +| **Internal** | Sent by the platform itself, for example by a service or by custom code running in the manager | +| **Client** | Sent through the [API](#using-the-api) by a user or service user. Notifications you send with `Send new` also get this source | +| **Global ruleset** | Sent by a global rule, such as a [When-Then rule](../060-rules-and-forecasting/20-when-then-rules.md#supported-actions) or [Groovy rule](../060-rules-and-forecasting/40-groovy-rules.md) | +| **Realm ruleset** | Sent by a rule in the realm | + + + +### Filtering notifications + +Use the controls at the top of the page to narrow down the overview: + +| Filter | Description | +| :----- | :---------- | +| **Source** | Only show notifications from one source. The default is `All sources` | +| **From** / **To** | Only show notifications sent within this period. The default is today, from 00:00 to 23:59 | + +To see the notifications of another realm, select that realm in the realm picker. A notification is listed in the realm of its recipient, so a notification sent from the master realm to a user in another realm shows up in that other realm. If the recipient's realm cannot be determined, the notification is listed in the realm of the sender. For global rules and internal notifications, that is the master realm. + +## Sending a notification + +To send a notification, you need the `write:notifications` role. + +1. Click `Send new` on the top right of the page. +2. Select the recipients: choose a **Recipient type** and select one or more recipients. +3. Choose the **Type** of notification, `Push` or `Email`, and enter its content. +4. For push notifications, optionally configure the **Actions**. +5. Click `Create`. + +The `Create` button is only enabled when you have selected at least one recipient, filled in the title or subject and the body, and entered a valid website URL (if you entered one). After the notification is sent, the overview reloads and shows the new notification with the source `Client`. + +### Recipients + +| Recipient type | Who receives the notification | Availability | +| :------------- | :---------------------------- | :----------- | +| **Users** | The selected users of the current realm | Requires `read:users`. Not available for restricted users | +| **Users linked to assets** | The users linked to the assets you select in the asset tree | Requires `read:assets`. Restricted users can only select assets they are linked to | +| **All users in realms** | Every user in the selected realms | Superusers only | + +How recipients are reached depends on the type of notification: +- **Email** — sent to the email address of each user. For `Users linked to assets`, the email is also sent to the address in the `email` attribute of the asset, if it has one. +- **Push** — sent to the console apps (for example the OpenRemote app on a phone) that are registered by the users. For push notifications the recipient in the overview is therefore the console asset, one row per device. + +Service users, users without an email address (for email), users without a registered console app (for push), and users who turned off that type of notification never receive it. + +### Content + +| Field | Description | +| :---- | :---------- | +| **Type** | `Push` for a notification on a mobile device, or `Email` | +| **Title** / **Subject** | The title of the push notification or the subject of the email. Required | +| **Body** | The message. Required. Emails are sent as HTML, so use tags such as `

`, `
` or `` for formatting; line breaks are not kept otherwise | + +### Actions + +Push notifications can include an action and buttons. All fields are optional. + +| Field | Description | +| :---- | :---------- | +| **Website to be opened** | The URL opened when the recipient taps the notification. The URL must include a scheme, such as `https://example.com` | +| **Open in browser (for external websites)** | Opens the website in the browser of the device instead of inside the app | +| **Text for action button** | Adds a button with this text. The button opens the website | +| **Text for decline button** | Adds a button with this text that dismisses the notification | +| **Priority** | `Normal` or `High`. Only applies to Android devices, where high priority notifications are delivered immediately, even when the device is idle. iOS devices always receive push notifications with high priority | + +### When sending fails + +If sending fails, you will see the message `Failed to send notification.` This happens when: +- none of the selected recipients can be reached, for example because the users have no email address or no console app with push notifications +- you are not allowed to send to one of the selected recipients +- the email or push channel is not [configured](#before-you-start) + +If the notification was sent to some recipients but failed for others, rows with the `Error` status are added to the overview for the recipients that failed. Close the dialog to see them. + +## Examples + +The examples below show which fields to fill in for common situations. See [Sending a notification](#sending-a-notification) for a description of all fields. + +### Send an urgent push notification to specific users + +1. Click `Send new`. +2. Set **Recipient type** to `Users` and select the users. +3. Set **Type** to `Push` and enter a **Title** and **Body**. +4. Under **Actions**, set **Priority** to `High`. This makes a difference on Android devices only; iOS devices always receive push notifications with high priority. +5. Click `Create`. + +### Open a website from a push notification + +1. Click `Send new`, select the recipients, and set **Type** to `Push` with a **Title** and **Body**. +2. Under **Actions**, enter the address in **Website to be opened**, including the scheme, such as `https://`. +3. Turn on **Open in browser (for external websites)** to open the website in the browser of the device. Leave it off to open the website inside the app. +4. Click `Create`. + +Recipients open the website by tapping the notification. + +### Add buttons to a push notification + +Buttons let recipients respond directly from the notification, for example to view more details or to dismiss the message. + +1. Click `Send new`, select the recipients, and set **Type** to `Push` with a **Title** and **Body**. +2. Under **Actions**, enter the **Website to be opened**. The action button opens this website. +3. Enter the **Text for action button**, for example `View details`. +4. Enter the **Text for decline button**, for example `Dismiss`. +5. Click `Create`. + +:::tip + +Always fill in the **Text for action button** when you add a decline button. If you enter a website but only a text for the decline button, that button opens the website instead. + +::: + +### Email the users linked to an asset + +Use this, for example, to inform the users responsible for a building or a machine. First make sure these users are [linked to the asset](./10-manager-ui.md#link-assets-to-users) and have an email address. + +1. Click `Send new`. +2. Set **Recipient type** to `Users linked to assets` and check the assets in the asset tree. +3. Set **Type** to `Email` and enter a **Subject**. +4. Enter the **Body** as HTML, for example `

The heating will be serviced on Monday.

`. +5. Click `Create`. + +If an asset has an `email` attribute, the email is also sent to that address. + +### Send an announcement to all users in a realm + +Only superusers can send a notification to every user in a realm. + +1. Click `Send new`. +2. Set **Recipient type** to `All users in realms` and check one or more realms. +3. Choose the **Type** and enter the content. +4. Click `Create`. + +A push announcement reaches every console app with push notifications enabled in the selected realms. An email announcement reaches every user with an email address. Each user (for email) or device (for push) gets its own row in the overview. + +### Check whether a rule sent its notifications + +When a rule should have sent a notification but nobody received it, use the overview to find out what happened. + +1. In the realm picker, select the realm of the recipients. +2. Set **Source** to `Realm ruleset` or `Global ruleset`, depending on where the rule is defined. +3. Set **From** and **To** to the period in which the rule should have triggered. +4. Find the notification by its title and check the **Status**: + - `Sent` — the notification left the platform. If it did not arrive, check the recipient's email or the notification settings of the app. + - `Error` — hover over the status to see why sending failed. + +If there is no row at all, either the rule did not trigger, or none of its recipients could be reached, for example because they have no email address or no app with push notifications enabled. + +## Viewing notification details + +Click a row in the overview to open the notification details. The details are read-only and show: +- **Recipient** — the recipient type and the ID of the recipient +- **Content** — the type, title or subject, and body +- **Actions** — the website, button texts and priority (push notifications only) +- **Properties** — the source, status, and the moments it was sent and delivered. If you have the `read:users` role, the source also shows the ID of the sender, such as the user for `Client` or the realm for `Realm ruleset` + +The IDs of users and assets are only shown when you have the `read:users` or `read:assets` role. Push device tokens are never shown. + +## Using the API + +You can also retrieve and send notifications through the HTTP API, for example to send notifications from an external application. Notifications sent this way get the source `Client` and require the same roles as the Notifications page: + +| Operation | Endpoint | Required role | +| :-------- | :------- | :------------ | +| [Retrieve notifications](../../rest-api/get-notifications.api.mdx) | `GET /api/{realm}/notification` | `read:notifications` | +| [Count notifications](../../rest-api/get-notifications-count.api.mdx) | `GET /api/{realm}/notification/count` | `read:notifications` | +| [Send a notification](../../rest-api/send-notification.api.mdx) | `POST /api/{realm}/notification/alert` | `write:notifications` | + +The linked REST API pages describe the parameters and request bodies. For authentication, see [Manager APIs](../050-manager-apis.md). + +## See Also + +- [Manager UI — Notifications](./10-manager-ui.md#notifications) +- [When-Then rules — Supported actions](../060-rules-and-forecasting/20-when-then-rules.md#supported-actions) +- [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md) +- [On mobile](./20-on-mobile.md) +- [Working on the mobile consoles — Push Notifications / FCM setup](../../developer-guide/140-working-on-the-mobile-consoles.md#push-notifications--fcm-setup) +- [Custom deployment — Setting environment variables](../010-deploying/10-custom-deployment.md#setting-environment-variables-and-docker-volume-mappings-for-services) diff --git a/versioned_docs/version-1.29.0/user-guide/020-manager-ui/img/notifications-overview.png b/versioned_docs/version-1.29.0/user-guide/020-manager-ui/img/notifications-overview.png new file mode 100644 index 00000000..35603f3e Binary files /dev/null and b/versioned_docs/version-1.29.0/user-guide/020-manager-ui/img/notifications-overview.png differ diff --git a/versioned_docs/version-1.30.0/user-guide/020-manager-ui/10-manager-ui.md b/versioned_docs/version-1.30.0/user-guide/020-manager-ui/10-manager-ui.md index e95f7f63..c174c4ac 100644 --- a/versioned_docs/version-1.30.0/user-guide/020-manager-ui/10-manager-ui.md +++ b/versioned_docs/version-1.30.0/user-guide/020-manager-ui/10-manager-ui.md @@ -188,6 +188,18 @@ The alarms functionality (top right) allows you to automatically generate alarms ![](img/alarms-overview.png) _Figure 13. The alarms page with an overview of all alarms._ +## Notifications + +The notifications page (top right, under the dots menu) shows all email and push notifications sent within the selected realm, and lets you send new ones. These features are supported: +* Overview of sent notifications: see what was sent by rules, the platform itself, or clients using the [Manager APIs](#manager-apis), and whether it was sent or failed. +* Filtering by source and by period, ordering by column, and paging. +* Send a notification: write an email or push notification and send it to users, users linked to assets, or all users in a realm. + +Viewing notifications requires the `read:notifications` role, sending them the `write:notifications` role. See [Notifications](./50-notifications.md) for more details. + +![](img/notifications-overview.png) +_Figure 14. The notifications page with an overview of all sent notifications._ + ## Settings and access Admin users of the 'Master' realm see the Realm selector on the top right to switch between Realms. Next to that the dots give you access to a series of general settings as well as account access related settings. We will explain these here: @@ -198,17 +210,17 @@ You can link multiple instances of OpenRemote (as Gateways) to a single Central See the [Edge Gateway documentation](../080-gateways-and-devices/10-edge-gateway.md) for more details. ![](img/manager-interconnect.png) -_Figure 14. Several OpenRemote instances can be interconnected, e.g. connecting multiple instances on edge gateways to one central cloud hosted instance. The Manager Interconnect page, used at the edge instances (left) uses the keys which are created on the central instance by adding Edge gateway Assets (right)._ +_Figure 15. Several OpenRemote instances can be interconnected, e.g. connecting multiple instances on edge gateways to one central cloud hosted instance. The Manager Interconnect page, used at the edge instances (left) uses the keys which are created on the central instance by adding Edge gateway Assets (right)._ ![](img/manager-interconnect-rate-limiting.png) -_Figure 15. Next to interconnecting you can choose which asset attributes are actually linked as well as the rate at which data is exchanged._ +_Figure 16. Next to interconnecting you can choose which asset attributes are actually linked as well as the rate at which data is exchanged._ ### Gateway tunnels On top of the 'Manager Interconnect' functionality, you can remotely access the full Manager UI of the Gateway instances of OpenRemote, by creating Gateway tunnels. See the [Edge Gateway documentation](../080-gateways-and-devices/10-edge-gateway.md) for more details. ![](img/create-gateway-tunnel.png) -_Figure 16. Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ +_Figure 17. Creating a gateway tunnel and opening the manager UI of the remote instance which is connected as a gateway._ ### Languages @@ -219,14 +231,14 @@ OpenRemote currently supports 9 languages: English, German, French, Spanish, Por The logs page shows information, warnings and errors of the different activities of OpenRemote. You can use it to understand the behaviour of the whole platform or debug issues, e.g. errors connecting agent with device. ![](img/logs-page.png) -_Figure 17. The Logs page to evaluate system behaviour._ +_Figure 18. The Logs page to evaluate system behaviour._ ### Account On the Account page you can (re)set you personal information or password. You can also monitor your past sessions or enable 2FA via an Authenticator (default disabled). ![](img/edit-account-change-password.png) -_Figure 18. The account page with contact details (left) and reset passwords (right)._ +_Figure 19. The account page with contact details (left) and reset passwords (right)._ ### Users and access configuration @@ -241,14 +253,14 @@ By linking assets to users, the system will understand which users are connected When, next to linking an asset to a user, you also set the Realm role to 'Restricted User', users will only have access to the assets they are linked to. Note that you additionally have to indicate on the assets which attributes of the asset they have access to. To do that, set the configuration item 'Access restricted user read/write' on the attribute ([see 'Configure attributes'](#configure-attributes)). ![](img/creating-users.png) -_Figure 19. Creating users for a selected realm, assigning roles. In this example, the user is made a 'restricted user' linked to only 6 assets._ +_Figure 20. Creating users for a selected realm, assigning roles. In this example, the user is made a 'restricted user' linked to only 6 assets._ ### Roles With the correct permissions, you can create and edit roles. These roles define which parts of the system a user is allowed to Read or Write, e.g. system settings, assets, attributes, map, or rules. Also see the userguide: [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md). ![](img/role-with-permissions.png) -_Figure 20. Roles are made of a set of permissions_ +_Figure 21. Roles are made of a set of permissions_ ### Realms @@ -257,16 +269,16 @@ Only the Master realm Admin user can create `Realms` by accessing the master rea You can create a realm by adding a `realmname` name (single word, lower case letters), and a `Friendly name`. You can (temporarily) disable realms, which blocks access for any user. ![](img/realms.png) -_Figure 21. Realms can be created to manage multiple independent projects within one OpenRemote instance_ +_Figure 22. Realms can be created to manage multiple independent projects within one OpenRemote instance_ Also see the userguide: [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md). ### Auto provisioning of devices -If you are an OEM, developing and producing your own hardware, you can provision your devices and OpenRemote to automatically have your devices connecting, once they get online. Using certificates (we currently support X.509) your devices will register and automatically generate and connect to an asset of a defined type in the OpenRemote Manager (see figure 22). For details, check out the documentation about ['Auto provisioning'](../080-gateways-and-devices/20-auto-provisioning.md). +If you are an OEM, developing and producing your own hardware, you can provision your devices and OpenRemote to automatically have your devices connecting, once they get online. Using certificates (we currently support X.509) your devices will register and automatically generate and connect to an asset of a defined type in the OpenRemote Manager (see figure 23). For details, check out the documentation about ['Auto provisioning'](../080-gateways-and-devices/20-auto-provisioning.md). ![](img/auto-provisioning-of-devices.png) -_Figure 22. Auto provisioning of devices_ +_Figure 23. Auto provisioning of devices_ ### Appearance @@ -277,7 +289,7 @@ You can change the logo's, use different colours, change the title and default l For adding map layers you can add GeoJSON files (created e.g. with https://geojson.io/). More advanced settings like visible asset and agent types on the asset and rules page, can be configured directly in a JSON file. For the options available in the JSON file and an example, check out [Configuring the Manager UI](../010-deploying/20-configuring-the-manager-ui.md). For the maps you can set the center point, zoom levels and boundaries. ![](img/appearance-settings.png) -_Figure 23. Appearance settings allow white labeling of your OpenRemote manager_ +_Figure 24. Appearance settings allow white labeling of your OpenRemote manager_ ## Manager APIs @@ -285,10 +297,10 @@ The Manager APIs let you interact with OpenRemote without using the UI. This can ### Service users -Service users can be created on the `Users` page, and selecting `Add user` in the `Service user` panel (see figure 24). The `Username` (ClientID) can be set using letters, dashes, and numbers, while the `Secret` will be generated automatically once saved. Note that you also need to select the role(s). +Service users can be created on the `Users` page, and selecting `Add user` in the `Service user` panel (see figure 25). The `Username` (ClientID) can be set using letters, dashes, and numbers, while the `Secret` will be generated automatically once saved. Note that you also need to select the role(s). ![](img/creating-service-users.png) -_Figure 24. Creating service users, with Username, Secret and Roles for a selected Realm_ +_Figure 25. Creating service users, with Username, Secret and Roles for a selected Realm_ ### HTTP, MQTT, and WebSocket diff --git a/versioned_docs/version-1.30.0/user-guide/020-manager-ui/50-notifications.md b/versioned_docs/version-1.30.0/user-guide/020-manager-ui/50-notifications.md new file mode 100644 index 00000000..cb9b2464 --- /dev/null +++ b/versioned_docs/version-1.30.0/user-guide/020-manager-ui/50-notifications.md @@ -0,0 +1,259 @@ +# Notifications + +The Notifications page gives you an overview of all email and push notifications sent within a realm, and lets you send new ones directly from the Manager UI. You can find it in the settings menu (the dots on the top right) under `Notifications`. The page shows the notifications of the realm that is currently selected in the realm picker. + +The Notifications page provides three capabilities: +- **Overview** — browse, filter and sort all notifications that were sent, whether they came from rules, the platform itself, or an API client +- **Send** — write an email or push notification and send it to users, users linked to assets, or all users in a realm +- **Details** — look at the full content, recipient and delivery status of a single notification + +![](img/notifications-overview.png) +_Figure 1. The Notifications page with an overview of all sent notifications._ + +## Before you start + +Notifications are only delivered when the matching channel is configured for your deployment: + +| Channel | Requirements | +| :------ | :----------- | +| **Email** | An SMTP server, configured using the `OR_EMAIL_HOST`, `OR_EMAIL_USER`, `OR_EMAIL_PASSWORD` and `OR_EMAIL_FROM` environment variables. See [setting environment variables](../010-deploying/10-custom-deployment.md#setting-environment-variables-and-docker-volume-mappings-for-services). Recipients need an email address. | +| **Push** | A Firebase Cloud Messaging configuration file, set using the `OR_FIREBASE_CONFIG_FILE` environment variable. See [Push Notifications / FCM setup](../../developer-guide/140-working-on-the-mobile-consoles.md#push-notifications--fcm-setup). Recipients need the [OpenRemote app](./20-on-mobile.md) (or your own console app) with push notifications enabled. | + +:::note + +If a channel is not configured, sending a notification of that type fails and nothing is added to the overview. When you run the manager in dev mode without this configuration, notifications are recorded in the overview and written to the log instead of being sent. + +::: + +### Required roles + +Access to the page is controlled by two roles, which you can assign on the [Roles](./10-manager-ui.md#roles) page: + +| Role | Description | +| :--- | :---------- | +| `read:notifications` | View the Notifications page and the notifications sent within the realm | +| `write:notifications` | Send notifications, using the `Send new` button or the [API](#using-the-api) | + +The admin roles don't give access to this page: users with `read:admin` or `write:admin` still need the notification roles above. Some parts of the page need additional roles: +- **Recipients** — to select users you need `read:users`, and to select assets you need `read:assets`; `read:admin` works for both. Without these roles, the recipients of users or assets are shown as `-` in the overview. The `Send new` button only appears if you have `write:notifications`, and is disabled if you can't select any recipients. +- **All users in a realm** — only superusers can send a notification to every user in a realm. +- **Restricted users** — a [restricted user](../070-identity-and-security/10-realms-users-and-roles.md#restricted-user-realm-role) only sees notifications they sent themselves, notifications sent to them, and notifications sent to their whole realm. They can only send notifications to users linked to the assets they are linked to. + +:::warning + +When you upgrade an existing installation, `read:notifications` and `write:notifications` are automatically added to the default `read` and `write` roles in every realm. Custom roles that you created yourself do not get them, so add the roles there if needed. + +Sending a notification through the API now requires the `write:notifications` role as well. Give this role to any [service user](./10-manager-ui.md#service-users) that sends notifications. + +::: + +## Viewing sent notifications + +The overview shows one row per recipient that was reached: a user or asset for an email, or a device with the app for a push notification. A user with two phones gets two rows for one push notification, and recipients that can't be reached get no row. By default, you see the notifications sent today, with the newest first. + +| Column | Description | +| :----- | :---------- | +| **Title** | The title of a push notification or the subject of an email. The icon in front shows whether it was a push notification or an email | +| **Body** | The message of the notification. For emails this is the HTML that was sent | +| **Status** | Whether the notification was sent or failed. See [Status](#status) | +| **Source** | What sent the notification. See [Source](#source) | +| **Recipient** | The user, asset or realm that received the notification. Users and assets link to their page in the Manager UI | +| **Sent on** | The moment the notification was sent | +| **Delivered on** | The moment a console app confirmed that it received the notification (push notifications only) | + +:::note + +Delivery confirmation does not work at the moment. The `Delivered on` column stays empty, and push notifications keep the `Sent` status, even when they arrived on the device. + +::: + +Click a column header to sort by that column; click again to reverse the order. You can sort by Title, Status, Source, Sent on and Delivered on. Sorting is applied to all notifications, not just the current page. Use the controls at the bottom of the table to change the number of rows per page and to move between pages. + +### Status + +| Status | Description | +| :----- | :---------- | +| `Sent` | The notification left the platform: it was accepted by the email server or by Firebase | +| `Delivered` | A console app confirmed that it received the push notification. Emails never get this status. Not set at the moment, see the note above | +| `Error` | Sending failed. Hover over the status to see the reason | + +### Source + +| Source | Description | +| :----- | :---------- | +| **Internal** | Sent by the platform itself, for example by a service or by custom code running in the manager | +| **Client** | Sent through the [API](#using-the-api) by a user or service user. Notifications you send with `Send new` also get this source | +| **Global ruleset** | Sent by a global rule, such as a [When-Then rule](../060-rules-and-forecasting/20-when-then-rules.md#supported-actions) or [Groovy rule](../060-rules-and-forecasting/40-groovy-rules.md) | +| **Realm ruleset** | Sent by a rule in the realm | + + + +### Filtering notifications + +Use the controls at the top of the page to narrow down the overview: + +| Filter | Description | +| :----- | :---------- | +| **Source** | Only show notifications from one source. The default is `All sources` | +| **From** / **To** | Only show notifications sent within this period. The default is today, from 00:00 to 23:59 | + +To see the notifications of another realm, select that realm in the realm picker. A notification is listed in the realm of its recipient, so a notification sent from the master realm to a user in another realm shows up in that other realm. If the recipient's realm cannot be determined, the notification is listed in the realm of the sender. For global rules and internal notifications, that is the master realm. + +## Sending a notification + +To send a notification, you need the `write:notifications` role. + +1. Click `Send new` on the top right of the page. +2. Select the recipients: choose a **Recipient type** and select one or more recipients. +3. Choose the **Type** of notification, `Push` or `Email`, and enter its content. +4. For push notifications, optionally configure the **Actions**. +5. Click `Create`. + +The `Create` button is only enabled when you have selected at least one recipient, filled in the title or subject and the body, and entered a valid website URL (if you entered one). After the notification is sent, the overview reloads and shows the new notification with the source `Client`. + +### Recipients + +| Recipient type | Who receives the notification | Availability | +| :------------- | :---------------------------- | :----------- | +| **Users** | The selected users of the current realm | Requires `read:users`. Not available for restricted users | +| **Users linked to assets** | The users linked to the assets you select in the asset tree | Requires `read:assets`. Restricted users can only select assets they are linked to | +| **All users in realms** | Every user in the selected realms | Superusers only | + +How recipients are reached depends on the type of notification: +- **Email** — sent to the email address of each user. For `Users linked to assets`, the email is also sent to the address in the `email` attribute of the asset, if it has one. +- **Push** — sent to the console apps (for example the OpenRemote app on a phone) that are registered by the users. For push notifications the recipient in the overview is therefore the console asset, one row per device. + +Service users, users without an email address (for email), users without a registered console app (for push), and users who turned off that type of notification never receive it. + +### Content + +| Field | Description | +| :---- | :---------- | +| **Type** | `Push` for a notification on a mobile device, or `Email` | +| **Title** / **Subject** | The title of the push notification or the subject of the email. Required | +| **Body** | The message. Required. Emails are sent as HTML, so use tags such as `

`, `
` or `` for formatting; line breaks are not kept otherwise | + +### Actions + +Push notifications can include an action and buttons. All fields are optional. + +| Field | Description | +| :---- | :---------- | +| **Website to be opened** | The URL opened when the recipient taps the notification. The URL must include a scheme, such as `https://example.com` | +| **Open in browser (for external websites)** | Opens the website in the browser of the device instead of inside the app | +| **Text for action button** | Adds a button with this text. The button opens the website | +| **Text for decline button** | Adds a button with this text that dismisses the notification | +| **Priority** | `Normal` or `High`. Only applies to Android devices, where high priority notifications are delivered immediately, even when the device is idle. iOS devices always receive push notifications with high priority | + +### When sending fails + +If sending fails, you will see the message `Failed to send notification.` This happens when: +- none of the selected recipients can be reached, for example because the users have no email address or no console app with push notifications +- you are not allowed to send to one of the selected recipients +- the email or push channel is not [configured](#before-you-start) + +If the notification was sent to some recipients but failed for others, rows with the `Error` status are added to the overview for the recipients that failed. Close the dialog to see them. + +## Examples + +The examples below show which fields to fill in for common situations. See [Sending a notification](#sending-a-notification) for a description of all fields. + +### Send an urgent push notification to specific users + +1. Click `Send new`. +2. Set **Recipient type** to `Users` and select the users. +3. Set **Type** to `Push` and enter a **Title** and **Body**. +4. Under **Actions**, set **Priority** to `High`. This makes a difference on Android devices only; iOS devices always receive push notifications with high priority. +5. Click `Create`. + +### Open a website from a push notification + +1. Click `Send new`, select the recipients, and set **Type** to `Push` with a **Title** and **Body**. +2. Under **Actions**, enter the address in **Website to be opened**, including the scheme, such as `https://`. +3. Turn on **Open in browser (for external websites)** to open the website in the browser of the device. Leave it off to open the website inside the app. +4. Click `Create`. + +Recipients open the website by tapping the notification. + +### Add buttons to a push notification + +Buttons let recipients respond directly from the notification, for example to view more details or to dismiss the message. + +1. Click `Send new`, select the recipients, and set **Type** to `Push` with a **Title** and **Body**. +2. Under **Actions**, enter the **Website to be opened**. The action button opens this website. +3. Enter the **Text for action button**, for example `View details`. +4. Enter the **Text for decline button**, for example `Dismiss`. +5. Click `Create`. + +:::tip + +Always fill in the **Text for action button** when you add a decline button. If you enter a website but only a text for the decline button, that button opens the website instead. + +::: + +### Email the users linked to an asset + +Use this, for example, to inform the users responsible for a building or a machine. First make sure these users are [linked to the asset](./10-manager-ui.md#link-assets-to-users) and have an email address. + +1. Click `Send new`. +2. Set **Recipient type** to `Users linked to assets` and check the assets in the asset tree. +3. Set **Type** to `Email` and enter a **Subject**. +4. Enter the **Body** as HTML, for example `

The heating will be serviced on Monday.

`. +5. Click `Create`. + +If an asset has an `email` attribute, the email is also sent to that address. + +### Send an announcement to all users in a realm + +Only superusers can send a notification to every user in a realm. + +1. Click `Send new`. +2. Set **Recipient type** to `All users in realms` and check one or more realms. +3. Choose the **Type** and enter the content. +4. Click `Create`. + +A push announcement reaches every console app with push notifications enabled in the selected realms. An email announcement reaches every user with an email address. Each user (for email) or device (for push) gets its own row in the overview. + +### Check whether a rule sent its notifications + +When a rule should have sent a notification but nobody received it, use the overview to find out what happened. + +1. In the realm picker, select the realm of the recipients. +2. Set **Source** to `Realm ruleset` or `Global ruleset`, depending on where the rule is defined. +3. Set **From** and **To** to the period in which the rule should have triggered. +4. Find the notification by its title and check the **Status**: + - `Sent` — the notification left the platform. If it did not arrive, check the recipient's email or the notification settings of the app. + - `Error` — hover over the status to see why sending failed. + +If there is no row at all, either the rule did not trigger, or none of its recipients could be reached, for example because they have no email address or no app with push notifications enabled. + +## Viewing notification details + +Click a row in the overview to open the notification details. The details are read-only and show: +- **Recipient** — the recipient type and the ID of the recipient +- **Content** — the type, title or subject, and body +- **Actions** — the website, button texts and priority (push notifications only) +- **Properties** — the source, status, and the moments it was sent and delivered. If you have the `read:users` role, the source also shows the ID of the sender, such as the user for `Client` or the realm for `Realm ruleset` + +The IDs of users and assets are only shown when you have the `read:users` or `read:assets` role. Push device tokens are never shown. + +## Using the API + +You can also retrieve and send notifications through the HTTP API, for example to send notifications from an external application. Notifications sent this way get the source `Client` and require the same roles as the Notifications page: + +| Operation | Endpoint | Required role | +| :-------- | :------- | :------------ | +| [Retrieve notifications](../../rest-api/get-notifications.api.mdx) | `GET /api/{realm}/notification` | `read:notifications` | +| [Count notifications](../../rest-api/get-notifications-count.api.mdx) | `GET /api/{realm}/notification/count` | `read:notifications` | +| [Send a notification](../../rest-api/send-notification.api.mdx) | `POST /api/{realm}/notification/alert` | `write:notifications` | + +The linked REST API pages describe the parameters and request bodies. For authentication, see [Manager APIs](../050-manager-apis.md). + +## See Also + +- [Manager UI — Notifications](./10-manager-ui.md#notifications) +- [When-Then rules — Supported actions](../060-rules-and-forecasting/20-when-then-rules.md#supported-actions) +- [Realms, users and roles](../070-identity-and-security/10-realms-users-and-roles.md) +- [On mobile](./20-on-mobile.md) +- [Working on the mobile consoles — Push Notifications / FCM setup](../../developer-guide/140-working-on-the-mobile-consoles.md#push-notifications--fcm-setup) +- [Custom deployment — Setting environment variables](../010-deploying/10-custom-deployment.md#setting-environment-variables-and-docker-volume-mappings-for-services) diff --git a/versioned_docs/version-1.30.0/user-guide/020-manager-ui/img/notifications-overview.png b/versioned_docs/version-1.30.0/user-guide/020-manager-ui/img/notifications-overview.png new file mode 100644 index 00000000..35603f3e Binary files /dev/null and b/versioned_docs/version-1.30.0/user-guide/020-manager-ui/img/notifications-overview.png differ