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”:

<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.