========
Channels
========

Channels are a mean for users to subscribe to area of interest, and receive news
regarding that area of interest. The channel delivery is managed by a customized
erlang module, named mod_channels, which runs on the XMPP server(s).

Currently the only available backend for mod_channels is ODBC backend. This means
that all the channel news and category management is being done via SQL tables.



*Subscription Management*
-------------------------

This section is dedicated to subscription management.
Please bear in mind that at the time of the writing for the present 
documentation, the channels are available only to users that are
created and authenticated using ODBC, *not* to external-authenticated users.
The subscription is managed by the *xmpp_service* buddy, so by all means check it: `<xmpp_service_supported_messages.html#channels>`__


*XMPP Channel news format*
--------------------------

This is an example of the message that will be delivered to the user test01, subscribed to the channel "canale1":

.. code-block:: xml

   <message to="test01@timpersonal" from="news_sender@timpersonal" xml:lang="en" id="51dd8ee2-8c70-452d-a40e-db2cd45285b9" type="chat">
       <x xmlns="jabber:x:oob">
          <type>chat_text</type>
          <action>chat_text</action>
          <payload>
          {
           "text": "vulevu vulevu vulevu"
           "type": "chat_text"
          }
          </payload>
      </x> 
      <body/>
      <thread>canale1</thread>
      <delay xmlns="urn:xmpp:delay" stamp="2019-06-24T09:02:34.000000Z" from="timpersonal">
             Channels News Delivery
      </delay>
   </message>

EIMe messages are supported (in the payload: you will receive them escaped of course), and the "stamp"
parameter in the <delay/> tag contains the publish timestamp for the news.
As you can see, the tags are being populated according the values. The basic message is fetched as a template from the news content, and then
enriched with the channel name (in this case, "canale1"), that goes in the <thread/> tag, while the UUID for the news is used as message id.
In this way you could have channels arranged as a tree, for example, like news/series, news/italy, news/italy/rome. There is no limit to the
channel name(s) characters or style, but we recommend using a tree-like structure in order to keep things tidy.



*Data Model*
-------------

In this section we'll show the data model for the channels, the purpose of the tables,
and we'll show some examples regarding the messages that will be receive by users
when they log in. The DB schema is living in the same schema as the XMPP server 
(e.g. for xmpp development environment, name is xmppsvil).

Please bear in mind that, should a channel_id be deleted from channels table, all the news pertaining to that channel will be deleted.

The news uuid is automatically generated on news insertion (but you can insert an UUID if you want, when you populate the news).
When a user connects, he automatically receives the news for all the channels he's subscribed to (please see below for subscription), that are
in the validity period for that news (for example, if you publish a news with a 48 hours validity, if a user subscribed to that
channel news, connects three days later, he will not receive it). You can write anything inside the <message/> tag, even custom payloads,
using the <x/> special EIMe tag. 


