1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
|
.. _ref-bus:
.. module:: trytond.bus
Bus
===
The Tryton server listens on ``POST`` requests on the routes matching
``/<database_name>/bus`` and replies with JSON_ dictionary containing:
``channel``
The channel on which this message has been received.
``message``
A dictionary that is the message the client must handle.
The specification of the message depends of its type.
All messages should at least content a unique identifier in the key
``message_id`` and their type in the key of the same name.
Client sending their requests on the route must be authenticated.
The request must submit a JSON_ dictionary containing:
``last_message``
A value identifying the last message received by the client.
This value can be ``null``.
``channels``
A list of strings denoting the channels the client is listening to.
.. _JSON: https://en.wikipedia.org/wiki/JSON
.. class:: Bus
Expose two methods that are used by the framework:
``publish`` and ``subscribe``.
.. classmethod:: Bus.publish(channel, message)
Send a message to a specific channel.
Implemented messages are:
* :ref:`Notifications <bus_notification_spec>`
.. classmethod:: Bus.subscribe(database, channels[, last_message])
Subscribe a user client to some ``channels`` of messages.
The ``message_id`` parameter defines the last message id received by the
client.
It defaults to ``None`` when not provided.
The default implementation provides an helper method to construct the response:
.. classmethod:: Bus.create_response(channel, message)
Create a dictionary suitable as a response from a message and a timestamp.
``channel`` is the channel on which the message has been received.
``message`` is the content of the message sent to the client.
.. note::
The implementation relies on the fact that the order of the messages
received is consistent across different trytond instances allowing to
dispatch the request to any trytond server running.
Notification
------------
Tryton provides a shortcut to send a notification with the ``notify`` function.
.. function:: notify(title[, body[, priority[, user[, client]]]])
Send a text message to a user's client to be displayed using a notification
popup. The meaning of ``title``, ``body`` and ``priority`` is defined in
:ref:`bus_notification_spec`.
If ``user`` is not set, the current
:attr:`~trytond.transaction.Transaction.user` is used.
Otherwise ``user`` is the user id to notify.
If ``client`` is not set then every client of the user receives the message.
If ``client`` and ``user`` are not set, the system send the notification to
the current user client.
Otherwise the notification is sent to the client whose id matches
``client``.
.. _bus_notification_spec:
Notification message
~~~~~~~~~~~~~~~~~~~~
Notification messages are composed of four parts:
``kind``
The string ``notification``.
``title``
A string containing a one-line summary of the message.
``body``
A string containing a short informative message for the user.
It can span multiple lines but no markup is allowed.
``priority``
An integer between 0 (low priority) to 3 (urgent).
The notification priority on the platform supporting it.
|
