105 lines
3.1 KiB
ReStructuredText
105 lines
3.1 KiB
ReStructuredText
.. _ref-bus:
|
|
.. module:: trytond.bus
|
|
|
|
===
|
|
Bus
|
|
===
|
|
|
|
.. class:: 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 request 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.
|
|
|
|
The :class:Bus exposes two methods that are used by the framework: ``publish``
|
|
and ``subscribe``.
|
|
|
|
.. classmethod:: Bus.publish(channel, message)
|
|
|
|
Send a message to a specific channel.
|
|
|
|
Currently 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)
|
|
|
|
Creates 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.
|
|
|
|
Please note that the implementation relies on the fact that the order of the
|
|
messages received is consistent accros 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`` method.
|
|
|
|
.. method:: 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 will receive the
|
|
message. If ``client`` and ``user`` are not set, the system will send the
|
|
notification to the current user client. Otherwise the notification will
|
|
be 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. A one-line summary of the message.
|
|
|
|
body
|
|
A string. The 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.
|