Channels table
```````````````

+-----------------+-----------------------------------------------------------------------------------+
| Column          | Purpose                                                                           |
+=================+===================================================================================+
| id              | A numeric auto-increment to refer to the channel+domain+category in a fast way    |
+-----------------+-----------------------------------------------------------------------------------+
| name            | The channel name                                                                  |
+-----------------+-----------------------------------------------------------------------------------+
| domain          | The XMPP domain this channel refers to                                            |
+-----------------+-----------------------------------------------------------------------------------+
| category        | The category for this channel. One of the ones in table channels_categories       |
+-----------------+-----------------------------------------------------------------------------------+
| sender          | The sender address that will be used to delivery news for this channel            |
+-----------------+-----------------------------------------------------------------------------------+


Content example:

+----+---------+-------------+----------+-------------+
| id |  name   |   domain    | category | sender      |
+====+=========+=============+==========+=============+
|  1 | canale1 | timpersonal | news     | news_sender |
+----+---------+-------------+----------+-------------+
|  3 | canale2 | timpersonal | news     | majordomo   |
+----+---------+-------------+----------+-------------+


Channels Categories table
``````````````````````````

+-----------------+-----------------------------------------------------------------------------------+
| Column          | Purpose                                                                           |
+=================+===================================================================================+
| name            | The category name                                                                 |
+-----------------+-----------------------------------------------------------------------------------+
| domain          | The XMPP domain this channel refers to                                            |
+-----------------+-----------------------------------------------------------------------------------+
| type            | The type of the category. By default it's "news"                                  |
+-----------------+-----------------------------------------------------------------------------------+

Bear in mind that if you delete a given category name for a given domain, the schema cascadely deletes all
the channels and consequently all the news for that category.

Content example:

+---------+-------------+----------+
| name    |   domain    | category |
+=========+=============+==========+
| canale1 | timpersonal | news     |
+---------+-------------+----------+

Channels news table
````````````````````

+----------------------+-----------------------------------------------------------------------------------+
| Column               | Purpose                                                                           |
+======================+===================================================================================+
| news_id              | An automatically generated UUID that identifies this particular news              |
+----------------------+-----------------------------------------------------------------------------------+
| channel_id           | The channel id for this news. Must be one of the channel ids in channels table    |
+----------------------+-----------------------------------------------------------------------------------+
| packet               | The basic XMPP packet for this news. See below for more details                   |
+----------------------+-----------------------------------------------------------------------------------+
| publish_timestamp    | The publish timestamp in microseconds. Automatically populated                    |
+----------------------+-----------------------------------------------------------------------------------+
| validity_hours       | How many hours should the content be valid. By default 24 hours.                  |
+----------------------+-----------------------------------------------------------------------------------+

Content example:


+--------------------------------------+------------+---------------------+----------------+---------------------------------------------------------------+
|               news_id                | channel_id |  publish_timestamp  | validity_hours | packet                                                        |
+======================================+============+=====================+================+===============================================================+
| 81b4756b-b43f-4df7-ae61-738d8593ccef |          3 |  1561366954000000   | 24             | <x xmlns='jabber:x:oob'><type>chat_text</type><action>        |
|                                      |            |                     |                | <action>chat_text</action><payload>{ "text": "evviva          |
|                                      |            |                     |                | le supercazzole!", "type": "chat_text" }</payload></x>        |
+--------------------------------------+------------+---------------------+----------------+---------------------------------------------------------------+
| 51dd8ee2-8c70-452d-a40e-db2cd45285b9 |          1 |  1561366954000000   | 24             | <x xmlns='jabber:x:oob'><type>chat_text</type><action>        |
|                                      |            |                     |                | <action>chat_text</action><payload>{ "text": "tutti a         |
|                                      |            |                     |                | protestare a mirafiori!", "type": "chat_text" }</payload></x> |
+--------------------------------------+------------+---------------------+----------------+---------------------------------------------------------------+
| 7a96f1be-b59c-4568-83a5-bfc568424f2a |          3 |  1561366954000000   | 20             | <x xmlns='jabber:x:oob'><type>chat_text</type><action>        |
|                                      |            |                     |                | <action>chat_text</action><payload>{ "text": "hello all       |
|                                      |            |                     |                | erlang devs", "type": "chat_text" }</payload></x>             |
+--------------------------------------+------------+---------------------+----------------+---------------------------------------------------------------+
| 0ff2be8c-eecc-46b2-a7ad-f8cfd9db620a |          3 |  1561366954000000   | 2345           | <x xmlns='jabber:x:oob'><type>chat_text</type><action>        |
|                                      |            |                     |                | <action>chat_text</action><payload>{ "text": "news 2",        |
|                                      |            |                     |                | "type": "chat_text" }</payload></x>                           |
+--------------------------------------+------------+---------------------+----------------+---------------------------------------------------------------+

Channels subscribers table
``````````````````````````

This is a simple join table that connects the web_users id and the channel_id, in a one-to-many fashion:


+-----------------+-----------------------------------------------------------------------------------+
| Column          | Purpose                                                                           |
+=================+===================================================================================+
| subscriber_id   | The subscribed id (the id column from web_users table)                            |
+-----------------+-----------------------------------------------------------------------------------+
| channel_id      | The channel id this user is subscribed to                                         |
+-----------------+-----------------------------------------------------------------------------------+

Content example:

+----------------+-----------------+
| subscriber_id  |   channel_id    | 
+----------------+-----------------+
| 27411549       | 1               | 
+----------------+-----------------+
| 27411549       | 2               | 
+----------------+-----------------+


Please remember that if you delete the user from the web_users table, all of his subscriptions will be cascadely deleted from this table.