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
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.
```typescript tab="TypeScript v1" 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();
}
}
typescript tab="TypeScript v2"
import { NotificationLink, Notification, User } from "@osdk/functions";
import { Issue } from "@ontology/sdk";
import { type Osdk } from "@osdk/client";
export default function createIssueNotification(issue: Osdk.InstanceHello,
A new issue has been assigned to you: ${issue.description}.;
const emailNotification = {
subject: "New issue",
body: emailBody,
links: links
}
return {
platformNotification: platformNotification,
emailNotification: emailNotification
}
}
```
```python tab="Python" from functions.api import function, Notification, PlatformNotification, ShortNotification, NotificationLink, User from ontology_sdk.ontology.objects import Issue
@function() def createIssueNotification(issue: Issue) -> Notification[Issue]:
If configuring a notification with an object link, you must declare the object type as part of the return type¶
# Link to the Issue object in the platform
links = [
NotificationObjectLink(label="Issue", objectTarget=issue)
]
#Create a short notification that will be shown within the platform
platform_notification = PlatformNotification(
heading="New issue",
content="A new issue has been assigned to you.",
links=links
)
# Define the email body. The email body may contain headless HTML, such as tables of data
emailBody = f"Hello, \n A new issue has been assigned to you: {issue.description}."
email_notification = EmailNotification(
subject="New issue",
body=emailBody,
links=links
)
return Notification(platform_notification, email_notification)
```
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:
typescript tab="TypeScript v1"
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();
}
}
```typescript tab="TypeScript v2" import { Users } from "@osdk/foundry.admin"; import { Issue } from "ontology_sdk"; import { Client } from "@osdk/client";
export default async function createIssueReminderNotification(client: Client, issue: Issue): Promise
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
const links: NotificationLink[] = [
{
label: "Issue",
linkTarget: {
type: "object",
object: issue
}
}
]
// You can also use this structure to build the entire notification inline
return {
shortNotification: {
heading: "Issue reminder",
content: "Investigate this issue.",
links: links
}
emailNotification: {
subject: "New issue",
body: emailBody,
links: links
}
}
}
python tab="Python"
from functions.api import function, Notification, PlatformNotification, ShortNotification, NotificationLink
from ontology_sdk.ontology.objects import Issue
from foundry_sdk import FoundryClient
import foundry_sdk
@function()
def createIssueReminderNotification(client: Client, issue: Issue) -> Notification:
client = FoundryClient(auth=foundry_sdk.UserTokenAuth(...), hostname="example.palantirfoundry.com")
user = client.admin.User.get(user_id)
emailBody = f"Hello, {user.firstName}, \n A new issue has been assigned to you: {issue.description}."
# Link to the Issue object in the platform
links = [
NotificationObjectLink(label="Issue", objectTarget=issue)
]
#Create a short notification that will be shown within the platform
platform_notification = PlatformNotification(
subject="New issue",
body="A new issue has been assigned to you.",
links=links
)
# 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
emailBody = f"Hello, {user.firstName}, \n A new issue has been assigned to you: {issue.description}."
email_notification = EmailNotification(
subject="New issue",
body=emailbody,
links=links
)
return Notification(platform_notification, email_notification)
```
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:
```typescript tab="TypeScript v1" 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
const user = await Users.getUserByIdAsync(issue.assignee);
const issueReporter = await Users.getUserByIdAsync(issue.reporter);
return [user, issueReporter];
}
}
typescript tab="TypeScript v2"
import { UserId, Principal } from "@osdk/functions";
import { Users, Groups } from "@osdk/foundry.admin";
import { Issue } from "ontology_sdk";
import { Client } from "@osdk/client";
/
* Given an Issue, returns users representing the current assignee for the Issue and the user
* who originally reported the issue.
*/
async function getIssueAssigneeAndReporter(client: Client, issue: Issue): Promise
```python tab="Python" from functions.api import Array, function, Principal, UserId from ontology_sdk.ontology.objects import Issue from foundry_sdk import FoundryClient import foundry_sdk
Given an Issue, returns users representing the current assignee for the Issue and the user¶
who originally reported the issue.¶
@function() def getIssueAssigneeAndReporter(issue: Issue) -> Array[UserId]: client = FoundryClient(auth=foundry_sdk.UserTokenAuth(...), hostname="example.palantirfoundry.com")
user = client.admin.User.get(issue.assignee)
issueReporter = client.admin.User.get(issue.assignee)
return [user.id, issueReporter.id]
Given an Issue, returns the user who is the current assignee of the issue and the group that issue belongs to.¶
@function() def getIssueAssigneeAndGroup(issue: Issue) -> Array[Principal]: # To return both groups and users, return the Principal type. client = FoundryClient(auth=foundry_sdk.UserTokenAuth(...), hostname="example.palantirfoundry.com")
user = client.admin.User.get(issue.assignee)
group = client.admin.Group.get(issue.group)
return [Principal.user(user.id), Principal.group(group.id)]
---
# 中文翻译
# 配置通知
可以使用函数灵活配置平台中应发送的通知，包括发送到用户电子邮件地址的外部通知。
在函数中配置通知需要使用 `Principal`（代表 `User` 或 `Group`）和 `notification` 类型。在阅读本节内容时，以下参考资料可能会有所帮助：
* [Principal、User 和 Group 类型参考](https://palantir.com/docs/foundry/functions/types-reference/#users-groups-and-principals)
* [通知类型参考](https://palantir.com/docs/foundry/functions/types-reference/#notification)
### 定义自定义通知
假设本体论(Ontology)中包含一个可以分配给 `User` 的 `Issue` 对象。您可以创建一个函数，定义应发送给指定 `User` 的通知，其中包含 `Issue` 的详细信息。
```typescript tab="TypeScript v1"
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 {
// 创建将在平台内显示的简短通知
const shortNotification = ShortNotification.builder()
.heading("新问题")
.content("一个新问题已分配给您。")
// 链接到平台中的 Issue 对象
.addObjectLink("Issue", issue)
.build();
// 定义电子邮件正文。电子邮件正文可以包含无头 HTML，例如数据表格
// 注意，您可以在内容中访问用户和问题的属性
const emailBody = `您好，${user.firstName}，
一个新问题已分配给您：${issue.description}。`;
const emailNotificationContent = EmailNotificationContent.builder()
.subject("新问题")
.body(emailBody)
.addObjectLink("Issue", issue)
.build();
return Notification.builder()
.shortNotification(shortNotification)
.emailNotificationContent(emailNotificationContent)
.build();
}
}
```typescript tab="TypeScript v2" import { NotificationLink, Notification, User } from "@osdk/functions"; import { Issue } from "@ontology/sdk"; import { type Osdk } from "@osdk/client";
export default function createIssueNotification(issue: Osdk.Instance
const platformNotification = {
heading: "新问题",
content: "一个新问题已分配给您。",
links: links
}
// 定义电子邮件正文。电子邮件正文可以包含无头 HTML，例如数据表格
const emailBody = `您好，
一个新问题已分配给您：${issue.description}。`;
const emailNotification = {
subject: "新问题",
body: emailBody,
links: links
}
return {
platformNotification: platformNotification,
emailNotification: emailNotification
}
}
python tab="Python"
from functions.api import function, Notification, PlatformNotification, ShortNotification, NotificationLink, User
from ontology_sdk.ontology.objects import Issue
@function()
def createIssueNotification(issue: Issue) -> Notification[Issue]:
如果配置带有对象链接的通知，则必须在返回类型中声明对象类型¶
# 链接到平台中的 Issue 对象
links = [
NotificationObjectLink(label="Issue", objectTarget=issue)
]
# 创建将在平台内显示的简短通知
platform_notification = PlatformNotification(
heading="新问题",
content="一个新问题已分配给您。",
links=links
)
# 定义电子邮件正文。电子邮件正文可以包含无头 HTML，例如数据表格
emailBody = f"您好，\n 一个新问题已分配给您：{issue.description}。"
email_notification = EmailNotification(
subject="新问题",
body=emailBody,
links=links
)
return Notification(platform_notification, email_notification)
```
检索用户和组¶
除了将 User 传入函数外，您还可以按需检索 User 或 Group。假设 Issue 对象有一个包含用户 ID 的 assignee 字段。在下面的示例中，函数返回一个提醒用户有关该问题的通知：
```typescript tab="TypeScript v1" 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
const user = await Users.getUserByIdAsync(issue.assignee);
const emailBody = `您好，${user.firstName}，
这是提醒您调查以下问题：${issue.description}`。
// 您也可以使用此结构内联构建整个通知
return Notification.builder()
.shortNotification(ShortNotification.builder()
.heading("问题提醒")
.content("请调查此问题。")
.addObjectLink("Issue", issue)
.build())
.emailNotificationContent(EmailNotificationContent.builder()
.subject("新问题")
.body(emailBody)
.addObjectLink("Issue", issue)
.build())
.build();
}
}
typescript tab="TypeScript v2"
import { Users } from "@osdk/foundry.admin";
import { Issue } from "ontology_sdk";
import { Client } from "@osdk/client";
export default async function createIssueReminderNotification(client: Client, issue: Issue): Promise您好，${user.firstName}，
这是提醒您调查以下问题：${issue.description}。
// 您也可以使用此结构内联构建整个通知
const links: NotificationLink[] = [
{
label: "Issue",
linkTarget: {
type: "object",
object: issue
}
}
]
// 您也可以使用此结构内联构建整个通知
return {
shortNotification: {
heading: "问题提醒",
content: "请调查此问题。",
links: links
}
emailNotification: {
subject: "新问题",
body: emailBody,
links: links
}
}
}
```
```python tab="Python" from functions.api import function, Notification, PlatformNotification, ShortNotification, NotificationLink from ontology_sdk.ontology.objects import Issue from foundry_sdk import FoundryClient import foundry_sdk
@function() def createIssueReminderNotification(client: Client, issue: Issue) -> Notification: client = FoundryClient(auth=foundry_sdk.UserTokenAuth(...), hostname="example.palantirfoundry.com")
user = client.admin.User.get(user_id)
emailBody = f"您好，{user.firstName}，\n 一个新问题已分配给您：{issue.description}。"
# 链接到平台中的 Issue 对象
links = [
NotificationObjectLink(label="Issue", objectTarget=issue)
]
# 创建将在平台内显示的简短通知
platform_notification = PlatformNotification(
subject="新问题",
body="一个新问题已分配给您。",
links=links
)
# 定义电子邮件正文。电子邮件正文可以包含无头 HTML，例如数据表格
# 注意，您可以在内容中访问用户和问题的属性
emailBody = f"您好，{user.firstName}，\n 一个新问题已分配给您：{issue.description}。"
email_notification = EmailNotification(
subject="新问题",
body=emailbody,
links=links
)
return Notification(platform_notification, email_notification)
### 返回收件人
上述 `Notification` API 允许您返回自定义通知内容。另一种使用函数配置通知的方式是返回通知的收件人列表。为此，请创建一个返回一个或多个 `Principal` 对象（例如 `User` 或 `Group` 对象）的函数。
在下面的示例中，函数返回报告问题的用户和当前分配给该问题的用户：
```typescript tab="TypeScript v1"
import { Function, User, Users } from "@foundry/functions-api";
import { Issue } from "@foundry/ontology-api";
export class NotificationFunctions {
/**
* 给定一个 Issue，返回代表该 Issue 当前分配人和最初报告该问题的用户。
*/
@Function()
public async getIssueAssigneeAndReporter(issue: Issue): Promise<User[]> {
if (!issue.assignee || !issue.reporter) {
throw new UserFacingError("无法为没有分配人或报告人的问题创建通知。");
}
const user = await Users.getUserByIdAsync(issue.assignee);
const issueReporter = await Users.getUserByIdAsync(issue.reporter);
return [user, issueReporter];
}
}
```typescript tab="TypeScript v2" import { UserId, Principal } from "@osdk/functions"; import { Users, Groups } from "@osdk/foundry.admin"; import { Issue } from "ontology_sdk"; import { Client } from "@osdk/client";
/*
* 给定一个 Issue，返回代表该 Issue 当前分配人和最初报告该问题的用户。
/
async function getIssueAssigneeAndReporter(client: Client, issue: Issue): Promise
return [user.id, issueReporter.id];
}
/*
* 给定一个 Issue，返回该 Issue 的当前分配用户以及该 Issue 所属的组。
/
async function getIssueAssigneeAndGroups(client: Client, issue: Issue): Promise
const user = await Users.get(client, issue.assignee);
const group = await Groups.get(client, issue.group);
return [{type: "user", id: user.id}, {type: "group", id: group.id}];
}
python tab="Python"
from functions.api import Array, function, Principal, UserId
from ontology_sdk.ontology.objects import Issue
from foundry_sdk import FoundryClient
import foundry_sdk
给定一个 Issue，返回代表该 Issue 当前分配人和最初报告该问题的用户。¶
@function() def getIssueAssigneeAndReporter(issue: Issue) -> Array[UserId]: client = FoundryClient(auth=foundry_sdk.UserTokenAuth(...), hostname="example.palantirfoundry.com") user = client.admin.User.get(issue.assignee) issueReporter = client.admin.User.get(issue.assignee) return [user.id, issueReporter.id]
给定一个 Issue，返回该 Issue 的当前分配用户以及该 Issue 所属的组。¶
@function() def getIssueAssigneeAndGroup(issue: Issue) -> Array[Principal]: # 要同时返回组和用户，请返回 Principal 类型。 client = FoundryClient(auth=foundry_sdk.UserTokenAuth(...), hostname="example.palantirfoundry.com") user = client.admin.User.get(issue.assignee) group = client.admin.Group.get(issue.group) return [Principal.user(user.id), Principal.group(group.id)] ```