RSS, Atom and OPML feeds for integrations #

This page is for integrators who need a simple, standard way to move lists of content between systems. A feed is a pull integration that needs no code: Exponential publishes a feed that any reader, aggregator or downstream system can poll, and it can read the RSS feeds of other systems and turn their items into content objects. The administration side is described in RSS feeds.

Contents #

1. When a feed is enough
2. Exporting
3. Importing
4. How imported items are keyed
5. Caching and freshness
6. Limits
7. Checklist

When a feed is enough #

Exporting #

An export lists the newest objects below one or more sources (a location, a class, and optionally the subitems) at /rss/feed/<address>, on the public site of the export's siteaccess. Formats (kernel/classes/ezrssexport.php):

Per source you choose which class attributes become the item's title, description, category and enclosure. Create and edit exports at Setup > RSS (/rss/list, policy rss/edit). Exports are stored in the database (ezrss_export and related tables), so set them up on each environment or include them in the database you copy.

Test an export from the receiving side:

curl -s https://example.com/rss/feed/<address> | head -20

Importing #

An import reads an RSS feed (RSS 0.91, 0.92, 1.0 and 2.0; kernel/classes/ezrssimport.php) and creates an object below its destination for every item it has not seen before. The import form has four parts: the feed and its URL, where the items go (destination and owner), what each item becomes (the class and the mapping of feed fields to attributes), and whether it runs.

Nothing is read until the cronjob runs: rssimport.php is in the global part of settings/cronjob.ini ([CronjobSettings] Scripts[]), which runs when runcronjobs.php is called without a part name:

php runcronjobs.php -s <siteaccess> --script=rssimport.php   # one run, by hand
php runcronjobs.php -s <siteaccess>                          # the global part, as the crontab runs it

The import refuses external entities and switches the network off while parsing (LIBXML_NONET), and fetches only http and https addresses.

How imported items are keyed #

Every object an import creates gets a remote id that starts with RSSImport_<import id>_; the RSS overview counts imported objects by that prefix. This is the same idea every integration should use: a stable, prefixed key per source record (Idempotent imports keyed by remote_id).

An import adds objects and never removes or updates them. To keep a busy feed from growing without limit, switch on the cleanup (content.ini [RSSImportCleanupSettings], command php bin/php/cleanuprss.php --apply, cronjob part cleanuprss), which keeps the newest N items of each active import (RSS import cleanup).

Caching and freshness #

Tell the consumers how often to poll; polling far more often than CacheTime gains nothing.

Limits #

• No Atom import: the importer reads the version attribute of an RSS root element only.
• GET /api/ezp/<version>/content/node/<id>/listAtom of the REST API answers 500; use an RSS export instead.
• An export lists the newest items, not a full archive: it is not a substitute for a data export.
• Imports do not follow updates or deletions of items at the source.

Checklist #

• To do: Export: format, address, sources, item count and attribute mapping agreed with the consumer.
• To do: Export: CacheTime and the polling interval written into the interface specification.
• To do: Import: destination, owner (a service account) and class mapping set; the feed URL uses https.
• To do: Import: the cronjob that runs rssimport.php is in the crontab and runs for the right siteaccess.
• To do: Import: cleanup configured if the feed is busy.

Related pages #

• RSS feeds
• RSS: Apple Podcasts feeds, a paged feed list and safer exports
• OPML exports
• Syndication between installations
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.