Workspace Notifications

Workspace notifications are alerts that inform users about specified events within the Appway Workspace. Example events could include an approval request – or, if used in conjunction with Workspace Collaboration, the user receiving an invitation to join a chat, or being mentioned in a discussion.

Introduction

This document outlines the components and functions that together make up Workspace Notifications:

Basic Notifications

Workspace Notifications allows alerts, known as "notifications", to be sent to a set of groups, roles, and/or users.

Every user has an FNZ Studio-internal notification inbox. The inbox can be displayed in different ways, using Workspace Notification Screen components:

• Notification List – for a dedicated list of notifications
• Notification Alert – for instant on-screen alerts
• Notification Popup – to display notifications via a popup widget
• A combination of these options

More details can be found in Screen Components.

Notifications from the FNZ Studio solution are sent using Script Functions. Extensions can also send notifications via the FNZ Studio SDK. Furthermore, notifications can be removed programmatically from users’ inboxes via a Script Function and the SDK.

When the system detects a user has read a notification, that notification is marked as read in the user’s notification inbox. A notification is classed as "read" once the user has clicked on it (for alerts, the list and the popup widget). With the popup widget, you can also configure notifications to automatically be marked as read once the popup has been opened, and then closed.

As illustrated in the image below, the notifications in the list already read by that user are no longer bold.

Delivery Channels

Every user has a notification inbox within FNZ Studio by default. Notifications can also be sent outside of FNZ Studio via other communication channels. FNZ Studio sends messages externally via "Notification Delivery Channels". When you send a notification, you can specify a list of delivery channel IDs. The notification backend will then take your notification and hand it to each of the specified delivery channels for delivery.

FNZ Studio’s default internal notification delivery is done via the "appway" delivery channel, implemented in the FNZ Studio core. When the "appway" delivery channel receives a notification to deliver, it stores the notification in the recipient’s FNZ Studio-internal notification inbox.

A further Notification Delivery Channel could be, for example, the "email" channel, implemented in the Mail Extension. When the Mail Extension gets a notification to deliver, it reads the recipient's user email address from the user's profile, and sends the notification to the email address listed. For more information on the email channel, see Mail Extension.

External communication systems can be integrated into the FNZ Studio notification system by implementing further Notification Delivery Channels via extensions.

The following extensions currently provide additional delivery channels:

• MailExtension (version 2.0 or greater): Deliver notifications via email
• SMSAdapter (version 3.0 or greater): Deliver notifications via text messages

Topics and Subscriptions

Workspace Notifications provides a publish-subscribe mechanism for notifications, based on the concepts of "subscriber" and "topic":

• A subscriber is a user, group, or role.
• A topic is a category of notifications that can be freely defined. A topic is identified by an arbitrary unique String ID.

Topics and subscriptions can be managed via:

• Script Functions (see Functions)
• Subscription Screen Components (see Screen Components)
• The FNZ Studio Composition (see Studio Administration and Monitoring)

Using Topics

Topics do not automatically generate notifications as soon as they are created, as the system simply does not know when or what to send as a notification to users. Immediately after creating the topic "New American Client", for example, there are, by default, no notifications related to that topic. To make topics work correctly, you have to set when a notification with that topic is to be sent regarding a process or event. With the topic "New American Client", you could choose to send notifications at the end of the client onboarding process, should the client be from the US, for example.

When a notification is generated – either using a Script Function (see Send a Notification with Topics) or the Appway SDK – you can specify a set of topics for the notification. This allows a decoupling of notification senders from recipients: You don’t have to know the user ID of every recipient of a specific notification when one is sent, only the relevant topic.

Using Subscriptions

Each user can be added to, or choose to subscribe to notifications on certain topics. A subscription means that a user receives all notifications corresponding to the given topic.

Subscriptions also support delivery channels. More precisely, every "subscription" is actually a combination of subscriber, topic, and delivery channel. If users subscribe to a certain topic via the delivery channel "appway", they only receive notifications for that topic in their FNZ Studio notification inbox. If the Mail Extension is installed and the users are also subscribed to the topic via the email delivery channel, they receive notifications for that topic via e-mail, in addition to the notification in their FNZ Studio inbox. Or, if they are not subscribed to the "appway" channel but only via email, they are notified via email only.

Using these mechanisms, users, complete groups and/or roles can be subscribed to topics via delivery channels.

Returning to the example of a client onboarding solution with a topic called "New American Client": All employees who need to be informed about new American clients are subscribed to this topic, from Relationship Managers, to Compliance, to FATCA Subject Matter Experts. If the onboarded client is a US citizen, a notification on the topic "New American Client" is sent out at the end of the client onboarding process, and all subscribed employees receive the notification. If the onboarded client has no ties to the US, no notification is generated.

You may also want to control subscriptions in a more fine-grained way. For example, a manager might decide to subscribe a group to a certain topic, but some users in the group might decide that they do not want to receive notifications for the topic; that is, they want to be excluded from the subscription. Users can exclude themselves from group and role subscriptions via the subscription Screen Components. Users can also be excluded via Script Functions (as part of the business logic), or via the FNZ Studio Composition (for administration).

So, when a notification message for a topic is sent, it is delivered to all users:

