Skip to content

Commit 32d4ef8

Browse files
wakonigwakonig
committed
feat: add documentation for sending custom notification events and setting up auto notifications
1 parent 167896b commit 32d4ef8

3 files changed

Lines changed: 295 additions & 0 deletions

File tree

‎docs/how-to/general/send-a-custom-notification-event.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
related:
3+
- title: Set Up Auto Notifications
4+
url: set-up-auto-notifications.md
5+
- title: Send Messages to SciLog
6+
url: send-messages-to-scilog.md
7+
- title: Send Messages to Signal
8+
url: send-messages-to-signal.md
9+
- title: Core Services
10+
url: ../../learn/system-architecture/overview/core-services.md
11+
---
12+
13+
# Send a custom notification event
14+
15+
!!! Info "Overview"
16+
Publish a custom notification event from BEC code so it can be routed to messaging services such as SciLog, Signal, or Teams.
17+
18+
## Prerequisites
19+
20+
- You are working in custom BEC code such as a plugin, service extension, or beamline-specific helper.
21+
- Your code has access to a BEC connector, for example `self.connector` or `client.connector`.
22+
- The target messaging service is enabled for your deployment or session.
23+
- If you want the event to be forwarded automatically, you have configured a matching route in [Set Up Auto Notifications](set-up-auto-notifications.md){ data-preview }.
24+
25+
## Notification publish interface
26+
27+
Publish a notification with:
28+
29+
```py
30+
connector.notify(event, message)
31+
```
32+
33+
- `event` is a string such as `"beamline_ready"` or `"sample_mount_failed"`
34+
- `message` can be either a plain string or a `NotificationMessageObject`
35+
36+
## 1. Send a simple custom event
37+
38+
If plain text is enough, send the event name together with a string message:
39+
40+
```py
41+
self.connector.notify(
42+
"beamline_ready",
43+
"Beamline checks passed and the station is ready for users.",
44+
)
45+
```
46+
47+
BEC wraps the string into a notification message object automatically before routing it.
48+
49+
## 2. Send a richer custom event
50+
51+
Use `NotificationMessageObject` when you want formatted text, tags, or attachments that can be adapted to the target messaging service:
52+
53+
```py
54+
from bec_lib.messaging_services import NotificationMessageObject
55+
56+
msg = NotificationMessageObject()
57+
msg.add_text("Sample mount failed", bold=True, color="red")
58+
msg.add_text(" Please check the robot status before retrying.")
59+
msg.add_tags(["sample-exchange", "robot"])
60+
61+
self.connector.notify("sample_mount_failed", msg)
62+
```
63+
64+
This is useful when the same event should later be routed to services with richer formatting support, especially SciLog.
65+
66+
## 3. Route the event to a messaging service
67+
68+
Publishing a custom event does not send it anywhere by itself. To forward it automatically, configure a route for the same event name from the BEC client as described in [Set Up Auto Notifications](set-up-auto-notifications.md){ data-preview }:
69+
70+
```py
71+
bec.messaging.scilog.set_auto_notifications(
72+
"beamline_ready",
73+
enabled=True,
74+
scopes="default",
75+
)
76+
```
77+
78+
After that, every `beamline_ready` notification published by your code is forwarded to the configured SciLog scope.
79+
80+
## 4. Use a stable event name
81+
82+
Choose one event string and keep it consistent between the publisher and the routing configuration:
83+
84+
```py
85+
self.connector.notify("sample_mount_failed", "Robot reported a mount failure.")
86+
```
87+
88+
```py
89+
bec.messaging.signal.set_auto_notifications(
90+
"sample_mount_failed",
91+
enabled=True,
92+
scopes="beamline-ops",
93+
)
94+
```
95+
96+
If the event names do not match exactly, BEC will not route the notification.
97+
98+
!!! success "Congratulations!"
99+
100+
You can now publish custom notification events from BEC code and connect them to the automatic notification routing system.
101+
102+
## Common pitfalls
103+
104+
- `connector.notify(...)` only publishes the event. It does not automatically choose a messaging service unless you configured a matching route.
105+
- The event name in `notify(...)` and the event name in `set_auto_notifications(...)` must match exactly.
106+
- Use `NotificationMessageObject` when you need tags, formatting, or attachments. Use a plain string when a simple text notification is enough.

