• Documentation
    • Search documentation
    karat

    +

    K

    API Reference ↗
    Ontology buildingFunctionsLanguage agnostic featuresConfigure notifications

    Configure notifications

    Configuring notifications is not yet supported in Python and TypeScript v2 functions.

    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:

    Define a custom notification

    Suppose that the ontology includes an Issue object that can be assigned to a User. You can create a function that defines the 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 you 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();
    }
}

    Retrieve 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 user ID. In the example below, the function returns a notification that reminds the user 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
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();
    }
}

    Return 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, create a function that returns one or more Principal objects, such as User or Group objects.

    In the example below, 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];
    }
}