• Who are directly subscribed to the topic with their user ID
• Who are part of at least one group that is subscribed to the topic, and not excluded from the subscription
• Who are part of at least one role that is subscribed to the topic, and not excluded from the subscription

The user who triggered a notification does not receive a notification if you specify that the triggering user should be excluded as a recipient of that notification.

It is also possible to send a publish-subscribe notification message with specified recipients. In this case, the notification is delivered to the intersection of the subscribed users and the supplied recipients, that is, users who are both subscribed to a topic and explicitly included as recipients in the notification.

You can therefore have general topics but specific addressees for any specific notification. A topic of this kind could be "My new American Clients". Notifications for that topic would not be sent to all users subscribed to the topic, but only to the key account manager assigned to that client, if that specific manager has not unsubscribed from the topic.

Notification Text Format

Notification messages contain text in String format.

FNZ Studio Labels are supported in both the notification text and notification type.

HTML is not supported in the message text for security reasons (the Screen components escape user-entered text). Furthermore, the notifications could be displayed in an e-mail or SMS, where HTML is not supported.

You can add links and user attributions (mentions) to the messages using the following LaTeX-inspired annotations inside the message text:

For example, to add a link to a programmatically generated notification, use the String, "This is a \link{http://www.appway.com}{Link to Appway}".

Multiple Inboxes per User

There can be several notification inboxes per user within FNZ Studio. Note that this mechanism is different from notification delivery channels. Delivery channels are there to implement different ways to reach a user (for example, through the FNZ Studio workspace, or by email); users can be allowed to manage which notifications they want to receive through which channels. Having many inboxes is a mechanism specific only to the FNZ Studio delivery channel. A user can have several inboxes for notifications within FNZ Studio, where a notification is assigned to exactly one of the inboxes based on a configured rule.

This allows you to display different notification icons and corresponding pop-ups, where each pop-up contains a notification of a certain kind. This makes sense from a user experience point of view when there are notifications of different importance/urgency, or for very different events. Then, the user can see how many new notifications there are for each inbox – even if the inboxes are closed – and can quickly react to important notifications.

To set up notification inboxes, you need to configure a Script Function that defines which notification goes to which inbox by returning an inbox ID for a given notification. This Function is similar to a rule in your email client which automatically puts incoming email into a certain folder based on the sender, subject, or content.

The inbox is not defined when sending the notification, but automatically chosen based on this Function, which essentially defines a rule to decide to which inbox an incoming notification should go. In the Screen, you just add different notification pop-up components, configure an icon and add the corresponding inbox ID for the different inboxes.

For details on configuration, see Multiple Inboxes.

Architecture

The Notifications architecture can roughly be divided into two parts, back end and front end.

The front end of the Notifications consists of Screen components that are implemented entirely in the Component Extension. The client side of the Screen components updates its state via RESTful AJAX requests to the server. The requests are triggered at regular polling intervals and on user interaction. The state is kept only on the client.

Screen components send independent requests, but listen to all the related responses in the page. They will update if the received content is relevant to their scope. For example, consider the case of a Notification List and a Notification Alert on the same page. As said, they communicate separately with the server. Let's assume that the Notification List sends a request, and the response contains a new notification. The Notification Alert will also handle the response and show the new notification, instead of waiting for its independent request to fetch the update.

The back end of Notifications is implemented in the FNZ Studio core. The notification data is distributed amongst the nodes of the cluster, relying on the Hazelcast in-memory datagrid. Every sent notification message is stored once, and a reference to the notification is added to each recipient’s notification inbox by the FNZ Studio notification delivery channel. In a productive system, over time, both the number of notification messages and the size of the notification inboxes grow. This can become a problem especially on file system storage, since each notification is stored in its own file and management operations (such as listing all files) become slow with many files. Furthermore, loading and storing notification inboxes becomes increasingly expensive as they grow. To prevent these issues, notifications older than a configurable number of days are deleted periodically.

Notifications offer APIs that can be used by FNZ Studio extensions to deploy topics, send notifications, and provide additional notification delivery channels (see Delivery Channels).

Security

Notification security is based on FNZ Studio authentication and authorization: A Screen in FNZ Studio is only accessible for authorized users, so any notifications displayed on a Screen are also only accessible for authorized users as well.

However, notification data is not only accessed in regular FNZ Studio HTTP requests on processes or Screens. As described in Chapter 2 above, the notification Screen Components rely on AJAX requests to periodically fetch new notifications or send updates to the server. To ensure that these requests are also secure, notifications have an additional security mechanism.

When a notification Screen Component is rendered, a token is generated based on the user ID of the requesting user. Every AJAX request by the Component has to include the token; the token validity is checked on the server side. This makes sure that AJAX requests come from authenticated and authorized sources only.

The token is constructed from a deterministic and a random part, and is then hashed using a configurable hashing algorithm. The stronger the hashing algorithm is, the harder it is to guess the token. The three options for the hashing algorithm are:

• crypt (cryptographically secure)
• md5 (non-trivial)
• none (trivial)

Computing the cryptographic hash, however, is computationally expensive. Thus, we recommend the md5 configuration, which is also the default.

Installation and Configuration

This chapter covers requirements for using Notifications, installing the necessary extension to use notifications, and highlights known compatibility issues.

Requirements

Your FNZ Studio installation can be a single-node or a cluster installation.

