Mercurial > libervia-backend

annotate doc/libervia-cli/notification.rst @ 4180:b86912d3fd33

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