Martini RSS Functions

Overview

Martini RSS Functions (RssMethods) let your services and workflows read an RSS feed from a URL and work with it as a data model, without hand-rolling feed-parsing code. They also let you convert a feed data model back into its XML representation, for example to re-publish or cache a feed you've already loaded.

What You Will Learn

How to read a feed with readRss
How the onlyNew parameter controls whether every feed entry or only new entries are returned
How Martini caches loaded feed entries so repeated calls can distinguish new entries from ones already seen
How to convert a feed data model back into an XML string or write it directly to a Writer with rssToString and rssToWriter

When To Use This

Use Martini RSS Functions when you need to:

Read the current entries of an RSS feed on demand, inside a service or workflow, instead of waiting for the RSS Trigger to poll on a schedule
Fetch only the entries added since the last time a given feed URL was read, without maintaining your own read/unread tracking
Re-serialize a feed data model — for example one you built or modified — back into a valid RSS/Atom XML document

Prerequisites

Martini Designer installed and running
A Martini package in the current workspace
A service or workflow to invoke the functions from
Basic understanding of the following:
- Invoke Function Node for workflows
- Function Step for services

Reading RSS Feeds with readRss

readRss fetches an RSS feed from a URL and returns it as a data model. It's exposed both as a generated function you can drag into a Function Node/Function Step, and as a Groovy one-liner directly on the feed URL string — '<url>'.readRss(onlyNew).

readRss requires a non-null url and an onlyNew flag that defaults to false when omitted in Designer.

Hidden single-argument overload

An older readRss(url) overload without onlyNew is hidden from the generated function surface. Always use the two-argument readRss(url, onlyNew) form shown below and pass onlyNew explicitly.

Getting Started with readRss

Call readRss with the feed's URL and onlyNew set to false to fetch every entry currently in the feed:

def feed = 'http://news.google.com/?output=rss'.readRss(false)
def titles = feed.entries.collect { it.title }

Expected result: feed is a data model with an entries property listing every item currently in the feed, each exposing properties such as title and link, so titles becomes a list of every entry's headline.

Controlling New-Entry Filtering with the onlyNew Parameter

The onlyNew parameter determines whether readRss returns every entry currently in the feed, or only the entries not previously returned for that url:

`onlyNew` value	Behavior
`false` (default)	All feed entries are included in `entries`, regardless of whether they were returned before.
`true`	Only entries not previously returned for this `url` are included in `entries`.

// Returns every entry currently in the feed
def allEntries = 'http://news.google.com/?output=rss'.readRss(false)

// Returns only entries not previously returned for this URL
def newOnly = 'http://news.google.com/?output=rss'.readRss(true)

How the RSS Feed Cache Works

To determine which entries are "new", Martini caches every entry it has loaded for a given feed url under ${martini-home}/data/rss. Each call to readRss compares the feed's current entries against this cache:

Entries not already present in the cache for that url are treated as new and are added to the cache.
When onlyNew is true, only these new entries are returned.
When onlyNew is false (the default), every entry currently in the feed is returned, regardless of whether it's already in the cache.

The cache is keyed by feed url, so reading the same feed from a different URL — for example a paginated or mirrored variant — is tracked independently, even if the entries overlap.

RSS Feed Return Value

readRss returns a data model with an entries property containing the feed's items. Each entry exposes common feed fields such as title, link, and publishedDate, matching the same information available through the RSS Trigger's entries/entry variables. Use this returned data model directly in a Map Step or Repeat Node, or pass it to rssToString/rssToWriter if you need to serialize it back to XML.

Troubleshooting Reading RSS Feed Issues

Problem	Cause	Fix
`entries` is empty even though the feed has content	`readRss` was called with `onlyNew: true` and every current entry was already cached from a previous call	Call `readRss(url, false)` to return every entry regardless of the cache, or clear the relevant cache file under `${martini-home}/data/rss`
Entries you've already processed keep reappearing	`onlyNew` was left at its default (`false`)	Pass `onlyNew: true` explicitly if you only want entries not previously returned for that `url`
`url` parameter error / `IllegalArgumentException`	`url` was `null`, which is not allowed for `readRss`	Provide a non-null feed URL string

Converting Feed Data Models to XML with rssToString and rssToWriter

rssToString and rssToWriter convert a feed data model — such as one previously returned by readRss — back into its XML representation. Use these when you need to re-publish, cache, or forward a feed you've already loaded and possibly modified, rather than rebuilding the XML by hand.

Getting Started with rssToString

Call rssToString with a feed data model to get its XML representation as a String:

def feed = 'http://news.google.com/?output=rss'.readRss(false)
def feedXml = rssToString(feed)

Expected result: feedXml contains a valid RSS/Atom XML document representing feed, ready to be returned as an HTTP response body, written to a file, or stored elsewhere.

Writing Feed XML Directly with rssToWriter

Call rssToWriter when you want the XML written directly to a Writer — for example an HTTP response writer or a file writer — instead of building an intermediate String:

// optain a Writer myWriter and an RSS feed to write to it
def feed = 'http://news.google.com/?output=rss'.readRss(false)
rssToWriter(feed, myWriter)

Expected result: the XML representation of feed is written to myWriter, and no String copy of the XML is held in memory.

Exceptions

Both rssToString and rssToWriter throw an exception if the feed data model can't be serialized:

An IOException is thrown if writing to the underlying Writer fails.
A FeedException is thrown if the XML representation of the feed can't be created — for example, if the feed data model is missing information required to produce valid RSS/Atom XML.

Troubleshooting Feed Conversion Issues

Problem	Cause	Fix
`FeedException` thrown by `rssToString`/`rssToWriter`	The feed data model passed in is missing fields required for a valid RSS/Atom feed	Pass the unmodified data model returned by `readRss`, or ensure any fields you add/remove still satisfy a valid feed structure
`IOException` thrown by `rssToWriter`	The target `Writer` was already closed, or the underlying stream failed while writing	Confirm the `Writer` passed to `rssToWriter` is open and its underlying stream is still writable

Helpful Resources

RSS Trigger — Automatically invoke a service or workflow on a schedule when an RSS feed has new entries
Data Models — Learn how Martini represents structured data such as the feed models used here
Invoke Function Node — Call RSS Functions from within a workflow
Function Step — Call RSS Functions from within a service
Community Q&A: Martini Community Have a question? Post or search it here.