If you expect a large number of notifications (more than 10,000 notifications present in your system at a time, for example), it is recommended that you use Cassandra or a relational database as FNZ Studio’s storage layer. See Notifications Architecture for more information.

Installation

Upload and start the ComponentExtension on your FNZ Studio system.

Configuration

Security

The hashing algorithm for the security token (see Security) can be configured via the property notification.security.level. The default security is set to md5. Other possible values are crypt and none.

Notification Cleanup

As described in Notifications Architecture, there is a Notification Cleanup Job which runs every day. This Cleanup Job deletes old messages and their corresponding inbox entries. You can see statistics relating to its execution in System Maintenance > System Overview > Job Scheduler. How old a notification needs to be to be considered "old" can be configured via the FNZ Studio configuration property nm.usermessaging.notification.ttl_days. The default age is 30 days.

Notification Removal

Notifications can be removed programmatically (see Removing Notifications). In order to apply the removal in client’s inboxes without a page reload, the components also poll for notification removals; FNZ Studio remembers notification removal operations for a certain amount of time to be able to answer these poll requests. This time can be configured via the FNZ Studio configuration property nm.usermessaging.notification.inbox.history.ttl_seconds. The default time is 60 seconds. It is generally safe to leave this on the default value. You just have to make sure that this value is at least twice the configured poll interval on the components if you change the poll interval.

Screen Component Polling Interval

Notification Screen Components poll the server to fetch updates. The default polling interval is 5 seconds. This value can be changed using the notification.pollTimeout property of the ComponentExtension.

User Profile Page

If your solution has a User Profile page, you can put the URL of that page in the property nm.usermessaging.userprofile.url. Adding the URL causes users' names and avatars contained in notifications to link to their User Profile page. The URL should contain the {userId} placeholder that is replaced by the actual user ID. If the URL does not contain the placeholder, the query string ?userId={userId} is automatically appended to the URL.

Multiple Inboxes

There can be multiple notification inboxes per user within FNZ Studio (see Multiple Inboxes per User). To use this feature, you need to define a Script Function which chooses an inbox for every incoming notification. This Script Function must have the following signature:

Function ChooseNotificationInbox(NotificationMessage $message) : String Begin 

// Example: Assign notifications to different inboxes based on their type property

Return $message.getType();

End

To configure this Function to be used to assign notifications to inboxes, set the following property:

nm.usermessaging.notification.inbox.function.id = ChooseNotificationInbox

By default, this Function is always called with the current version filter. If the notification is sent from a process, for example, the filter would be the process filter. Alternatively, you can define the version filter to be used using the following property:

nm.usermessaging.notification.inbox.function.versionfilter

Compatibility

Using Workspace Notifications requires one the following browsers:

• Internet Explorer 11
• Safari (latest version)
• Chrome (latest version)
• Firefox (latest version)

Notification Screen Components

'Notifications' comprises five Screen components, found under 'Other' in the Screen Editor:

• Notification List
• Notification Alert
• Notification Popup
• Notification Topic Subscription
• Notification Single Topic Subscription

Notification List

The Notification List Screen Component shows the notifications received by a user. Clicking a notification marks it as read.

Notification List: edit mode

Notification List: preview mode

Notification List Configuration

The Notification List Screen Component has the following configuration properties (Properties tab):

• Show Notification Icon – If selected, the notification icon is displayed. By default, it is the avatar of the user who triggered the notification, which appears next to that notification in the list. If this property is selected, the following property is also available:
  • Use Notification Type Icon – If selected, the user's avatar is not displayed. It is replaced by another element (e.g. an icon representing the type of notification) if custom CSS is applied. By default, no other element is displayed.
• Timestamp Format Pattern – allows you to select a Format Pattern Business Object to set the desired date format.
• Inbox Id – (Optional) ID of the Notification Inbox to load for the given user. Define a Script Function that takes a NotificationMessage and returns a String representing the Inbox ID. Then, set the nm.usermessaging.notification.inbox.function configuration property to this ID.

Notes on the Show Notification Icon and Use Notification Type Icon properties:

• You can set an avatar on the users’ profile pages in Studio, or import it through the LdapSyncAdapter extension.
• If you select the Use Notification Type Icon property, the user's avatar is replaced by the icon chosen to represent that message type. There are no pre-existing type icons contained within Workspace Notifications. Type icons have to be styled through an external CSS resource. The type name is set as CSS class to the notification icon, which is a div HTML element. For example, this could be the code:

.awNotificationElement_userAvatar:empty {   

        width: 32px;   

        height: 32px; 

}  

.Community {   

        background-image: url('{ CONTEXT_PATH }/resource/object/aw.defaultpages.portal.CommunityIcon/TimestampFilter-1565273023829/community.png');

        background-size: cover;

}

With the result:

Notification List Style Business Object

The Notification List Style Business Object (Style tab) allows customizing the appearance of a Notification List (numbers refer to the styling properties described below). See also: Style Business Object and Virtual Style Business Object.

• Background – Sets the background color for the whole component.
• Border – Sets the style (thickness, color, and so on) of the border for the whole component.
• Notification Element Separator – (1) Sets the style (thickness, color, and so on) of the line that separates each single notification.
• Inner Spacing – Sets the space between the message area and the component border.
• Toolbar Actions – (2) Refers to a Button Style Business Object to set the style of the action buttons, such as Mark All as Read, or Delete All.
• Show More Button – Refers to a Button Style Business Object to set the style of the corresponding button.
• Notification Element (virtual) – (3) Refers to a Notification Element (virtual)Style Business Object to style each individual notification (see below).

