Overview

ROQ Suite ships with a flexible notification service. Users can set their preferences and preferred channels like in-app and email.

Configuration

You can configure notifications in the Console: ➚ console.roq.tech/settings/notification/types (make sure that you selected the right project and environment).

Setup of new notification-types

To create a new notification-type, you need to define a unique key, set a category, add a short description, and configure the channels. Here, the key is a string of your choice that will be used in code to send a notification, e.g., "WELCOME_NOTIFICATION". Categories and the short description provide an overview. This information has no impact on how sending or receiving notifications in the application.

You can select two kinds of notification channels: in-app and e-mail. For both channels you can set the default settings of the user preferences (enabled or disabled for new users). You can also disable the entire channel, meaning it is not used at all.

In-app notification channel

For in-app notifications, you need to create a template for each active locale (see https://docs.roq.tech/dev/managing-locales ). Each template has a localized title, an icon (e.g., "@mui/icons-material/Person") and the localized content. In the content you can access data from ROQ Platform's database using the {{...}} syntax. You can review the GraphQL docs to see what's available.

Example:

{{user.firstName}} {{user.lastName}} just joined ROQ One
CODE

E-mail notification channel

You can also notify your users using e-mails. To do so, you need to activate the mail channel and select an already existing mail-type (see Mails).

User preferences

Your users can use ROQ One's settings page (/settings) to decide which type of notification they want to receive and through which channel(s). These settings are saved on ROQ Platform using the upsertNotificationTypeUserPreference() mutation.

API documentation

If you are building on top of ROQ One, this logic is pre-integrated with ROQ Platform and working out of the box! However, you can still read this documentation if you wish to customize it or are just curious about how things work.

Frequently fetch all notifications of a user

The main query of the notification service is notificationsInAppForCurrentUser() which is called every 15 seconds to check for updates.

query {
  notificationsInAppForCurrentUser{
    data {
      id
      userId
      title
      content
      locale
      createdAt
      read
      icon
    }
  }
}
GRAPHQL

Of course, the query can be used with all default filters, but it will only return the current user’s notifications. When browsing ROQ One, you can see the actual query in your developer toolbar when using ROQ One. It can be called using these parameters:

{
  "limit": 20,
  "order": {
    "order": "DESC",
    "sort": "CREATED_AT"
  },
  "notificationfilter": {
    "createdAt": {
      "moreThan": "2022-03-22T11:25:23.671Z"
    }
  },
  "unreadCountFilter": {
    "createdAt": {
      "moreThan": "2022-03-22T11:25:23.671Z"
    },
    "read": {
      "equalTo": false
    }
  }
}
GRAPHQL

ℹ As you can see the ID of the current user is not submitted as a parameter. For security reasons the ID is taken from the user's JWT token and cannot be changed.

ROQ One: The default limit of 20 notifications and the frequency of 15 second can be changed either in code or via these environment variables (see frontend/src/configuration/app/public.config.ts)

NEXT_PUBLIC_NOTIFICATION_FIRST_LOAD_COUNT
NEXT_PUBLIC_NOTIFICATION_POLLING_DELAY_SECONDS
CODE

How to send notifications via GraphQL API

You can send notifications to a single user or to a group of users with the createNotification() mutation like this:

mutation {
  createNotification(
    notification: {
      key: "WELCOME_NOTIFICATION"
      entities: [{ uuid: "32e1d3d6-93d3-4f7d-ab41-2f80756eabf1", type: "user" }]
      recipients: {
        excludedUserIds: ["81981428-7d3d-4383-8e8e-712dba6b24a9"]
        userIds: ["f2a67a92-7dc0-4a1c-ae14-41298154e942"]
        allUsers: false
        userGroups: {
          userGroupIds: ["e978b318-82ae-4b28-99a4-d87741aceb8c"]
          operator: AND
        }
      }
    }
  ) {
    webNotifications
  }
}
GRAPHQL

key

Key of notification-type that you created in the Console, eg. "WELCOME_NOTIFICATION"

recipients:
userIds

Array of user IDs that are notified. ⚠️ You need to use the ID's of the user of ROQ Platform. These IDs are saved in your user entity in the field roqIdentifier

recipients:
userGroups

Object that contains a list of user-groups. You can also set a boolean value to decide who will be notified.

  • operator: AND - Notify all users that are related to all listed user-groups

  • operator: OR - Notify all users that are related to any of the user-group

⚠ You need to use the ID's of the user-groups of ROQ Platform which you can fetch from the PI using your project-specific IDs:

query {
  userGroups(filter: { remoteId: { equalTo: "123" } }) {
    data {
      id
    }
  }
}
GRAPHQL

recipients:
excludedUserIds

List of user IDs (of ROQ Platform) who shouldn't be notified. A typical use case is when a user performs an action and all users of the same user-group should be notified, except of the acting user.

recipients:
allUsers

Boolean value. If set to true then all users will be notified.

entities

Array of entities with ID and type. Here you can pass additional information which you can use the notification template. For instance if you want to notify about a new file upload, then you can pass the ID of file here, so that you can re-use it in the template like this:

File uploaded: {{file.name}}
CODE