Send in-app notifications within model-driven apps

The notification table stores notifications for each user. Your model-driven app automatically polls the system for new notifications and displays them in the notification center. The notification sender or your system administrator can configure how the notification is shown and how it can be dismissed. Notifications appear in the notification center until the recipient dismisses them or they expire. By default, a notification expires after 14 days but your administrator can override this setting.

Each notification row is meant for a single user, identified by the Owner column value. If a notification needs to be sent to multiple users, a record needs to be added for each recipient. The sender controls the recipient through the Owner column.

This topic outlines the steps for how to send in-app notifications to a specific user by using a client API.

Enable the in-app notification feature

To use the in-app notification feature, you need to enable the In-app notifications setting. This setting is stored within the model-driven app.

  1. Sign in to Power Apps.

  2. Open the solution that contains the model-driven app.

  3. Select the model-driven app and click Edit split menu to open using the modern app designer

  4. Open Settings and switch to Upcoming

  5. Enable "In-app notifications"

    Custom page as main page

  6. Click Save to save the settings change

  7. Click Publish on the model-driven app

Send basic in-app notifications

Because the notification system uses a table, you can use any table functionality to create new notifications.

Screenshot of a Welcome notification.

The following examples use the notification table and a notification record to create notifications.

In-app notifications can be sent by using the createRecord API.

var systemuserid = "Guid of the user";
var notificationRecord =
{
  "title": "Welcome",
  "body": "Welcome to the world of app notifications!",
  "ownerid@odata.bind": "/systemusers(" + systemuserid + ")",
  "icontype": 100000000, // info
  "toasttype": 200000000 // timed
}
// Create notification record
Xrm.WebApi.createRecord("appnotification", notificationRecord).
  then(
      function success(result) {
          console.log("notification created with ID: " + result.id);
      },
      function (error) {
          console.log(error.message);
          // handle error conditions
      }
  );

Notification polling

In-app notifications uses polling to retrieve notifications periodically when the app is running. New notification are retreived at start of the model-driven app and when a page navigation occurs as long as the last retreival is more than one minute ago. If a user stays on a page for a long duration, new notifications will be retrieved.

Notification table

The following are the columns for the Notification (appnotification) table.

Column display Column name Description
Title title The title of the notification.
Owner ownerid The user who receives the notification.
Body body Details about the notification.
IconType icontype The list of predefined icons. The default value is Info. For more information, go to Changing the notification icon later in this topic.
Toast Type toasttype The list of notification behaviors. The default value is Timed. For more information, go to Changing the notification behavior later in this topic.
Expiry (seconds) ttlinseconds The number of seconds from when the notification should be deleted if not already dismissed.
Data data JSON that's used for extensibility and parsing richer data into the notification. The maximum length is 5,000 characters.

Important

  • The appmoduleid field is not used and should not be set on the appnotification entity.

Changing the notification behavior

You can change in-app notification behavior by setting Toast Type to one of the following values.

Toast Type Behavior Value
Timed The notification appears for a brief duration (the default is four seconds) and then disappears. 200000000
Hidden The notification appears only in the notification center and not as a toast notification. 200000001

Changing the notification icon

You can change the in-app notification icon by setting Icon Type to one of the following values. When using a custom icon, specify the iconUrl parameter within the data parameter.

Icon Type Value Image
Info 100000000 Info Icon
Success 100000001 Success Icon
Failure 100000002 Failure Icon
Warning 100000003 Warning Icon
Mention 100000004 Mention Icon
Custom 100000005

Using markdown in Title and Body

The data field supports overriding the Title and Body simple strings with a limited subset of markdown based.

Below is the supported markdown.

Text Style Markdown
Bold **Bold**
Italic _Italic_
Bullet list - Item 1\r- Item 2\r- Item 3
Numbered list 1. Green\r2. Orange\r3. Blue
Hyperlinks [Title](url)

Newlines can be included with the body using \n\n\n\n.

You can control where a navigation link opens by setting the navigationTarget parameter.

Navigation target Behavior Example
dialog Opens in the center dialog. "navigationTarget": "dialog"
inline Default. Opens in the current page. "navigationTarget": "inline"
newWindow Opens in a new browser tab. "navigationTarget": "newWindow"