Notification Element (Virtual) Style Business Object

The Notification Element (Virtual) Style Business Object is referenced from the Notification List Style Business Object to style each single notification:

The Notification Element (Virtual) Style Business Object has a further state beside the Default one:

• Unread – State of the notification when it has not been read yet.

The Notification Element (Virtual) Style Business Object allows styling each single notification (numbers refer to the styling properties described below).

• Background – Sets the background color for the whole component.
• Topic Background – (1) Sets the background color for the area where the notification topic is described (under the notification itself).
• Border – Sets the style (thickness, color, and so on) of the border for the whole component.
• Inner Spacing – Sets the space between the message area and the component border.
• Notification Username – (2) Refers to a Text Style Business Object to set the style of the name of the user sending the notification.
• Notification Type – (3) Refers to a Text Style Business Object to set the style of the text indicating the type of notification on the top-right corner.
• Notification Content – (4) Refers to a Text Style Business Object to set the style of the actual notification message.
• Notification Link/Mention – (5) Refers to a Link Style Business Object to set the style of the links or user mentions contained in the notification message.
• Notification Timestamp – (6) Refers to a Link Style Business Object to set the style of the notification timestamp.
• Topic Label – (7) Refers to a Text Style Business Object to set the style of the text indicating the notification topic.

Notification Alert

The Notification Alert is a semi-transparent box that appears on users' screens as soon as they receive a notification. Clicking on the notification alert marks it as read, and makes it disappear.

Notification Alert: edit mode

Notification Alert: preview mode

Notification Alert Configuration

The Notification Alert Screen Component has the following configuration properties (Properties tab):

• Show Notification Icon – If selected, the notification icon is displayed. By default, it is the avatar of the user who triggered the notification, which appears next to that notification in the list. If this property is selected, the following property is also available:
  • Use Notification Type Icon – If selected, the user's avatar is not displayed. It is replaced by another element (e.g. an icon representing the type of notification) if custom CSS is applied. By default, no other element is displayed.
• Show Notification Type – If selected, the notification type (e.g. Chat) is shown on the top-right corner of the alert.
• Inbox Id – (Optional) ID of the Notification Inbox to load for the given user. Define a Script Function that takes a NotificationMessage and returns a String representing the Inbox ID. Then, set the nm.usermessaging.notification.inbox.function configuration property to this ID.

Notification Alert Style Business Object

The Notification Alert Style Business Object (Style tab) allows customizing the appearance of a Notification Alert (numbers refer to the styling properties described below).

• Background – Sets the background color for the whole component.
• Topic Background – (1) Sets the background color for the area where the notification topic is described.
• Border – Sets the style (thickness, color, and so on) of the border for the whole component.
• Shadow – Sets the shadow effect for the component.
• Inner Spacing – Sets the space between the message area and the component border.
• Outer Spacing – Sets the space between the component and the outer element (e.g. a Layout Container).
• Notification Username – (2) Refers to a Text Style Business Object to set the style of the text representing the name of the user who sent the notification.
• Notification Type – (3) Refers to a Text Style Business Object to set the style of the text indicating the type of notification in the top-right corner.
• Notification Content – (4) Refers to a Text Style Business Object to set the style of the actual notification message.
• Notification Link/Mention – (5) Refers to a Link Style Business Object to set the style of the links or user mentions contained in the notification message.
• Notification Timestamp – (6) Refers to a Text Style Business Object to set the style of the message timestamp.
• Topic Label – (7) Refers to a Text Style Business Object to set the style of the text indicating the notification topic.

Notification Popup

The Notification Popup is a button that displays the number of unread notifications. When clicked, the Notification List appears next to it.

Notification Popup: edit mode

Notification Popup: preview mode

Notification Popup Configuration

The Notification Popup Screen Component has the following configuration properties (Properties tab):

• Popup Position – Sets the position of the component in relation to the popup button:
  • Top left
  • Top right
  • Bottom left
  • Bottom right
• Mark All as Read when Closing the Popup – If selected, all notifications are marked as read when closing the Popup. If deselected, you need to click on each notification to mark it as read.
• Popup Icon – Allows selecting the icon identifying the button opening the Popup.
• Icon Color – Allows changing the color of the Popup icon if you are using SVG icons (as set through the nm.workspace.icons.preferredIconType configuration property).
• Show Notification Icon – If selected, it shows the notification icon. By default, it is the avatar of the user who triggered the notification. If selected, the following property is displayed:
  • Use Notification Type Icon – If selected, the user's avatar is not displayed. It is replaced by another element (e.g. an icon representing the type of notification) if custom CSS is applied. By default, no other element is displayed.
• Timestamp Format Pattern – Allows selecting a Format Pattern Business Object to set the desired date format.
• Inbox Id (optional) – (Optional) ID of the Notification Inbox to load for the given user. Define a Script Function that takes a NotificationMessage and returns a String representing the Inbox ID. Then, set the nm.usermessaging.notification.inbox.function configuration property to this ID.

Notification Popup Style Business Object

