Configure notifications

Functions can be used to flexibly configure notifications that should be sent in the platform, including notifications that are sent externally to a user's email address.

Configuring a notification in a Function makes use of the Principal (representing a User or Group) and notification types. These references may be useful while working through this section:

• Reference for Principal, User, and Group types
• Reference for notification types

Defining a custom notification

Suppose that the ontology includes an Issue object which can be assigned to a user. We want to write a Function that defines a notification that should be sent to the given User with details about the Issue.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import { EmailNotificationContent, Function, Notification, ShortNotification, User } from "@foundry/functions-api";
import { Issue } from "@foundry/ontology-api";

export class NotificationFunctions {
    @Function()
    public createIssueNotification(issue: Issue, user: User): Notification {
        // Create a short notification that will be shown within the platform
        const shortNotification = ShortNotification.builder()
            .heading("New issue")
            .content("A new issue has been assigned to you.")
            // Link to the Issue object in the platform
            .addObjectLink("Issue", issue)
            .build();

        // Define the email body. The email body may contain headless HTML, such as tables of data
        // Note that we can access properties of both the user and the issue in the content
        const emailBody = `Hello, ${user.firstName},

A new issue has been assigned to you: ${issue.description}.`;

        const emailNotificationContent = EmailNotificationContent.builder()
            .subject("New issue")
            .body(emailBody)
            .addObjectLink("Issue", issue)
            .build();

        return Notification.builder()
            .shortNotification(shortNotification)
            .emailNotificationContent(emailNotificationContent)
            .build();
    }
}

Retrieving users and groups

In addition to having a User passed into the Function, you may retrieve a User or Group on demand. Suppose that the Issue object has an assignee field that contains a userId, and we want to implement a notification that reminds the user about the Issue. We could do so as follows:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import { EmailNotificationContent, Function, Notification, ShortNotification, User, Users } from "@foundry/functions-api";
import { Issue } from "@foundry/ontology-api";

export class NotificationFunctions {
    @Function()
    public async createIssueReminderNotification(issue: Issue): Promise<Notification> {
        if (!issue.assignee) {
            throw new UserFacingError("Cannot create notification for issue without an assignee.");
        }

        const user = await Users.getUserByIdAsync(issue.assignee);

        const emailBody = `Hello, ${user.firstName},

This is a reminder to investigate the following issue: ${issue.description}`.

        // You can also use this structure to build the entire notification inline
        return Notification.builder()
            .shortNotification(ShortNotification.builder()
                .heading("Issue reminder")
                .content("Investigate this issue.")
                .addObjectLink("Issue", issue)
                .build())
            .emailNotificationContent(EmailNotificationContent.builder()
                .subject("New issue")
                .body(emailBody)
                .addObjectLink("Issue", issue)
                .build())
            .build();
    }
}

Returning recipients

The Notification API documented above allows you to return custom notification content. Another way you can use Functions to configure notifications is by returning a list of recipients for the notification. To do so, simply write a Function that returns one or more Principals (such as Users or Groups). In the below example, the Function returns both the user who reported the issue and the user who is currently assigned to the issue.

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import { Function, User, Users } from "@foundry/functions-api";
import { Issue } from "@foundry/ontology-api";

export class NotificationFunctions {
    /**
     * Given an Issue, returns Users representing the current assignee for the Issue and the user
     * who originally reported the issue.
     */
    @Function()
    public async getIssueAssigneeAndReporter(issue: Issue): Promise<User[]> {
        if (!issue.assignee || !issue.reporter) {
            throw new UserFacingError("Cannot create notification for issue without an assignee or reporter.");
        }

        const user = await Users.getUserByIdAsync(issue.assignee);
        const issueReporter = await Users.getUserByIdAsync(issue.reporter);

        return [user, issueReporter];
    }
}