1"use strict";(self.webpackChunkopenremote_docs=self.webpackChunkopenremote_docs||[]).push([["109108"],{169047(e,t,i){i.r(t),i.d(t,{metadata:()=>n,default:()=>a,frontMatter:()=>l,contentTitle:()=>o,toc:()=>h,assets:()=>d});var n=JSON.parse('{"id":"user-guide/manager-ui/notifications","title":"Notifications","description":"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.","source":"@site/versioned_docs/version-1.28.0/user-guide/020-manager-ui/50-notifications.md","sourceDirName":"user-guide/020-manager-ui","slug":"/user-guide/manager-ui/notifications","permalink":"/docs/1.28.0/user-guide/manager-ui/notifications","draft":false,"unlisted":false,"editUrl":"https://github.com/openremote/documentation/edit/main/docs/user-guide/020-manager-ui/50-notifications.md","tags":[],"version":"1.28.0","sidebarPosition":50,"frontMatter":{},"sidebar":"docsSidebar","previous":{"title":"Geocoding","permalink":"/docs/1.28.0/user-guide/manager-ui/geocoding"},"next":{"title":"Assets, Agents and Attributes","permalink":"/docs/1.28.0/user-guide/assets-agents-and-attributes"}}'),s=i(474848),r=i(28453);let l={},o="Notifications",d={},h=[{value:"Before you start",id:"before-you-start",level:2},{value:"Required roles",id:"required-roles",level:3},{value:"Viewing sent notifications",id:"viewing-sent-notifications",level:2},{value:"Status",id:"status",level:3},{value:"Source",id:"source",level:3},{value:"Filtering notifications",id:"filtering-notifications",level:3},{value:"Sending a notification",id:"sending-a-notification",level:2},{value:"Recipients",id:"recipients",level:3},{value:"Content",id:"content",level:3},{value:"Actions",id:"actions",level:3},{value:"When sending fails",id:"when-sending-fails",level:3},{value:"Examples",id:"examples",level:2},{value:"Send an urgent push notification to specific users",id:"send-an-urgent-push-notification-to-specific-users",level:3},{value:"Open a website from a push notification",id:"open-a-website-from-a-push-notification",level:3},{value:"Add buttons to a push notification",id:"add-buttons-to-a-push-notification",level:3},{value:"Email the users linked to an asset",id:"email-the-users-linked-to-an-asset",level:3},{value:"Send an announcement to all users in a realm",id:"send-an-announcement-to-all-users-in-a-realm",level:3},{value:"Check whether a rule sent its notifications",id:"check-whether-a-rule-sent-its-notifications",level:3},{value:"Viewing notification details",id:"viewing-notification-details",level:2},{value:"Using the API",id:"using-the-api",level:2},{value:"See Also",id:"see-also",level:2}];function c(e){let t={a:"a",admonition:"admonition",code:"code",em:"em",h1:"h1",h2:"h2",h3:"h3",header:"header",img:"img",li:"li",ol:"ol",p:"p",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(t.header,{children:(0,s.jsx)(t.h1,{id:"notifications",children:"Notifications"})}),"\n",(0,s.jsxs)(t.p,{children:["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 ",(0,s.jsx)(t.code,{children:"Notifications"}),". The page shows the notifications of the realm that is currently selected in the realm picker."]}),"\n",(0,s.jsx)(t.p,{children:"The Notifications page provides three capabilities:"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Overview"})," \u2014 browse, filter and sort all notifications that were sent, whether they came from rules, the platform itself, or an API client"]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Send"})," \u2014 write an email or push notification and send it to users, users linked to assets, or all users in a realm"]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Details"})," \u2014 look at the full content, recipient and delivery status of a single notification"]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:[(0,s.jsx)(t.img,{src:i(170560).A+"",width:"1920",height:"963"}),"\n",(0,s.jsx)(t.em,{children:"Figure 1. The Notifications page with an overview of all sent notifications."})]}),"\n",(0,s.jsx)(t.h2,{id:"before-you-start",children:"Before you start"}),"\n",(0,s.jsx)(t.p,{children:"Notifications are only delivered when the matching channel is configured for your deployment:"}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Channel"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Requirements"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Email"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["An SMTP server, configured using the ",(0,s.jsx)(t.code,{children:"OR_EMAIL_HOST"}),", ",(0,s.jsx)(t.code,{children:"OR_EMAIL_USER"}),", ",(0,s.jsx)(t.code,{children:"OR_EMAIL_PASSWORD"})," and ",(0,s.jsx)(t.code,{children:"OR_EMAIL_FROM"})," environment variables. See ",(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/deploying/custom-deployment#setting-environment-variables-and-docker-volume-mappings-for-services",children:"setting environment variables"}),". Recipients need an email address."]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Push"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["A Firebase Cloud Messaging configuration file, set using the ",(0,s.jsx)(t.code,{children:"OR_FIREBASE_CONFIG_FILE"})," environment variable. See ",(0,s.jsx)(t.a,{href:"/docs/1.28.0/developer-guide/working-on-the-mobile-consoles#push-notifications--fcm-setup",children:"Push Notifications / FCM setup"}),". Recipients need the ",(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/manager-ui/on-mobile",children:"OpenRemote app"})," (or your own console app) with push notifications enabled."]})]})]})]}),"\n",(0,s.jsx)(t.admonition,{type:"note",children:(0,s.jsx)(t.p,{children:"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."})}),"\n",(0,s.jsx)(t.h3,{id:"required-roles",children:"Required roles"}),"\n",(0,s.jsxs)(t.p,{children:["Access to the page is controlled by two roles, which you can assign on the ",(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/manager-ui/#roles",children:"Roles"})," page:"]}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Role"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"read:notifications"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"View the Notifications page and the notifications sent within the realm"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"write:notifications"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Send notifications, using the ",(0,s.jsx)(t.code,{children:"Send new"})," button or the ",(0,s.jsx)(t.a,{href:"#using-the-api",children:"API"})]})]})]})]}),"\n",(0,s.jsxs)(t.p,{children:["The admin roles don't give access to this page: users with ",(0,s.jsx)(t.code,{children:"read:admin"})," or ",(0,s.jsx)(t.code,{children:"write:admin"})," still need the notification roles above. Some parts of the page need additional roles:"]}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Recipients"})," \u2014 to select users you need ",(0,s.jsx)(t.code,{children:"read:users"}),", and to select assets you need ",(0,s.jsx)(t.code,{children:"read:assets"}),"; ",(0,s.jsx)(t.code,{children:"read:admin"})," works for both. Without these roles, the recipients of users or assets are shown as ",(0,s.jsx)(t.code,{children:"-"})," in the overview. The ",(0,s.jsx)(t.code,{children:"Send new"})," button only appears if you have ",(0,s.jsx)(t.code,{children:"write:notifications"}),", and is disabled if you can't select any recipients."]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"All users in a realm"})," \u2014 only superusers can send a notification to every user in a realm."]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Restricted users"})," \u2014 a ",(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/identity-and-security/realms-users-and-roles#restricted-user-realm-role",children:"restricted user"})," 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."]}),"\n"]}),"\n",(0,s.jsxs)(t.admonition,{type:"warning",children:[(0,s.jsxs)(t.p,{children:["When you upgrade an existing installation, ",(0,s.jsx)(t.code,{children:"read:notifications"})," and ",(0,s.jsx)(t.code,{children:"write:notifications"})," are automatically added to the default ",(0,s.jsx)(t.code,{children:"read"})," and ",(0,s.jsx)(t.code,{children:"write"})," roles in every realm. Custom roles that you created yourself do not get them, so add the roles there if needed."]}),(0,s.jsxs)(t.p,{children:["Sending a notification through the API now requires the ",(0,s.jsx)(t.code,{children:"write:notifications"})," role as well. Give this role to any ",(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/manager-ui/#service-users",children:"service user"})," that sends notifications."]})]}),"\n",(0,s.jsx)(t.h2,{id:"viewing-sent-notifications",children:"Viewing sent notifications"}),"\n",(0,s.jsx)(t.p,{children:"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."}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Column"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Title"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"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"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Body"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The message of the notification. For emails this is the HTML that was sent"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Status"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Whether the notification was sent or failed. See ",(0,s.jsx)(t.a,{href:"#status",children:"Status"})]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Source"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["What sent the notification. See ",(0,s.jsx)(t.a,{href:"#source",children:"Source"})]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Recipient"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The user, asset or realm that received the notification. Users and assets link to their page in the Manager UI"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Sent on"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The moment the notification was sent"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Delivered on"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The moment a console app confirmed that it received the notification (push notifications only)"})]})]})]}),"\n",(0,s.jsx)(t.admonition,{type:"note",children:(0,s.jsxs)(t.p,{children:["Delivery confirmation does not work at the moment. The ",(0,s.jsx)(t.code,{children:"Delivered on"})," column stays empty, and push notifications keep the ",(0,s.jsx)(t.code,{children:"Sent"})," status, even when they arrived on the device."]})}),"\n",(0,s.jsx)(t.p,{children:"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."}),"\n",(0,s.jsx)(t.h3,{id:"status",children:"Status"}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Status"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"Sent"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The notification left the platform: it was accepted by the email server or by Firebase"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"Delivered"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"A console app confirmed that it received the push notification. Emails never get this status. Not set at the moment, see the note above"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"Error"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Sending failed. Hover over the status to see the reason"})]})]})]}),"\n",(0,s.jsx)(t.h3,{id:"source",children:"Source"}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Source"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Internal"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Sent by the platform itself, for example by a service or by custom code running in the manager"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Client"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Sent through the ",(0,s.jsx)(t.a,{href:"#using-the-api",children:"API"})," by a user or service user. Notifications you send with ",(0,s.jsx)(t.code,{children:"Send new"})," also get this source"]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Global ruleset"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Sent by a global rule, such as a ",(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/rules-and-forecasting/when-then-rules#supported-actions",children:"When-Then rule"})," or ",(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/rules-and-forecasting/groovy-rules",children:"Groovy rule"})]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Realm ruleset"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Sent by a rule in the realm"})]})]})]}),"\n",(0,s.jsx)(t.h3,{id:"filtering-notifications",children:"Filtering notifications"}),"\n",(0,s.jsx)(t.p,{children:"Use the controls at the top of the page to narrow down the overview:"}),"\n",(0,s.jsxs)(t.table,{chi
1ldren:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Filter"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Source"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Only show notifications from one source. The default is ",(0,s.jsx)(t.code,{children:"All sources"})]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:[(0,s.jsx)(t.strong,{children:"From"})," / ",(0,s.jsx)(t.strong,{children:"To"})]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Only show notifications sent within this period. The default is today, from 00:00 to 23:59"})]})]})]}),"\n",(0,s.jsx)(t.p,{children:"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."}),"\n",(0,s.jsx)(t.h2,{id:"sending-a-notification",children:"Sending a notification"}),"\n",(0,s.jsxs)(t.p,{children:["To send a notification, you need the ",(0,s.jsx)(t.code,{children:"write:notifications"})," role."]}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Send new"})," on the top right of the page."]}),"\n",(0,s.jsxs)(t.li,{children:["Select the recipients: choose a ",(0,s.jsx)(t.strong,{children:"Recipient type"})," and select one or more recipients."]}),"\n",(0,s.jsxs)(t.li,{children:["Choose the ",(0,s.jsx)(t.strong,{children:"Type"})," of notification, ",(0,s.jsx)(t.code,{children:"Push"})," or ",(0,s.jsx)(t.code,{children:"Email"}),", and enter its content."]}),"\n",(0,s.jsxs)(t.li,{children:["For push notifications, optionally configure the ",(0,s.jsx)(t.strong,{children:"Actions"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Create"}),"."]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["The ",(0,s.jsx)(t.code,{children:"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 ",(0,s.jsx)(t.code,{children:"Client"}),"."]}),"\n",(0,s.jsx)(t.h3,{id:"recipients",children:"Recipients"}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Recipient type"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Who receives the notification"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Availability"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Users"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The selected users of the current realm"}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Requires ",(0,s.jsx)(t.code,{children:"read:users"}),". Not available for restricted users"]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Users linked to assets"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The users linked to the assets you select in the asset tree"}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["Requires ",(0,s.jsx)(t.code,{children:"read:assets"}),". Restricted users can only select assets they are linked to"]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"All users in realms"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Every user in the selected realms"}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Superusers only"})]})]})]}),"\n",(0,s.jsx)(t.p,{children:"How recipients are reached depends on the type of notification:"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Email"})," \u2014 sent to the email address of each user. For ",(0,s.jsx)(t.code,{children:"Users linked to assets"}),", the email is also sent to the address in the ",(0,s.jsx)(t.code,{children:"email"})," attribute of the asset, if it has one."]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Push"})," \u2014 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."]}),"\n"]}),"\n",(0,s.jsx)(t.p,{children:"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."}),"\n",(0,s.jsx)(t.h3,{id:"content",children:"Content"}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Field"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Type"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:[(0,s.jsx)(t.code,{children:"Push"})," for a notification on a mobile device, or ",(0,s.jsx)(t.code,{children:"Email"})]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:[(0,s.jsx)(t.strong,{children:"Title"})," / ",(0,s.jsx)(t.strong,{children:"Subject"})]}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"The title of the push notification or the subject of the email. Required"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Body"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["The message. Required. Emails are sent as HTML, so use tags such as ",(0,s.jsx)(t.code,{children:"<p>"}),", ",(0,s.jsx)(t.code,{children:"<br>"})," or ",(0,s.jsx)(t.code,{children:"<a>"})," for formatting; line breaks are not kept otherwise"]})]})]})]}),"\n",(0,s.jsx)(t.h3,{id:"actions",children:"Actions"}),"\n",(0,s.jsx)(t.p,{children:"Push notifications can include an action and buttons. All fields are optional."}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Field"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Description"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Website to be opened"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:["The URL opened when the recipient taps the notification. The URL must include a scheme, such as ",(0,s.jsx)(t.code,{children:"https://example.com"})]})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Open in browser (for external websites)"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Opens the website in the browser of the device instead of inside the app"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Text for action button"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Adds a button with this text. The button opens the website"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Text for decline button"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:"Adds a button with this text that dismisses the notification"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.strong,{children:"Priority"})}),(0,s.jsxs)(t.td,{style:{textAlign:"left"},children:[(0,s.jsx)(t.code,{children:"Normal"})," or ",(0,s.jsx)(t.code,{children:"High"}),". Only applies to Android devices, where high priority notifications are delivered immediately, even when the device is idle. iOS devices always re
1ceive push notifications with high priority"]})]})]})]}),"\n",(0,s.jsx)(t.h3,{id:"when-sending-fails",children:"When sending fails"}),"\n",(0,s.jsxs)(t.p,{children:["If sending fails, you will see the message ",(0,s.jsx)(t.code,{children:"Failed to send notification."})," This happens when:"]}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsx)(t.li,{children:"none of the selected recipients can be reached, for example because the users have no email address or no console app with push notifications"}),"\n",(0,s.jsx)(t.li,{children:"you are not allowed to send to one of the selected recipients"}),"\n",(0,s.jsxs)(t.li,{children:["the email or push channel is not ",(0,s.jsx)(t.a,{href:"#before-you-start",children:"configured"})]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["If the notification was sent to some recipients but failed for others, rows with the ",(0,s.jsx)(t.code,{children:"Error"})," status are added to the overview for the recipients that failed. Close the dialog to see them."]}),"\n",(0,s.jsx)(t.h2,{id:"examples",children:"Examples"}),"\n",(0,s.jsxs)(t.p,{children:["The examples below show which fields to fill in for common situations. See ",(0,s.jsx)(t.a,{href:"#sending-a-notification",children:"Sending a notification"})," for a description of all fields."]}),"\n",(0,s.jsx)(t.h3,{id:"send-an-urgent-push-notification-to-specific-users",children:"Send an urgent push notification to specific users"}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Send new"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Set ",(0,s.jsx)(t.strong,{children:"Recipient type"})," to ",(0,s.jsx)(t.code,{children:"Users"})," and select the users."]}),"\n",(0,s.jsxs)(t.li,{children:["Set ",(0,s.jsx)(t.strong,{children:"Type"})," to ",(0,s.jsx)(t.code,{children:"Push"})," and enter a ",(0,s.jsx)(t.strong,{children:"Title"})," and ",(0,s.jsx)(t.strong,{children:"Body"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Under ",(0,s.jsx)(t.strong,{children:"Actions"}),", set ",(0,s.jsx)(t.strong,{children:"Priority"})," to ",(0,s.jsx)(t.code,{children:"High"}),". This makes a difference on Android devices only; iOS devices always receive push notifications with high priority."]}),"\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Create"}),"."]}),"\n"]}),"\n",(0,s.jsx)(t.h3,{id:"open-a-website-from-a-push-notification",children:"Open a website from a push notification"}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Send new"}),", select the recipients, and set ",(0,s.jsx)(t.strong,{children:"Type"})," to ",(0,s.jsx)(t.code,{children:"Push"})," with a ",(0,s.jsx)(t.strong,{children:"Title"})," and ",(0,s.jsx)(t.strong,{children:"Body"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Under ",(0,s.jsx)(t.strong,{children:"Actions"}),", enter the address in ",(0,s.jsx)(t.strong,{children:"Website to be opened"}),", including the scheme, such as ",(0,s.jsx)(t.code,{children:"https://"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Turn on ",(0,s.jsx)(t.strong,{children:"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."]}),"\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Create"}),"."]}),"\n"]}),"\n",(0,s.jsx)(t.p,{children:"Recipients open the website by tapping the notification."}),"\n",(0,s.jsx)(t.h3,{id:"add-buttons-to-a-push-notification",children:"Add buttons to a push notification"}),"\n",(0,s.jsx)(t.p,{children:"Buttons let recipients respond directly from the notification, for example to view more details or to dismiss the message."}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Send new"}),", select the recipients, and set ",(0,s.jsx)(t.strong,{children:"Type"})," to ",(0,s.jsx)(t.code,{children:"Push"})," with a ",(0,s.jsx)(t.strong,{children:"Title"})," and ",(0,s.jsx)(t.strong,{children:"Body"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Under ",(0,s.jsx)(t.strong,{children:"Actions"}),", enter the ",(0,s.jsx)(t.strong,{children:"Website to be opened"}),". The action button opens this website."]}),"\n",(0,s.jsxs)(t.li,{children:["Enter the ",(0,s.jsx)(t.strong,{children:"Text for action button"}),", for example ",(0,s.jsx)(t.code,{children:"View details"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Enter the ",(0,s.jsx)(t.strong,{children:"Text for decline button"}),", for example ",(0,s.jsx)(t.code,{children:"Dismiss"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Create"}),"."]}),"\n"]}),"\n",(0,s.jsx)(t.admonition,{type:"tip",children:(0,s.jsxs)(t.p,{children:["Always fill in the ",(0,s.jsx)(t.strong,{children:"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."]})}),"\n",(0,s.jsx)(t.h3,{id:"email-the-users-linked-to-an-asset",children:"Email the users linked to an asset"}),"\n",(0,s.jsxs)(t.p,{children:["Use this, for example, to inform the users responsible for a building or a machine. First make sure these users are ",(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/manager-ui/#link-assets-to-users",children:"linked to the asset"})," and have an email address."]}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Send new"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Set ",(0,s.jsx)(t.strong,{children:"Recipient type"})," to ",(0,s.jsx)(t.code,{children:"Users linked to assets"})," and check the assets in the asset tree."]}),"\n",(0,s.jsxs)(t.li,{children:["Set ",(0,s.jsx)(t.strong,{children:"Type"})," to ",(0,s.jsx)(t.code,{children:"Email"})," and enter a ",(0,s.jsx)(t.strong,{children:"Subject"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Enter the ",(0,s.jsx)(t.strong,{children:"Body"})," as HTML, for example ",(0,s.jsx)(t.code,{children:"<p>The heating will be serviced on Monday.</p>"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Create"}),"."]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["If an asset has an ",(0,s.jsx)(t.code,{children:"email"})," attribute, the email is also sent to that address."]}),"\n",(0,s.jsx)(t.h3,{id:"send-an-announcement-to-all-users-in-a-realm",children:"Send an announcement to all users in a realm"}),"\n",(0,s.jsx)(t.p,{children:"Only superusers can send a notification to every user in a realm."}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Send new"}),"."]}),"\n",(0,s.jsxs)(t.li,{children:["Set ",(0,s.jsx)(t.strong,{children:"Recipient type"})," to ",(0,s.jsx)(t.code,{children:"All users in realms"})," and check one or more realms."]}),"\n",(0,s.jsxs)(t.li,{children:["Choose the ",(0,s.jsx)(t.strong,{children:"Type"})," and enter the content."]}),"\n",(0,s.jsxs)(t.li,{children:["Click ",(0,s.jsx)(t.code,{children:"Create"}),"."]}),"\n"]}),"\n",(0,s.jsx)(t.p,{children:"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."}),"\n",(0,s.jsx)(t.h3,{id:"check-whether-a-rule-sent-its-notifications",children:"Check whether a rule sent its notifications"}),"\n",(0,s.jsx)(t.p,{children:"When a rule should have sent a notification but nobody received it, use the overview to find out what happened."}),"\n",(0,s.jsxs)(t.ol,{children:["\n",(0,s.jsx)(t.li,{children:"In the realm picker, select the realm of the recipients."}),"\n",(0,s.jsxs)(t.li,{children:["Set ",(0,s.jsx)(t.strong,{children:"Source"})," to ",(0,s.jsx)(t.code,{children:"Realm ruleset"})," or ",(0,s.jsx)(t.code,{children:"Global ruleset"}),", depending on where the rule is defined."]}),"\n",(0,s.jsxs)(t.li,{children:["Set ",(0,s.jsx)(t.strong,{children:"From"})," and ",(0,s.jsx)(t.strong,{children:"To"}
1)," to the period in which the rule should have triggered."]}),"\n",(0,s.jsxs)(t.li,{children:["Find the notification by its title and check the ",(0,s.jsx)(t.strong,{children:"Status"}),":","\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.code,{children:"Sent"})," \u2014 the notification left the platform. If it did not arrive, check the recipient's email or the notification settings of the app."]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.code,{children:"Error"})," \u2014 hover over the status to see why sending failed."]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,s.jsx)(t.p,{children:"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."}),"\n",(0,s.jsx)(t.h2,{id:"viewing-notification-details",children:"Viewing notification details"}),"\n",(0,s.jsx)(t.p,{children:"Click a row in the overview to open the notification details. The details are read-only and show:"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Recipient"})," \u2014 the recipient type and the ID of the recipient"]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Content"})," \u2014 the type, title or subject, and body"]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Actions"})," \u2014 the website, button texts and priority (push notifications only)"]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"Properties"})," \u2014 the source, status, and the moments it was sent and delivered. If you have the ",(0,s.jsx)(t.code,{children:"read:users"})," role, the source also shows the ID of the sender, such as the user for ",(0,s.jsx)(t.code,{children:"Client"})," or the realm for ",(0,s.jsx)(t.code,{children:"Realm ruleset"})]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["The IDs of users and assets are only shown when you have the ",(0,s.jsx)(t.code,{children:"read:users"})," or ",(0,s.jsx)(t.code,{children:"read:assets"})," role. Push device tokens are never shown."]}),"\n",(0,s.jsx)(t.h2,{id:"using-the-api",children:"Using the API"}),"\n",(0,s.jsxs)(t.p,{children:["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 ",(0,s.jsx)(t.code,{children:"Client"})," and require the same roles as the Notifications page:"]}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Operation"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Endpoint"}),(0,s.jsx)(t.th,{style:{textAlign:"left"},children:"Required role"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.a,{href:"/docs/1.28.0/rest-api/get-notifications",children:"Retrieve notifications"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"GET /api/{realm}/notification"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"read:notifications"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.a,{href:"/docs/1.28.0/rest-api/get-notifications-count",children:"Count notifications"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"GET /api/{realm}/notification/count"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"read:notifications"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.a,{href:"/docs/1.28.0/rest-api/send-notification",children:"Send a notification"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"POST /api/{realm}/notification/alert"})}),(0,s.jsx)(t.td,{style:{textAlign:"left"},children:(0,s.jsx)(t.code,{children:"write:notifications"})})]})]})]}),"\n",(0,s.jsxs)(t.p,{children:["The linked REST API pages describe the parameters and request bodies. For authentication, see ",(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/manager-apis",children:"Manager APIs"}),"."]}),"\n",(0,s.jsx)(t.h2,{id:"see-also",children:"See Also"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsx)(t.li,{children:(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/manager-ui/#notifications",children:"Manager UI \u2014 Notifications"})}),"\n",(0,s.jsx)(t.li,{children:(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/rules-and-forecasting/when-then-rules#supported-actions",children:"When-Then rules \u2014 Supported actions"})}),"\n",(0,s.jsx)(t.li,{children:(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/identity-and-security/realms-users-and-roles",children:"Realms, users and roles"})}),"\n",(0,s.jsx)(t.li,{children:(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/manager-ui/on-mobile",children:"On mobile"})}),"\n",(0,s.jsx)(t.li,{children:(0,s.jsx)(t.a,{href:"/docs/1.28.0/developer-guide/working-on-the-mobile-consoles#push-notifications--fcm-setup",children:"Working on the mobile consoles \u2014 Push Notifications / FCM setup"})}),"\n",(0,s.jsx)(t.li,{children:(0,s.jsx)(t.a,{href:"/docs/1.28.0/user-guide/deploying/custom-deployment#setting-environment-variables-and-docker-volume-mappings-for-services",children:"Custom deployment \u2014 Setting environment variables"})}),"\n"]})]})}function a(e={}){let{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,s.jsx)(t,{...e,children:(0,s.jsx)(c,{...e})}):c(e)}},170560(e,t,i){i.d(t,{A:()=>n});let n=i.p+"assets/images/notifications-overview-864026506b049be0e7fc1512c1243b84.png"}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.