Location: 开发参考功能服务

订阅和通知

和用户交互相关的功能

docutils document without title

1 关注 subscriptions
- 1.1 订阅人管理
- 1.2 通知通知方式
2 通知功能 notifications
3 默认通知方式
- 3.1 流程默认通知方式
- 3.2 提到我的默认通知方式
4 自定义即时推送
5 自定义短信通知

1 关注 subscriptions

关注也就是订阅，一旦订阅，会收到关联的通知。

订阅用 obj.subscriptions 进行管理。

1.1 订阅人管理

可以用如下方法得到对象的订阅人:

obj.subscriptions.getSubscribedMembers()

其他：

getSubscribedMembers(): 得到一组已订阅的人员(tuple.)
setSubscribedMembers(members): 将对象的订阅列表设置成members
subscribeMember(member): 新增一个订阅人员(人员不允许是 ‘Anonymous’)
subscribeMembers(members): 新增一组订阅人员
unsubscribeMember(member): 删除一个订阅人员
subscribeAuthenticatedMember(): 在当前的订阅列表里面新增当前的登录人员
unsubscribeAuthenticatedMember(): 在订阅列表里面删除当前的登录人员
hasSubscriptionFor(member=None): 如果member 在订阅列表返回‘True’，否则返回‘False’
hasSubscriptionForAuthenticatedMember(): 当前登录人员在订阅列表返回‘True’，否则返回‘False’

1.2 通知通知方式

设置:

obj.subscriptions.setSubscribeMethods(methods)

读取:

obj.subscriptions.getSubscribeMethods()

2 通知功能 notifications

每个对象可以发送关联的通知，通过 obj.notifications 进行通知管理。

如果没有直接关联的对象，可以认为是和整个站点关联，使用 root.notifications 来进行管理。

2.1 发送通知 send

可采用用户对对象的订阅方式(短信、邮件、系统消息)，进行消息发送.

比如给自己发送一个消息:

obj.notifications.send(
    title='hello, world',
    to_pids=[request.me.id],
    methods=['message'],
    exclude_me=False,
)

完整API为:

obj.notifications.send(
    body='',
    title='',
    to_pids=['users.admin'],
    methods=['message'],
    exclude_me=False,
    action='',
    attachments=[],
    from_pid=None,
    exclude_pids=[],
    title_msg_id=None, body_msg_id=None,
    title_msg_mapping=None, body_msg_mapping=None
)

其中基本信息包括：

body: 用户输入的消息文本
title: 用户输入的标题信息
action: 具体做了什么操作
- share: 分享
- sendme: 发送给我的
- upload: 上传
- new_revision: 更新版本
- new: 新建
- edit: 编辑
- comment: 评论
- fix_revision: 定版
- workflow_sign: 触发流程
- workflow_resign: 更改流程
- remind: 催办
- mention_in_comment: 在评注中提醒指定用户
- mention_in_group: 在群组中提醒指定用户
methods: 发送的通知方式，具体见后
attachments: 附件uid的列表

2.2 发送给谁

默认发送给对象的订阅人，更多参数：

to_pids: 发送给指定人员
exclude_me: 是否排除自己，避免自己给自己发通知造成骚扰
exclude_pids: 需要排除的人

2.3 消息的国际化

消息发给多人，可以根据消息接收方的默认语言进行国际化(消息接受方每次登录，会根据选择语言设置默认语言)。

2.3.1 title的翻译

title_msg_id: 软件包的翻译的字符串 msgid，用于标题的国际化。比如 zopen.xxx:xxxx 表示从软件包 zopen.xxx 中获取翻译字符串 xxxx

如果找不到对应的字符串，将回退到使用 title 参数的值
title_msg_mapping: title_msg_id 对应的字符串中如果有需要填充的变量，使用这个参数传入。dict，其中指定所有变量名和值。有两种方式可以用于指定 mapping 中变量的值：
- mapping 类似 {'step': 'vote'} 直接指定变量 step 的值为 vote
- mapping 也可以指定翻译后的文字作为变量值，例如:
```
{
    'step': {
        'obj': root.object_by_uid(123),
        'msgid': 'vote',
        'default': 'vote',
    }
}
```
  以上例子中，将会使用指定的 obj 来翻译 msgid，将结果作为 mapping 中 step 字段的值；如果没有找到这个 msgid，那么将 default 作为 step 字段的值。

2.3.2 body的翻译

body_msg_id: 和 title_msg_id 类似，指定用于翻译的字符串 msgid，用于消息正文的国际化。找不到对应字符串时回退到 body 参数的值。
body_msg_mapping: body_msg_id 对应的字符串中如果有需要填充的变量，使用这个参数传入。是一个 dict，其中指定所有变量名和值。使用方法与 title_msg_mapping 类似。

注意：

每个 action 对应的各种翻译 msgid 为 action_xxx
系统根据不同的 action 以及不同的 object_types 类型自动选择不同的消息通知频道进行提醒
关于消息标题和内容的国际化详细示例，请参考 开放 API → 内容管理 → api/v1/content/notify

2.4 解析文本中提到的用户 check_mention_in_text

通常在文本中使用 @用户名 的格式（类似 Twitter 和微博）可以指定提醒被 @ 的用户。这个接口可以从文本中找出被提到的用户 ID:

obj.notifications.check_mention_in_text('@admin this is a test')

以上代码将返回 ['users.admin'] 。

2.5 通知方式 list_methods

可以通过如下方法得到支持的通知方式:

obj.notifications.list_methods(request)

返回如下信息:

[
('message':'系统消息'),
('sms':'短信'),
('email':'邮件'),
('im':'即时推送'),
]

系统消息通知效果:

张三 action : [title]body
关联对象: obj
附件：attachment 1
      attachment 2

邮件效果:

邮件标题：张三 action：title
邮件正文：body

          关联对象：名称 http://xxx
          附件：

短信效果:

张三 action：[title] body , 关联对象是 xxx

3 默认通知方式

3.1 流程默认通知方式

流程处理通知 (action为： workflow_sign或remind)，对即时性要求很高，通常需要通过邮件或者微信钉钉方式推送。

在站点设置中可以统一设置通知方式:

root.settings[‘workflow_notify_methods’]

另外每个人可以单独设置，存放到个人的Profile里面:

root.profiles.set(‘workflow_notify_methods’,[])

3.2 提到我的默认通知方式

类似流程通知方式，只是参数为 mentioned_notify_methods

4 自定义即时推送

系统可以进行定制的即时推送，需要设置推送脚本:

root.settings['im_notify_scripts'] = ['zopen.rxt:notify']

可以支持多种推送方式的，这个推送脚本需要提供如下接口:

notify(title=title,
    body=body,
    from_pid=from_pid,
    exclude_pids=excludes,
    to_pids=toids,
    action=action,
    obj=_obj,
    request=request,
    attachments=attachments,
    to_ims=[],)

5 自定义短信通知

私有云版本可以设置使用自定义脚本进行短信通知。

在控制台里面设置通知方式为 script
编写一个脚本，传递 number 和 text 参数
将这个注册到 root.settings['sms_driver_script']

可以屏蔽短信通知:

root.settings['enable_sms_notify'] = False

易开发

大道至简，新一代企业应用无栈开发