lib-notify 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793685190/FIN+5.3.1+lib-notify 中文整理基于 FIN 5.3.1

导读： 通知扩展

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

---

目录（导读）

• lib
• meta
• docs
• tags
• funcs
• views
• Overview
• Setup
• Topics
  • Topic Groups
• Using XQuery in Topics
• Subscribing to Topics
  • Topic Access
• Supporting Functions
• Examples
  • def
• notify(arg, topic)
  • supertypes
• notifyTopicSubscribers(topic)
  • usage
  • tags
  • src

---

概述（中译）

通知扩展

---

API 正文（英文）

docs

Overview • Setup • Topics • Using XQuery in Topics • Subscribing to Topics • Supporting Functions • Examples

---

tags

notifyTopic	A topic that can be subscribed
notifyTopicProj	The value is a project name

---

funcs

notify	Send an email to all users subscribed to the given topic
notifyTopicSubscribers	Return a list of user rec's for users that are subscribed to the given topic

---

views

notifyTopics	Fresco UI view

---

lib notify

Overview

The notify extension provides a way to create and configure "topics". Users can subscribe to topics to receive notifications associated with that topic. When used in tandem with the task extension you can easily configure email reports and digests to be sent at regular intervals.

Setup

The notify extension is designed to run in one project on your host. Thus, you can easily centralize and manage all your topics in one project. Select the project where you want to manage your topics, and go to the Settings | Ext view and enable the notifyExt. We refer to this project as the "notify" project.

You then create notifyTopic tasks in your notify project. By default, users have no access to subscribe to these tasks until you take the following steps to grant them access:

1. The user must have access to the "notify" project. If they don't have access to this project, they will not be able to manage their own subscriptions.
   1. Note - even if they don't have access to that project, a superuser can still configure notifications on that user via the User app; users will not be able to manage their own subscriptions though.
   2. Be aware that by granting the user access to the notify project, they have potential access to recs in the project beside topics.
2. Once a user is granted access to the "notify" project, by default, they have access to all configured topics and can subscribe to them.
3. You can further restrict which topics a user has access to by configuring topic access filters as described below.

Finally, review the Using XQuery in Topics section if any notifyTopic tasks in your notify project leverage the XQuery APIs.

Topics

Use the Task | Topics view to create and manage topics. A topic is a task with the notifyTopic tag applied to it. Topics are uniquely identified by their display name (not their Ref id).

Typically, the task is configured to subscribe to obsSchedule observations. Using a schedule allows you to configure your notification to occur at regular intervals (e.g. for digest notifications). You then configure the taskExpr to do your actual notification.

The notify extensions provides a built-in notify() function that can be used to email all users subscribed to a particular topic. You pass it a grid that will be formatted as HTML and emailed to the users. Therefore, the taskExpr of your topic will usually do two things: 1) build up the grid of data to for the email, and 2) call notify().

The following example shows a notifyTopic that is configured to send a daily digest of all sparks in the project where the notifyExt is enabled.

dis: "All Sparks (Digest)"
notifyTopic
obsSchedule
obsScheduleTimes: [01:00:00]
task
taskExpr:
  ruleSparksDigest(null, yesterday, null).notify(taskCur().dis)

Topic Groups

Topics can be grouped in the UI by using a special naming convention with the display name. The general format for a topic name is <Topic Name><sp>(<subtype>), but only the <Topic Name> is required. When multiple topics share the same name, they will be grouped together for selection in the UI. For example, suppose you have a spark daily digest topic, and a spark immediate topic:

// The UI will contain two distinct topic selections:
"All Sparks Digest"
"All Sparks Immediate"

// However if you use grouping, there will only be one "All Groups" topic, with
// checkboxes to select digest and/or immediate:
"All Sparks (Digest)"
"All Sparks (Immediate)"

Using XQuery in Topics

In larger SkySpark deployments, it is expected that the notifications will be sent using information from multiple projects that exist on the same SkySpark host or on another host across the cluster using XQuery.

IMPORTANT: Review the Task Security docs and ensure a task user account is created and the projAccessFilter tag is configured so that the notifyTopic tasks can access all required projects via XQuery (or there is no projAccessFilter so the task user can access all projects).

The following example shows a notifyTopic that is configured to send a daily digest of all sparks in the cluster.

dis: "All Sparks (Digest)"
notifyTopic
obsSchedule
obsScheduleTimes: [01:00:00]
task
taskExpr:
  xq().xqEval("ruleSparksDigest(null, yesterday, null)").xqExecute
    .flatten
    .notify(taskCur().dis)

Subscribing to Topics

Once you have configured one or more topics, there are two ways that users can become subscribed to a topic. Admin users can manually configure which topics a user is subscribed to using the User app and editing the notifications tag on the user.

Users can manage their own subscriptions in the "user menu" by selecting the Notifications menu option and selecting which notifications they want to receive. If a user does not have an email address configured, then this menu option will not be available.