‎docs/how-to/general/set-up-auto-notifications.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
---
2+
related:
3+
- title: Send a Custom Notification Event
4+
url: send-a-custom-notification-event.md
5+
- title: Send Messages to SciLog
6+
url: send-messages-to-scilog.md
7+
- title: Send Messages to Signal
8+
url: send-messages-to-signal.md
9+
- title: Core Services
10+
url: ../../learn/system-architecture/overview/core-services.md
11+
---
12+
13+
# Set up auto notifications
14+
15+
!!! Info "Overview"
16+
Configure BEC to send automatic notifications for scan and alarm events through a messaging service such as SciLog or Signal.
17+
18+
## Prerequisites
19+
20+
- You have a running BEC IPython client session.
21+
- The messaging service you want to use is enabled for your deployment or session.
22+
- You know which target scope to use for that service, for example a SciLog logbook or a Signal group scope.
23+
24+
## Notification interface and event types
25+
26+
Auto notifications are configured per messaging service from the BEC client with:
27+
28+
```py
29+
bec.messaging.<service>.set_auto_notifications(event_type, enabled=True, scopes=...)
30+
```
31+
32+
Supported event types are:
33+
34+
<table>
35+
<colgroup>
36+
<col style="width: 28%;">
37+
<col style="width: 72%;">
38+
</colgroup>
39+
<thead>
40+
<tr>
41+
<th>Event type</th>
42+
<th>Emitted when</th>
43+
</tr>
44+
</thead>
45+
<tbody>
46+
<tr>
47+
<td><code>"new_scan"</code></td>
48+
<td>A scan enters the <code>open</code> state, meaning BEC has started the scan.</td>
49+
</tr>
50+
<tr>
51+
<td><code>"scan_completed"</code></td>
52+
<td>A scan finishes with the status <code>closed</code> or <code>user_completed</code>.</td>
53+
</tr>
54+
<tr>
55+
<td><code>"alarm_warning"</code></td>
56+
<td>BEC raises an alarm with warning severity.</td>
57+
</tr>
58+
<tr>
59+
<td><code>"alarm_minor"</code></td>
60+
<td>BEC raises an alarm with minor severity.</td>
61+
</tr>
62+
<tr>
63+
<td><code>"alarm_major"</code></td>
64+
<td>BEC raises an alarm with major severity.</td>
65+
</tr>
66+
<tr>
67+
<td><code>"scan_interlock"</code></td>
68+
<td>The scan interlock is triggered because beamline states do not match, and again when that interlock is cleared.</td>
69+
</tr>
70+
</tbody>
71+
</table>
72+
73+
!!! tip "Custom event names"
74+
75+
You can also use custom event names. BEC supports any event string, as long as something in your deployment publishes notifications with the same event name.
76+
77+
To learn how to publish one of these events from custom BEC code, see [Send a Custom Notification Event](send-a-custom-notification-event.md){ data-preview }.
78+
79+
For example, if a custom service or plugin publishes a `beamline_ready` notification, you can route it like this:
80+
81+
```py
82+
bec.messaging.scilog.set_auto_notifications(
83+
"beamline_ready",
84+
enabled=True,
85+
scopes="default",
86+
)
87+
```
88+
89+
## 1. Enable an automatic notification
90+
91+
Enable a notification by choosing the service, event, and target scope.
92+
93+
For example, route new scan notifications to SciLog:
94+
95+
```py
96+
bec.messaging.scilog.set_auto_notifications(
97+
"new_scan",
98+
enabled=True,
99+
scopes="default",
100+
)
101+
```
102+
103+
This stores a routing rule for the `new_scan` event. When a new scan starts, BEC forwards the notification to the configured SciLog scope.
104+
105+
You can do the same for Signal when your deployment exposes a named Signal scope:
106+
107+
```py
108+
bec.messaging.signal.set_auto_notifications(
109+
"alarm_major",
110+
enabled=True,
111+
scopes="beamline-ops",
112+
)
113+
```
114+
115+
## 2. Add more event routes
116+
117+
You can enable more than one event for the same service:
118+
119+
```py
120+
bec.messaging.scilog.set_auto_notifications(
121+
"scan_completed",
122+
enabled=True,
123+
scopes="default",
124+
)
125+
126+
bec.messaging.scilog.set_auto_notifications(
127+
"scan_interlock",
128+
enabled=True,
129+
scopes="default",
130+
)
131+
```
132+
133+
You can also route the same event to more than one service. For example, keep SciLog for the permanent record and send major alarms to Signal as well:
134+
135+
```py
136+
bec.messaging.scilog.set_auto_notifications(
137+
"alarm_major",
138+
enabled=True,
139+
scopes="default",
140+
)
141+
142+
bec.messaging.signal.set_auto_notifications(
143+
"alarm_major",
144+
enabled=True,
145+
scopes="beamline-ops",
146+
)
147+
```
148+
149+
## 3. Use the default scope
150+
151+
If your messaging service already has a suitable default scope, set it once and omit `scopes=` afterwards:
152+
153+
```py
154+
bec.messaging.scilog.set_default_scope("default")
155+
156+
bec.messaging.scilog.set_auto_notifications(
157+
"new_scan",
158+
enabled=True,
159+
)
160+
```
161+
162+
This is useful when most notifications should go to the same logbook or group.
163+
164+
## 4. Disable an automatic notification
165+
166+
Disable a route by setting `enabled=False` for the same event and scope:
167+
168+
```py
169+
bec.messaging.scilog.set_auto_notifications(
170+
"new_scan",
171+
enabled=False,
172+
scopes="default",
173+
)
174+
```
175+
176+
If that was the only route for this service and event, BEC removes it from the notification configuration.
177+
178+
!!! success "Congratulations!"
179+
180+
You have configured automatic notifications in BEC. You can now route scan and alarm events to your messaging services without sending each message manually.
181+
182+
## Common pitfalls
183+
184+
- `set_auto_notifications(...)` raises an error if the messaging service is not enabled for the current deployment or session.
185+
- Use the supported event strings exactly as shown above.
186+
- For services with configured scopes such as SciLog, the scope must exist before you enable auto notifications.
187+
- Signal auto notifications are typically routed to a configured Signal scope such as a group, not to an arbitrary phone number.

‎zensical.toml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,8 @@ nav = [
105105
{ "Messaging Services" = [
106106
{ "Send Messages to SciLog" = "how-to/general/send-messages-to-scilog.md" },
107107
{ "Send Messages to Signal" = "how-to/general/send-messages-to-signal.md" },
108+
{ "Set Up Auto Notifications" = "how-to/general/set-up-auto-notifications.md" },
109+
{ "Send a Custom Notification Event" = "how-to/general/send-a-custom-notification-event.md" },
108110
] },
109111
] },
110112
{ Learn = [

0 commit comments

Comments
 (0)