The Notification Popup Style Business Object (Style tab) allows customizing the appearance of a Notification Popup (numbers refer to the styling properties described below).

• Badge Color – (1) Refers to a Color Style Value Business Object to set the color of the badge indicating the number of unread notifications.
• Unread Notification Badge – (2) Refers to a Text Style Business Object to set the style of the number of unread notifications inside the badge.
• Icon – (3) Refers to an Icon Style Business Object to set the style of the button opening the Notification Popup.
• Notification List – (4) Refers to a Notification List Style Business Object to set the style of the Notification List displayed when clicking on the Popup button.
• Popup – (5) Refers to a Popup (virtual) Style Business Object to set the style of the popup itself.

Notification Topic Subscription

The Topic Subscription Widget allows the user to subscribe and unsubscribe from topics. The concepts of 'topics' and 'subscriptions' are covered in more detail in Topics and Subscriptions.

The subscription window the user sees is illustrated below:

Notification Topic Subscription Configuration

The following properties are available:

• Topics – The list of topics to display. If the list is empty, all existing topics are displayed.

Notification Single Topic Subscription

The Notification Single Topic Subscription is for use when there is only one possible topic that the user could be subscribing to within the context they are in.

Notification Single Topic Subscription Configuration

The following properties are available:

• Topic ID – The ID of the topic the user can subscribe to or unsubscribe from .

All Topic IDs for the topics created are listed under: Solution Maintenance > Processes > Notification Management > Topics

Functions

This chapter discusses the functions related to notifications, grouped by theme. The first section covers the primitive types used as parameters or return types. Further sections outline the functions' purpose, parameters and return values.

Primitive Types

UserMessageLink

A UserMessageLink represents a link in a notification message. Links are added to the text of the notification via a special markup (see Notification Text Format). The methods are:

• String getLabel() – Get the label for the link
• String getLinkURL() – Get the link URL
• boolean isMainLink() – Check if the link is the main link in the notification

UserMessageAttachment

Note: Attachments for notifications are already available in the APIs, but are not yet supported.

A UserMessageAttachment is a reference to a cluster file that can be attached to a notification message. Note that the Screen Components do not currently display the attachments. The constructor and methods are :

• Constructor NEW(UserMessageAttachment, $name, $mimetype, $clusterFileID) – Create an attachment with name, mime type (can be null), and the cluster file ID
• String getName() – Get the name of the attachment (never null)
• String getMimeType() – Get the mime type of the attachment (can be null)
• String getClusterFileID() – Get the ID of the cluster file this attachment references (never null)

NotificationMessage

The Primitive Type NotificationMessage is an abstract class that represents a notification message in Workspace Notifications. There are two concrete subclasses:

• AddressedNotificationMessage – A notification message with an explicit set of recipients
• PubSubNotificationMessage – A notification message with topics that is sent to all who are subscribed to that topic

The NotificationMessage is the message that is submitted to the system and is shared between all recipients. Every recipient user, however, has a view on a NotificationMessage that is represented by the 'Notification' type.
The NotificationMessage object contains:

• The sender's User ID
• The 'send' timestamp
• The message text
• Attachments (references to cluster files attached to the message)

Available methods are:

• String getID() – Get the ID of the message
• String getUserID() – Get the user ID of the user on behalf of whom the notification is sent
• long getTimestamp() – Get the timestamp when the notification was sent in milliseconds
• String getType() – Get the type of the notification (freely defined and specified when sending the notification)
• String getTypeTranslated() – Get the type of this notification translated to the current user's language, or null if the notification has no type
• String getTypeTranslated(String $language, String $userID) – Get the type of this notification translated to the given language (if any) or the given user's language (if any), or the current language
• String getText() – Get the notification text. It is plain text, possibly containing annotations as described in Section Notification Text Format
• String getTextTranslated() – Get the text with labels translated to the current language (in an HTTP request, the current user's language)
• String getTextTranslated(String $language, String $userID) – Get the text with labels translated. The language is determined as follows:
  • If a language is specified, the string is translated to the given language
  • If no language but a user ID is specified, the string is translated to the language guessed for the given user.
  • If neither language nor user are specified, the string is translated to the current language (in an HTTP request, the current user's language).
• String getTextAsPlainText(String $language, String $userID) – Get the text as plain text (mentions, attributions, and links are converted to plain text) and translated depending on the $language and $userID arguments. For a description of how the language to translate to is determined, see String getTextTranslated(String $language, String $userID).
• String getTextAsHTML(String $language, String $userID) – Get the text as plain text (mentions, attributions, and links are converted to links) and translated depending on the $language and $userID arguments. For a description of how the language to translate to is determined, see String getTextTranslated(String $language, String $userID).
• String getTextConverted(String $attributionSubst, String $mentionSubst, String $linkSubst, String language, String $userID) – Get the text with annotations replaced with the given replacements and translated depending on the $language and $userID arguments. For a description of how the language to translate to is determined, see String getTextTranslated(String $language, String $userID).
  Parameters:
  • $attributionSubst – Substitution for the attributions, placeholders $1 and $2 are replaced with user ID and attribution display value, respectively
  • $mentionSubst – Substitution for the mentions, placeholders $1 and $2 are replaced with user ID and mention display value, respectively
  • $linkSubst – Substitution for the links, placeholders $1 and $2 are replaced with URL and link name, respectively
• List<UserMessageLink> getLinks() – Get the list of links in the notification.
• List<UserMessageAttachment> getAttachments() – Get the attachments of the notification.

Note: Attachments for notifications are already available in the APIs, but are not yet supported.

AddressedNotificationMessage

The Primitive Type AddressedNotificationMessage represents notification messages with a set of recipients that is explicitly supplied when the message is created. The notification is delivered to the recipients supplied to the SendAddressedNotification function via the FNZ Studio notification delivery channel.

Available methods are:

• List<String> getReceivers() – Get the list of receivers (user IDs, groups prefixed with 'GROUP:', and roles prefixed with 'ROLE:') of this notification.
• List<String> getDeliveryChannelIDs() – Get the IDs of the delivery channels via which this notification should be/has been delivered.

PubSubNotificationMessage

The Primitive Type PubSubNotificationMessage represents notification messages with a set of topics. The notification module sends this message to all users who are subscribed to at least one of the message's topics (and not excluded from the corresponding subscription) at the time when the message is sent.

Available methods are:

• List<String> getTopics() – Get the topics specified when sending the notification.
• List<String> getReceivers() – Get the recipients specified when sending the notification.
• boolean isExcludeSendingUser() – Check if the user on behalf of whom the notification was sent was excluded from the delivery (even if that user may be subscribed).

Notification

The Primitive Type Notification represents a user's view of a notification message delivered to that user via the FNZ Studio notification delivery channel: In other words, the objects in the user's notification inbox. The primitive type contains the notification message and a Boolean flag. The flag indicates if the user has read the notification message.

Available methods are:

• NotificationMessage getMessage() – Get the user’s notification.
• boolean isRead() – Check if the user has already read the notification.

NotificationSubscriptionFilter

The NotificationSubscriptionFilter allows you to define properties on the basis of which to filter notification subscriptions. The filter properties and their effect are described in the following table:

• user ID of a user
• group ID with prefix “GROUP:” for a group,
• role ID with prefix “ROLE:” for a role|If set, subscriptions must match the exact same subscriber ID.

• The subscriber ID is their ID
• The subscriber ID is the ID of a group the user is currently part of (irrespective of whether the user is excluded from the subscription or not)
• The subscriber ID is the ID of a role the user is currently part of (irrespective of whether the user is excluded from the subscription or not)

The Primitive Type NotificationSubscriptionRecord represents subscriptions in Workspace Notifications. A subscription is a triple combination of (subscriberID, topicID, deliveryChannelID). Additionally, it contains a set of user IDs that are excluded from the subscription.

If subscription records are retrieved with a filter containing a user ID, the records do not contain the set of excluded users, for performance reasons. A flag that says if the queried user is excluded from the subscription is set instead.

Available methods are:

• String getSubscriberID() – Get ID of the subscriber.
• String getTopicID() – Get ID of the topic.
• getNotificationDeliveryChannelID() – Get ID of the channel.
• List<String> getExcludedUserIDsAsList() – Get the IDs of the users who are excluded from the subscription (only non-null if no user has been specified as part of the filter).
• boolean isQueriedUserExcluded() – Check if the queried user is excluded from the subscription (only set if there was a user specified as part of the filter).

Sending Notifications

Send a Simple Notification

The function SendAddressedNotification sends a notification to a list of recipients (users/groups/roles) and returns the created addressed notification message.

SendAddressedNotification($receivers, $deliveryChannelIds, $userID, $type, $text, $attachments)

Available parameters are:

• $receivers (Indexed String) – The user IDs, group IDs (with prefix “GROUP:”), and role IDs (with prefix “ROLE:”) to send this notification to. The notification is sent to all users with the given user IDs and all users who are currently part of at least one of the supplied groups or roles.
• $deliveryChannelIds (Indexed String) – List of delivery channel IDs. If this is null, the standard "appway" delivery channel is used. If not, the notification is delivered to the given recipients via the given delivery channels.
• $userID (String) – ID of the user on behalf of whom the notification is sent
• $type (String) – A short user-readable type for the notification (e.g., 'US Customers', 'Account Opening', etc.) that is displayed to the user in the notification inbox (and can be part of the subject of externally delivered notification messages)
• $text (String) – The message text to send
• $attachments (Indexed UserMessageAttachment, optional) – A list of attachments (cluster files, see UserMessageAttachment primitive type) for the notification.

Note: Attachments for notifications are already available in the APIs, but are not yet supported.

The return value is:

• $notificationMessage (AddressedNotificationMessage) – The created AddressedNotificationMessage object.

Send a Notification with Topics

The function SendPubSubNotification sends a notification with a list of topics, and returns the created pubsub notification message.

SendPubSubNotification($topics, $receivers, $userID, $type, $text, $attachments, $excludeSendingUser)

Available parameters are:

• $topics (Indexed String) – Indexed collection of topic IDs this notification belongs to. Users subscribed to at least one of the topics will receive the notification via the delivery channels they are subscribed to (if no recipients are specified).
• $receivers (Indexed String) – Indexed collection of recipients (users, groups, and roles). If this is null, all subscribed users will receive the notification. If this is not null, only the intersection of subscribed users and users belonging to the recipients will receive the notification.
• $userID (String) – The user on behalf of which to send this notification
• $type (String) – A short user-readable type for the notification (e.g. 'US Customers', 'Account Opening', and so on) that is displayed to the user in the notification inbox. The type can also be part of the subject of externally-delivered notification messages.
• $text (String) – The notification text to send.
• $attachments (Indexed UserMessageAttachment, optional) – A list of attachments (cluster files, see UserMessageAttachment primitive type) for the notification. Note that not every delivery channel may be able to deliver attachments.

Note: Attachments for notifications are already available in the APIs, but are not yet supported.

• $excludeSendingUser (Boolean, optional) – If set to true, the notification will not be delivered to the user who triggered/sent the notification (the user whose user ID specified as the third argument of this function), even if that user (or one of the groups/roles the user is a member of) is subscribed to one of the notification's topics and would thus usually be part of the recipient set. The default setting for this parameter is false: Everybody who is subscribed will receive the notification.

The return value is:

• $notificationMessage (PubSubNotificationMessage) – The created PubSubNotificationMessage object.

Removing Notifications

The RemoveNotification Script Function allows you to remove the NotificationMessage of a Notification Object.

RemoveNotifications($messageIds, $userId)

Accessing Notification Inboxes

Get number of unread notifications

The function GetNumUnreadNotifications gets the number of unread notifications for a given user in that user's Appway notification inbox.

Please note that only notifications sent via the Appway delivery channel are considered by this function. Notifications sent via other channels (such as an e-mail delivery channel) are not counted by this function.

GetNumUnreadNotifications($userID, $inbox)

Load notifications

The function LoadNotifications loads the notifications sent to a user’s Appway-internal notification inbox.

Please note that only notifications sent via the Appway delivery channel are considered by this function. Notifications sent via other channels (such as an email delivery channel) are not returned by this function.

LoadNotifications($userID, $n, $unreadOnly, $inbox)

Mark notification as read

The function MarkNotificationRead marks a notification in a user’s Appway-internal notification inbox as read.

If a notification is marked as read, it is also marked as read in the notification Screen Components, and does not count toward the number of unread notifications.

MarkNotificationRead($userID, $notificationId, $inbox)

Managing Notification Topics

There are two ways to create a topic: explicitly or implicitly.

When you explicitly create a topic using the function CreateNotificationTopic, you can also add a name and description to the topic.

A topic is created implicitly when generating notification subscriptions using the SubscribeForNotifications function. This is covered in Subscribe to Notifications.

Create a Notification Topic

Create a notification topic in the publish/subscribe system with a given ID (mandatory), a description (optional) and a topic name (also optional).

Name and description are used by the Notification screen components.

Initially, a topic has no subscribers.

CreateNotificationTopic($topic, $description, $name)

Returns nothing.

Delete a Notification Topic

DeleteNotificationTopic() deletes a previously-created notification topic. This includes topics created explicitly (via the CreateNotificationTopic function) and implicitly (via the SubscribeForNotifications function – see Subscribe to Notifications).

Note that deleting a topic also deletes all associated subscriptions.

Returns nothing.

Get all existing Topic IDs

GetNotificationTopicIds() gets the IDs of all notification topics in the system. The existing notification topics are all notification topics that have been created explicitly (via the CreateNotificationTopic function) or implicitly (via the SubscribeForNotifications function) and have not been deleted via the DeleteNotificationTopic function or the Console.

No arguments.

Get a Notification Topic’s Name

Get the user-readable name for the given notification topic. If the topic does not exist or has no name, null is returned.

GetNotificationTopicName($topic)

Get a Notification Topic’s Description

Get the user-readable description for the given notification topic. If the topic does not exist or has no description, null is returned.

GetNotificationTopicDescription($topic)

Managing Topic Subscriptions

Subscribe to Notifications

SubscribeForNotifications($subscriberID, $topic, $deliveryChannelID)

To add subscribers to a topic, use the SubscribeForNotifications function. If the given topic did not previously exist, it is created simultaneously. Note that when creating a topic this way, no name or description is generated for the topic.

Returns nothing.

Unsubscribe from Notifications

Unsubscribe a previously subscribed user/group/role from the given topic via the given delivery channel. If no delivery channel is supplied, the subscriber will be unsubscribed from receiving notifications with the given topic via the default Appway delivery channel. To exclude a user from the subscription of a group/role, please use ExcludeFromNotificationSubscription.

UnsubscribeFromNotificationsFunction($subscriberID, $topic, $deliveryChannelID)

Exclude from Notification Subscription

Exclude the given user from the subscription of a group/role to the given topic via the given channel.

If no delivery channel is supplied, the exclusion affects the Appway delivery channel.

This function should be used if users who are subscribed to a topic because they are part of a group/role that is subscribed to the topic would like to stop receiving any more notifications for that specific subscription.

ExcludeFromNotificationSubscription($userID, $subscriberID, $topic, $deliveryChannelID)

Unexclude from Notification Subscription

Un-exclude the given user from the subscription of a group/role to the given topic via the given channel. If no delivery channel is supplied, the un-exclusion will affect the Appway delivery channel. This function should be used if a user who was originally subscribed to a topic because she is part of a group/role that is subscribed for the topic was excluded from the subscription, but would like to undo the exclusion and receive notifications corresponding to the given subscription again.

UnexcludeFromNotificationSubscription($userID, $subscriberID, $topic, $deliveryChannelID)

Get Notification Subscriptions

Get the subscription records matching the given notification subscription filter. This function should be used to retrieve the existing subscriptions when a user should be given the possibility to alter them. For more information on the structure and semantics of subscription records and notification subscription filters, see Notification Subscription Filter and Notification Subscription Record.

Note that for performance reasons, if subscription records are retrieved with a filter containing a user ID, the records do not contain the set of excluded users, but only a flag that says if the queried user is excluded from the subscription.

GetNotificationSubscriptions($filter)

Get Notification Receivers

Get the set of user IDs that receive a notification with the given topics and the given delivery channel.

This Function is useful if you want to handle delivery of notifications yourself, but still use Appway’s topic and subscription management system. An example could be sending notification emails that contain more data than just the notification text. You can still rely on Appway’s topic and subscription management, fetch the set of receivers using GetNotificationReceivers, and, instead of (or in addition to), sending notifications via the SendAddressedNotification and SendPubSubNotification Script Functions, send them with a custom mechanism, including all the data you want.

GetNotificationReceivers($topics, $deliveryChannelId)

Integration Link Component

The Component Extension provides an Integration Link end component, Send Notification, to send notifications from an integration link. This is particularly useful for sending notifications for asynchronous events, such as a new discussion message (in combination with the Discussion Message start element from the WorkspaceCollaboration extension).

The properties are divided into two tabs: routing and content. Routing contains all the information about who should receive the notification. Content contains all the information about the actual content.

In the Routing tab, you can choose to send a simple addressed notification (Routing Type "Send to fixed users"), or a publish-subscribe notification (Routing Type "Publish to topic(s)"). Based on your selection, the other available routing properties change. In case of an addressed notification, the properties are the same as the parameters of the "SendAddressedNotification Function" (see Send a Simple Notification).

Studio Administration and Monitoring

Workspace Notifications are administered via the Studio Solution Maintenance > Processes > Notification Management. In general, you can manage topics, subscriptions and users' notification inboxes.

Topics and Subscriptions

As explained in Notification Topics, users can subscribe to receive notifications on certain topics.

The Topics section (selectable on the left side) in the Notifications Console tab gives you an overview of all topics that exist at that point in time within Appway, and also lists the users subscribed to those topics.

Adding or Removing Additional Topics

You can add additional topics by clicking on the arrow in the top left and click Create Topic. To change the name or description of a topic, right click on the topic and select Edit Name/Description. Topics also support dependencies, so you can right click the topic and select Show Dependencies to find all usages of the topic. To delete a topic, right-click and select Delete Topic.

Configuring Subscriptions

You can dynamically subscribe users to topics using Script Functions (see Functions). However, as a developer or administrator, you can also configure the subscriptions per topic by right-clicking on the topic and selecting Edit Subscriptions.

This opens a modal window that allows you to select a notification delivery channel on the top, since all subscriptions are relative to a channel. Below that, it lists unsubscribed users, groups, and roles on the left side, and subscribed users, groups, and roles on the right side. To subscribe additional users, groups, or roles, select them (press Shift for multi selection), and click the >> button. Unsubscribing works the same way, only in reverse.

As described in Topics and Subscriptions, group and role subscriptions can have excluded users. To configure the excluded users for a specific group or role, right-click on the group or role, and select Edit excluded users. This opens another modal window that lets you shift users in the given group or role between not-excluded (left side) and excluded (right-side).

Inboxes

The Inboxes section (selectable on the left side) gives you an overview of all users with a non-empty notification inbox (empty inboxes do not exist), including the total number of notifications in the inbox, and the number of notifications they have not yet read.

If you use the feature to have multiple notification inboxes per user (see Multiple Inboxes per User), there are multiple entries for every user, one for every inbox. The inbox ID is composed of the user ID and the inbox type, e.g. ‘NM|alerts’ for the default user NM’s ‘alerts’ inbox. The default inbox ID is just the user ID.

Right-clicking on an inbox allows you to remove notifications. This means that all references to notifications are removed from the selected inbox. After this operation, that user’s inbox is empty. The actual notification messages, however, are not deleted since they could be referenced from other inboxes.

You can also delete old or all notifications via the menu on the top left. This deletes the corresponding inbox entries, as well as the notification messages themselves.

Performance Monitoring

To monitor the memory consumption of the notifications, you can use the Node Inspector. The relevant maps are:

• Notification Messages
• Notification Index Entries
• Notification Inboxes
• Notification Inbox Histories

CPU statistics for the notifications AJAX helper are recorded. Under System Maintenance > Statistics > CPU Statistics, you can see the statistics with Context Type AjaxHelpers and Context SecureNotificationAjaxHelper. They show the number of calls as well as various server-side timing measurements.

The realTime (avg) column can be used as a health indicator. It shows the total time consumed by an AJAX call of a notification Component on the server-side, which should normally be smaller than 20 ms.

Furthermore, you can reset the statistics and check the realTime (sum) after e.g. 60 seconds. Dividing the value (in seconds) by (60 * number of cores) yields the utilization of the system by notification AJAX calls.

Should the notifications consume too many CPU resources, you can increase the polling interval (see Configuration).