Mercurial > libervia-backend

comparison doc/libervia-cli/notification.rst @ 4135:646b328b3980

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc (cli): `notification` commands documentation.
author Goffi <goffi@goffi.org>
date Wed, 18 Oct 2023 15:33:46 +0200
parents
children
comparison
equal deleted inserted replaced
4134:8d361adf0ee1 4135:646b328b3980
1 .. _libervia-cli_notification:
2
3 ====================================
4 notification: notifications handling
5 ====================================
6
7 Notifications can be retrieved, expired or created with the ``notification`` commands.
8
9 add
10 ====
11
12 Add and broadcast a new notification. Only admin profiles can add a notification.
13
14 It can be used for service announcement, such as planned maintenance.
15
16 To make an announcement to all profiles, use the ``-g, --is-global``. Note that such
17 global notification aren't deleted when using :ref:`libervia-cli_notification_expire`
18 command: you have either to use ``-e EXPIRE_AT, --expire-at EXPIRE_AT`` to
19 set an expiration date, or to delete them manually with
20 :ref:`libervia-cli_notification_delete`.
21
22 example
23 -------
24
25 Add a global service announcement to indicate that the server will be shut down. The
26 expiration date is set so that the notification will be expired after expected end of
27 maintenance::
28
29 $ li notification add service "Server will be shut down for maintenance." -P HIGH -g -e "2023-10-22"
30
31 get
32 ===
33
34 Retrieve notification for current profile. If ``-f, --follow`` argument is used, the CLI
35 will continue to run and show any new incoming notification.
36
37 examples
38 --------
39
40 Louise wishes to obtain her current notifications and display any new notifications as
41 they are issued::
42
43 $ li notification get -f
44
45 Louise wants to see all her chat notifications which are at least of high priority (this
46 includes urgent ones)::
47
48 $ li notification get -t chat -P HIGH
49
50 .. _libervia-cli_notification_delete:
51
52 delete
53 ======
54
55 Delete a notification by its ID. The notification must belong to the profile doing the
56 request.
57
58 If ``-g, --is-global`` is used, a global notification is to be deleted. Only admins can
59 delete a global notification.
60
61 example
62 -------
63
64 Louise (who is an admin) wants to delete a previous global service announcement with ID ``123``::
65
66 $ li notification delete -g 123
67
68 .. _libervia-cli_notification_expire:
69
70 expire
71 =======
72
73 Delete expired notification (the ones with an expiration date set).
74
75 If ``-l TIME_PATTERN, --limit TIME_PATTERN`` is used, also delete notification which have
76 been **created** before the given limit. Some notifications can't be deleted this way: if
77 they are global, or if they require a user action. Using ``now`` as time pattern will
78 clear all the notifications that can be deleted.
79
80 By default, only notifications of requesting profile are deleted (except for expired ones
81 which are always deleted). If ``-a, --all`` is used, notification for all profiles can be
82 deleted. This option is notably useful to schedule automatic notification cleaning.
83
84 example
85 -------
86
87 Louise want to expire notification for all profiles that are older than 7 days::
88
89 $ li notification expire -a -l "7 days ago"