Iceberg contains some great support for working with web services and resources which return xml data, such as RSS feeds. If the service you are interested in allows you to make HTTP requests such as POST, GET, PUT or DELETE, then you can use Iceberg to connect to it.
This quick start will show you how to set up a fully functional RSS feed reader with using Iceberg in about 15 minutes.
First of all, if you haven't already, download a copy of Iceberg and install it.
Open your browser and point it to your local Iceberg location. If the welcome screen below does not appear automatically, you can open it by clicking the Show welcome page link on the home tab, or, from the Applications tab, the Show the Getting Started Wizard under Useful Links to the right of the page.
Click the Build application now link to start the Application Wizard. When it appears, fill in the following values:
Application name: RSS Feed Reader
Object names: RSS Feed, RSS Item
Click Make My Application to proceed to the next step
Define a relationship between RSS Feed and RSS Item. A feed can have many items. Click Save Changes to apply the relationship, and then click Continue To Setup your Forms
We want to make some modifications to the objects that Iceberg has create for us. Firstly, we want to add some additional fields to RSS Item, and also reorganize its default form to make it easier to use when adding new feeds. A full discussion on working with Iceberg forms is beyond the scope of this tutorial, but you can find lots more information on the Learn Iceberg wiki.
Create a new field of type Large Text, called Item Template. Make sure the Allow Html/Xml checkbox is ticked. This field will store the magic xml fragment that takes care of turning the rss feed into variables that you can use in your process.
We will also create a Small Text field called RSS Feed Url which will store the location of the rss feed.
Finally, we will rearrange the fields on the form. To do so, remove all of the system fields created by Iceberg (by dragging them into the Available Items area), and then add a single column Fieldset to the form called Item Template, to separate this field from the others. When you are done, your form should look similar to the following image. Click Finish Customizing when you are happy with it.
You will be presented with a screen allowing you to create a new RSS Feed item. That's what we will do now. I've chosen the CNN Technology feed, you may use any feed you like. Clicking on the feed link will take you to a page similar to the one shown here:
We are interested in two things. Firstly, the url of the page, which we already have, and secondly, we want to access the raw xml returned from the feed. In order to get that, right click on the page and click View Source. (note: the technique for viewing a page's source may vary based on your browser). If you are using Internet Explorer with its default settings, the source will open in a new Notepad window. If it doesn't, copy the source and paste it into a new Notepad window. You should now have something similar to the following image:
Don't worry too much if you don't understand this. All you need is very basic xml/html skills to complete the next step. What we want to do, is set up a 'template' xml document which will show Iceberg what information it should extract from the xml. To do this, we only need to follow a simple rule:
Identify the element which contains the information you need, if this element is a repeating element, remove all but one of them. It does not matter which one you keep, Iceberg only cares about the tag names, not the data within them. It is important to only have one element in a repeating sequence however.
In this case, the repeating element we want information from is the item element. In an RSS feed, each story is defined by a corresponding item element. Therefore, by following the above rule, we remove all of the items except the first one.
Now for the magic part. Looking at an item, we can see that there are a common elements that contain the information we need. In particular, the elements we are interested in are: title, description, link and pubDate. The way we tell iceberg about these elements is by replacing their content with the name of a variable. A variable is simply a word enclosed in curly braces, such as {title}. When we apply this template in a process loop later in this guide, Iceberg will examine the live xml feed and place the values of these elements in the variables we define here. Iceberg will take care of managing repeating elements like item for you so you can loop over the document and the variables will have different values for each item in the feed.
The final template should look similar to the following image.
Note that there is only one item element, and that the contents of its sub elements have been replaced with some variables.
Note: for clarity I have removed additional elements from the channel tag (such as title, copyright, image etc). You can leave these in your template is you wish.
Note: also that you need to keep the channel tag wrapped around the single item. This allows Iceberg to understand where the item tag can be found in the live xml feed.
Note: to capture the value of an attribute, simply replace the content of the attribute with a variable name. For example, to capture the href and text of a link, you would set up a template containing something like this: <a href="{link}">{text}</a>.
Now that we have the item template that we need, we can create a new RSS Feed. Copy the xml you edited in the Notepad window and paste it into the Item Template field in the new RSS Feed form in Iceberg. We also enter the feed url into the RSS Feed Url field. The form should look similar to the image below. Click Create when you are ready, and then close the nested popup window. We will now move on to the RSS Feed Item form.
Click on the link to customize the RSS Feed Item form. Remember the variables we added to the Item Xml template above? Well now we will create some fields to capture that information. IF you recall, we want to capture four pieces of information: title, description, link and publicationDate. Iceberg has already created a Description field for us, and we will use the existing Name field to store the title of the item. That means we only need to create fields for link and publicationDate. To do do, create two Small Text additional fields called Link and Publication Date. Rearrange the form by moving the unnecessary system fields into the Available Items area. When you are finished, the form should look similar to the following image.
The last thing we will do for this form, is to make the RSS Feed field read-only. If you recall, we defined a relationship between an RSS Feed and its RSS Items. When we did this, Iceberg automatically created a field for us called RSS Feed and placed it in the Available Items area. This field associates an item with the feed it came from. Because an item logically can not be moved from one feed to another, we want to make that official by preventing the user from changing it through the front end. To do so, double-click on the RSS Feed field, and ensure the Read-Only checkbox is checked.
Now we have the RSS items set up the way we want them, we can close the wizard and return to the main Iceberg interface. Navigate to the Applications tab to see your new RSS Feed Reader application
You will notice that there are two new tabs called RSS Feeds and RSS Items, which were created for you by the Application Wizard. Click on the RSS Feeds tab to view a list of all the feeds we have so far. You will notice that there is one feed called CNN News (or whatever you named your item when you created the feed above). You will also notice that there are lots of columns which we don't need. To get rid of them, customize the view and rearrange the columns. Add the following columns: Name, RSS Feed Url.
Choosing the columns for the feed list
Much better
We are now ready to create a process which will retrieve the RSS items from the feed! In Iceberg, all the behavior or logic is defined in processes. A process can be run when you create or change an object, or, as we are about to do, you can run a process when the user clicks a button. Go back to the Applications tab, and click on the RSS Feed Reader Application. You will see a form similar to the image below. Click on the link to customize the RSS Feeds form.
We are going to add a new Button to this form, called Get Items. In the Process To Run drop down, leave (Create New Process) selected. After you create the button, add it to the form. When you add a button to a form, it doesn't matter where you place it, as it is moved to the top of the form when it is displayed.
We are now ready to define the process which will retrieve the rss items for us. Open the process designer by clicking the Launch Process Designer button on the top right of the page. When the process designer loads and you have logged in, open the 'Get Items' Button Clicked process by clicking on it.
The first step we will add, is an Expression to retrieve the xml for the RSS feed. Select the Toolbox tab on the left of the process designer, and drop an Expression object on to the form. When the Expression form appears, click the text area to edit the content of the Expression. We are doing two things here. Firstly, we are retrieving the xml data, and secondly, we want to tell Iceberg to loop over this xml and extract the data we want from it.
To achieve the first objective, retrieving the xml, we use the built-in get() function in Iceberg. This function will retrieve the content from a particular url. If you recall, we have already defined the url we need in the RSS Feed object, in the RSS Feed Url field. To place the value of this field in the expression text, expand the Click here to insert drop down, and navigate to the RSS Feed Url property in the Current Object folder.
To achieve the second goal, looping over the xml and extracting its values, we use another built-in function called xpathloop(). This is a special function which is used to control Loops in Iceberg. When you place a Loop directly after an Expression with this function, the Loop will use the xml and the optional template to extract values for you. Because we have to pass the xml from the rss feed into this special function, we have used a variable called xml.
Earlier on, we defined an xml template for our RSS Feed, and now its time to use it! The xpathloop function takes two pieces of information. The first piece is the xml we want to loop over, and the second is the template which tells Iceberg how to extract information from that xml. To complete the expression:
add an xpathloop function from the OPTIONS LIST folder in the Click here to insert drop down.
leave the first argument as xml
for the second argument, we insert the Item Template field from the Current Object folder, as we did with RSS Feed Url above
When you are finished, you should have the following text in the expression text area:
var xml = get({Current Object: RSS Feed Url});
xpathLoop(xml, {Current Object: Item Template})
If you find the above confusing, just copy and paste this into the field and move on to the next step. The image below shows the Expression form when you have finished setting it up
The next step in the process is a Loop over the items in the RSS Feed. To enable this, we simply have to add a Loop to the process, and directly connect the Expression we just created to it. You do not need to set the values on the Loop form, as the Loop is smart enough to know that it should use the xml and its associated template.
Now we have a process which will retrieve the RSS Feed and will loop over all the items in it, extracting their values into variables which you can use. That's most of the work done. The only step left, is to create a new RSS Item object using the values from each item in the feed. To do so, add a new Create Business Object step into the process between the Loop start and end points. When the Create Business Object form appears, specify that you want to create a new object of type RSS Item (from the drop down list pictured below). Also ensure that the Create a new object in the database radio is checked.
Now you can enter apply the variables which were extracted from the RSS Feed to this new object. To do this, you simply type the variable name including the curly braces into the text box for its corresponding field. As you may notice from the screenshots below, you can insert html into the text boxes as well as just plain text. This allows us to make the Link field an actual HTML link as opposed to just a piece of text. To do so, enter the following text into the fields text box:
<a href='{link}' target='_blank'>Full story</a>
This is a powerful feature that enables you to have complete control over forms and fields in Iceberg. To associate this item with the feed it originated from, set the RSS Feed field to the ID field of the Current Object.
That's all there is to it, you are now ready to use the feed reader. the complete process is comprised of only two logical steps and a single loop.
Close the process designer and return to Iceberg. Navigate to the RSS Feeds tab and select the CNN News feed. When the form appears, click the Get Items button to load the feed. When the page refreshes, you will see a listing of items in the RSS Items related list underneath the form. When the list appears initially, it wont look very useful with all the default system fields displayed as columns. Lets fix that by removing the columns we don't want, scroll to the bottom of the page, and click the columns button
Remove the unwanted columns, and add the following columns in order: Name, Publication Date and Link
Now the list of items looks much better. You can see the headline for each story, and clicking on the Full Story link will open a new page taking you to the full page for that item. You have just built a functional feed reader. You can now add more feeds to the RSS Feeds list.
Any ideas for where to go next? What about setting up a scheduled process to check for new items every hour? How about adding a check to see if an item already exists before creating it again? There's really no limit to what you can do once you grasp the basics.