Managing security for notifications

The in-app notification feature uses three tables. A user needs to have the correct security roles to receive notifications and to send notifications to themselves or other users.

Usage Required table privileges
User has no in-app notification bell and receives no in-app notification None: Read privilege on the app notification table.
User can receive in-app notifications
  • Basic: Read privilege on the app notification table.
  • Create, Read, Write, and Append privileges on the model-driven app user setting.
  • Read and AppendTo privileges on setting definition.
User can send in-app notifications to self Basic: Create and Read privileges on the app notification table.
User can send in-app notifications to others Read privilege with Local, Deep, or Global access level on the app notification table based on the receiving user's business unit.

Notification storage

The app notification table uses the organization's database storage capacity. Because of this, it's important to consider the volume of notifications sent and the expiration setting. More information: Microsoft Dataverse storage capacity

Examples

The following examples show how to create notifications that include actions, custom body definitions, and custom icons.

Notification with an action that has a title and URL

This example shows how to create a notification by adding title and URL to the actions parameter.

{
  "data": {
    "actions": [
      {
        "title": "Open Bing",
        "data" : {
          "url": "https://bing.com"
        }
      }
    ]
  }
}

Notification with one action

This example shows how to create a notification by adding one action to the actions parameter.

App notification with a single action.

var systemuserid = "<user-guid>";
var notificationRecord = 
{
    "title": "Congratulations",
     "body": "Your customer rating is now an A. You resolved 80% of your cases within SLA thi week and average customer rating was A+",
     "ownerid@odata.bind": "/systemusers(" + systemuserid + ")",
    "icontype": 100000001, // success
    "data": JSON.stringify({
    "actions": [
     {
        "title": "View cases",
        "data": {
      "url": "?pagetype=entitylist&etn=incident&viewid=00000000-0000-0000-00aa-000010001028&viewType=1039"
      }      
     }
    ]
   })
}
Xrm.WebApi.createRecord("appnotification", notificationRecord).
  then(
      function success(result) {
          console.log("notification created with single action: " + result.id);
      },
      function (error) {
          console.log(error.message);
          // handle error conditions
      }
  );

Notification with multiple actions

This example shows how to create a notification that includes multiple actions.

App notification with multiple actions.

// Notification with multiple actions as center dialog 
var systemuserid = "<user-guid>";
var notificationRecord = 
{
    "title": "Upcoming Service Reminder",
     "body": "This is to inform you that you have an upcoming service request for your vehicle.",
     "ownerid@odata.bind": "/systemusers(" + systemuserid + ")",
    "icontype": 100000000, // info
    "data": JSON.stringify({
      "actions": [
       {
        "title": "Coho Winery",
        "data": {
          "url": "?pagetype=entityrecord&etn=account&id=b0a19cdd-88df-e311-b8e5-6c3be5a8b200",
          "navigationTarget": "dialog"
             }      
       },
       {
         "title": "Service Appointment",
        "data": {
          "url": "?pagetype=entityrecord&etn=appointment&id=96db3cf0-e605-ec11-94ef-000d3a36469a",
          "navigationTarget": "dialog"
           }
       }
    ]
   })
}
Xrm.WebApi.createRecord("appnotification",notificationRecord).
  then(
      function success(result) {
          console.log("notification created with multiple actions: " + result.id);
      },
      function (error) {
          console.log(error.message);
          // handle error conditions
      }
  );

Notification with a custom body definition

This example shows how to create a notification by adding a custom body definition that includes an inline link.

Notification with a block of text that includes an inline link.

var systemuserid = "<user-guid>";
var notificationRecord = 
{
    "title": "SLA critical",
   "body": "Records assigned to you is critically past SLA.",
   "ownerid@odata.bind": "/systemusers(" + systemuserid + ")",
    "icontype": 100000002, // failure
    "data": JSON.stringify({
    "body": "Case record [Complete overhaul required (sample)](?pagetype=entityrecord&etn=incident&id=0a9f62a8-90df-e311-9565-a45d36fc5fe8) assigned to you is critically past SLA and has been escalated to your manager."
    })
}
Xrm.WebApi.createRecord("appnotification",notificationRecord).
  then(
      function success(result) {
          console.log("notification created with custom body: " + result.id);
      },
      function (error) {
          console.log(error.message);
          // handle error conditions
      }
  );

