XSendAppNotification and related action functions (preview)

Applies to: Canvas apps Model-driven apps

[This article is pre-release documentation and is subject to change.]

Send an in-app notification with optional actions to a recipient.

Important

• This is a preview feature.
• Preview features aren’t meant for production use, may have restricted functionality, and may change significantly before release. These features are available before an official release so that customers can get early access and provide feedback.
• To help identify these as preview features, each function is prefixed with an X. Upon release, the X will need to be removed from any formulas that use these functions and arguments updated for any function changes.
• These functions can only be used with the Dataverse low-code plug-ins.

Description

The XSendAppNotification function is used to send notifications within an app to a recipient. These notifications appear as either a toast or within the notification center for the app user. For more information, see Send in-app notifications within model-driven apps.

In addition, an in-app notification can include zero to many actions on the notification card. To add actions to the app notification card, the following functions are used as parameters in the XSendAppNotification function. For more information on each action type, see Notification actions.

• XCreateUrlAction: Adds a URL action to the notification card.
• XCreateSidePaneActionForDashboard: Adds a side pane action that navigates to a page with a type of dashboard within the side pane.
• XCreateSidePaneActionForEntity: Adds a side pane action that navigates to a page with a type of entityrecord within the side pane.
• XCreateSidePaneActionForEntityList: Adds a side pane action that navigates to a page with a type of entitylist within the side pane.
• XCreateTeamsChatAction: Adds a Teams chat action to the notification card.

Syntax

XSendAppNotification

XSendAppNotification (Title, Recipient, Body, Actions, Icon Type, Toast Type, Expiry, Priority)

Parameter	Type	Required	Description
Title	String	Yes	The title of the app notification.
Recipient	Entity	Yes	An entity of systemuser who is the recipient of the notification.
Body	String	No	The notification body.
Actions	Function	No	An array of the action functions to add actions ot the notification.
Icon Type	Int	No	Picklist value for the type of icon (info, success, failure, warning, mention, custom).
Toast Type	Int	No	Picklist value for the type of toast (timed versus hidden).
Expiry	Int	No	The number of seconds from when the notification should be deleted if not already dismissed.
Priority	Int	No	Picklist value for the priority of notification (normal or high).

XCreateUrlAction

XCreateUrlAction (Title, URL, Navigation Target)

Parameter	Type	Required	Description
Title	String	Yes	The title that displays for the action.
URL	String	Yes	The URL to be opened when the action is selected.
Navigation Target	String	No	Defines where the navigation link opens. The options are: dialog: Opens in the center dialog. inline: Default. Opens in the current page. newWindow: Opens in a new browser tab.

XCreateSidePaneActionForDashbaord

XCreateSidePaneActionForDashboard (Title, Pane ID, Pane Title, Dashboard ID)

Parameter	Type	Required	Description
Title	String	Yes	The title that displays for the action.
Pane ID	String	Yes	The ID of the new side pane.
Pane Title	String	Yes	The title to display for the side pane.
Dashboard ID	GUID	Yes	The ID of the dashboard to open in the side pane.

XCreateSidePaneActionForEntity

XCreateSidePaneActionForEntity (Title, Pane ID, Pane Title, Entity Name, Entity ID)

Parameter	Type	Required	Description
Title	String	Yes	The title that displays for the action.
Pane ID	String	Yes	The ID of the new side pane.
Pane Title	String	Yes	The title to display for the side pane.
Entity Name	String	Yes	The logical name of the entity.
Entity ID	String	Yes	The ID of the entity record to open in the side pane.

XCreateSidePaneActionForEntityList

XCreateSidePaneActionForEntityList (Title, Pane ID, Pane Title, Entity Name)

Parameter	Type	Required	Description
Title	String	Yes	The title that displays for the action.
Pane ID	String	Yes	The ID of the new side pane.
Pane Title	String	Yes	The title to display for the side pane.
Entity Name	String	Yes	The logical name of the entity to open as a list in the side pane.

XCreateTeamsChatAction

XCreateTeamsChatAction (Title, Chat ID, Member IDs, Record ID, Entity Name, Initial Message)

Parameter	Type	Required	Description
Title	String	Yes	The title that displays for the action.
Chat ID	String	No	If opening an existing chat, the ID of the chat session to be opened.
Member IDs	GUID	No	If creating a new chat, an array of Microsoft Entra Object ID values of the participants to be included in the chat.
Record ID	GUID	No	If linking to a Dynamics 365 record, the ID of the record to which the chat should be linked.
Entity Name	String	No	If linking to a Dynamics 365 record, the logical name of the entity of the record to which the chat should be linked.
Initial Message	String	No	An introductory message of the new chat.

Examples

In-app notification with a title, recipient, and body

The following sends a simple in-app notification to a recipient with a title and body. It doesn't include any actions and utilizes default values for all other parameters.

XSendAppNotification(
    "Welcome", 
    LookUp(Users, 'Primary Email'="<User's email address>"), 
    "Welcome to the world of in-app notifications!"
)

In-app notification with two actions

The following example formula can be used with an automated plugin when a a new Task record is created. The formula is designed to send an in-app notification to the owner of the task record. The notification card contains two actions that the owner can take:

• A side pane action, opens the new task record in a side pane.
• A Teams chat action, initiates a Teams chat with the owner of the account record that is assigned as the Regarding table record for the new task. It's important to note that this assumes an account record has been selected in the task field.

XSendAppNotification(
	"New task assigned",
	AsType(ThisRecord.Owner, Users),
	"A new task has been assigned to you to follow up with your customer",
	[XCreateSidePaneActionForEntity(
		"View task",
		1123,
		"Your task",
		"task",
		ThisRecord.Task    
		),
	XCreateTeamsChatAction(
		"Chat with account manager",
		[AsType(AsType(ThisRecord.Regarding, Accounts).Owner, Users).'Microsoft Entra Object ID'],
		AsType(ThisRecord.Regarding, Accounts).Account, 
		"account", 
		ThisRecord.Description
		)
	]
)