Topic Access

You can restrict access to the topics a user can see by using standard SkySpark tag access filters. Add a notifyTopicAccessFilter to the user rec with the appropriate filter for that user.

You can assign a topic to a project by setting the notifyTopicProj tag on the topic. Only users that have access to that project will be able to see the topic.

Supporting Functions

Several functions exist across the various extensions to aid in generating notifications:

• ruleSparksDigest() : Get sparks (optionally filtered by targets and rules) formatted for digest that occurred since some time, or during a span.
• ruleKpisDigest() : Get KPIs (optionally filtered by targets and rules) formatted for digest that occurred during a span.
• arcDigest() : Get arc summaries formatted for digest that occurred since some time, or during a span.
• flatten() : Flattens a list to a single level.

The flatten() func should be noted. In most cases your topic taskExpr is going to do a an XQuery to get sparks, arcs, etc. from across the cluster. If you are using XQuery in your taskExpr, ensure you review the Using XQuery in Topics section for required setup instructions. The result of an XQuery evaluation is going to be a list of grids (Grid[]). The flatten func will flatten that list into a single Grid that you can pipe it to the notify() func. So a common pattern for notification expressions (taskExpr) will look like this:

xq().xqEval("...").xqExecute.flatten.notify(taskCur().dis)

Also if you have configured the notifyTopicProj tag on the task, you will probably want to limit the scope of your xquery to that configured project:

xq().xqProjs(taskCur()->notifyTopicProj).xqEval(...).xqExecute.flatten.notify(taskCur().dis)

Examples

This example shows how to use arcDigest() to send a daily digest of arcs. We configure the topic to run at ten minutes after midnight. In this example, we are only getting ticket arcs from the current project (the same one that the notifyExt is running in). It does not get arcs from the cluster.

dis: "Tickets (Digest)"
notifyTopic
obsSchedule
obsScheduleTimes: [00:10:00]
task
taskExpr:
  readAll(arc and tickets).arcDigest(yesterday).notify(taskCur().dis)

The following example shows how to configure a topic for "immediate" notification. We use xquery to find all tickets arcs that have occurred within the last 5 minutes. Only tickets that have been updated in the last 5 minutes will be reported in the notification. This example demonstrates a technique for maintaining state between invocations so we know what time period to query for arcs.

dis: "Tickets (Immediate)"
notifyTopic
obsSchedule
obsScheduleFreq: 5min
task
taskExpr:
  do
    lastCheck: taskLocalGet("lastCheck", now() - 5min)
    endTs: now()
    span: (lastCheck..endTs).toSpan

    xq()
      .xqDefine("since", span)
      .xqEval("readAll(arc and ticket).arcDigest(since)")
      .xqExecute
      .flatten.notify(taskCur().dis)

    taskLocalSet("lastCheck", endTs)
  end

Similar strategies can be employed with the other supporting functions to create notifications for sparks and KPIs.

---

---

def

func:notify

notify(arg, topic)

Send an email to all users subscribed to the given topic. The arg may be any Axon type that can be converted to a Grid. The grid will be run through the HTML exporter to generate the email body content.

---

meta

admin	✓
def	func:notify
is	func
lib	lib:notify
name	notify

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

func:notifyTopicSubscribers

notifyTopicSubscribers(topic)

Return a list of user rec's for users that are subscribed to the given topic.

recs: notifyTopicSubscribers("My Topic")

---

meta

admin	✓
def	func:notifyTopicSubscribers
is	func
lib	lib:notify
name	notifyTopicSubscribers

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
func	Axon function

---

---

def

notifyTopic

A topic that can be subscribed.

---

meta

def	notifyTopic
is	task
lib	lib:notify
mandatory	✓

---

usage

notifyTopic  task

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
task	Dispatch task function

---

tags

dis	Display name for an entity
disabled	Indicates the entity is in a disabled state
id	Defines the unique identifier of an entity in system using a ref value type
notifyTopicProj	The value is a project name
observes	Observable subscription - see docs
taskExpr	Task messaging handling Axon expression
taskStatus	Current status of a task

---

---

def

notifyTopicProj

The value is a project name. Only users who have access to this project will be able to manage subscriptions to this topic.

---

meta

def	notifyTopicProj
is	str
lib	lib:notify
tagOn	notifyTopic

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

view:notifyTopics

Fresco UI view. See Views

---

meta

admin	✓
appName	task
def	view:notifyTopics
defName	notifyTopic
disKey	ui::topics
icon	view
is	view
lib	lib:notify
order	501

---

supertypes

feature	Feature namespace of definitions formatted as feature:name
view	Fresco UI view

---

src

view:   {inherit: "table"}
search: {input var kind:"Str" defVal:""}
new:    {action: "recNew"}
edit:   {action: "recEdit" select}
trash:  {action: "recTrash" select}
data:   {expr:"readAll(notifyTopic, { sort, search:{{search}} })"}