larger smaller normal text version of this page
phplist Documentation

Conceptual Setup of RSS feed distribution via phplist

The components of the PHPlist rss system


phplist has this wonderful system you can use to distribute several sources of information (news, site updates, bookmarks, calendars, job listings...) to people who can subscribe to a selection they're interested in. All of the following applies to a phplist installation where the RSS feature has been enabled: see List configuration .


Components

Let's first explain the components of the system:

RSS Sources


(Also called RSS feeds, news feeds...).
Rss sources are basically just files that sit or lie on a webserver (whatever way you want to think of files on a webserver :-) ). Sometimes they're static (.xml or .rdf) files, sometimes they're dynamically generated. What's important is that they contain information in a format that can be read by other software, such as phplist. An RSS source or feed has a title and a description of its own, and consists of individual items (news articles, job or event descriptions, whatever. These items then typically have a title, a link (where you can find more information) and a description: this is the body text. The rss sources can be both your own data (on your own webserver), or come from and external website (provided you have the permission to redistribute them).
If you want to know more about RSS, read the excellent RSS Tutorial for Content Publishers and Webmasters or the Wikipedia entry on RSS


phplist: Subscribers, Messages and Lists


So how do we now match RSS sources with subscribers? You could think of several ways doing so, we'll explain the way phplist has done it.


Subscribing to an RSS source is subscribing to a list


While creating your lists (see ListListsInfo) you can associate an rss source with a list. So by subscribing to lists, users can indicate what they're interested in, so from what rss sources they want to receive information.

Subscribers


In phplist, subscribers indicate they want to receive their updates daily, weekly, or monthly (indicated with different colors on the schemas).

PHPlist: matching sources and subscribers

Messages


There is a separate category of messages, evidently called rss-messages that picks up the contents of rss feeds and brings it to the subscribers of the rss-feed lists. An rss message has the token [RSS] in its message body. You 'll find them under the tab rss in your phplist interface.
RSS messages remain "submitted" after the queue has been processed. Every time the queue is being processed, the send process checks whether there are any new RSS items that can be sent to subscribers (see further how this is done).
However, there can be only one RSS message queue per frequency. If a second RSS message of the same frequency has been submitted (= sent or put in queue), then the previously "submitted" message of the same RSS frequency has its status "submitted" changed to "sent". So this means there can only be as many RSS messages submitted (and ready for sending) as there are frequencies: daily, weekly, monthly.










Send process


PHPlist and RSS: how it works
When the processqueue link has been hit (by a browser or by a cron job), the Send Process checks whether there are any RSS messages ready to be sent (= status "submitted"). For every RSS message, having a specific frequency, it goes over the lists the message has been sent to. From those lists, it collects the subscribers having the same frequency as the RSS message.
For such a subscriber, the system controls that
  • it has been at least a day/week/month since last RSS message has been sent
  • there are new RSS items in his or her sources (items that he or she hasn't received so far)
If those two conditions are met, a message is sent containing the new RSS items from the sources/lists subscribed at.

In the schema you'll see that:
  • subscriber 1 (frequency daily) gets the daily message with items from the blue and green RSS source
  • subscriber 2 doesn't get any message because the RSS message of his frequency has not been sent to the source he's subscribed at
  • subscriber 3 doesn't get any message because no weekly RSS message has been sent
  • subscriber 4 does get an RSS message, however only containing items from the blue feed because the monthly RSS message is only sent to the blue feed
  • subscriber 5 doesn't get a message because he's not subscribed to any feed


Extra conditions: threshold number and max nr of items to send


PHPlist and RSS : threshold and max numberIn the Configuration menu, the following two values have to be set:
  • "Minimum amount of items to send in an RSS feed" : this is the number of items that has be surpassed before a mail can be sent (actually, threshold is a better name than minimum here). Setting this amount to e.g. 3 makes sure that only messages are sent that contain at least 4 items, so that subscribers do not get annoyed with too many unimportant messages. Setting it to 0 makes sure a message will be sent as soon as there is a new RSS item in one of the subscriptions.
  • "Maximum amount of items to send in an RSS feed": an upper limit in order to make messages not to grow too large (e.g. for people on busy feeds and low frequency, or for the first RSS message that is being sent after subscription to an already populated feed


Troubleshooting


If you have set up your RSS message system and messages are not being sent when processing the queue, what can have gone wrong?
  • Is RSS enabled in the config file (see [[PhpListConfiguration phplist list configuration)?
  • Have you associated one or more lists with an rss feed?
  • Have RSS feed items been retrieved by the Get RSS process (see GetRSSInfo), typically by a cron job(you can check it with the View RSS menu option, see ViewRSSInfo)?
  • Has at least one RSS message been set up (a message with [RSS] in its message body and with a frequency = daily, weekly, monthly) and been submitted?
  • are there any users subscribed to the lists/sources the message has been sent to?
  • do at least one of those users have the same frequency set as the sent message?
  • has enough time (day, week, month) elapsed since last time this subscriber got an RSS message (while testing, delete and resubscribe the test mail adress)
  • are there any new RSS items for this subscriber? Is the number higher than the threshold number?


Typical setups


From the above description of the send process, you might have the impression that the RSS feature is hard to grasp. However, there are some setups that seem quite natural and obvious:


Not differentiating between frequencies

PHPlist and RSS : typical setup
Put simply: make sure all your RSS messages are sent to all your RSS lists/sources (an rss source associated with a list you don't send an RSS message to doesn't make sense anyway).
This way you present your users the list of feeds to select from, and it doesn' matter what frequency they choose for themselves, they'll get the same content, only in smaller or bigger packages (provided the number of items is always under the max nr). The RSS items that will end up in their mailbox only depend on their list selection, not on the frequency. The frequency only determines maybe title or some template elements that mention "daily/monthly/weekly update" etc....


Hiding the frequency for the subscriber


The choice whether a mailing should be daily, weekly or montly often depends more on the kind of content you offer than on the subscriber's preferences. If you offer a "daily updates" feed for distribution, than the weekly or monthly RSS messages might become too heavy anyway. Vice versa for a news source that's only once updated in a week or a month. In that case you can hide the RSS frequency in the subscribe pages and set all your users by default on daily, weekly or monthly, simplifying both your interface and setup (only one RSS message to configure).


Extra: controlling the send time by controlling the RSS feed


PHPlist and RSS : simplified setupSetting all your subscribers' RSS frequency to daily still gives you the possibility of differentiating the send times of the lists/sources you have by organising the updates of the underlying RSS feeds with a certain frequency.
This way you can offer people a "daily update" together with a "weekly calendar", or a "weather overview of the past month" together in the same phplist installation, all of the messages fully automated and run by scripts that package the news items of the past day, the calendar of the upcoming week, wheather overview of the past month, in daily, weekly, monthly refreshed RSS feeds. The awkward thing here might be the fact that the subject of your daily RSS message does not reflect the varying content. You could set up a cron job changing the message subject every day (such as ... Update of Sunday.. xth of month) but there is no way to vary the subject according to the content of the message, that being user/subscription dependent.





CategoryDocumentation
Page was generated in 0.0793 seconds