The following is another example of a custom body definition. This one includes an inline link and bold formatting.

Notification with a block of text that includes an inline link and bold text.

var systemuserid = "<user-guid>";
var notificationRecord = 
{
    "title": "SLA Missed",
   "body": "Records assigned to you is critically past SLA.",
   "ownerid@odata.bind": "/systemusers(" + systemuserid + ")",
    "icontype": 100000003, // warning
    "data": JSON.stringify({
    "body": "Case record [Average order shipment time (sample)](?pagetype=entityrecord&etn=incident&id=0a9f62a8-90df-e311-9565-a45d36fc5fe8) **assigned** to you just went out of SLA."
    })
}
Xrm.WebApi.createRecord("appnotification",notificationRecord).
then(
      function success(result) {
          console.log("notification created with custom body and bold styling: " + result.id);
      },
      function (error) {
          console.log(error.message);
          // handle error conditions
      }
  );

Notification with a custom icon

This example shows how to add a custom icon to a notification. Within the notification, set iconType to Custom and in the body, include iconUrl with a value pointing to a web resource. The icon can be either an SVG or PNG file type.

Notification with a custom icon.

var systemuserid = "<user-guid>";
var notificationRecord = 
{
  "title": "Welcome",
  "body": "Welcome to the world of app notifications!",
  "ownerid@odata.bind": "/systemusers(" + systemuserid + ")",
  "icontype": 100000005, // custom
  "data": "{ 'iconUrl': '/WebResources/cr245_AlertOn'}"
}
Xrm.WebApi.createRecord("appnotification", notificationRecord).
  then(
      function success(result) {
          console.log("notification created with custom icon: " + result.id);
      },
      function (error) {
          console.log(error.message);
          // handle error conditions
      }
  );

Notification with a custom title and body

This example adds a custom title and a body definition that allows multiple links, bold formatting, and italic formatting.

Notification that includes a custom title, multiple links, bold text, and italic formatting.

var systemuserid = "<user-guid>";
var notificationRecord = 
{
    "title": "Complete overhaul required (sample)",
   "body": "Maria Campbell mentioned you in a post.",
   "ownerid@odata.bind": "/systemusers(" + systemuserid + ")",
    "icontype": 100000004, // mention
    "data": JSON.stringify({
    "title": "[Complete overhaul required (sample)](?pagetype=entityrecord&etn=incident&id=0a9f62a8-90df-e311-9565-a45d36fc5fe8)",
    "body": "[Maria Campbell](?pagetype=entityrecord&etn=contact&id=43m770h2-6567-ebm1-ob2b-000d3ac3kd6c) mentioned you in a post: _\"**[@Paul](?pagetype=entityrecord&etn=contact&id=03f770b2-6567-eb11-bb2b-000d3ac2be4d)** we need to prioritize this overdue case, [@Robert](?pagetype=entityrecord&etn=contact&id=73f970b2-6567-eb11-bb2b-000d3ac2se4h) will work with you to engage with engineering team ASAP.\"_",
     "actions": [
      {
        "title": "View record",
       "data": {
       "url": "?pagetype=entityrecord&etn=incident&id=0a9f62a8-90df-e311-9565-a45d36fc5fe8"
       }
      }
     ]
    })
}
Xrm.WebApi.createRecord("appnotification",notificationRecord).
  then(
      function success(result) {
          console.log("notification created with custom title and body: " + result.id);
      },
      function (error) {
          console.log(error.message);
          // handle error conditions
      }
  );

In-app notifications vs. push notifications

The Power Apps Notification connector is for push notifications, which are separate from in-app notification. Push notifications only appear on the mobile device notifications list to open the app. In-app notifications appear when the app is open. We recommend limiting the use of push notifications to high-priority items, to avoid overwhelming the user. For more information, go to: