Sending in-app notifications to your SAS Viya users
For administrators, communicating clearly with users is important. Keeping users informed about important goings-on that may affect them can help with reducing any negative impact; for example, in scenarios where outages are required to address an incident or to perform routine maintenance. Forewarned is forearmed. A new CLI plugin allows administrators to proactively initiate messages to send to users, which will appear in the UI when users log in to a SAS Viya application.
New in 2021.1.3 is a notifications plug-in to the sas-viya CLI. The notifications plug-in allows administrators (any member of the SAS Administrators group) to send a notification message to users from the command line, which a command that looks something like:
/opt/sas/viya/home/bin/sas-viya notifications send --message "The system will be going down in 30 minutes." --subject "System outage" --level alert
{
"category": "system",
"level": "alert",
"links": null,
"message": "The system will be going down in 30 minutes.",
"read": false,
"subject": "System outage",
"type": "customAdminNotification",
"userId": "geladm"
}
The notification was sent successfully.
Notifications must include a subject, message, and level (alert, warn or info) as required fields. Thy are sent with REST calls through the Notifications service. Notifications are distributed to all users (although this may change in future updates) provided they have logged in to a SAS application at least once before. They appear in all visual interfaces in the notifications menu (bell icon), which also displays a count of unread notifications.
Note that the subject is displayed, but the value of the message parameter is not. It’s therefore important to include a sufficient amount of information in the subject of a notification.
A user can also view the notifications they have received using the notifications CLI plugin, which provides a lot more detail about a notification:
/opt/sas/viya/home/bin/sas-viya notifications list
{
"items": [
{
"category": "system",
"creationTimeStamp": "2021-08-25T05:30:36Z",
"id": "6f39d06d-c37b-43c6-ab26-e9cfc1723598",
"level": "alert",
"links": [
{
"href": "/notifications/notifications/6f39d06d-c37b-43c6-ab26-e9cfc1723598",
"method": "GET",
"rel": "self",
"type": "application/vnd.sas.notification",
"uri": "/notifications/notifications/6f39d06d-c37b-43c6-ab26-e9cfc1723598"
},
{
"href": "/notifications/notifications/6f39d06d-c37b-43c6-ab26-e9cfc1723598",
"method": "DELETE",
"rel": "delete",
"type": "",
"uri": "/notifications/notifications/6f39d06d-c37b-43c6-ab26-e9cfc1723598"
},
{
"href": "/notifications/notifications/6f39d06d-c37b-43c6-ab26-e9cfc1723598/readState",
"method": "GET",
"rel": "read",
"type": "text/plain",
"uri": "/notifications/notifications/6f39d06d-c37b-43c6-ab26-e9cfc1723598/readState"
},
{
"href": "/notifications/notifications/6f39d06d-c37b-43c6-ab26-e9cfc1723598/readState?value=false",
"method": "PUT",
"rel": "markUnread",
"type": "text/plain",
"uri": "/notifications/notifications/6f39d06d-c37b-43c6-ab26-e9cfc1723598/readState?value=false"
},
{
"href": "/notifications/notifications",
"method": "GET",
"rel": "up",
"type": "application/vnd.sas.collection",
"uri": "/notifications/notifications"
},
{
"href": "/notifications/subscriptions/decf4dc8-866d-40ce-90da-ae4a4213ee01",
"method": "GET",
"rel": "subscription",
"type": "application/vnd.sas.notification.subscription",
"uri": "/notifications/subscriptions/decf4dc8-866d-40ce-90da-ae4a4213ee01"
}
],
"message": "The system will be going down in 30 minutes.",
"publishTimeStamp": "2021-08-25T05:30:36Z",
"read": true,
"recipientId": "Henrik",
"subject": "System outage",
"subscriptionName": "Administrator generated notification",
"type": "customAdminNotification",
"userId": "sasboot",
"version": 2
}
]
}
The output can be filtered by read/unread state, level, sender, and more (add the -h flag to the command to view the inline help to view all options).
It’s also possible to send notifications from SAS Environment Manager, by following these instructions. Notifications sent from Environment Manager will always be of “alert” type and do not have a message – the notification text is sent as the subject.
Note that the notifications created above have a category attribute with a value of “system”. Administrator-initiated notifications sent using the methods above are system notifications. There are other notification types though (for example, from applications like SAS Visual Analytics, Workflow Manager and the Backup service). These notifications are sent automatically from the source applications (again, using the Notifications service). For example, when sharing a VA report, the user you are sharing with is notified.
These kind of notifications can also be viewed using the CLI, and they have a category value of “application” as shown below. Other properties vary by product.
/opt/sas/viya/home/bin/sas-viya --output text notifications show --id c1b67c5c-ea63-4b9c-8bed-936fd1d4f869
Id c1b67c5c-ea63-4b9c-8bed-936fd1d4f869 Version 2 Type shareActivity Category application Source Level info RecipientId Hazel Read false Message The item "Q1 Revenue" has been shared with you by "Henrik". You have the following permissions for that item: Read, Edit, Share Subject The item "Q1 Revenue" has been shared with you by "Henrik". UserId Hazel SubscriptionName Notifications about sharing activities PublishTimeStamp 2021-08-25T05:52:25.305Z CreationTimeStamp 2021-08-25T05:52:25.305Z Properties map[shareType:readEditShare sharedWithType:user] DetailsVersion 2 DetailsType application/vnd.sas.event.notification Details
If you’ve set your mail server’s connection details in the configuration, notifications are also sent via email (as long as the sas.notifications.delivery configuration instance’s mailEnabled property is turned on).
These new updates to notifications make the process of reaching your users quickly (and effectively!) nice and easy. Displaying messages in the UI is a nice visual complement (or replacement) to notifying users about things like outages via email.
Thanks for reading. Leave a comment below to ask questions or share your own experiences.
Find more articles from SAS Global Enablement and Learning here.
