Welcome to Awasu

Innovative RSS

The Awasu main window If you're looking for something to read your favorite blogs and news channels with, Awasu offers both power and flexibility and is far and away one of your best choices. It comes with:

  • a modern and fully customizable user interface.
  • individually configurable channels.
  • advanced features to manage your channels.
  • content archiving, coupled with an advanced search engine.
  • an extensive API.

You can also do many other things like:

  • automatically download your favorite podcasts.
  • integrate with many popular online services.
  • automatically keep your blogroll up-to-date.
  • keep working even when you're not online.
  • actively monitor your feeds for things you're interested in.
  • bookmark and annotate items.
  • keep multiple copies of Awasu in sync with each other, and even other feed readers.
  • take information out Awasu and republish it.

Take the tour or check out the feature list for more details.

Powerful RSS

End-to-end information management If you want a tool for monitoring information from any source, something that will let you intelligently manage the information flow, that offers powerful features not available in any other feed reader, then Awasu is your only choice.

Awasu's plugin architecture lets you extract information from any data source and monitor it in the same way as a regular feed. Advanced XML features let you also easily integrate with web services and other XML data sources.

And you're not restricted to processing just RSS/Atom data, Awasu can get at any information embedded in your feeds. Whether it be the increasingly popular microformats or your own proprietary XML metadata, Awasu can extract it, present it to the user and do further processing on it.

Awasu also lets you hook into the flow of information to perform your own custom actions as it is processed. You can monitor the information, analyze it and then respond to it. No longer are you restricted to using a passive tool like a web browser. Awasu lets you actively manage your information in the way you want to and leverage it for your benefit.

Awasu is the only feed reader that offers a powerful and comprehensive end-to-end management of transporting and processing your information

.

Your RSS

There's no doubt that feeds have become immensely popular and everyone from the BBC, Microsoft and Google are offering them. Maybe you have a few yourself!

Instead of letting your customers struggle to decide which feed reader to install and how, only to then be faced with figuring out how to subscribe to your feeds, make it easy for them and provide a branded version of Awasu. All they have to do is download and run the installer and they'll be immediately set up with your customized feed reader, with your feeds already in place and updating.

It really couldn't be any easier!


Feature summary

General features

  • Monitors any site that provides an RSS or Atom feed.
    There are millions of channels available on the Internet, including all the major news sites and weblogs, and the number is growing daily. Awasu can also monitor sites and other data sources even if a feed is not available!
  • Notification balloon Lets you know when new content is found.
    You can customize each channel to show a notification balloon, play a sound or animate the system tray icon. Or all three!
  • Keeps track of what you have already read so you don't waste time looking at things more than once.
  • Automatically removes ads, web-bugs, and other unwanted content from your feeds before showing it.
  • Lets you read linked-to articles and shows images embedded in feeds even when you're not online.
    These are downloaded and archived in the background so that they are available even when you are not connected to the Internet.
  • Lets you keep Awasu synchronized with not only other copies of Awasu but other feed readers as well.
  • Channel folders Advanced channel management features let you keep your channels organized, only showing the ones you want.
    Much more powerful than the traditional method of using folders and sub-folders, Awasu's smart folders and channel filters let you precisely control which channels are displayed at any given time.
  • Each channel can be individually customized.
  • Automatically detects new feeds as you browse.
    Auto-discovery is a way for web sites to let programs such as Awasu know that they have feeds. Whenever you browse to a web site announcing their feeds in this way, Awasu will let you know so you can check them out and subscribe.
  • Automatically downloads podcasts (enclosures) and other related files.
  • Comprehensive security features ensure that potentially dangerous content is not delivered to your computer via your feeds.
    Awasu removes any potentially dangerous HTML content from your feeds before presenting it to you, as well as integrating with Internet Explorer's own security features.
  • Lets you quickly identify and delete dead and dormant channels, ensuring that you're only subscribed to current and relevant channels.
  • Fully customizable user interface.
    Includes advanced features such as docking and auto-hide windows, personalized menus and toolbars, and full-screen mode. You also have full control over the presentation of your channels .
  • Optimized keyboard interface for the fastest possible browsing. Or if you prefer the mouse, a one-click mode is provided to speed navigation.
  • System tray menu Channels can be added to the Favorites menu, system tray menu, Tasks Pane or Sidebar for quick access.
  • Uses wizards to help you get started with the more powerful features of Awasu.
  • Supports secure feeds using HTTP authentication and/or SSL.
  • Uses advanced HTTP features to ensure the most efficient use of bandwidth.
  • Comprehensive support and documentation.

Productivity features

  • Workpads let you save and annotate feed items.
    Reports can be generated from the contents of a workpad, making them a great research tool. Scour the net for articles of interest and collect them in a workpad, add your own comments and then put them all together into a single report.
  • Archives all feed content and provides an advanced search engine to help you find what you're looking for.
  • Item filters and search agents can be set up that will flag items of interest. You can also create search channels that will monitor the results of a search query as a feed in its own right.
  • Allows content to be exported out of Awasu.
    Reports are remarkably flexible and can used to perform tasks such as:
    • provide a single-page summary of your channel content
    • export your channels any format whatsoever e.g. OPML, HTML, XML, CSV, plain-text, etc.
    • automatically keep your blogroll up-to-date
    • create meta-channels
    Reports can be saved to a file, emailed out or uploaded to a web site.
  • Provides quick access to online tools such as Google, Twitter and Wikipedia.
    You can also easily integrate with any other PC- or web-based tool.
  • Integrates seamlessly with the most popular web sites.
    Awasu knows how to subscribe to feeds published by web sites such as Google and YouTube.

Advanced features

  • An extensive API opens up access to the information in Awasu, and control over its functionality.
  • Allows information to be retrieved from any source using plugins.
    You are no longer restricted to monitoring content provided by third-party feeds. Whether the information you want is on a web page, in a database or provided by a web service, you can write a plugin to retrieve it and transfer it into Awasu.
  • Using channel hooks, you can tap into the flow of information as it moves around within Awasu to perform actions such as send out emails or update databases.
  • Find out more about Awasu's end-to-end information management.

    Metadata modules allow any information to be extracted from the feed XML, not just RSS/Atom data.
    This let you publish feeds with your own specialized information embedded in them, then extract and process it on the client side.
  • Application plugins can be installed to extend the functionality of Awasu itself.
  • A powerful template processing engine gives you complete control over Awasu's output.
  • Allows feeds to be modified using XSLT.
  • Allows web services, or any other data source that publishes information using XML, to be queried using SOAP.


Plugins

Channel plugins Plugins are small programs that are used to extend Awasu's functionality [1].

No longer are you limited to feeds provided by somebody else. If you have information that you want to monitor, simply write a channel plugin to extract it and convert it to a feed that can be read by Awasu.

Nor are you limited to the features provided in Awasu. If you want to extend it to do more things, just write an application plugin!

It only takes a minimal amount of programming experience to write a plugin [2] and all the information you need can be found in the For developers section.

Channel plugins

Channel plugins can be used to retrieve information from anywhere at all, whether it be a web site, your corporate databases or even a running program. They are simply small programs that Awasu runs to retrieve the relevant information and generate a feed that can be read by Awasu.

Here are a few examples of what plugins can do:

  • Monitor job sites
    Specify what kind of jobs you are interested in and Awasu will let you know as soon as it finds something suitable. This can easily be extended to auction or trading sites. Perhaps you're in the market for a new car or looking to rent an apartment. The possibilities are endless!
  • Track package shipments
    Specify a shipping number and Awasu will notify you as it passes through each stage of delivery.
  • Keep tabs on what's happening at your corporate branch offices
    For example, you could keep track of the last 10 sales from each office. You could even ask to be specifically notified of any sales over a certain amount or to special customers.

Application plugins

Application plugins extend the functionality of Awasu itself by adding new features. Just open the Plugins tab in the Control Center to see what's available.

The list of plugins installed as standard can be found here and you can also write your own.

Read more about...
  • Awasu's end-to-end information management
  • Getting more plugins and other extensions
  • Writing your own plugins

[1] The Awasu Wiki has plugins and other extensions written by both us and other people that you can download and use. If you write something that might be useful to others, feel free to upload it and make it available to all.
[2] If you're working with web services, you don't even need to write a plugin! Just use SOAP and XSLT to query the web service and convert the results into a feed.


Channel hooks

Channel hooks Channel hooks are a powerful feature of Awasu that transform it from being just another feed reader into something much more profound.

Like plugins, they are small programs or scripts that get run by Awasu but while plugins are used to generate feeds, hooks are run when certain things happen e.g. when a channel is updated or new items are received. In other words, they hook into the flow of information within a channel.

Why is this so important? Browsers such as Internet Explorer or Firefox and every other feed reader available today are passive tools; they simply display the data as it arrives without understanding anything about what they are showing. Channel hooks let you monitor the information, analyze it and then respond to it.

Some examples

Here are some examples of what channel hooks can do:

  • Monitor your warehouse and take action when stock gets low
    A channel plugin gets the current stock levels in your warehouse from a corporate database and converts it into a feed which Awasu uses to constantly show you the latest information. Every time the channel is updated, a hook is also called that checks if anything is running low and if so, sends a request to your buying department to replenish it.
  • Monitor your stock portfolio and respond to events
    Awasu monitors a channel that shows the current prices of shares in your stock portfolio. Every time the channel is updated, a hook is also called to check for sudden price movements. If something is detected, Awasu sends an urgent SMS message to your mobile phone to notify you and asks if you want to buy or sell any stock. You reply with an SMS message and Awasu forwards those instructions to your broker.
  • Search the Internet for articles and save them in a database
    If you are a researcher, you will probably have quite a few channels relating to your field of interest. A channel hook can be set up that gets called every time new items are found on any of those channels. The new items can be checked for certain words or concepts and if they match, saved in a database. Leave Awasu running for a while and pretty soon, you'll have a database full of items directly related to the subject you are interested in.
Read more about...
  • Awasu's end-to-end information management
  • Channel hooks installed as standard
  • Getting more channel hooks and other extensions
  • Writing your own channel hooks


End-to-end information management

End-to-end information management. Awasu lets you manage your information from end to end, all the way from the server through to the client, where it can be analyzed, processed and responded to.

Awasu is the only feed reader that lets you:

Retrieve information from any data source.
Plugins can be written to retrieve data from any source e.g. a database or scraped from a web page.
Have access to all the information in the feeds.
Metadata modules let Awasu extract additional information from your feeds, even if it's in your own proprietary format!
Analyze and respond to the information as it comes in.
Channel hooks are small programs that can process the incoming information and respond to it.

Retrieve information from any data source

Most feed readers only allow you to subscribe to channels via a web server.

This is not much good if you want information that is not available this way e.g. it's in a database or locked up in another program.

Or maybe it's on another web site that don't offer feeds and have no plans to do so.

Perhaps it's sensitive information that you don't want to publish on a web site that is accessible by anyone and everyone.

Channel plugins Awasu's channel plugins solve all these issues and let you monitor any kind of information, regardless of where it is.

Whether it's in a database or other third-party application, if it's only available from a web page, no matter where the information you want lives, you can write a plugin to retrieve it and convert it into a feed that Awasu can use.

Access to your information

Most feed readers only know how to handle RSS and Atom.

Some of them might support XML extensions commonly used by feeds such as Dublin Core or wfw:commentRss but as new extensions become popular, you have to wait for the developers to add support for them, if it happens at all.

And you know there's no way they'll be adding support for your in-house, proprietary extensions.

Metadata modules Awasu's metadata modules let you extract and process any information embedded in your feeds.

This additional metadata can then be used throughout the system e.g. you can show it to the user or have your channel hooks process it.

Analyze and respond to the information

Most feed readers are passive tools; they simply display the data as it arrives without understanding anything about what they are showing.

They download vast amounts of information only to blindly dump it on your lap, not caring if you read it, ignore it or just delete it all.

Channel hooks Awasu's channel hooks provide an active response to the information as it comes in.

They are small programs that get run when certain things happen (e.g. when a channel is updated or new items are received) and carry out some action based on what they find.

Using channel hooks, Awasu can actively monitor the incoming information and take appropriate action based upon what it finds.

Read more about...
  • Extracting information embedded in feeds
  • Getting more plugins and other extensions
  • Writing your own plugins
  • Where to get more channel hooks and other extensions
  • Writing your own channel hooks


Creating new channels

Getting started Once you've got Awasu installed, the first thing you will want to do is subscribe to a few channels (also known as feeds).

These are published by web sites to let programs like Awasu know what their latest stories are. Awasu will check your channels on a regular basis and let you know when it finds new stuff.

When Awasu is run for the first time, you will be shown a page [1] that gives you some channels to get started with.

  • Click on the orange Awasu icon for any channels that interest you.
    This starts the Channel Wizard that will guide you though the process of setting up a new channel.
  • Click the Next button until you reach the end of the wizard.
  • The new channel will be added to My Channels and the latest stories retrieved.

Read more about...
  • The Channel Wizard
  • Finding more channels to subscribe to

[1] You can always show this page again by choosing Welcome Page from the Help main menu.


Reading your channels

The Awasu main window Now that you have subscribed to a few channels, the next thing you'll want to do is read them!

  • Make sure the My Channels window is visible.
    The default key to do this is F4, or choose Control Center from the View menu.
  • Click on a channel to open its window.
    If you can't see all your channels, a channel filter may be active that is hiding some of them. Set the droplist at the top of My Channels to "All" to show all your channels.
  • The top part of each channel's window (the item pane) shows the stories currently available for that channel while the bottom part (the browser pane) is a normal web browser window that shows the stories themselves [1].
  • Awasu provides a lot of keyboard shortcuts to let you get through your feeds quickly.
    F8, Shift-F8 | Opens the next/previous story.
    F7 | Hides/shows the item pane (to make more space for the browser pane).
    F9 | Shows the channel's summary page.
    F11 | Go into full-screen mode.
    Or if you prefer using the mouse, all of these commands are available from the menu and toolbars.

Awasu keeps track of each feed item and tags them with the following icons:

New feed item | New items that have been received since you last looked at the channel.
Unread feed item | Old items that you have not yet read.
New feed item (revised) Unread feed item (revised) | Items that have been modified by the publisher since they were first received [2].
Feed item matched by a search agent | Items that are being flagged by a search agent.

Awasu also highlights channels in My Channels that have received new stories since you last looked at them ( Channel with new content) or still have unread items [3].

Read more about...
  • Configuring your channels
  • Changing the way content is presented for your channels
  • Reading your channels even when you are offline

[1] Some publishers don't include the story content itself in the feed or only a short excerpt of it, forcing you to click through to their site if you want to read it. If you are not always online (e.g. because you use a laptop or are on dialup, Awasu can be configured to automatically download these linked-to stories so that they are available even when you are offline.
[2] Channels must be configured to track revised items for this icon to be shown.
[3] The My Channels window can also be configured to show how many unread items are in each channel.


Configuring channels

The Channel Properties dialog Each of your channels can be configured individually.

  • Make sure the My Channels window is visible.
    The default key to do this is F4, or choose Control Center from the View menu.
  • Right-click on a channel in My Channels and choose Properties.
  • You will be shown the Channel Properties dialog where you can configure all aspects of the channel e.g. how often it is updated, how its content will be presented, etc.

Read more about...
  • Configuring your channels
  • Changing the default settings for new channels
  • Changing the default content presentation for your channels


Configuring Awasu

The Program Options dialog Awasu provides many options that control how it operates.

Choose Options from the Tools main menu to open the Program Options dialog.

From here you can configure most aspects of Awasu's operation.

Read more about...
  • Configuring Awasu
  • Changing the visual appearance of Awasu
  • Changing the default settings for new channels
  • Configuring Awasu's advanced settings
  • Configuring how Awasu archives and searches your content
  • Managing enclosures


Finding more channels

Browsing the channel packs The easiest way to start finding more channels is to browse through Awasu's channel packs. These are sets of channels that have been hand-picked for their high-quality, interesting and useful information.

Choose the Channel packs option from the File main menu.

Then browse through the packs and their channels and subscribe to the ones that you are interested in.

Awasu's Getting Started page links to resources to help you find more channels.

Read more about...
  • Importing channels from an OPML file or other feed readers
  • How auto-discovery can find feeds for a web site


Awasu's windows

The My Channels window Control Center

This window shows your channels, which can be grouped into folders.

  • My Channels

    The My Channels window shows your channels. Choose My Channels from the View main menu (or just press F4) to open it.

    Channels can be organized into folders and you can control which channels are shown at any given time using channel filters.

    You can also pick out your favorite channels and add them to the Favorites main menu, system tray menu and/or Sidebar for quick access.

  • My Searches

    The My Searches window shows your search agents. Choose My Searches from the View main menu to open it.

    These constantly monitor the information coming in on your channels and flag anything that might be of interest.

  • Plugins

    The Plugins window shows the installed application plugins. Choose Plugins from the View main menu to open it.

    These add extra features to Awasu. Just click on the one you want to open it and follow the instructions.

The Tasks Pane Tasks Pane

The Tasks Pane brings together Awasu's most commonly used features into one place.

Choose Tasks Pane from the View main menu to open it.

The first page gives quick access to Awasu features, the second page to your favorite channels, reports and workpads.

The Downloaded Files window Downloaded Files

The Downloaded Files window shows all the enclosures that Awasu has downloaded for you.

Choose Downloaded Files from the View main menu to open it.

Double-click on a file to play it [1], or right-click to show a context menu with more commands.

The Sidebar window Sidebar

The Sidebar is a special window that sits outside of the main Awasu window and can be docked to either side of your desktop.

It can be turned on and off from the Display page of the Program Options dialog.

The Sidebar can be configured to show the latest stories from your favorite channels, letting you keep tabs on what's new regardless of whatever else may be happening on your desktop.

Read more about...
  • Creating new channels
  • Organizing your channels using folders
  • Using channel filters to control what channels are shown in My Channels
  • Creating search agents to monitor your content
  • Extending Awasu with application plugins
  • Enclosures

[1] Files will be automatically removed from the Downloaded Files window as they are played but you can hold down the Shift key when double-clicking to override this and leave them where they are.


Starting the Channel Wizard

There are many different ways to start the Channel Wizard that will guide you through the process of creating a new channel:

  • Choose New channel from the File main menu.
  • Drag a link [1] into My Channels.
  • Right-click on a link [1] in a web page and choose Subscribe in Awasu from the context menu.

Starting the Channel Wizard There are several different types of channel that can be created, depending on where the channel's feed will be retrieved from.

However, most channels will be downloaded from the Internet and you should enter the feed's URL here (which should start with http:// or https:// and usually ends with .rss, .xml or .rdf).

Click on Next to start configuring the new channel, or Create now to create the new channel with default settings.

Feed services

Feed services Feed services are a special feature of Awasu that make it easy to subscribe to feeds coming from the most popular web sites [2].

Choose the service you are interested in, fill out the details and Awasu will automatically figure out how to subscribe.

Even better, if the web site changes the way their feeds work and breaks your channels, Awasu will be able to fix things and get them going again.

New channel defaults

New channel defaults

Clicking on the Defaults button lets you configure default settings for new channels.

New channels can be configured to expire after a specified amount of time [3], after which Awasu will ask you want you want to do with them. They can also be automatically placed in one or more folders of your choice.

Read more about...
  • Finding channels to subscribe to
  • Handling feed errors
  • Channel plugins
  • Writing your own plugins
  • Using search channels to monitor the results of a search query
  • Advanced feed processing features

[1] Feed links are often highlighted by an icon, commonly Feed icon or Feed icon.
[2] Awasu regularly downloads the latest definitions for the feed services so you always have the latest ones.
[3] Perhaps because you're not sure if you will want to keep them, or by nature they're a short-lived feed e.g. comment feeds.


Plugin parameters

Setting plugin channel parameters If you are using a channel plugin that has any configuration settings, you will be given an opportunity to set them up before the feed is generated.

If the plugin has any global settings, you can change them by clicking on the Global button.

Changes made to the global settings will affect all channels being serviced by the plugin.

Read more about...
  • Channel plugins
  • Writing your own plugins


Channel details

Changing the channel details The next step of the wizard lets you change the channel's informational details.

Click the Show feed button if you want to take a look at the channel before subscribing to it.

Everything here can be changed later at any time by opening the Channel Properties dialog.

Read more about...
  • Changing a channel's details after it has been created


Channel settings

Changing the channel's settings The next step lets you set up how the channel will operate.

This page is identical to the one in the Channel Properties dialog and is described in detail there.

Read more about...
  • Changing the default settings for new channels
  • Changing a channel's settings after it has been created


Advanced settings

Changing the channel's advanced settings The next step lets you set advanced options for the channel.

This page is identical to the one in the Channel Properties dialog and is described in detail there.

Read more about...
  • Changing a channel's advanced settings after it has been created


Confirmation

Confirming the new channel Finally, the wizard will show a summary of the new channel.

Click on the Finish button to complete the wizard and create the new channel.

Read more about...
  • Changing a channel's configuration after it has been created


Handling feed errors

Handling errors in the Channel Wizard Sometimes there will be a problem with the feed, which will prevent the Channel Wizard from progressing.

Common reasons for feed errors are given below and while in all cases, you can ignore the error and continue on, this is not recommended unless you are sure you know what you are doing.

Is the feed URL correct?

Feeds are not the same as web pages so simply entering the address of your favorite web site into the Channel Wizard may not work [1].

You should find out if the site offers a feed and what its URL is. Icons are often used to highlight their feeds (commonly Feed icon or Feed icon), and these can be dragged into the My Channels window.

Some sites support auto-discovery in which case you just have to open the web site in Awasu and you will be notified that a feed has been found.

If a feed is not available, plugins are available that monitor a web page for changes or extract information from a web page and convert it into a feed.

Does the feed have errors in it

Sometimes a feed will be rejected because it contains errors. Click on the Validate button to submit the feed to the Feed Validator for checking.

If the feed is invalid, the best solution is to contact the publisher and let them know so that they can fix it [2].

It is also possible to work around some feed errors by writing a plugin that fixes the problem before it is fed into Awasu.

Do you need to be logged in?

Some feeds require you to be logged in before you can use them.

The easiest way to check this is to click on the Show as HTML button. If you are taken to a login page, then this is probably what has happened.

You should either be logged in before you start Awasu or open a window in Awasu and log in from there.

[1] If you enter the URL of a web page, Awasu will try to find any feeds embedded in it but some sites make it hard to find their feeds and this does not always work.
[2] Awasu already works around the most commonly seen problems but most of the time, it's not a good idea to blindly ignore errors and they should be fixed by the publisher.


Channel settings

Changing a channel's settings To change a channel's configuration, open its Channel Properties dialog.

You can do this by right-clicking on the channel in the My Channels window and choosing Properties, or from the Edit main menu.

The first page lets you control how the channel will operate.

  • Automatically update this channel
    Awasu will regularly check this channel for new content at the specified interval.
  • Animate the system tray icon
    Animates the system tray icon when new content is received.
  • Play a sound
    Plays a sound when new content is received.
  • Show me a notification balloon
    Shows a notification balloon when a new item is received.
    Where the balloons are shown and for how long can be set in the Program Options.
  • Consolidate multiple new items into a single balloon
    Combines multiple new items into a single notification balloon instead of showing one for each item.
The system tray menu
  • Channel folders
    Click here to assign the channel to folders.
    This can also be done by dragging the channel around in My Channels but doing it here is often quicker.
  • Auto-download enclosures
    Awasu will automatically download any enclosures embedded in the channel's feed.
    Enclosures must also be enabled globally in the Program Options.
  • Mark all items as read on close
    Automatically marks all feed items as read when the channel's window is closed.
  • Show in the sidebar
    Shows the channel in the Sidebar.
  • Show in the system tray menu
    Shows the channel in the system tray menu.
    This menu can be shown by right-clicking on the system tray icon. If you have a lot of channels in this menu, you may want to organize them by putting some of them in sub-menus.

Content presentation

Configuring a channel's content presentation Awasu provides a great deal of control over how feed content is presented.

Default settings can be made in the Program Options but can also be overridden individually for each channel.

The overall look and feel of the channel's summary page is controlled by a template file. Compact presentation is useful for feeds that provide only titles (i.e. no descriptions) for their feed items and tells the template files to switch to a more compact layout.

You can also configure:

  • which feed items will be shown (all of them, only unread ones or only new ones)
  • how far back to show items from (by age or by number of items)
  • how feed content will be presented (full content, a short excerpt or a plain-text version).

Item panes

Configuring item panes

Click on the Item pane button to configure the appearance of the item pane. You can change where it will appear within the the channel's window and add columns to show more information about each item (e.g. author, timestamp or any other piece of item metadata).

Click on the Filters button to configure the channel to highlight items of interest and modify the feed content (e.g. remove ads) before it is shown to you.

Read more about...
  • Changing how your channels look
  • Changing the default content presentation for your channels
  • Changing the default settings for new channels
  • Configuring the notification balloons
  • Enclosures
  • Highlighting feed items of interest
  • Modifying feed content


Channel details

Configuring a channel's details This page contains information about the channel.

The controls at the top of the page depend on what type of channel is being shown.

  • Name
    This is what will appear in My Channels and the channel's summary page.
  • Home
    The channel's home page.
    This is where you will be taken if you click on the channel's picture in its Channel Properties dialog or summary page.
  • Image
    The picture shown in the channel's Properties dialog, summary page and system tray menu.
    To change this picture, enter the URL of another image or click on the browse button to find one on your computer.
  • Width/Height
    The width and height of the channel image can be changed here.
  • Description
    A brief description of the channel.
    This will be shown in the channel's summary page (unless Brief headers is enabled in the Program Options).
  • Editor/Webmaster
    Some feed publishers may provide email addresses to contact the editor and/or webmaster.
  • Schedule
    Shows the skip schedule for the channel.
    The skip schedule specifies certain days and/or hours within each day in which the publisher requests that automated channel updates be temporarily suspended. This is usually done to save bandwidth since the publisher is sure that there will be no new content published at these times.
  • Show feed
    Shows the latest feed for the channel.
    Shift-Click to see the raw feed XML instead of the formatted version.
  • Validate feed
    Submits the feed to the Feed Validator to be checked.

Types of channel

There are four different types of channel that can be created, depending on where the feed comes from.

  • Downloaded from the Internet
    Channels downloaded from the Internet These feeds are published by a web site and give the latest content for that site.

  • Generated by a channel plugin
    Channels generated by a plugin These feeds are generated dynamically by a channel plugin.

  • Generated from search results
    Channels generated from search results These feeds are generated dynamically from search results, letting you monitor your archived content for items of interest.

  • Read from a file
    Channels read from a file These feeds are read directly from a file.
Read more about...
  • Channel plugins
  • Using search channels to monitor the results of a search query
  • Advanced feed processing features
  • Validating feeds


Plugin parameters

Setting plugin channel parameters If the channel is a plugin channel that can be configured, you will see an additional page that shows the available parameters.

If the plugin has any global settings, you can change them by clicking on the Global button.

Changes made to the global settings will affect all channels being serviced by the plugin.

Read more about...
  • Channel plugins
  • Writing your own plugins


Advanced settings

Channel advanced settings

This page contains advanced settings for the channel.

  • Expire this channel
    Awasu will ask you what you want to do with the channel when the specified expiry date passes (keep, delete or extend it).
    This is useful when subscribing to short-lived channels (e.g. comment feeds) or channels that you are not sure you will want to keep. A default expiry period can be set for all new channels.
  • Safe feed content
    Click here to control how Awasu ensures the channel's feed content is safe before showing it to you.

  • Keep content for
    Archives your feed content for the specified amount of time.
    This overrides the global setting in the Program Options.
  • Exclude from search
    Excludes the channel's feed content from the search index.
    This is useful if the publisher is putting out feed items with no descriptions or other content that can skew search results.
  • Track revised items
    Tick this box to keep every revision of a feed item.
    This can be used to track what changes a publisher has made to a feed item. If this feature is turned off, only the most recent version of each feed item is kept.
  • Show revised items separately
    Tick this box to show each revision of a feed item as a separate item.
    The normal behavior is to show only the most recent version. Older versions are available by right-clicking on the feed item and choosing Show revisions

  • Download feed items for reading offline
    Downloads linked-to feed items for reading offline.
    Images embedded in the web pages can also be downloaded but will require more disk space to store.

  • Add new items to workpads
    Tick this box to automatically add new feed items to workpads as they arrive.

Channel hooks

Channel hooks are small programs that Awasu runs to do something as each channel is processed. For example, hooks can be used to send out emails when new items arrive or store them in a database if they meet certain requirements.

To attach a hook to a channel, click on the green plus icon and browse to the appropriate .HOOK file (they will usually be stored in the ChannelHooks sub-directory).

The My Channels context menu may contain special commands (if any are available) for hooks that have been attached to a channel. These commands are also available from the Edit main menu.

Read more about...
  • Configuring default settings for new channels
  • Managing your archived content and search index
  • Organizing your channels using folders
  • How Awasu ensures your feed content is safe
  • Using workpads to store feed items
  • Channel hooks
  • Writing your own channel hooks


Errors

Channel errors The last page of the Channel Properties dialog shows any errors that the channel has had in the current session.

Click on the Show Last Feed button to see the last feed received for the channel. This can be useful for trouble-shooting problems since web sites can sometimes return invalid feeds.

If you suspect that there may a problem with the feed's XML, you can click on the Validate button to submit the feed to the Feed Validator for verification.

Read more about...
  • Common reasons for feed errors
  • Validating feeds


Item filters

Feed item filters Awasu can be configured to search for and highlight items that are of particular interest to you.

This can be done globally across all your channels, or for individual channels.

Feed item filters Specify what you want to look for and where [1].

Matching items can be highlighted with different colors and an icon of your choice.

Read more about...
  • Item content filters
  • Safe feed content
[1] You can search any piece of item metadata. The most commonly used ones are provided in the drop-list.


Item content filters

Feed item filters Awasu can be configured to modify feed content before showing it to you.

This can be done globally across all your channels, or for individual channels.

The main use of this is to remove ads and other unwanted content from your feeds (see below). Some versions of Awasu will automatically download ad-removal definitions from the Awasu servers, and you can easily add your own.

Feed item filters Specify what you want to search for and what to replace it with. If you don't specify any replacement text, Awasu will show a special "content removed" icon instead.

Read more about...
  • Item filters
  • Safe feed content


Safe feed content

Awasu goes to great lengths to ensure that your feed content is safe by removing potentially dangerous HTML before showing it to you.

This process is completely transparent and the only time you are likely to notice it is when feed publishers embed things like YouTube videos in their feeds using the <object> or <embed> HTML tags. Because these tags can be used to transmit malicious content into your computer, Awasu removes them and you will not see them in the channel summary pages.

Configuring safe feed content While it is not recommended, Awasu can be configured to allow certain HTML tags or attributes through, both globally and for individual channels.

Simply enter the names of the tags and attributes [1] you want to allow.

[1] Attributes should be entered in the format TAG:ATTRIBUTE. You can use * as a wildcard to mean "any tag" or "any attribute". For example, *:style will allow the style attribute for any HTML tag, while p:* will allow any attribute found in a <p> tag.


Channel favorites

The Organize Favorites dialog Awasu gives you quick access to your favorite channels.

Open the Organize Favorites dialog from the Favorites main menu and add your favorite channels.

They will then appear in the Favorites main menu, and also the Tasks Pane, giving you quick access to them.

When you have a channel open, it can be quickly added or removed from your Favorites, either via the Favorites main menu or by right-clicking on the window's browser tab.

For even faster access, hotkeys can be assigned to individual channels:

  • Select the channel in the list.
  • Click in the Hotkey box in the top right-hand corner of the dialog.
  • Press the key combination you want to use.
  • Click on the button on the right to assign the hotkey.
Read more about...
  • Organizing your channels using folders
  • Using channel filters to control what channels are shown in My Channels
  • Putting channels in the system tray menu
  • Putting channels in the Sidebar


Channel folders

Channel folders in the My Channels window Awasu provides a sophisticated way of organizing your channels using smart folders.

Channels can be arranged in folders, but with one key difference from other traditional, tree-based programs: they can appear in more than one folder. Just hold down the Control key when dragging them around.

This seemingly simple enhancement allows for some powerful changes in the way you manage your channels. No longer do you have do decide if a channel belongs under News or Technology. If it belongs in both, then just put it in both!

This becomes particularly useful when you start using channel filters which let you control which channels appear in My Channels at any given time.

For example, you might want to show only those channels that:

  • are in the My Favorites folder.
  • are in the News or Blogs folder and have new content.
  • are in the Technology and News folders, or any of their sub-folders.
Setting up a folder hierarchy is actually another way of tagging your channels. Putting a channel in a folder called News is the same as tagging it with the word "news".

Awasu takes the tagging concept to the next level by allowing you to create a hierarchy of tags e.g. all channels that live in the News folder, for example, are news-related but you can further sub-classify them by creating sub-folders such as News/International and then News/International/Europe. A channel placed in this last folder automatically gets tagged with "news", "international" and "europe".

Folder order

How to drag folders in My Channels You can easily change the order in which your folders appear by dragging them around.

Folders are divided into three zones and where a folder ends up after being dragged depends on which zone in the target folder you drag it into (see diagram).

Read more about...
  • Getting quick access to your favorite channels
  • Using channel filters to control what channels are shown in My Channels
  • Putting channels in the system tray menu
  • Putting channels in the Sidebar


Channel filters

Channel filters let you manage your channels in a much more sophisticated way than the traditional method of putting them into folders and sub-folders.

A filter is simply a set of conditions that a channel must meet for it to appear in My Channels [1]. In other words, you can control which channels are shown at any given time.

The power comes from the available criteria and how they can be combined. For example, you can configure Awasu to show only:

  • channels that have new content.
  • channels that are from the same web site.
  • channels that are in one or more channel folders.
  • any combination of these.

My Channels is constantly kept up-to-date and so channels will be added and removed as things happen in Awasu e.g. channels are updated or new items received.

Managing your channel filters

The Organize Channel Filters dialog Open the Channel Filters dialog from the View main menu.

To create a new channel filter, click the green plus icon to start the Channel Filter Wizard that will guide you through the process. [2]

For quick access, hotkeys can be assigned to channel filters:

  • Select the filter in the list.
  • Click in the Hotkey box in the top right-hand corner of the dialog.
  • Press the key combination you want to use.
  • Click on the button on the right to assign the hotkey.
You can quickly create a filter for a folder by right-clicking on it in the My Channels window and choosing New channel filter (in the Folders sub-menu).

Configuring a channel filter Configuring channel filters

There are three main criteria used to filter channels.

By choosing an option from the Filter by droplist, you can include only those channels that have new content or unread items.

You can also include channels only if they live in one or more of the specified channel folders.

Channels can also be filtered if they have certain words in their feed URL, channel name or description [3].

If you specify more than one of these criteria, channels must meet all of them to be included in My Channels.

Some examples

Here are some examples of how channel filters can be used:

  • Filtering by URL
    You may have a number of Awasu-related feeds e.g. one for the main news feed plus one for each of the forums. Each feed comes from awasu.com so you can create a new filter that searches for this in the channel URL. Applying this filter restricts My Channels to showing only Awasu channels .
  • Filtering by content
    Want to see only news-related feeds? Create a filter that searches for the word "news" in either the channel title or description.

    While this will probably work fine, it can be a little unreliable since you are relying on the title or description as provided by the channel publisher (which may change at any time). You can override this information in the Channel Properties dialog but organizing the channels into folders is a much better solution. Simply drag the channels to the News folder and then create a filter that shows only those channels that are in this folder.

The power of this method of organizing channels becomes apparent when you have many channel folders and filters that use them.

Example channel folders For example, let's say you are a musician with an interest in technology so you create a bunch of folders (see screenshot) and arrange your channels in them accordingly.

Channels can be put into more than one folder, so a feed advertising rock gigs would be assigned to Music, Rock and Gig listings, a feed about the latest synthesizers would be in News, Technology and Music while something like Wired.com would be in News and Technology.

Now you can create filters to show channels that meet the following criteria:

  • Channels that are in Music and Technology.
  • Channels that are in Music, Gig listings and have new content.
    This will show only channels that have new gig listings.
  • Channels that are in Music, Gig listings and Jazz.
    This will show only jazz gig listings, old and new.
Read more about...
  • Configuring quick access to your favorite channels
  • Organizing your channels using folders
  • Putting channels in the system tray menu
  • Putting channels in the Sidebar

[1] Channel filters are also used elsewhere in Awasu e.g. to control which channels are included in a channel report.
[2] Or Shift-Click to bypass the Wizard and go straight into the main dialog.
[3] If you know how to use regular expressions, you can also use them here.


Channel reports

Channel reports allow information to be extracted from Awasu and exported in any format [1].

Content can be taken directly from your channels (selected either via a channel filter or channel folders) or you can collect stories of interest in a workpad, edit them, add your own comments and then export everything to a report.

Once a report has been generated, further custom processing can be done on it (e.g. conversion to a PDF, merging with other reports), and it can be emailed out or uploaded to a web site.

Managing your reports

Organize channel reports Open the Channel Reports dialog from the View main menu.

To create a new channel report, click on the green plus icon to start the Channel Report Wizard that will guide you through the process [2].

For quick access, hotkeys can be assigned to channel reports:

  • Select the report in the list.
  • Click in the Hotkey box in the top right-hand corner of the dialog.
  • Press the key combination you want to use.
  • Click on the button on the right to assign the hotkey.
Your reports will also appear in the Tasks Pane for quick access.

Hint
You can quickly create a report for a folder by right-clicking on it in the My Channels window and choosing New channel report (in the Folders sub-menu).
Read more about...
  • Configuring channel reports

[1] Using Awasu's powerful template processing engine.
[2] Or Shift-Click to bypass the Wizard and go straight into the main dialog.


Configuring reports

Configure channel report Report source

The first thing to configure is the source i.e. where the report content will come from.

  • From a channel filter
    Any channels that pass the specified filter will be included in the report.
  • From channel folders
    All channels in the specified folder(s) will be included in the report.
  • From a workpad
    The report will be generated from the items in a workpad.

Reports can also be configured to:

  • Automatically mark feed items as read.
  • Automatically remove feed items from workpads.
    This feature is useful when you are using a workpad as a holding place for feed items that will be sent somewhere else. Items get added to the workpad as you browse your channels and when the report is run, it gets emailed or FTP'ed somewhere and the workpad is cleared, ready for the next batch of items.
  • Automatically re-run when the underlying workpad is changed.
    This feature could be used if you want to keep a web page synchronized with the contents of your workpad. Every time you add or remove something from the workpad, the report is re-generated and uploaded to your web server.

Report template

A template file controls the the format of the report's output. Many templates are supplied as standard, in a variety of different styles, and there are also several special-purpose templates provided:

  • CompactChannelReport.template
    Generates a minimal (links only) HTML page.
  • MyBlogroll.template
    Generates an HTML code fragment suitable for inclusion in your blog as a blogroll.
    This report uses the predefined My Blogroll channel filter so all you have to do is put the channels you want to be included into the My Blogroll folder and they will automatically be included in the report.
  • MetaChannel.template
    Combines one or more channels together into a single meta-channel.

These templates can be customized to suit your needs [1] and you can also write your own.

Once the report has been generated, a post-processing command can optionally be run to do some extra work e.g. convert it to a PDF or audio file.

The post-processing command can be parameterized.

Report output

Generated reports can be:

  • shown in Awasu
  • stored in a file (perhaps so that they can be read by another program)
  • FTP'ed up to a web server
  • emailed out

A post-processing command could also be used to send the report somewhere e.g. using scp or sftp.

The configuration for each of these output destinations can be parameterized.

Report schedule

Reports can be configured to automatically run, either at regular intervals (e.g. every 3 hours) or at specific times (see right).

This is particularly useful when used in conjunction with the FTP upload feature since it lets you keep content on a web site up-to-date. For example, you could generate a blogroll report once a day and automatically upload it to your blog to ensure that your blogroll is always up-to-date.

Or you could send out a regular email based on the contents of a workpad or some of your channels.

Read more about...
  • Writing your own template files
  • Template parameters available for channel reports

[1] If you want to tweak one of the standard report templates, you should take a copy of it and modify that to ensure that your changes are not overwritten when you upgrade to a new version of Awasu. You can also use the ProcessTemplateIncludes.py utility to merge all the include files for an existing template into a single file that can easily be edited and used, without having to worry about it being affected by changes in future versions of Awasu.


Advanced features

The following report elements can be parameterized:

  • post-processing command
  • output filename
  • FTP upload filename
  • email subject and body

and recognize these parameters:

  • {%REPORT-FILENAME%}
  • {%REPORT-NAME%}
  • {%REPORT-DESCRIPTION%}
  • {%REPORT-TIME%}
    Use the format argument to control the format of the timestamp (using strftime syntax) e.g. c:\temp\report-{%REPORT-TIME% format="%Y-%m-%d"}.html
  • {%CHANNEL-FILTER-NAME%}
  • {%WORKPAD-NAME%}
  • {%CHANNEL-FOLDERS%}
    By default, channel folders are comma-separated, delimited using double-quotes. Use the sepChar argument to specify a different separator, quoteChar to specify a new delimiter e.g. {%CHANNEL-FOLDERS% sepChar=; quoteChar=#} or {%CHANNEL-FOLDERS% quoteChar=[]}
  • {%TEMPLATE-FILENAME%}
  • any user-defined template parameters

Read more about...
  • Configuring reports


Workpads

Workpad Workpads are holding stations for feed items, either because you want to read them later or you want to collect them together and generate a report.

There are many ways to add an entry to a workpad:

  • Drag a link in.
  • Right-click on a feed item in the item pane and use the Send to sub-menu.
  • Press Control-Shift-W to add a URL from the clipboard [1].
  • Right-click on a link in a web page and choose Add to Awasu workpad [1] [2].

Editing a Workpad item Workpad items can be edited and annotated individually. This is most useful when you are going to generate a report from the workpad and want to add your own notes.

You can also define custom fields for each workpad and then specify values for them for each workpad item.

These powerful features mean that you can browse your channels and collect items of interest in a workpad, add your own comments, then put it all together into a final report. A great tool if you're doing research or writing a document on a particular topic!

The Awasu API also allows a feed to be generated from the contents of a workpad, so other people can subscribe to your workpads and be notified of your changes!

Managing your workpads

The Organize Workpads dialog Open the Organize workpads dialog from the View main menu. From here, you can manage your workpads.

Workpads can be docked or floated anywhere on the screen and there are settings in the Program Options to automatically show/hide workpads when items are added and removed.

Your workpads will also be listed in the Tasks Pane for quick access.

The first workpad in the list is considered to be the default workpad and is the one that certain operations (described above) will use.

Read more about...
  • Defining custom fields for a workpad
  • Generating reports from items in workpads
  • Setting workpad options

[1] This operation will add a new entry to the default workpad.
[2] You can do this in any Internet Explorer window (not just within Awasu) as long as it was opened after Awasu was started.


Custom fields

Custom fields can be defined for each workpad e.g. Priority, Source, Assign to.

Each workpad item can then specify its own set of values for each field.

These values will then appear for each item in reports generated from that workpad.

Read more about...
  • Workpads


Search

The Find dialog Awasu's advanced search engine lets you find the information you are looking for.

Open the Find dialog from the Edit menu. Then type in what you are looking for, where you want to search and over what period of time.

You can control how feed item content will be presented in the results page:

  • All
    Each feed item will be shown in its entirety.
  • Excerpt
    A brief excerpt of each feed item will be shown.
  • Plain text
    A plain-text version of each feed item will be shown.
  • None
    No feed item content will be shown (only item links will be shown).
You can also set up search agents to watch for and flag things of interest, or search channels that let you monitor the results of a search as a feed.

Simple searches

To do a simple search, make sure the Enable advanced syntax checkbox is un-ticked.

Type in one or more words you want to look for and Awasu will locate feed items that contain any of these words (i.e. it will do a boolean OR search).

Advanced search queries

For more advanced search queries, first make sure Enable advanced syntax is ticked.

You can search for words or phrases (enclosed in double quotes), optionally joined together using the boolean keywords OR, AND, NOT (which must be in capitals). If no boolean operator is specified, OR is assumed.

Words and phrases may also be preceded by a plus/minus sign to indicate that they must or must not appear in documents.

For example:

  • Hello world (searches for documents that contain "hello" or "world")
  • "Hello world" AND foobar (searches for documents that contain both "hello world" and "foobar")
  • Hello +world (searches for documents that must contain "world" and optionally "hello")

Words and phrases can also be grouped by enclosing them in parentheses.

The following characters are reserved for special functions in search queries:
    + - && || ! ( ) { } [ ] ^ " ~ * ? : \
If you want to search for these characters, they must be escaped by preceding them with a backslash.

Using wildcards

You can use ? to represent a single character or * for 0 or more characters.

For example:

  • te?t (matches "test" and "text" and "tent")
  • quick* (matches any word that starts with "quick" e.g. quickly, quicker, quicken, etc.)
You cannot use * nor ? as the first character of a search query.

Really advanced features

Words or phrases can be marked as being more important by appending a ^ followed by the boost factor. This is a number that indicates how important the word or phrase is to the query. By default, each word or phrase is given a boost factor of 1 but you can change this for each one. Values must be greater than 0 but can be less than 1 (to indicate less important terms). For example: "hello world"^2 foobar^0.5.

Proximity searches can find words that are near each other. Append a ~ to the end of a phrase followed by the range in words. For example, "foo bar"~10 finds documents that contain the words "foo" and "bar" within 10 words of each other.

You can also do fuzzy searches by appending a ~ to the end of a single word (not phrase). For example, "roam~" will match words like "foam" and "roams".

Read more about...
  • Filtering the results of a search query
  • Using search channels to monitor the results of a search query
  • Monitoring your content using search agents


Search result filtering

Filtering by URL

Search results can be filtered by URL by including a clause like this in the query:

site:awasu.com

Due to the nature of the content of some feeds, and the common use of third-party services to deliver feeds, Awasu will also check the feed URL of the channel that items came from, and also the channel's home URL (if the publisher has specified one). So, the clause above will include items in search results that meet any of the following conditions:

  • the item links to a page at awasu.com
  • the item came from a channel whose feed URL is at awasu.com
  • the item came from a channel whose home URL is at awasu.com

To turn this extra checking off and limit results to only items that link to awasu.com, include the following clause in the query:

smartsite:no

The behavior of site filters can be reversed, to show only results not at awasu.com, like this:

!site:awasu.com

Filtering by folder

Search results can also be filtered by channel folder by including a clause like this in a query:

folder:...

where ... is either a folder GUID or a regular expression that is used to match folder names. If you don't want to worry about regex's, any substring of the folder name will do e.g. folder:foo will match any folder that has "foo" in its name. If there are spaces in the folder name, it must be quoted e.g.

folder:"Developing nations"

By default, sub-folders will also be checked, so if you want to disable this and match folders exactly, include the following clause in the query:

subfolders:no

As with URL's, folder matching can also be reversed, like this:

!folder:...

Filtering by item state

Search results can be also filtered by item state (i.e. whether an item has been read or not):

state:read
or:
state:unread

Read more about...
  • Using Awasu's search engine


Search channels

Creating a new search channel Search channels use Awasu's advanced search engine to constantly monitor your feed content for items of interest.

Start the Channel Wizard and indicate that you want the channel's feed to be generated from search results.

Enter the search query that you want to use.

Awasu will now create a new channel whose feed is automatically generated from search results. As new things are found by your search query, they will appear as new items in the feed!

Read more about...
  • Search query syntax
  • Filtering the results of a search query
  • Monitoring your feeds using search agents


Search agents

Configuring a search agent Search agents use Awasu's advanced search engine to monitor your feed content and flag things of interest.

To create a new search agent, choose New search agent from the File main menu, or right-click in the My Searches window.

Enter a search query to specify what you want Awasu to monitor your channels for and how it should be highlighted in the UI.

The Search Agents context menu in My Channels When a search agent finds matching channels or feed items, it will flag them with a special icon. You can also choose to highlight them in different colors.

If something is being flagged by more than one search agent, right-click on it and choose Search agents from the context menu to see which ones have matched it.

Read more about...
  • Search query syntax
  • Filtering the results of a search query
  • Monitoring your feeds using search channels


User tools

Awasu's user tools provide an easy way to integrate external applications and services without having to go to the trouble of writing a plugin or channel hook.

Standard user tools can be invoked from the Tools menu and perform common operations such as searching Google or looking up the meaning of a word. Most tools work with some text selected in the browser window but others could just open a web page or start another program on your computer.

Send-to user tools [1] operate on a feed item or web page.

Right-click on a feed item in the item pane to send it to the clipboard, a workpad, someone via email, or one of the installed external services.

Or right-click on a browser tab to do the same for the current web page.

A special Send to popup menu is also available at the bottom of every feed item.

Managing the tools

The Organize User Tools dialog Open the Organize user tools dialog from the View main menu.

To add a new tool, click on the green plus icon and enter a name [2]. Then enter the command that you want to run.

Read more about...
  • Configuring user tools

[1] Awasu regularly downloads the latest definitions for the Send To tools so you always have the latest ones.
[2] Awasu will show the name you enter here in the Tools menu but you can change this by entering something in the Menu box. Awasu will also automatically assign keyboard shortcuts but you can override this by putting an ampersand (&) in front of the letter you want to use e.g. "G&oogle" will show up in the menu as Google.


Configuring user tools

There are three types of user tool, differentiated by their command:

  • URL
    These start with http:// or https:// and open a URL, usually in Awasu or an external browser window.
  • Javascript
    These start with javascript: and execute Javascript on a browser tab in Awasu.
  • Application
    All other user tools are interpreted as commands that launch an application on your computer.

URL tools can be opened either in Awasu or an external browser window, or they can be configured to send a silent request.

If POST data is configured (in the Advanced page), an HTTP POST request is sent, otherwise an HTTP GET is sent.

A username/password can also be configured here for requests that require authentication.

The response from URL and application tools can be checked and the user notified of the result.

A list of regular expressions can be configured that the response is checked against, and a message shown to the user if any match. For URL tools, the RE's are tested against the HTTP response while for applications, the response starts with EXIT CODE: ..., followed by the stdout output, then the stderr output.

For example, if the tool is an application that exits with 0 if it is successful, you could add the following two checks:

EXIT CODE: 0 | Success!
EXIT CODE: (\d+) | Failed - error code {%1%}
Read more about...
  • User tools


Synchronizing Awasu

Awasu offers a wide range of synchronization options:

  • Sync with another copy of Awasu
    This is the most powerful option and will keep every aspect of Awasu synchronized. It is described in this section below.
  • Sync with other feed readers
    Awasu can synchronize with any other feed reader that makes their services available.
  • Sync with other feed readers using OPML [1] or SIAM

Synchronizing with another copy of Awasu

Saving the sync data

Saving the sync data The first thing to do is to save of copy of everything on the Awasu you want to synchronize from.

Open the Save sync data dialog from the File main menu and choose where you want to save the sync data:

  • File
    You can save the sync data to a file that you will transfer to the other Awasu yourself.
    This could be on a floppy disk or keychain drive, or via email.
  • FTP
    You can also upload the sync data to an FTP server.

Or if you want to use some other means of transferring the file (e.g. SCP or SFTP), you can save the sync data to a file on your PC and run a command to do it instead.

Historical data should be set to at least the number the days between each sync [2]. For example, if you sync between home and work 5 days a week, this should be set to something larger than 3 (i.e. the 3 days between Friday and Monday).

You can also choose to include the last feed received for each channel. This slows synchronization down and increases the size of the sync data file considerably but allows the other computer to immediately have a copy of the latest feed for each channel instead of having to download it again.

Loading the sync data

Loading the sync data On the other Awasu, you can now load the sync data you saved previously.

Open the Load sync data dialog from the File main menu and browse to the sync data file.

You can also choose to prevent certain things from being synchronized. For example, you would probably want to have different blackout times on your work and home computers [3].

It is strongly recommended that you have the report enabled so that you can check for any errors and possible problems.
Note that external files such as plugin scripts, template files, etc. need to be transferred manually.

Automatically loading and saving sync data

Once everything is working, Awasu can be configured to automatically load and save the sync data when it starts and exits.

However, it is recommended that you only turn this option on after everything has settled down and synchronization is being done without any warnings or errors.

Read more about...
  • Configuring Awasu to automatically save and load sync data at startup/exit
  • Synchronizing with other feed readers

[1] OPML is the least flexible way of synchronizing channels but is supported by most feed readers.
[2] Setting this value incorrectly will not have any serious consequences other than Awasu sometimes erroneously flagging items that you have already seen or read as new or unread.
[3] It is possible to disable the synchronization of any of Awasu's settings so if there's something you would like to exclude that is not already in the list, post a request in the Awasu Forums to get the necessary incantations.


Importing/exporting channels

Awasu provides a powerful and flexible way of sharing information with other feed readers [1].

This is convenient if you use more than one feed reader and want to keep them synchronized, or if you are changing from one to another. It can be done by either communicating directly with the other feed reader or via OPML [2].

Support for synchronizing with third-party feed readers is not installed as standard. Plugins can be downloaded from here and more will be made available as other feed readers make their services available.

Exporting channels Exporting channels

Choose Export to... from the File|Synchronization menu to show the main Export dialog.

Choose where you want to export your channels to in the Export to droplist at the top of the dialog.

Then choose which channels you want to export.

Importing channels Importing channels

Importing channels is a two-step process.

Choose Import from... from the File|Synchronization menu to show the main Import dialog.

Choose where you want to import channels from and enter any other required information.

Importing channels You will then be shown the channels and folders from the other feed reader and asked to choose which ones you want to import (any channels you are already subscribed to will be marked with a green tick).

When you click Import, the selected channels will be imported using the default settings for new channels.

Read more about...
  • Synchronizing with another copy of Awasu

[1] If you want to synchronize with another copy of Awasu, a more comprehensive way of doing this is described here.
[2] OPML is a file format widely used to transfer channels between feed readers. However, it only allows for the transfer of your channels, not which feed items you have read. SIAM is also supported but is less-widely used.


Enclosures

The Downloaded Files window Awasu can automatically download files (also known as enclosures) that have been attached to feed items so that they are ready for use on your PC when you need them.

Enclosures are most commonly used for podcasting although they are by no means restricted to only this. They can be used to distribute any kind of file e.g. new versions of software, updated Office documents or perhaps audio segments that are part of an online language lesson.

Unlike email attachments, enclosures are not transmitted together with the feed item. Instead, only a link to the file is included so if you want to open the file, you must first download it. Awasu can be configured to either automatically download enclosures when they are received or if you want to save bandwidth, simply let you know that a feed item has a related file and you can selectively choose which ones to download.

Managing enclosures

Most of the settings relating to automatically downloading files can be found in the Enclosures page of the Program Options dialog.

Channels can also be individually configured from the Channel page of their Channel Properties dialog.

Related links in the channel summary page If feed items have any related links, they will be shown in the channel summaries [1]. Files that have already been downloaded will be shown with a small icon that you can click to open the file directly from your computer. Otherwise, you will see them as a normal link that you can click to start downloading them.

You can also manage all your enclosures from the Downloaded Files window.

Read more about...
  • Configuring Awasu for enclosures
  • Setting enclosure options for individual channels

[1] This information will not be shown in the channel summary pages if Brief feed items is turned on.


Working offline

Awasu can still be used, even when you're not connected to the Internet.

This is great if you use a laptop since you can leave Awasu running overnight to download all the latest news, then take it with you to read on your way to work in morning or during lunch at the coffee-shop! Or if you're on dial-up, you can download everything in one go, then disconnect and read it at your leisure.

Offline feed items

Configuring offline feed items Feed publishers will often only include an excerpt of each feed item (or sometime nothing at all!) which means you have to click through to read the entire article, which is not much use if you're offline.

Awasu can be configured to download the linked-to articles and store them in its database, so you can read them even when you're offline.

Feed items that are available offline are marked with a special icon in the channel summary pages.

Feed item available for offline reading

Web pages tend to be complicated affairs these days and saving them for reading offline is not a straight-forward task. They often contain scripts that try to connect to other web sites which will obviously not work if you are offline. This means that you will sometimes see a delay when opening these offline feed items, or the page will sometimes not display properly (e.g. because it's trying to get stylesheets, etc. from other sites). However, the content will always be available, which is the most important thing.

Offline feed item images

Configuring offline feed item images Feed items also often have images embedded in them which will be displayed as ugly "broken image" boxes if you are not online.

To get around this, Awasu can be configured to download these images and show them even when you are offline [1].

Read more about...
  • Configuring Awasu to download feed items for offline reading
  • Configuring Awasu to download images for offline reading

[1] When you are offline, <img> URL's are replaced with special ones that Awasu will handle itself. This means that if you copy a feed item's HTML to use elsewhere (e.g. because you want to quote it in one of your own blog posts), any image URL's will need to be fixed up.


Finding your channels

Finding channels You know you subscribed to a channel, but where is it?!

As you subscribe to more channels, it can sometimes be hard finding the one you want.

Instead of fiddling around with channel filters or navigating through folders, just choose Find channel from the File menu, enter a few characters from the channel's name, description or URL and Awasu will go find it for you.

Read more about...
  • Organizing your channels using folders
  • Organizing your channels using filters
  • Adding channels to the Favorites menu
  • Adding channels to the system tray menu
  • Adding channels to the Sidebar


Cleaning up channels

Cleaning up your channels Awasu lets you quickly find broken and dormant channels and clean them up.

Channels often go stale, either because they have been abandoned by the publisher or have been moved to another place and the publisher forgot to say where.

Choose Clean up channels from the Tools main menu and pick which channels you want to clean up.

You will also be asked about channels that have expired.

You can also delete individual folders and channels by right-clicking on them in the My Channels window and choosing Delete channel or Delete folders/channels.

When deleting folders, you will also be given the option of deleting any channels contained in them, and any channel filters that reference it.

Read more about...
  • Configuring channels to expire


Feed auto-discovery

Configuring auto-discovery Awasu can automatically find feeds embedded in web pages as you browse.

Auto-discovery is a way for web sites to automatically announce their feeds to visitors, saving you the trouble of having to search their web site to find them.

If auto-discovery is turned on, any time Awasu opens a web page that is announcing a feed, a blinking icon will be shown in the caption bar or status bar that you can double-click on to start the Channel Wizard.

Auto-discovery indicator

If you have a older machine, you may want to turn auto-discovery off since the process of searching each web page you open for feeds can slow things down a bit. You can always do auto-discovery manually from the Tools main menu.

Possible feeds

Possible auto-discovered feed URL's Even if a web page is not announcing a feed, Awasu is smart enough to find links that may be feeds.

In these cases, a special dialog will appear that lets you check to see if they really are feeds or not [1].

If you choose not to subscribe to a feed, you can also add its URL to an exclusion list that will cause it to be ignored next time you visit the web page.

[1] If you have a fast internet connection, you can turn on Auto-verify possible feeds which will automatically verify each possible feed when the dialog is opened.


Feed processing

Channel feed processing Awasu allows for sophisticated processing to be performed at all stages of a channel's update cycle.

Using SOAP

SOAP is an XML technology that programs can use to communicate with web services.

Channels can have a SOAP request file associated with them that will be sent to the channel's URL using an HTTP POST (instead of the usual HTTP GET). The results will be sent back as a SOAP response which will then typically be converted, using XSLT, into a feed that Awasu can process.

Using XSLT to modify feeds

XSLT is an XML technology that can be used to modify an XML document. Awasu deals exclusively with XML data and so is ideally positioned to use this technology.

Channels can have one or more XSLT files associated with them that will be applied to the downloaded feed, modifying it in some way before it is processed by Awasu. For example, items can be removed from the feed, new metadata attached to feed items, the order of the feed items changed, etc.

Used in conjunction with SOAP request files, this is a particularly powerful feature since it allows Awasu to query web services (or any other data source that publishes information using XML) and transform the result into a feed that Awasu can use.

Read more about...
  • The XSLT's installed as standard
  • The SOAP request files installed as standard
  • Download more SOAP and XSLT files


Metadata modules

Many feed publishers are now embedding additional information in their feeds such as licensing details, geocodes or publisher-specific metadata which is simply ignored by most feed readers because they don't even realize it's there!

Metadata modules Metadata modules let Awasu extract this extra information out of a channel's feed and store it in the archive database. This information is then accessible along with all the other normal feed metadata and can be inserted in channel summary pages, reports, etc.

You must have MXSML installed to use this feature.

Check out the Awasu Wiki for metadata modules you can download and use.

Configuring metadata modules From the Advanced page of the Program Options dialog, click on the Metadata modules button and choose which metadata modules you want Awasu to process.

Each metadata module will show any information it finds in the channel summary pages.

An example feed and screenshots of each metadata module in action can be found here.

More information

In its simplest form, metadata modules let Awasu recognize new microformats and other RSS extensions as they come out, without having to wait for Awasu to be updated to recognize them. Metadata modules for extensions currently in common use, such as slash:comments and wfw:commentRss, are installed as standard with Awasu.

However, there are much more powerful applications of metadata modules that open up some intriguing possibilities, especially in a corporate environment. While some feed readers have support built into them for the more popular RSS extensions, that's not much use if the one you want is not recognized or even worse, if the feed is using your own proprietary extensions since there's no way a third-party feed reader will be updated to recognized it.

Awasu offers an end-to-end means of transporting and processing your information:

  • You publish feeds with your own specific information embedded in them using any XML formats you want.
  • Metadata modules let you extract this information when it arrives on the client-side.
  • Channel hooks can then analyze this information and act upon it.
Read more about...
  • Awasu's end-to-end information management


Awasu Administration

Awasu Administration is a separate program [1] that can be used to manage Awasu on your PC.

This program is best run from an Administrator account, otherwise you will only be able to manage your own Awasu installation and some options may not be available.

User management

In the event Awasu cannot automatically find a user's data files, click on the green "plus" button to locate them manually.

This page lets you manage the installation for each person that is using Awasu on your computer.

You can:

  • Optimize their archive database, to keep it running at maximum efficiency.

  • Rebuild their search index (used to provide fast searches over the archived content).

  • Reset their installation. You can delete all of their channels and settings, and/or reset selected parts of their user interface.

[1] admin.exe can be found in your Awasu installation directory (by default, C:\Program Files (x86)\Awasu\).


Introduction to templates

Templates are a powerful feature of Awasu that give you complete control over how your channels, reports, etc. will look.

A template file is simply a copy of what the output file should look like, but with placeholders to indicate where you want things like the channel name, item descriptions, etc. to appear. When it comes time to generate the output, Awasu will replace the placeholders with the real information.

Here's a really simple example that generates an HTML list for all the feed items in a channel:

<ul>
{%REPEAT% FeedItems}
    <li> <a href="{%ITEM-METADATA% url}"> {%ITEM-METADATA% name} </a> </li>
{%/REPEAT%}
</ul>

{%REPEAT% FeedItems} instructs Awasu to repeat the enclosed text for each feed item. Each time, {%ITEM-METADATA% url} and {%ITEM-METADATA% name} will be replaced with the appropriate piece of item metadata (i.e. the URL and name respectively).

Read more about...
  • Inserting channel and item metadata
  • Conditionally processing template code
  • Encoding inserted values
  • Repeating template code
  • Include files


Metadata

Metadata means "information about information."

Awasu brings news to you via your channels but it also tracks a lot of additional information about it all e.g. when a feed item was published, who wrote it, if it has any enclosures, etc.

This metadata can be inserted in templates using the {%CHANNEL-METADATA%} and {%ITEM-METADATA%} parameters.

Metadata tree Metadata is stored in a tree-like hierarchy, so a channel's metadata might look something like the diagram on the right.

Each piece of channel metadata is accessed using the {%CHANNEL-METADATA%} parameter, so if you were generating an HTML page, you could create an email link for the author like this:

<a href="mailto:{%CHANNEL-METADATA% author/email}">
    {%CHANNEL-METADATA% author}
</a>
This example contains some potential problems which are discussed here, together with how to work around them.

Entries in the metadata hierarchy are either metadata values (e.g. Name or URL in the example above) or metadata groups (e.g. Link or Author).

Metadata groups have no actual value themselves but if they are used in template parameters (e.g. {%CHANNEL-METADATA% author}) then Awasu will check the child metadata values and choose the most appropriate one.

So, in the example above, Awasu will generate a mailto: link for the author's email address, using the author's name, email address or URL (in that order of preference) as the display text.

The {%ITEM-METADATA-DUMP%} and {%CHANNEL-METADATA-DUMP%} parameters will output a formatted dump of the current item or channel's metadata and are very useful to see what metadata is available when writing your own templates. They work best when wrapped in <pre> tags, to preserve the formatting.
Read more about...
  • Conditionally processing template code
  • Encoding inserted values
  • Repeating template code
  • Include files


Conditional sections

Templates can test for certain conditions and generate different output according to the result.

{%?xxx%} tests if the xxx parameter has been set and if so, generates the output up to the next {%ENDIF%} tag. {%??xxx%} does the same, but the xxx parameter must also evaluate to a boolean true.

{%!xxx%} does the opposite, generating output if the parameter has not been set. {%!!xxx%} does the same, but the xxx parameter must also evaluate to a boolean false.

All of these can also have an {%ELSE%} clause.

The following example checks if a feed item has an author. If it does, it outputs the author's name [1], wrapped in a mailto: link if the author's email address has been given.

{%?CHANNEL-METADATA% author}            test if the channel has specified an author
    {%?CHANNEL-METADATA% author/email}  test if the author's email address was given
        <a href="mailto:{%@%}">           - yes: start the mailto: link
    {%ENDIF%}
        {%CHANNEL-METADATA% author}     insert the author's name/email/URL
    {%?CHANNEL-METADATA% author/email}  test if the author's email address was given
        </a>                              - yes: close the mailto: link
    {%ENDIF%}
{%ELSE%}
    No author was specified!            insert this if no channel author was specified
{%ENDIF%}
This example contains some potential problems which are discussed here, together with how to work around them.

Note the use of {%@%} as a shorthand for the parameter evaluated in the previous {%?xxx%} or {%!xxx%} tag.

Read more about...
  • Inserting channel and item metadata
  • Encoding inserted values
  • Repeating template code
  • Include files

[1] If the author's name has not been given, Awasu will check for an email address or URL as described here.


Parameter encoding

There is one small problem in the previous example: if the author's name contains a < character, the generated output might look something like this:

<a href="mailto:joe@blow.com"> Joe<Blow </a>

and the < character will cause problems in an HTML browser.

Awasu automatically handles this by checking the extension of the output file and encoding values appropriately e.g. in the example above, if the output file had a .HTM or .HTML (or .XML) extension, the problematic < character would be inserted as &amp;.

However, there may be cases where the default handling is not enough and so you can force encoding by adding encode and chars arguments to the template parameter. For example:

{%CHANNEL-METADATA% author encode=sgml chars=<&"}

This insert the channel's author but SGML-encodes the three special characters specified.

The encode argument may have the values json, jsonval, sgml, attr, percent, csv, or none .

The previous example also suffers from the same problem when generating the mailto: link, if the email address contains a " character.

The code below shows how both these issues can be fixed:

{%?CHANNEL-METADATA% author}
    {%?CHANNEL-METADATA% author/email}
        <a href="mailto:{%@% encode=sgml chars=<&\"}">
    {%ENDIF%}
        {%CHANNEL-METADATA% author encode=sgml chars=<&\"}
    {%?CHANNEL-METADATA% author/email}
        </a>
    {%ENDIF%}
{%ELSE%}
    No author was specified!
{%ENDIF%}
This example code works fine if a channel has only one author specified but if there's more than one, it will only show the first one. How to handle multiple authors is described here.
Read more about...
  • Inserting channel and item metadata
  • Conditionally processing template code
  • Repeating template code
  • Include files


Repeating sections

Templates often need to repeatedly process the same piece of code, using different values each time.

For example, channel summary pages need to iterate through each feed item being shown, inserting the content and other details for each one into the page. This is done by using the {%REPEAT%} tag.

The previous example doesn't handle the case of more than one author being specified for a channel, so we'll fix that using a repeating section.

{%?CHANNEL-METADATA% author}
    {%REPEAT% author}
        {%?CHANNEL-METADATA% author/email}
            <a href="mailto:{%@% encode=sgml chars=<&\"}">
        {%ENDIF%}
            {%CHANNEL-METADATA% author encode=sgml chars=<&\"}
        {%?CHANNEL-METADATA% author/email}
            </a>
        {%ENDIF%}
    {%/REPEAT%}
{%ELSE%}
    No author was specified!
{%ENDIF%}

Awasu now repeats the template code enclosed by the {%REPEAT%} and {%/REPEAT%} tags, one time for each instance of the specified metadata value found (in this case, author).

Read more about...
  • Inserting channel and item metadata
  • Conditionally processing template code
  • Encoding inserted values
  • Include files


Include files

You will often want to use the same piece of code in different template files.

This can be easily done by putting the common code into its own file and then using the {%INCLUDE%} tag to insert the contents of that file into the template when it is needed.

Awasu uses this feature heavily, putting the bulk of the template code into a separate file that is then included by whoever needs it.

For example, the Rusty.template file looks like this:

<html>

<head>
    {%INCLUDE% includes/StandardHead.include}
    <style>
        {%INCLUDE% Rusty.css}
        {%INCLUDE% Rusty.user.css isOptional} [1]
    </style>
    {%INCLUDE% includes/StandardHead2.include}
</head>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

<body>
    {%INCLUDE% includes/StandardBody.include}
</body>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->

</html>

In each case, the {%INCLUDE%} tag is replaced with contents of the specified file.

The ProcessTemplateIncludes.py utility script is provided that expands out all {%INCLUDE%} tags to produce a single big file. This is useful if you want to use one of the existing templates as a starting point and change it without affecting anything else.

The special {%BASE-DIR-URL%} template parameter is updated each time to point to the base URL that the template file currently being processed lives in. This allows template files to reference external resources such as images.

For example, from Rusty.css:

.banner
{
    background-image: url( "{%BASE-DIR-URL% encode=attr}/images/Rusty/banner.png" ) ;
    background-repeat: repeat-x ;
    border: 3px double ;
    padding: 10px ;
    color: #fff ;
}
Read more about...
  • Inserting channel and item metadata
  • Conditionally processing template code
  • Encoding inserted values
  • Repeating template code

[1] The isOptional parameter means that an error won't be reported if the file is not found. This lets you make your CSS customizations in this file and not lose them when you upgrade to a new version of Awasu.


Metadata

Information about channels and feed items is stored as metadata (information about information), arranged in a tree-like hierarchy.

Metadata tree A metadata entry can be one of two types:

  • metadata value: has an associated value.
  • metadata group: used to group metadata values together.

For example, a channel's metadata might look something like the diagram to the right. There are two metadata groups, Link and Author, and everything else is a metadata value.

While each type of metadata can be used either as a value or group, in practice each is typically used as one or the other.

The following are usually used as metadata groups.

Metadata ID | Description
Author | Feed/item author. This will have one or more of the following child nodes: Name, URL, Email
Contributor | Feed/item contributor. This will have one or more of the following child nodes: Name, URL, Email
Editor | Channel editor. This will have either a Name or Email child node.
Webmaster | Channel webmaster. This will have either a Name or Email child node.
Image | Channel image. This will have a URL child node and optionally Width and/or Height child nodes.
Icon | Channel icon. This will have a URL child node.
Category | Feed/item category. This will have one or more of the following child nodes: ID, URL, Name
Link | A link. This will have a URL child node and any of the following optional child nodes: Relation, Name, MediaType, Language.
Comments | Indicates where a feed item's comments can be found. This metadata node is found in RSS feeds only and has a single URL child node.
Source | States the item's source. For RSS feeds, this will have a Link and/or a Name child node. For Atom 1.0 feeds, it will have one or more of the following child nodes: ID, Name, Description, Author, Contributor, Link, Category, Copyright, Icon, Image, Modified.

The following are usually used as metadata values.

Metadata ID | Description
ID | Feed/item identifier.
Name | Feed/item name.
Description | Feed/item description.
Copyright | Feed/item copyright message.
Language | Feed/item language ID.
Published | Feed/item published date.
Modified | Feed/item modified date.
URL | Specifies a URL.
Email | Specifies an email address.
SkipDays | Specifies which days a feed should not be updated. This metadata is found in RSS feeds only and is a list of day numbers (where 0=Sunday).
SkipHours | Specifies which hours a feed should not be updated. This metadata is found in RSS feeds only and is a list of hour numbers (0-23).
Relation | Specifies a relation type. This is usually a child of a Link node and specifies the link's reltype.
MediaType | Specifies a media type. This is usually a child of a Link node and specifies the link's media type.
Width | Specifies a width.
Height | Specifies a height.
Size | Specifies a size.
Length | Specifies a length.
Read more about...
  • Default child metadata values
  • Metadata pseudo-values


Default child values

If a metadata group is used when a value is expected, Awasu will check the group's child nodes for a value to return instead.

For example, Editor is usually a metadata group so if you write {%CHANNEL-METADATA% editor}, Awasu will check the the metadata group's child nodes for a name or email address or home page URL for the actual value to use.

This table lists which child nodes Awasu will check for each metadata group, and in which order.

Metadata ID | Check order
Author/Publisher | Name, Email, URL
Contributor/Reviewer | Name, Email, URL
Editor/Webmaster | Name, Email, URL
Image/Icon | URL
Category | Name, ID, URL
Link | URL, Name
Comments | URL
Source | Name
Read more about...
  • Standard metadata values
  • Metadata pseudo-values


Metadata pseudo-values

Pseudo-values are not real metadata entries that appear in a feed or item's metadata tree, but Awasu synthesizes values for them as if they were.

The following pseudo-values can be used with the {%CHANNEL-METADATA%} template parameter.

Metadata ID | Description
HomeUrl | Searches the channel's links and returns the channel's home URL.
Copyright! | Checks the channel's copyright message and prepends it with "Copyright" if it doesn't already contain this word.

The following pseudo-values can be used with the {%ITEM-METADATA%} template parameter.

Metadata ID | Description
AwasuId | Returns Awasu's internal item ID.
URL | Returns the URL that best represents the item.
Name! | Returns the item's title, automatically generating one if not present.
Timestamp | Checks the item's modified, published and received times (in that order) and returns a string of the form "Last changed: ...". A noCaption argument may be added if you don't want the message prefix.
Description | Returns the item's description. This will be formatted according to the current presentation settings (e.g. full content, plain text, excerpt, etc.) but this can be overridden by adding a format argument (full/excerpt/plain/none).
Read more about...
  • Standard metadata values
  • Default child metadata values


Standard template parameters

The following template parameters are always available:

Parameter | Description
REPEAT-NUMBER | Returns the repeat number when used inside a repeating section (starting from 1).
@ | Returns the evaluated result of the last conditional parameter.
BASE-DIR | The directory the current template file lives in.
RESOURCES-URL | The base URL for retrieving resources from the Resources/ sub-directory under the Awasu installation directory.

Additional template parameters can be defined in the Advanced page in the Program Options.
Read more about...
  • Writing your own template files


Channel summary page template parameters

This section describes the parameters available in the templates used to generate channel summary pages.

The following parameters are always available.

Parameter | Description
CHANNEL-METADATA | Inserts channel metadata. This parameter is the main way of accessing information about the channel.
CHANNEL-METADATA-TYPE | Inserts the type of the specified channel metadata (text/html/unknown). This parameter is most useful when used with a mode=atom10 argument which restricts the output to "text" or "html", making it suitable for generating Atom 1.0 output.
CHANNEL-METADATA-DUMP | Inserts a dump of the channel's metadata tree. This is useful when writing new templates and you want to see what metadata the channel has.
LAST-UPDATE-TIME | When the channel was last updated.
LAST-SUCCESSFUL-UPDATE-TIME | When the channel was last successfully updated.
CHANNEL-UPDATE-INFO | Inserts a message showing the last successful update time and the number of previous update errors.
FEED-ITEM-COUNT-INFO | Inserts a message of the form "Showing X of Y items" This is only set if the number of feed items being shown is less than the number of available feed items.
WATERMARK-IMAGE-URL | The URL of the watermark image.
OFFLINE-ITEM-IMAGE-URL | The URL of the image used to indicate that a feed item is available for offline reading.
SHOW-CHANNEL-DESCRIPTION | Set if the channel's description should be shown.
SHOW-CHANNEL-DETAILS | Set if the channel's details should be shown.
SHOW-ITEM-DESCRIPTION | Set if feed item descriptions should be shown.
SHOW-ITEM-DETAILS | Set if feed item details should be shown.
SHOW-ITEM-RELATED-LINKS | Set if feed item related links should be shown.

The following parameters are available inside a FeedItems repeating section.

Parameter | Description
ITEM-METADATA | Inserts item metadata. This parameter is the main way of accessing information about the item.
ITEM-METADATA-TYPE | Inserts the format of the specified item metadata (text/html/unknown). This parameter is most useful when used with a mode=atom10 argument which restricts the output to "text" or "html", making it suitable for generating Atom 1.0 output.
ITEM-METADATA-DUMP | Inserts a dump of the item's metadata tree. This is useful when writing new templates and you want to see what metadata the item has.
ITEM-DUMP | Inserts a complete dump of the item. This is useful when writing new templates and you want to see everything Awasu knows about the item.
ITEM-STATE | Inserts the item's state ("new", "read" or "unread").
ITEM-IMAGE-URL | Inserts the URL for the item's image.
OFFLINE-ITEM-URL | Inserts a special URL that will show a feed item even when you are offline.
ITEM-RELATED-LINKS-INFO | Inserts an HTML fragment that lists the related links for a feed item. While an item's links are available via its Link metadata, this parameter does additional processing such as eliminating duplicates, the URL for the item itself, Atom service links, etc.
METADATA-MODULE-BLOCK | Inserts template code for any active metadata modules. This parameter takes a single argument specifying which piece of template code to insert (channelDescription, channelDetails, itemDescription or itemDetails).

The following parameters are available inside a SendTo, SendTo-Workpads or SendTo-UserDefined repeating section.

SENDTO-NAME | Inserts the name of the current Send-To tool.
SENDTO-ID | Inserts the ID of the current Send-To tool.
Read more about...
  • Writing your own template files
  • The standard template parameters


Channel report template parameters

This section describes the parameters available in templates used to generate reports.

The following parameters are always available.

Parameter | Description
REPORT-NAME | The report's name.
REPORT-DESCRIPTION | The report's description.
REPORT-TIME | The time the report was generated.
REPORT-FILENAME | The file the report is being saved to.
CHANNEL-FILTER-NAME | The channel filter being used to select channels to include in the report.
WORKPAD-NAME | The workpad the report is being generated from.
TEMPLATE-FILENAME | The template file being used to generate the report.
GROUP-ITEMS-BY-CHANNEL | Flags if items should be grouped by channel.
WATERMARK-IMAGE-URL | The file path to the watermark image.

The following parameters are available inside a Channels or Channels-IfGroupingItems repeating section.

Parameter | Description
CHANNEL-METADATA | Inserts channel metadata. This parameter is the main way of accessing information about the channel.
CHANNEL-METADATA-TYPE | Inserts the type of the specified channel metadata (text/html/unknown). This parameter is most useful when used with a mode=atom10 argument which restricts the output to "text" or "html", making it suitable for generating Atom 1.0 output.

The following parameters are available inside a FeedItems repeating section.

Parameter | Description
ITEM-METADATA | Inserts item metadata. This parameter is the main way of accessing information about the item.
ITEM-METADATA-TYPE | Inserts the format of the specified item metadata (text/html/unknown). This parameter is most useful when used with a mode=atom10 argument which restricts the output to "text" or "html", making it suitable for generating Atom 1.0 output.
ITEM-METADATA-DUMP | Inserts the item's metadata tree. This is useful when writing new templates and you want to see what metadata the item has.
ITEM-IMAGE-URL | Inserts the URL for the item's image.

The following parameters are available in workpad reports only.

Parameter | Description
WORKPAD-NAME | The name of the workpad.
WORKPAD-DESCRIPTION | The workpad's description.
ITEM-NOTES | Any notes that have been entered by the user for the feed item.

The following parameters are available inside a CustomFields repeating section.

CUSTOM-FIELD-NAME | The name of the current custom field.
CUSTOM-FIELD-NAME | The value of the current custom field.
Read more about...
  • Writing your own template files
  • The standard template parameters


Search channel template parameters

This section describes the parameters available in templates used by search channels to generate their feeds.

The following parameters are always available.

Parameter | Description
CHANNEL-METADATA | Inserts channel metadata. Outside a SearchResults repeating section, this parameter refers to the search channel itself.
CHANNEL-METADATA-TYPE | Inserts the type of the specified channel metadata (text/html/unknown). This parameter is most useful when used with a mode=atom10 argument which restricts the output to "text" or "html", making it suitable for generating Atom 1.0 output.

The following parameters are available inside a SearchResults repeating section.

Parameter | Description
CHANNEL-METADATA | Inserts channel metadata. Inside a SearchResults repeating section, this parameter refers to the channel the current search result came from.
ITEM-METADATA | Inserts item metadata from the current search result.
ITEM-METADATA-TYPE | Inserts the format of the specified item metadata (text/html/unknown). This parameter is most useful when used with a mode=atom10 argument which restricts the output to "text" or "html", making it suitable for generating Atom 1.0 output.
ITEM-METADATA-DUMP | Inserts a dump of the item's metadata tree. This is useful when writing new templates and you want to see what metadata the item has.
ITEM-SCORE | The current search result's score.
OPEN-CHANNEL-URL | Inserts a URL that will open the channel the current search result came from in Awasu.
OPEN-ITEM-URL | Inserts a URL that will open the current search result in Awasu.
Read more about...
  • Writing your own template files
  • The standard template parameters


Search result template parameters

This section describes the parameters available in templates used to generate a search results page.

The same parameters as search channels are available, plus the following additional ones.

Parameter | Description
QUERY-STRING | The original query string.
RESULT-COUNT | The number of search results.
RESULT-COUNT-MSG | The number of search results (as a formatted message).
PAGE-COUNT | The number of pages of search results.
PAGE-COUNT-MSG | The number of pages of search results (as a formatted message).
NO-SEARCH-RESULTS | Set if no search results were found.
PAGE-NO | The current search results page number.
PREV-PAGE-URL | The URL for the previous page of search results (if available).
PREV-PAGE-IMAGE-URL | The URL for the "previous page" image.
NEXT-PAGE-URL | The URL for the next page of search results (if available).
NEXT-PAGE-IMAGE-URL | The URL for the "next page" image.
ITEM-IMAGE-URL | The URL of each item's image.
Read more about...
  • Using templates
  • The standard template parameters


General options

Awasu general options This page controls the general operation of Awasu.

  • Play sound on error
    Awasu will play a sound if an error occurs.
  • Mouse
    Click here to set mouse options.

  • Disable all animation
    Disables all animation.
  • Disable all sound
    Disables all sound.
  • Disable watermarks
    Disables watermark images in channel summary pages and reports.

  • Blackout times
    Click here to set times during which Awasu should not automatically update any channels.
    For example, if you want to leave Awasu running overnight on your PC at work and you know that you won't be there (hopefully).

  • Show notification balloons
    Shows notification balloons when new channel content is received.
    You still need to turn on notification balloons for individual channels but this setting lets you turn them off across the board. You can also temporarily pause balloons (e.g. because you want to watch a movie full-screen) by right-clicking on the Awasu icon in the system tray.
  • Disable at startup
    Disables notification balloons for new content received during the first round of channel updates after Awasu is started.
    When you start Awasu, most of your channels will usually be due for an update and receive new content when they do. If you have a lot of channels configured to show notification balloons, it can take a long time to get through them all so this option lets you disable them for the initial round of updates after Awasu starts.
  • Show error notification balloons
    Shows notification balloons when errors occur.
  • Run from the system tray
    Runs Awasu as a system tray application.
    Awasu will hide itself in the taskbar when minimized and will send itself to the system tray instead of exiting. To really exit the program, right-click on the system tray and choose Exit from the menu there.
  • Run automatically when Windows starts
    Starts Awasu automatically when you log in to Windows.
  • Start minimized
    Starts Awasu minimized.
    If this is enabled in conjunction with the Run from the system tray option, Awasu will start in the system tray only.

  • Auto-load sync data at startup
    Automatically loads synchronization data when Awasu starts.
  • Auto-save sync data
    Configures when Awasu should save synchronization data.
    Doing this during channel blackouts will give best results.

    If you configure this to happen periodically, do a test run first to make sure everything is working, and then those same settings will be used for subsequent automatic runs.

  • Check for new releases
    Notifies you when new versions of Awasu are released.
  • Check for new beta releases
    Notifies you when new beta versions of Awasu are released.

  • Open folders at startup
    Opens all the channels in the specified folders when Awasu starts.

Setting the mouse options Mouse options

  • One-click operation
    Awasu will respond to single clicks instead of requiring double-clicks.

If you have a three-button mouse, you can also configure what Awasu will do when you click with the middle button.

Read more about...
  • Synchronizing Awasu


Display options

Awasu display options This page controls the display and presentation of Awasu.

  • Visual style
    Controls the overall appearance of Awasu.
  • Show sidebar
    Shows the Sidebar window.

Browser windows

  • Use
    Controls what Awasu will use as its embedded browser.
  • Enable tabbed browsing
    Lets you have more than one browser window open at once.
  • Window tabs
    Controls where window tabs will appear.
  • Colored window tabs
    Shows window tabs using different colors.
  • Default zoom
    Controls how large content will be when a browser window is first opened.
  • Navbars
    Controls whether navbars should be initially visible or hidden when opening browser windows.
  • Simple navbars
    Shows simplified navbars (to minimize clutter).

My Channels display options

My Channels display options
  • Auto-show My Channels
    Automatically shows My Channels when the last browser window is closed.
  • Show unread item counts in My Channels
    Shows the number of unread items each channel has.
    Turning this on can slow Awasu down somewhat so you should try disabling it if you find that switching channel filters is slow.
  • Show how many channels are in each My Channels folder
    Shows how many channels are in each folder.
  • Always show channels with update errors in My Channels
    Channels that have had too many update errors will always be shown in My Channels, regardless of any channel filter settings.

Channel window display options

Channel window display options
  • Max. item pane size
    Limits the size of the channel window item panes.
    This option is provided so that they don't take too much space away from the browser pane. You can always override this limit by choosing the Size to fit context menu option (or pressing Control-F7) twice quickly in succession.
  • Auto-hide feed items
    Automatically hides the item pane when feed items are opened.
  • Brief headers
    Shows only a brief header in the channel summary pages.
  • Brief feed items
    Shows only brief feed items in the channel summary pages.

Workpad display options

Workpad display options
  • Auto-show workpads
    Automatically shows workpads when items are added.
  • Auto-hide workpads
    Automatically hides workpads when items are opened or removed.
  • Auto-remove items from workpads
    Automatically removes items from workpads when they are opened.

My Searches options

My Searches options
  • Show number of results
    Shows the number of results for each search agent.

Default content presentation

Configuring the default content presentation Awasu gives you a great deal of control over how your feed content is presented.

Here you can configure the default settings that will be used to control the presentation of each channel. These can be overridden individually for each channel in their Channel Properties dialog.

The template file controls the overall appearance of the channel summary pages. You can also configure which feed items you want to see, how far back you want to see them from and how the feed content should be presented. Feed items can either be shown one at a time, or as a river of news.

You can also add columns to item panes, highlight items of interest and modify the feed content before it is shown to you.

Read more about...
  • Changing how your channels look
  • Configuring the default settings for new channels
  • Searching for and highlighting feed items of interest
  • Modifying feed content before it is shown


Default channel settings

Changing the default settings for new channels This page lets you configure the default settings for new channels.

It is almost identical to the page found in the Channel Properties dialog and is described in detail there.

Additional settings can also be made at the start of the Channel Wizard.

Changes that you make here will only affect new channels that are subsequently created. Existing channels will not be affected.

If you want to change the default content presentation settings for your channels, you can do this from the Display page.

Read more about...
  • Changing the default content presentation for channels
  • Configuring individual channels


Advanced options

Awasu advanced options This page controls advanced features of Awasu.

  • Auto-detect an Internet connection
    Suspends all channel updates and other Internet activity if your computer is not online.
  • Delay before updating channels
    Awasu will wait before starting to update channels, either after the program has just started or after a system resume.
    This is useful for systems where there is a delay before the Internet connection is ready to be used e.g. because an IP address needs to be assigned.
  • Proxy authentication
    Click here to set proxy authentication details.
  • SMTP server (email)
    Click here to configure your SMTP server (for sending out emails).
    SMTP config
    If you want to use GMail:
    • Use a server address of gmail.com:465.
    • Enable SSL and login.
    • Enter your username/password.
    If you want to use Hotmail:
    • Use a server address of smtp.live.com:587.
    • Enable TLS and login.
    • Enter your username/password.

  • Token
    A security token that must be included in every call to the Awasu API.
  • Server port
    The HTTP port that Awasu will listen on to process requests from web pages.
    You should only change this value if it is conflicting with another application.
  • Remote access
    Allows access to the Awasu API from other computers.

  • Allow feed URL's to be updated automatically by the publisher
    Publishers may notify feed readers that their feed has moved to a new address. Tick this box to allow Awasu to update your channels with the new URL.
    It is possible for improperly-configured networks (typically wifi networks that require you to log on before you can access the net) to cause your feed URL's become scrambled. Awasu will warn you if this appears to be happening and lets you revert them back to their original URL's.
  • Enable auto-discovery
    Lets you know if Awasu finds any feeds being announced by web sites as you browse.

  • Script timeout
    The maximum amount of time external scripts and programs will be allowed to run for.
  • External HTML editor
    The path to another application to use for editing HTML content.

  • Safe feed content
    Safe feed content Click here to control how Awasu ensures your feed content is safe before showing it to you.
    "Allow embedded multimedia" is a shorthand for allowing <object> and <iframe>, which are the most commonly used tags for embedding multimedia into web pages.
  • Metadata modules
    Click here to control which metadata modules get processed when updating feeds.
  • Templates
    Click here to define additional global template parameters.
    This feature can be used to control features in channel and report templates.

Read more about...
  • How Awasu automatically detects feeds embedded in web pages
  • How Awasu ensures your feed content is safe
  • Metadata modules


Archive options

Awasu archive and search index options This page controls how Awasu archives and searches your feed content.

  • Keep content for
    Controls how long your feed content will be archived for.
    This can also be set individually for each channel.
  • Download embedded feed item images for reading offline
    Awasu will download images embedded in feed items so they can be shown even when you are offline.
  • Database access
    Setting this to "fast" lets Awasu run much faster but there is a very small risk of a corruption in the archive database if Windows stops unexpectedly (i.e. because it crashed or the power goes out).

  • Enable the search index
    Controls whether Awasu should update the search index as new content is received.
    Maintaining the search index is a time-consuming process and can sometimes slow Awasu down if you have a lot of channels. If you don't use Awasu's search features, turning the search index off will speed things up considerably.
  • Results per page
    Controls how many search results to show per page.
  • Restrict search index updates
    Restricts search index updates to certain times.
    Ticking this box will speed up Awasu noticeably by deferring updates to the search index to times when you are not using it e.g. overnight. The only disadvantage is that new feed content will not be returned as search results until the next time the search index is updated.
Read more about...
  • Downloading content for reading offline
  • Awasu's advanced search engine


Enclosure options

Awasu enclosure options This page controls how Awasu downloads and manages enclosures.

For safety, Awasu strictly controls what it downloads, and only files with the specified filename extensions or mime types will be downloaded.

  • Automatically download enclosures
    Awasu will automatically download enclosures attached to feed items.
    This is a master switch for downloading enclosures; it must also be turned on for individual channels.
  • Save in
    Where downloaded files will be saved.
  • File types
    The types of file that may be downloaded (specified by file extension or MIME type).
  • Files can be downloaded...
    Controls when enclosures may be downloaded.
    Since enclosures are often large, you may want to only download them when you are not using Awasu (e.g. overnight) so that they don't take bandwidth away from your normal browsing.
  • Automatically delete files after
    Controls how long downloaded files should be kept before being automatically deleted.
  • Max. # new enclosures per channel update
    Limits the number of new enclosures that will be downloaded per channel update.
    This setting stops Awasu from downloading huge amounts of content in certain situations e.g. you have just subscribed to a new channel, or the publisher has bulk-changed the enclosure URL's.

  • Download queue
    Click here to manage the files that are waiting to be downloaded.
Channels can be configured individually in the Channel page of the Channel Properties dialog.
Read more about...
  • Enclosures
  • Configuring individual channels for enclosures


Fonts

Awasu font options This page controls the visual presentation of Awasu.

  • Use bold fonts
    Shows channels with new content in a bold font.
  • Italicize read items
    Shows feed items that you have already read in italics.


Hints

Awasu hints Awasu will show you hints to let you know about certain things as they happen.

This page lets you turn these hints on and off.


Channel templates

Awasu comes with many template files that control how your channels look.

You can change the appearance of all your channels from the Display page of the Program Options or individually for each channel from the Channel page of the Channel Properties dialog.

Cork channel summary template Eclipse channel summary template Grape channel summary template Lime channel summary template Marshmallow channel summary template MT Georgia Blue channel summary template Notebook channel summary template Overcast channel summary template Pink channel summary template Rusty channel summary template Slashdot channel summary template Terminal channel summary template Wordpress channel summary template

It's easy to tweak these templates [1] or write more of your own, so check out other people's contributions on the Awasu Wiki and feel free to add your own.

Read more about...
  • Writing your own template files

[1] If you want to make changes to one of the standard channel templates, you should do it on a copy of the template file to ensure that your changes are not overwritten when you upgrade to a new version of Awasu.


Docking windows

Floating docking windows Awasu provides sophisticated features for managing the key informational windows.

They can be docked to any side of the main window or detached and made to float [1].

Auto-hide docking windows If windows are docked, they can also be made to automatically hide themselves when not in use.

Look for the small pushpin in the title bar and click on it so that pin is pointing to the left (or use the Window|Pin menu item).

The window will now automatically hide itself when it is not being used.

To show the docking window again, move the mouse over the window's placeholder, or choose the appropriate menu item.

Read more about...
  • Customizing your menus
  • Customizing your toolbars

[1] Double-click on the window title bars to dock/undock them, or just drag them around.


Commands

Customizing commands To show the Customize dialog, choose Customize from the Tools menu.

The first page lets you customize your toolbars and menus.

Simply drag commands from the right-hand pane and onto a toolbar or menu.

If you want to remove commands from a toolbar or menu, just drag them off.

Read more about...
  • Customizing your toolbars
  • Customizing your keyboard shortcuts
  • Customizing your menus


Toolbars

Customizing the toolbars This page lets you customize your toolbars.

To create a new toolbar, click on the New button and give it a name.

Then drag commands from existing toolbars or menus onto the new toolbar.

If you want to remove commands, just drag them off.

Read more about...
  • Customizing your toolbars and menus
  • Customizing your keyboard shortcuts
  • Customizing your menus


Keyboard

Customizing the keyboard If you prefer to use the keyboard instead of the mouse, you can customize your keyboard shortcuts here.

To create a new shortcut for a command:

  • Select the command in the Category and Commands windows.
  • Click inside the Press New Shortcut Key window and then press the keyboard sequence you want to assign e.g. Control-N or Alt-F.
  • Click on the Assign button to assign that keyboard sequence to the command.
  • The new keyboard shortcut will now appear in the list of Current Keys.

Read more about...
  • The default keyboard shortcuts
  • Customizing your toolbars and menus
  • Customizing your toolbars
  • Customizing your menus


Menu

Customizing the menus This page lets you customize Awasu's menus.

Choose a context menu from the right-hand side of the dialog and it will appear on the screen.

You can then drag commands from other menus or toolbars onto it.

To remove commands, simply drag them off.

Read more about...
  • Customizing your toolbars and menus
  • Customizing your toolbars
  • Customizing your keyboard shortcuts


Options

Other customization options This page lets you customize other aspects of Awasu's user interface.

Read more about...
  • Customizing your toolbars and menus
  • Customizing your toolbars
  • Customizing your keyboard shortcuts
  • Customizing your menus


Overview

One of the most powerful features of Awasu is its extensibility.

This section describes plugins and other add-ins that are installed as standard. You can also download more from the Awasu Wiki.

If you want to write your own plugins or hooks, you will find details in the For developers section.

Application plugins

Application plugins add extra functionality to Awasu itself. Open the Plugins window to see the plugins that have been installed.

Channel hooks

Channel hooks are small programs that hook into the flow of information as it is processed in Awasu. They can be attached to a channel from the Advanced page of the Channel Properties dialog.

The following hooks are installed as standard:

  • Channel Monitor Window
    Shows a small window that can be left floating on your desktop that displays the latest content for a channel.
  • Send Email
    Sends out an email when new feed items are received on a channel.
  • Log Channel Activity
    Logs all channel hook activity and is useful for exploring how Awasu interacts with hooks.
You can find more channel hooks on the Awasu Wiki.

XSLT

XSLT can be used to convert XML data into a feed or to modify an existing feed.

The following XSLT's are supplied as standard:

  • ReverseFeed.xsl
    Accepts a feed and reverses the feed items.
    This is useful for feeds that don't publish their content in reverse chronological order (as is the custom).
You must have MSXML installed to use these.

You can find more XSLT's on the Awasu Wiki.

SOAP

SOAP is used to send specialized requests to another computer (often a web service).

The following SOAP request files are supplied as standard:

  • GoogleSearch-SoapRequest.xml
    Queries Google's web service and lets you monitor the results as a feed.
    Check the comments in the file for details on how to set up a channel.
You must have MSXML installed to use these.

You can find more SOAP files on the Awasu Wiki.
Read more about...
  • Plugins
  • Writing your own plugins
  • Channel hooks
  • Writing your own channel hooks
  • Using SOAP and XSLT


Channel Monitor Window

The Channel Monitor Window channel hook This channel hook opens a small window that shows the latest stories for a channel. It can be left floating on your desktop, even if the main Awasu window has been minimized.

Configuring the channel hook

Configuring the Channel Monitor Window Channel hooks can be attached to a channel from the Advanced page in the Channel Properties dialog.

  • Hide read items
    Turn this on to hide feed items that you have already read.
  • Always on top
    Turn this on to keep the monitor window on top of all other windows on your desktop.

Read more about...
  • Channel hooks
  • Writing your own channel hooks


Send Email

This channel hook sends out emails when new content arrives on a channel.

Channel hooks can be attached to a channel from the Advanced page in the Channel Properties dialog.

You must configure a SMTP server for Awasu to be able to send out emails (this only needs to be done once).

Configuring a channel

Configuring the Send Email channel hook parameters

  • Send-To Email Address
    The address to send the emails to.
    This parameter is mandatory.
  • From Email Address
    The address to use as the From address in the email.
  • Reply-To Email Address
    The address to use as the Reply-To address in the email.
  • Email Subject Line
    The email subject line.
    Use {%DEFAULT-SUBJECT-LINE%} as a placeholder for Awasu's default subject line, {%CHANNEL-NAME%} for the channel's name.
  • Consolidate New Feed Items
    Turn this on if you want to consolidate multiple new feed items into a single email (instead of sending out one email per new item).
  • New Feed Item Template
    Path of a template file that will be used to generate the email.
  • Consolidated New Feed Items Template
    Path of a template file that will be used to generate the email (if new items are being consolidated).
If the template file has an extension of .HTM or .HTML, the email will be sent out in HTML format, otherwise it will be sent as plain-text.
Read more about...
  • Channel hooks
  • Writing your own channel hooks

[1] These settings only need to be set once and apply to all instances of this channel.


Log Channel Activity

This channel hook logs every time it is called and can be used to explore how Awasu interacts with channel hooks.

Channel hooks can be attached to a channel from the Advanced page in the Channel Properties dialog.

Configuring the channel hook

Configuring the LogChannelActivity channel hook parameters Simply specify a log file and whether you want config files to be dumped. Turning this on will log a copy of the INI file Awasu passes in (as a command-line parameter) each time the channel hook is called, and is useful for determining what information is sent through for each type of event.

The hook will log activity for all events by default, but this can be changed by editing the .HOOK file so that it only registers for events that you are interested in.

This channel hook is written in Python and so requires the Python interpreter to be installed.

Read more about...
  • Channel hooks
  • Writing your own channel hooks


Introduction

Plugins are small programs that Awasu can run to perform a task.

There are two types of plugin:

  • Channel plugins.
    These generate feeds for web sites or other data sources that don't already have one.
  • Application plugins
    These add new features to Awasu.

Plugins can be written in any language you want. The only requirement is that they be able to read a Windows INI file and can write to the console. Popular choices are scripting languages such as Python or Perl but you could also use Java, C++ or C#.

Libraries are available on GitHub that simplify the process of writing an Awasu extension.

Channel hooks are similar to plugins and are small programs that get run when certain things happen while a channel is updating e.g. new items are received.
Read more about...
  • Getting started with channel plugins
  • Defining parameters for a channel plugin
  • Extending Awasu with application plugins
  • Advanced plugin topics


Channel plugins

The simplest kind of plugin is a channel plugin, so we'll start with one of those. We'll write it in Python, since it's very easy to see what's happening, even if you don't know the language.

The sample code is available on GitHub.

Running a simple channel plugin

Start Awasu, open the Channel Wizard and select the script file python-channel/sample_python_channel.py. When you have finished going through the wizard, Awasu will call this script to generate a feed and show you the results.

The script looks like this:

# set the feed parameters
home_url = "https://test.com"
n_items = 5

# generate the RSS feed
print( "<rss>" )
print( "<channel>" )
print()
print( "<title>Sample Python Channel</title>" )
print( "<link>{}</link>".format( home_url ) )
print( "<description>This is a demo RSS feed generated by the sample Python channel plugin.</description>" )
print()
for i in range( 1, n_items+1 ):
    print( "<item>" )
    print( "    <title>Item {}</title>".format( i ) )
    print( "    <link>{}/item-{}.html</link>".format( home_url, i ) )
    print( "    <description>This is the description for item {}.</description>".format( i ) )
    print( "</item>" )
    print()
print( "</channel>" )
print( "</rss>" )

That's it! Plugins just print out their feed to the console and Awasu will take it from there. We won't go into the details of the exact format of an feed here but it's easy to see how things are organized. Most of the time, you won't need anything more than this.

How plugins are run

A few notes about how plugins are run:

  • Awasu determines which program to run by checking the script's file extension and looking up the appropriate association in the Windows Registry. Most of the time, the scripting engine will set this up for you when it is installed but it is possible to override this or define new associations if necessary. You should definitely read this section if you are writing plugins in Java.
  • If the plugin writes anything to the error output (stderr) or returns a non-zero exit code, this will be treated as an error by Awasu and processing will be aborted. In the example above, we simply run off the end of the script, which will return a zero exit code by default.
  • The plugin will be run in the directory in which the script resides. For a stand-alone script this is not important but will be relevant if the script needs to locate data files or other helper scripts.
Read more about...
  • Defining parameters for a channel plugin
  • Advanced plugin topics


Plugin parameters

In the previous example, the home URL and number of feed items to generate were hard-coded in the script. We'll make these user-configurable by adding some parameters to the plugin.

Setting up parameters for a channel plugin

Start the Channel Wizard and select the script SamplePythonChannel2.py. This time there will be an extra step in the wizard that lets you set the home URL and the number of feed items to generate.

To define plugin parameters, create a file in the same directory that has the same name as the script but with a .plugin extension. It should look something like this:

[ChannelParameterDefinition-1]
Name = HomeUrl
Type = string
DefaultValue = https://test.com
Description = Our demo home URL.
IsRequired = 1

[ChannelParameterDefinition-2]
Name = nItems
Type = int
DefaultValue = 5
Description = The number of feed items to generate.
IsRequired = 1

Each section defines a new parameter and can be repeated as many times as required. The exact format of this file is given in the appendix.

Getting parameter values at runtime

When the script is run, it receives a single command-line parameter, the path to an INI file that contains the values for these parameters for the channel requesting the feed. For this example, if the user had changed the number of items to generate but left the home URL with the default value, the plugin will be given an INI file that might look something like this:

[ChannelParameters]
HomeUrl = https://test.com
nItems = 3

We now modify the start of the script to read these values from the INI file, instead of using hard-coded values:

# get our channel parameters
parser = configparser.ConfigParser()
parser.read( sys.argv[1] )
home_url = parser.get( "ChannelParameters", "HomeUrl", fallback="" )
n_items = int( parser.get( "ChannelParameters", "nItems", fallback=0 ) )

# the rest of the script is the same as before...

Now you can create as many channels as you like using the same script, but with different parameters.

Read more about...
  • Getting started with channel plugins
  • Advanced plugin topics


Application plugins

Writing an application plugin is a very similar process to writing a channel plugin. However, instead of being selected via the Channel Wizard, they are loaded by Awasu when it starts and appear in the Plugins window.

How Awasu loads application plugins

To see an application plugin in action, copy the two files in the SamplePythonPlugin/ directory to the AppPlugins/ directory in the Awasu installation directory, then restart Awasu. You should see a new entry in the Plugins window.

When Awasu starts, it scans AppPlugins/ (and its sub-directories) looking for files with a .plugin extension. This file contains information about the plugin e.g.

[Config]
Plugin = sample_python_app_plugin.py
AppPluginId = SamplePythonAppPlugin
AppPluginDisplayName = Sample Python App Plugin

The Plugin parameter gives the name of the plugin script, which must reside in the same directory. AppPluginId must be a unique identifier string while AppPluginDisplayName is the display name that the user will see.

How the application plugin's start page is generated

When the user first opens the plugin from the Plugins window, the plugin will be asked to generate an HTML page that will be shown to the user. The plugin script will be run with a Windows INI file as before, but with a few more parameters:

[System]
Command = GenerateMainPage
AppServerUrl = ...
PluginServerUrl = ...

where the Command parameter specifies what the plugin is being asked to do. In this case, it will be GenerateMainPage and the plugin should accordingly print out to the console an HTML page that Awasu will show to the user in a browser window.

Setting up parameters for the application plugin

As before, you can define channel parameters for the plugin. This example also defines a global plugin parameter:

[PluginParameterDefinition-1]
Name = DomainName
Type = string
DefaultValue = https://test.com
Description = Domain name for generated URL's.
IsRequired = 1

[ChannelParameterDefinition-1]
Name = nItems
Type = int
DefaultValue = 5
Description = Number of items to generate.
IsRequired = 1

[ChannelParameterDefinition-2]
Name = ItemTitleStem
Type = string
DefaultValue = Item Title
Description = Stem to use for generated item titles.
IsRequired = 1

[ChannelParameterDefinition-3]
Name = GenerateDescriptions
Type = bool
DefaultValue = 1
Description = Flags if descriptions should be generated for feed items.

Global plugin parameters (defined in PluginParameterDefinition- sections) are shared by all channels serviced by the plugin i.e. if the user changes their values, it will affect every channel. This example also defines 3 other parameters that can be set independently for each channel.

Writing interactive application plugins

It is possible to embed special links in the generated HTML page that will cause a request to be routed back to the plugin when the user clicks on them. This lets users interact with the plugin.

The general format of these URL's looks like this:

PLUGIN_SERVER_URL/APP_PLUGIN_ID/RequestName?ParamString
where PLUGIN_SERVER_URL is the string defined by the PluginServerUrl value in the INI file and APP_PLUGIN_ID is the plugin's ID. RequestName and ParamString can be anything you like and will be passed back to the plugin when the user clicks on the link. For example, if your HTML-generation code looked something like this:
url = PLUGIN_SERVER_URL + "/" + APP_PLUGIN_ID + "/foo/bar?p1=hello&p2=world"
print( "<a href='" + url + "'>Click here!</a>" )
when the user clicks on the link, the plugin will be called with the following information in the INI file:
[System]
Command = ProcessRequest
PluginRequest = foo/bar
ParamString = p1=Hello&p2=World

Sending requests to Awasu

Calls to the Awasu API can also be sent, using the values specified in the AppServerUrl and AppToken parameters.

For example, to embed a link that lets users subscribe to Awasu's feed, you would do something like this:

url = APP_SERVER_URL + "/channels/subscribe?url=https://awasu.com/news.xml"
print( "Click <a href='" + url + "'>here</a> to subscribe to Awasu.")

If you're technically-minded, a description of how this all works can also be found here.

How the sample application plugin works

Getting back to our sample plugin, the script starts off with this piece of code (at the bottom of the file):

# load the INI file passed in to us
parser = configparser.ConfigParser()
parser.read( sys.argv[1] )

# process the requested command
scriptCmd = parser.get( SYSTEM_PARAMETERS_SECTION_NAME, "Command", fallback="" )
if scriptCmd == "GenerateMainPage":
    generate_main_page( parser )
elif scriptCmd == "ProcessRequest":
    plugin_request = parser.get( SYSTEM_PARAMETERS_SECTION_NAME, "PluginRequest", fallback="" )
    param_string = parser.get( SYSTEM_PARAMETERS_SECTION_NAME, "ParamString", fallback="" )
    process_request( parser, plugin_request, param_string )
else:
    raise RuntimeError( "Unknown script command: " + scriptCmd )

We load the INI file passed in to us and determine what we're being asked to do: generate the main page or process a request (because the user clicked on a link that has been routed back to us). An exception is raised if an error occurs which will print a message to the error console. Awasu will detect this and treat it as an error.

This is the generate_main_page() function that builds the plugin's HTML start page:

# get the app settings
app_server_url = parser.get( SYSTEM_PARAMETERS_SECTION_NAME, "AppServerUrl", fallback="" )
if not app_server_url:
    raise RuntimeError( "No app server URL was specified." )
app_plugin_server_url = parser.get( SYSTEM_PARAMETERS_SECTION_NAME, "AppPluginServerUrl", fallback="" )
if not app_plugin_server_url:
    raise RuntimeError( "No app plugin server URL was specified." )

# get the plugin settings
domain_name = parser.get( PLUGIN_PARAMETERS_SECTION_NAME, "DomainName", fallback="" )
if not domain_name:
    raise RuntimeError( "No domain name was specified." )

# generate a URL that will let the user subscribe to a channel that
# we will generate. We embed some information in URL path and parameters
# for demonstration purposes. These will get passed in to process_request()
# when the channel is updated.
api_token = parser.get( SYSTEM_PARAMETERS_SECTION_NAME, "ApiToken", fallback="" )
url = "{}/channels/subscribe?token={}&silent=1".format( app_server_url, api_token )
url += "&url={}/{}/foo/bar?p1=Hello%26p2=World".format( app_plugin_server_url, APP_PLUGIN_ID )

# generate the main page
print( """
<html>
<body>
<h2> Sample Python Plugin </h2>
<p> This is the main page for the sample Python plugin.
<p> The plugin settings are:
<ul>
    <li> DomainName: {domain_name}
</ul>
<p> Click <a href='{url}'>here</a> to subscribe to a test channel.
</body>
</html>
""".format( **locals() ) )

We insert a link that will send a channel subscription request to Awasu for a URL that will be routed back to us when it is used.

When Awasu goes to update the channel, the URL tells it that the channel is actually being generated by a plugin. The plugin is then run again with the Command parameter set to ProcessRequest and our process_request() function is called:

# get the plugin settings
domain_name = parser.get( PLUGIN_PARAMETERS_SECTION_NAME, "DomainName", fallback="" )
if not domain_name:
    raise RuntimeError( "No domain name was specified." )

# get the channel settings
n_items = int( parser.get( CHANNEL_PARAMETERS_SECTION_NAME, "nItems", fallback=5 ) )
item_title_stem = parser.get( CHANNEL_PARAMETERS_SECTION_NAME, "ItemTitleStem", fallback="Item Title" )
generate_descriptions = int( parser.get( CHANNEL_PARAMETERS_SECTION_NAME, "GenerateDescriptions", fallback=1 ) )

# put together a channel description
description = ... # code not relevant to this discussion snipped here

# generate the RSS feed
print( "<rss>" )
print( "<channel>" )
print()
print( "<title>Sample Python Plugin</title>" )
print( "<link>" + domain_name + "</link>" )
print( "<description><![CDATA[" + description + "]]></description>" )
print()
for i in range( 1, n_items+1 ):
    print( "<item>" )
    print( "    <title>{} {}</title>".format( item_title_stem, i ) )
    print( "    <link>{}/item-{}.html</link>".format( domain_name, i ) )
    if generate_descriptions:
        print( "    <description>This is the description for item {}</description>".format( i ) )
    print( "</item>" )
    print()
print( "</channel>" )
print( "</rss>" )
Read more about...
  • Getting started with channel plugins
  • A more advanced example of writing an application plugin


Querying a database

The Java sample plugin is a little more advanced. It provides two channels that can be subscribed to but instead of generating dummy data, it queries a database and returns a feed for the rows it finds.

Compile the plugin and copy the .jar, .plugin and .db files to the AppPlugins/ directory and restart Awasu. You should see a new entry in the Plugins window.

How the sample plugin works

One of the tables contains hypothetical data for a company's sales and you can see the plugin in action by subscribing to this channel and then adding a row to the database. The next time the channel updates, you will receive a notification of the new sale!

The subscription URL's on the main page are created so that they have a database table name embedded in them. This is so that we can determine which table to query when Awasu calls us to generate a feed:

// generate a channel URL
StringBuffer buf = new StringBuffer() ;
buf.append( "<a href='" ) ;
buf.append( appServerUrl + "/channels/subscribe" ) ;
buf.append( "?token=" + apiToken ) ;
buf.append( "&silent=1" ) ;
buf.append( "&url=" + appPluginServerUrl + "/" + APP_PLUGIN_ID + "/" + tableName ) ;
buf.append( "'>" ) ;
buf.append( tableName ) ;
buf.append( "</a>" ) ;
return buf.toString() ;

When Awasu calls the script to generate a feed, it passes us whatever information we may have embedded in the URL. In our case, this will be the table name which we query and generate a feed for accordingly:

// prepare the SQL query
String sql ;
if ( maxRows < 0 )
    sql = "SELECT * FROM customer_sales" ;
else
    sql = "SELECT * FROM customer_sales LIMIT " + Integer.toString(maxRows) ;
Statement stmt = conn.createStatement() ;
ResultSet rs = stmt.executeQuery( sql ) ;

// generate the RSS feed
StringBuffer rssBuf = new StringBuffer() ;
rssBuf.append( "<rss>\n" ) ;
rssBuf.append( "<channel>\n" ) ;
rssBuf.append( "<link>http://intranet/sales</link>\n" ) ;
rssBuf.append( "<title>Latest Customer Sales</title>\n" ) ;
while( rs.next() ) {
    rssBuf.append( "<item>\n" ) ;
    // NOTE: This is a dummy URL that demonstrates how one might be generated for a given sales item.
    String url = "http://intranet/sales/" + rs.getString("id") ;
    rssBuf.append( "<link>" + url + "</link>\n" ) ;
    String title = rs.getString("customer_name") + " ($" + rs.getInt("amount") + ")" ;
    rssBuf.append( "<title>" + title + "</title>\n" ) ;
    StringBuffer buf = new StringBuffer() ;
    buf.append( rs.getString("date_of_sale") + ": " ) ;
    buf.append( rs.getString("item_count") + " x " + rs.getString("item_name") ) ;
    String comments = rs.getString("Comments") ;
    if ( comments != null )
        buf.append( "<br><i>" + comments + "</i>" ) ;
    rssBuf.append( "<description><![CDATA[" + buf.toString() + "]]></description>\n" ) ;
    rssBuf.append( "</item>\n" ) ;
}
rssBuf.append( "</channel>\n" ) ;
rssBuf.append( "</rss>\n" ) ;
System.out.println( rssBuf.toString() ) ;
Read more about...
  • Writing application plugins
  • Getting started with channel plugins
  • Defining parameters for a channel plugin


Summary

As you have seen, it's pretty easy to write Awasu plugins, whether they be channel plugins that dynamically generate a feed, or application plugins that extend Awasu itself.

One of the key features of Awasu's plugin architecture is that not only can you write a plugin in any language you choose, you can also write it outside of Awasu in whatever development environment you may have. All you have to do is set up an INI file containing the appropriate parameters and pass it to your script as the command-line argument. Once you've got everything working, simply copy everything over and give it to Awasu.

You can download many plugins that have been written by us and other people from the Awasu Wiki. If you write something that might be useful to others, feel free to upload it there as well!


Plugin configuration file

A plugin configuration file (.plugin extension) is used by both channel plugins and application plugins.

  • It is optional for channel plugins and is only necessary if the plugin defines any parameters.
    This file must reside in the same directory as the plugin script itself and have the same name (except for the extension).
  • It is mandatory for application plugins and must contain at least the name of the plugin script (which must reside in the same directory). It can also contain definitions of any global or per-channel parameters.
    This file must reside in the AppPlugins/ directory (or sub-directory) where it will be loaded by Awasu when it starts.

The format of this file is as follows:

[Config]
Plugin =                Application plugin script. Must be in the same directory.
AppPluginId =           Application plugin ID. Must be unique within Awasu and contain only letters, digits and underscores.
AppPluginDisplayName =  Display name that the user will see (optional).
AuthorName =            Plugin author's name (optional).
AuthorEmailAddress =    Plugin author's email address (optional).
PluginNotes =           User notes (optional).
HelpFile =              Path or URL to a help file (optional).

Defining plugin parameters

Plugins can define user-configurable parameters. Global plugin parameters apply to all channels being serviced by the plugin and are defined as follows:

[PluginParameterDefinition-1]
Name =                  Parameter name. Must be unique.
Type =                  Parameter type. Must be one of "int", "bool", "string", "password" [1], "double", "file" or "dir".
DefaultValue =          Default value (optional).
Choices =               A list of choices the user can choose from (optional) [2].
RestrictedChoices =     A list of choices the user must choose from (optional) [2].
Description =           Description of the parameter (optional).
IsRequired =            Flags if the parameter is mandatory (optional).
AutoTrim =              Flags if whitespace should be trimmed (optional).
FileFilters =           A list of file types (for file parameters only) (optional) [3].

This information can be repeated for as many parameters as the plugin wishes to define (just keep incrementing the number in the section name).

Per-channel parameters are defined in a similar way. Each channel will get its own copy of these parameters, allowing the user to configure them independently of other channels:

[ChannelParameterDefinition-1]
... everything is the same as above ...

Special plugin parameters

There are several parameters that have special meaning for Awasu.

  • Download URL
    Specifies the URL of a file that Awasu will download on behalf of the plugin (taking care of cookies and proxies).
    When the plugin is run, the path to the downloaded file will be passed to the plugin in the DownloadUrlFile parameter in the [System] section of the INI file.
  • Download user name
    Download password
    Optional authentication details if Download URL is being used.
  • Script timeout
    Specifies how long the script will be allowed to run (in seconds) before Awasu will abort it.
    If this parameter is not present, Awasu will use the global default value set in the Program Options.
[1] Password parameters are the same as string parameters but are encrypted in the config files.
[2] The format of this parameter is Choice 1|Choice 2|Choice 3. A choice value can either be a simple string or of the form Actual value:Display value, if you want to show the user something other than the real underlying value (e.g. your script might look for a 0/1 value but show the user "No" and "Yes").
[3] The format of this parameter is XXX files|*.xxx|YYY files|*.yyy. Awasu will automatically add an entry for "All files (*.*)".


Plugin request INI file

Every time a plugin is run, it will receive a single command-line parameter, the path of a Windows INI file that contains information about what the plugin is being asked to do.

This is a list of the parameters present in this INI file:

[System]

Command =                       Plugin command ("GenerateMainPage" or "ProcessRequest").
PluginRequest =                 Plugin request (for "ProcessRequest" commands).
ParamString =                   Plugin request parameters (for "ProcessRequest" commands).
AppServerUrl =                  URL stem for requests to be sent to Awasu.
AppPluginServerUrl =            URL stem for requests to be sent to a plugin.
ChannelConfigFile =             Location of the channel's config file (this will be set if the plugin is being called to generate a channel's feed).
ChannelDisplayName =            The channel's display name (if applicable).
ChannelHomeUrl =                The channel's home URL(if applicable).
PluginConfigFile =              Location of the plugin's config file.
AppPluginConfigFilename =       Location of the application plugin's config file.

DownloadUrlFile =               Location of the downloaded file (if the plugin requested it via the DownloadUrl parameter).

VersionString =                 Awasu version string.
HttpApiToken =                  An API token (if you need to generate links that call the API).

InstallDir =                    Awasu installation directory.
AppPluginsDir =                 Location of Awasu's application plugins.
ResourcesDir =                  Location of Awasu's resources.
ImagesDir =                     Location of Awasu's images.
MetadataModulesDir =            Location of Awasu's metadata modules.
ChannelSummaryTemplatesDir =    Location of Awasu's channel summary templates.
ReportTemplatesDir =            Location of Awasu's report templates.
SearchResultTemplatesDir =      Location of Awasu's search result templates.
SearchChannelTemplatesDir =     Location of Awasu's search channel templates.
ApiTemplatesDir =               Location of Awasu's API response templates.
AppConfigFile =                 Location of Awasu's global config file.

UserName =                      Current user's logon name.
RoamingDataDir =                Location of the user's roaming data.
LocalDataDir =                  Location of the user's local data.
UserConfigFile =                Location of the user's config file.
ChannelsDir =                   Location of the user's channel config files.
SearchIndexDir =                Location of the user's search index.
ArchiveDatabase =               Location of the user's archive database.
LogsDir =                       Location of the user's log files.
UserResourcesDir =              Location of the user's resource files.
DefaultDownloadSaveDir =        Location of the user's default download directory.
UserOutputDir =                 Location of the user's default output directory.

[PluginParameters]

...                             One entry for each global parameter defined by the plugin (name=value).

[ChannelParameters]

...                             One entry for each per-channel parameter defined by the plugin (name=value).
Read more about...
  • Writing plugins


Application server requests

Application plugins can insert links in an HTML page that send requests to Awasu.

Using the AppServerUrl and ApiToken parameters in the INI file that is passed to the script, URL's that call the Awasu API can be constructed e.g. to get a list of channels:

APP_SERVER_URL/channels/list?token=API_TOKEN
Details about the available services are in the Awasu API section.

Read more about...
  • Writing application plugins
  • The Awasu API


Plugin server requests

Application plugins can insert links in an HTML page that send a request back to itself when the user clicks on them.

Using the PluginServerUrl parameter that is passed to the script, URL's can be constructed with the form:

PLUGIN_SERVER_URL/APP_PLUGIN_ID/PluginRequest?ParamString
where APP_PLUGIN_ID is the target plugin's ID and PluginRequest and ParamString can be whatever you like. When the user clicks on this link, the script will be run with the following INI file:
[System]
Command = ProcessRequest
PluginRequest = ...
ParamString = ...
Read more about...
  • Writing application plugins


File associations

Awasu will usually use the file associations stored in the Windows Registry to determine which application to run a script with.

Configuring Awasu to run Java plugins

Since Java does not make an association for .class files when it is installed, Awasu creates one internally:

.class = java.exe "%1" "%2"

However, this assumes that java.exe is in your path. If this is not the case or you want to create other associations, create a GLOBAL.INI file in the same directory as the Awasu executable (e.g. C:\Program Files (x86)\Awasu\) that looks like this:

[Scripting File Associations]
.class = c:\jre\java.exe "%1" "%2"

Use %1 as a placeholder for the script name, and %2 for the INI file that will be passed in to the script. These placeholders should be wrapped in quotes to safeguard against paths that have spaces in them.

Extending the plugin browser dialog

It is also possible to provide additional file types to users when they are browsing for plugins by adding entries to the GLOBAL.INI file that look like this:

[Script File Types]
.rb = Ruby scripts

Awasu adds the following entries by default:

.exe = Executables
.py = Python scripts
.pl = Perl scripts
.u = Java scripts
Read more about...
  • Writing plugins


How requests are sent to Awasu

Awasu passes a string to plugins via the AppPluginServerUrl parameter in the INI file that might look like this:

[System]
AppPluginServerUrl = http://127.0.0.1:12345

Plugins can then use this value to generate and insert URL's into a page that would then look like this:

http://127.0.0.1:12345/MyAppPluginId/foo/bar?p1=hello?p2=world

Awasu will be listening on the appropriate port and receives the HTTP request when the user clicks on the link. It figures out which plugin to send the request to (using the plugin ID embedded in the URL) and inserts the request name and parameters into the plugin's INI file, like this:

[System]
Command = ProcessRequest
PluginRequest = foo/bar
ParamString = p1=Hello&p2=World

The plugin can then use this information to process the request appropriately.

You should not rely on the port number being any particular value since the user can change it in the Program Options.

You should also not rely on the format of the AppPluginServerUrl parameter since it may change in future versions of Awasu.
Read more about...
  • Writing plugins


Introduction

Channel hooks are small programs that get run whenever something happens on a channel.

They work in exactly the same way as plugins except that while channel plugins are run whenever the channel needs to be updated, channel hooks are run whenever an event occurs on the channel.

This section assumes that you are already familiar with how plugins work.

Read more about...
  • Setting up the channel hook
  • Defining parameters for the channel hook
  • Defining commands for the channel hook
  • How channel hooks are invoked


Getting started

Channel hooks are set up by creating a configuration file that has a .HOOK extension. The main parameters are defined like this:

[Config]
ScriptFilename = ...
DisplayName = ...
AuthorName = ...
AuthorEmailAddress = ...
Notes = ...
HelpFile = ...

ScriptFilename specifies where the actual channel hook script lives. If it is not an absolute path then it is assumed that it is in the same directory as the .HOOK file.

Registering for events

Channel hooks must register for the events that they want to be called for.

The available events are:

Event | Description
ChannelHookLoaded | Raised when the channel hook has been loaded.
ChannelHookAttached | Raised when the channel hook has been attached to the channel.
ChannelHookDetached | Raised when the channel hook has been detached from the channel.
BeginChannelUpdate | Raised before the channel is updated.
EndChannelUpdate | Raised after the channel has been updated.
NewFeedItem | Raised when a new feed item has been received for the channel. A new process is started to run the channel hook for every event. If a hook wants to be notified of new feed items, it is better to register for the ConsolidatedNewFeedItems event (to handle all the new feed items in one go), rather than the NewFeedItem event (which will be much slower since it will invoke the channel hook once for each new feed item).
ConsolidatedNewFeedItems | Raised when one or more new feed items have been received for the channel.
RevisedFeedItems | Raised when one or more revised feed items have been received for the channel.
EndDownloadOfflineFeedItem | Raised when a feed item has finished being downloaded for offline reading.
ChannelAutoDownloadCompleted | Raised after an enclosure has finished being downloaded.
ChannelAutoDownloadCleanup | Raised just before a previously-downloaded enclosure is deleted (because it is too old).
MarkFeedItemsAsViewed | Raised when feed items are marked as read/unread.
ChannelConfigChanged | Raised when the channel's configuration has been changed by the user.
ChannelFeedUrlChanged | Raised when the channel's feed URL has been changed by the publisher.
ChannelError | Raised whenever an error occurs on the channel.

A channel hook indicates that it wants to be notified of an event by including it in the [Events] section in the .HOOK file. For example:

[Events]
BeginChannelUpdate = 1
ConsolidatedNewFeedItems = 1

Whenever an event the channel hook has registered for occurs, it will be called and passed an INI file that contains detailed information about the event.

The contents of the INI file depends on the type of event. Attach the supplied LogChannelActivity channel hook to your channel to examine how Awasu invokes hooks for each type of event.
Read more about...
  • Defining parameters for the channel hook
  • Defining commands for the channel hook
  • How channel hooks are invoked


Defining parameters

Channel hooks can define parameters that the user can set to control their operation.

There are two types of parameter:

  • Global parameters
    These apply to all instances of the channel hook.
  • Instance parameters
    These apply to a single instance of the channel hook.

Global parameters

Global parameters are defined in the .HOOK file like this:

[GlobalChannelHookParameterDefinition-1]
Name = ...
Type = ...

[GlobalChannelHookParameterDefinition-2]
Name = ...
Type = ...

etc.

The values that the user sets for these parameters will apply to all instances of the channel hook. See here for a full list of available parameter settings.

Instance parameters

Instance parameters are defined in the .HOOK file like this:

[ChannelHookParameterDefinition-1]
Name = ...
Type = ...

[ChannelHookParameterDefinition-2]
Name = ...
Type = ...

etc.

The user can set these parameters individually for each channel. See here for a full list of available parameter settings.

Read more about...
  • Defining commands for the channel hook
  • How channel hooks are invoked


Defining commands

One way that channel hooks differ from plugins is that they can define commands that the user can invoke to instruct the hook to do something.

The channel hook commands menu For example, the Channel Monitor Window hook defines commands to open and close the monitor window.

Commands are defined in the .HOOK file like this:

[ChannelHookCommandDefinition-1]
Name = ...
DisplayName = ...

[ChannelHookCommandDefinition-2]
Name = ...
DisplayName = ...

Commands defined here will appear in the My Channels context menu and Edit main menu when the channel is active (see screenshot).

Read more about...
  • Defining parameters for the channel hook
  • How channel hooks are invoked


How channel hooks are invoked

Channel hooks are invoked in exactly the same way as plugins. Awasu generates a Windows INI file that contains information about the event and the path to this file is passed to the channel hook as its single command-line parameter.

Awasu will invoke a channel hook for two reasons:

  • In response to an event occurring on the channel. The config file will look like this:
    [Config]
Command = ProcessEvent
EventName = ...
  • The user is sending a command to the channel hook. The config file will look like this:
    [Config]
Command = ProcessCommand
CommandName = ...

Global parameter values can be retrieved (by parameter name) from the [GlobalChannelHookParameters] section, instance parameter values from [ChannelHookParameters].

Read more about...
  • Registering the channel hook for events
  • Defining commands for the channel hook


Introduction

The Awasu API opens up Awasu's functionality to both third-party applications and Awasu extensions, allowing powerful features to be built on top of Awasu's information management engine. In particular, full create/read/update/delete functionality is available for key Awasu features such as channels, reports and workpads, allowing these to be maintained dynamically.

The services offered are grouped into the following categories:

  • Channel operations
  • Report operations
  • Workpad operations
  • Feed item operations
  • Search operations
  • Miscellaneous

Requests and responses are done over HTTP [1] and by default, Awasu listens for requests on port 2604 [2]. In this documentation, "$" is used to mean "the appropriate URL stem for issuing Awasu API requests" e.g. $/channels/list means http://localhost:2604/channels/list [3].

Libraries are available on GitHub that simplify the process of calling the Awasu API.

Security

By default, a security token must be included in each API call (via the token parameter), to prevent unauthorized access to your Awasu.

Hint
It is possible (but not recommended) to remove the security token so that API calls will not need to specify a token parameter.

Remote access

Awasu API remote access By default, access to the Awasu API is restricted to programs running on the same computer as Awasu. To allow access from other computers, open the Program Options, choose which network interfaces to allow access on and a port number to accept requests on.

Template response files

Most API calls return a response generated from a template file in the Resources/API sub-directory under the Awasu installation directory. The filename is usually derived from the name of the API call e.g. $/channels/list will look for a template file starting with channels-list.

The file extension is taken from the format parameter. Response template files for XML and JSON are supplied by default but new formats can be added by creating a new response template file with the appropriate extension, and then specifying that extension in the API call e.g. $/reports/list?format=txt will return a response generated from a file called reports-list.txt.

API parameters

All API calls take parameters, specified in the usual way as part of the HTTP request (key=val pairs in the URL). It is also possible to submit requests using an HTTP POST request, and specifying parameters in the POST data, as attributes of an <apiArgs> node, and/or key/value pairs in the node's CDATA. For example,

GET buildInfo?f=html&token=xyz
is equivalent to
POST buildInfo
<apiArgs f="html"> token=xyz </apiArgs>
This is the recommended way of submitting requests if you are using an API token.

Standard parameters

All API calls recognize the standard parameters described below.

token | API token. If a token has been set in the Program Options, it must be specified in each API call.
format (f) | Format to return the results in (usually xml or json). For API calls that return a response generated from a template file, this parameter is used to determine which template file to use (see above). The default format is usually xml.
responseTemplate (rt) | Response template filename. For API calls that return a response generated from a template file, this parameter is used to determine which template file to use (see above).
silent | Flags if a silent response (HTTP 204) should be returned. A "HTTP 204 No Response" will cause most browsers to stay on the current page, allowing links to be clicked with no visible effect.
Read more about...
  • Configuring the Awasu API
  • Writing your own response template files

[1] This means that most requests can be made by entering them in a browser's address bar.
[2] This can be changed in the Program Options
[3] Assuming you are sending the request to an Awasu running on the same computer, and it is accepting requests on the default port.


Channel operations

$/channels/list
Returns information about one or more channels.
Channels can be specified either by ID (recommended), by name, via channel filters, or channel folders.
Parameters:
id | Comma-separated list of channel ID's. Use * to return all channels.
name (n) | Comma-separated list of channel names. Use * to return all channels. Enable the regex switch to use regular expressions.
filter | Comma-separated list of channel filter names. Enable the regex switch to use regular expressions.
regex (re) | Flags if channel names and channel filter names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
folderId | Comma-separated list of channel folder ID's.
folderName | Comma-separated list of channel folder names.
subFolders | Flags if channels in sub-folders of a targeted folder should be returned. Only applies to the folderId and folderName parameters.
verbose (v) | Flags if verbose information should be returned about each channel.
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/get
Returns the summary page for a channel.
Any combination of ID (recommended), name and/or filter may be specified, but only one channel must match.
Parameters:
id | Channel ID.
name (n) | Channel name. Enable the regex switch to use regular expressions.
filter | Comma-separated list of channel filter names. Enable the regex switch to use regular expressions.
regex (re) | Flags if channel names and channel filter names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
showFeedItemsMode (sfim) | Controls which feed items will be shown (default|all|unread|new).
showFeedItemsWindow (sfiw) | Controls how many feed items will be shown (positive values are the number of days to go back, negative values are the number of feed items, 0 means "default").
feedItemDescriptionFormat (fidf) | Controls the presentation of feed item content (default|full|excerpt|plainText).
Note that a custom template can be specified via the responseTemplate parameter, or including the template as the POST data for the HTTP request.
$/channels/open
Opens one or more channels in Awasu.
Channels can be specified either by ID (recommended), by name, via channel filters or channel folders.
Parameters:
id | Comma-separated list of channel ID's. Use * to open all channels.
name (n) | Comma-separated list of channel names. Use * to open all channels. Enable the regex switch to use regular expressions.
filter | Comma-separated list of channel filter names. Enable the regex switch to use regular expressions.
regex (re) | Flags if channel names and channel filter names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
folderId | Comma-separated list of channel folder ID's.
folderName | Comma-separated list of channel folder names.
subFolders | Flags if channels in sub-folders of a targeted folder should be returned. Only applies to the folderId and folderName parameters.
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/create
Creates a new channel.
The channel configuration must be passed in as the POST data. See below for more details.
Parameters: None
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/update
Updates one or more channels.
Changes to the channel configuration must be passed in as the POST data. See below for more details.
Channels can be specified either by ID (recommended), by name, via channel filters, or channel folders.
Parameters:
id | Comma-separated list of channel ID's. Use * to update all channels.
name (n) | Comma-separated list of channel names. Use * to update all channels. Enable the regex switch to use regular expressions.
filter | Comma-separated list of channel filter names. Enable the regex switch to use regular expressions.
regex (re) | Flags if channel names and channel filter names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
folderId | Comma-separated list of channel folder ID's.
folderName | Comma-separated list of channel folder names.
subFolders | Flags if channels in sub-folders of a targeted folder should be returned. Only applies to the folderId and folderName parameters.
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/delete
Deletes one or more channels.
Channels can be specified either by ID (recommended), by name, via channel filters, or channel folders.
Parameters:
id | Comma-separated list of channel ID's. Use * to delete all channels.
name (n) | Comma-separated list of channel names. Use * to delete all channels. Enable the regex switch to use regular expressions.
filter | Comma-separated list of channel filter names. Enable the regex switch to use regular expressions.
regex (re) | Flags if channel names and channel filter names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
folderId | Comma-separated list of channel folder ID's.
folderName | Comma-separated list of channel folder names.
subFolders | Flags if channels in sub-folders of a targeted folder should be returned. Only applies to the folderId and folderName parameters.
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/errors
Gets the error log for one or more channels.
Channels can be specified either by ID (recommended), by name, via channel filters, or channel folders.
Parameters:
id | Comma-separated list of channel ID's. Use * to get the error log for all channels.
name (n) | Comma-separated list of channel names. Use * to get the error log all channels. Enable the regex switch to use regular expressions.
filter | Comma-separated list of channel filter names. Enable the regex switch to use regular expressions.
regex (re) | Flags if channel names and channel filter names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
folderId | Comma-separated list of channel folder ID's.
folderName | Comma-separated list of channel folder names.
subFolders | Flags if channels in sub-folders of a targeted folder should be returned. Only applies to the folderId and folderName parameters.
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/subscribe
Starts the Channel Wizard.
Parameters:
url (u) The feed URL to preload.
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/import
Starts the Import from dialog.
Parameters:
url (u) | The URL of the import file.
type (t) | The format being used to import channels. Currently only OPML is supported.
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/folders/tree
Returns information about the My Channels folders.
Parameters: None
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/folders/create
Creates a new My Channels folder.
Parameters:
name (n) | The name of the new folder.
parent (p) | The ID of the parent folder.
after (a) | The ID of the folder to insert the new folder after.
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/folders/delete
Deletes a My Channels folder.
Parameters:
id The ID of the folder to be deleted.
Use * to delete all folders.
The standard parameters recognized by all Awasu API calls are listed here.
$/channels/filters/list
Returns information about the channel filters.
Parameters:
verbose (v) Flags if verbose information should be returned about each channel filter.
The standard parameters recognized by all Awasu API calls are listed here.

Creating and updating channels

When creating a new channel, or updating existing ones, the channel configuration must be sent as the request's POST data. The format is the same as that returned by $/channels/list except that there is no top-level <channels> node. For example, the following POST request sent to $/channels/create will create a new channel:

<channel type="standard">
    <feedUrl> https://awasu.com/news.xml </feedUrl>
</channel>

Channel type

The type of channel is configured via the channel@type attribute:

  • To create a normal channel, simply specify the feed URL e.g.
    <channel type="standard">
    <feedUrl> https://awasu.com/news.xml </feedUrl>
</channel>
  • To create a plugin channel, specify the path to the plugin and optionally, any plugin parameter values e.g.
    <channel type="plugin">
    <pluginChannel path="{:INSTALL-DIR:}/Samples/python-channel2/sample_python_channel2.py">
        <param name="nItems"> 3 </param>
    </pluginChannel>
</channel>
  • To create a search channel, specify the query string and any other parameters e.g.
    <channel type="search">
    <searchQuery searchInUrls="no" searchInTitles="yes" searchInDescriptions="yes">
        query string
        <scoreCutoff> 25 </scoreCutoff>
    </searchQuery>
</channel>

Channel configuration

Most channel configuration is fairly straight-forward and values are configured via child nodes in the root <channel> node.

Basic channel details such as its name and description are usually specified by the publisher in the feed itself but can be overridden by the user e.g.

<channel type="standard">
    <name> ... </name>
    <description> ... </description>
    <homeUrl> ... </homeUrl>
</channel>

The channel summary page can be configured like this:

<channel type="...">
    <channelSummary compact="no" showItems="..." itemWindow="..." contentFormat="...">
        <templateFilename> {:INSTALL-DIR:}/Resources/Channel Summary Templates/Rusty.template </templateFilename>
    </channelSummary>
 </channel>
where:
  • showItems must be one of Default, All, Unread, New
  • itemWindow is either a number of items to show (negative values) or a number of days to go back (positive values)
  • contentFormat must be one of Default, Full, Excerpt, PlainText, None

Feed authentication

The username and/or password can be set for channels as follows:

<channel type="standard">
    <auth>
        <name> ... </name>
        <password> ... </password>
    </auth>
</channel>

To remove the authentication details from a channel, include an empty <auth> node:

<channel type="standard">
    <auth />
</channel>

Channel hooks

Channel hooks can be added to new or existing channels as follows:

<channel type="...">
    <channelHook path="...">
        <param name="..."> ... </param>   include as needed
    </channelHook>
</channel>

To update a hook that has already been attached to a channel, it must be identified by its ID. The hook itself cannot be changed and so only the display name and/or hook parameters may be altered.

To detach a hook from a channel, include a delete="yes" attribute e.g.

<channel type="...">
    <channelHook id="..." delete="yes" />
</channel>

Directory aliases

Any settings that include a directory path (e.g. template filename or output filename) can use one of the following directory aliases:

{:INSTALL-DIR:} | the Awasu installation directory
{:USER-DATA:} | the user's roaming data directory
{:USER-LOCALDATA:} | the user's local data directory
{:USER-OUTPUT:} | the user's My Documents folder
Read more about...
  • The Awasu API
  • Report operations
  • Workpad operations
  • Feed item operations
  • Search operations
  • Miscellaneous operations


Report operations

$/reports/list
Returns information about one or more reports.
Reports can be specified either by ID (recommended) or by name.
Parameters:
id | Comma-separated list of report ID's. Use * to return all reports.
name (n) | Comma-separated list of report names. Use * to return all reports. Enable the regex switch to use regular expressions.
regex (re) | Flags if report names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
verbose (v) | Flags if verbose information should be returned about each report.
The standard parameters recognized by all Awasu API calls are listed here.
$/reports/run
Runs one or more channel reports.
Reports can be specified either by ID (recommended) or by name.
Parameters:
id | Comma-separated list of report ID's. Use * to run all reports.
name (n) | Comma-separated list of report names. Use * to run all reports. Enable the regex switch to use regular expressions.
regex (re) | Flags if report names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
The standard parameters recognized by all Awasu API calls are listed here.
$/reports/get
Runs a channel report and returns the result.
Any combination of ID or name may be specified, but only one report must match.
Parameters:
id | Comma-separated list of report ID's.
name (n) | Comma-separated list of report names. regex switch to use regular expressions.
regex (re) | Flags if report names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
contentType (ct) | Response MIME type. If no MIME type is configured here, Awasu will attempt to auto-detect HTML, XML and plain-text.
The standard parameters recognized by all Awasu API calls are listed here.
$/reports/create
Creates a new channel report.
The report configuration must be passed in as the POST data. See below for more details.
Parameters: None
The standard parameters recognized by all Awasu API calls are listed here.
$/reports/update
Updates one or more channel reports.
Changes to the report configuration must be passed in as the POST data. See below for more details.
Reports can be specified either by ID (recommended) or by name.
Parameters:
id | Comma-separated list of report ID's. Use * to update all reports.
name (n) | Comma-separated list of report names. Use * to update all reports. Enable the regex switch to use regular expressions.
regex (re) | Flags if report names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
The standard parameters recognized by all Awasu API calls are listed here.
$/reports/delete
Deletes one or more channel reports.
Reports can be specified either by ID (recommended) or by name.
Parameters:
id | Comma-separated list of report ID's. Use * to delete all reports.
name (n) | Comma-separated list of report names. Use * to delete all reports. Enable the regex switch to use regular expressions.
regex (re) | Flags if report names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
The standard parameters recognized by all Awasu API calls are listed here.

Creating and updating channel reports

When creating a new report, or updating existing ones, the report configuration must be sent as the request's POST data. The format is the same as that returned by $/reports/list except that there is no top-level <channelReports> node. For example, the following POST request sent to $/reports/create will create a new report:

<channelReport>
    <name> My New Report </name>
    <dataSource type="channelFilter">
        <channelFilterName> All </channelFilterName>
    </dataSource>
</channelReport>

Report type

The type of report is configured via the dataSource@type attribute:

  • To create a report based on a channel filter, the POST data should include the following:
    <dataSource type="channelFilter" markItemsAsRead="yes" groupByChannel="yes" includeItems="new">
    <channelFilterName> ... </channelFilterName>
</dataSource>
    The includeItems attribute can be one of: All, New, Unread, None

  • To create a report based on channel folders, the POST data should include the following:
    <dataSource type="channelFolders" markItemsAsRead="yes" groupByChannel="yes" includeItems="all" includeSubFolders="no">
    <channelFolder id="..."> ... </channelFolder>
</dataSource>
    Channel folders can be specified either by ID or name.

    The includeItems attribute can be one of: All, New, Unread, None.

  • To create a report based on a workpad, the POST data should include the following:
    <dataSource type="workpad" markItemsAsRead="yes" removeItems="yes" runOnChange="no">
    <workpad id="..."> ... </workpad>
</dataSource>
    The workpad can be specified either by ID or name [1].

FTP, email and post-processing command

FTP, email and the post-processing command are configured via XML sub-nodes. For example, the following will update the TO address in an existing report's configuration:

<email>
    <toAddress> joe@blow.com </toAddress>
</email>

To remove the configuration from a report, simply include an empty XML node. For example, the following will remove any post-processing command:

<postProcessingCommand />

The report can be configured to check the post-processing command's return code as follows:

<postProcessingCommand>
    <returnCodes type="..."> ... </returnCodes>
</postProcessingCommand>

where a comma-separated list of return codes are specified and the type attribute can be one of: NoCheck, EqualTo, NotEqualTo

Template parameters

When updating an existing report, template parameters specified in the POST data are applied to any existing template parameters configured in the report i.e. they will update the parameter's value if it already exists, or create a new one if it doesn't.

To remove a template parameter from the report's configuration, include a delete="yes" attribute.

For example:

<templateParam name="param1"> value1 </templateParam>    create/update param1
<templateParam name="param2" />                          create/update param2 (empty value)
<templateParam name="param3" delete="yes" />             remove param3

Directory aliases

Any settings that include a directory path (e.g. template filename or output filename) can use one of the following directory aliases:

{:INSTALL-DIR:} | the Awasu installation directory
{:USER-DATA:} | the user's roaming data directory
{:USER-LOCALDATA:} | the user's local data directory
{:USER-OUTPUT:} | the user's My Documents folder
Read more about...
  • The Awasu API
  • Channel operations
  • Workpad operations
  • Feed item operations
  • Search operations
  • Miscellaneous operations

[1] Use @ for the default workpad.


Workpad operations

$/workpads/list
Returns information about one or more workpads.
Workpads can be specified either by ID (recommended) or by name.
Parameters:
id | Comma-separated list of workpad ID's. Use * to return all workpads or @ for the default workpad.
name (n) | Comma-separated list of workpad names. Use * to return all workpads or @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re) | Flags if workpad names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
items (i) | Flags if the feed items contained in each workpad should also be returned.
The standard parameters recognized by all Awasu API calls are listed here.
$/workpads/get
Returns the items in a workpad.
Workpads can be specified either by ID (recommended) or by name.
Parameters:
id | Workpad ID. Use @ for the default workpad.
name (n) | Workpad name. Use @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re) | Flags if workpad names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
notes | Flags if the user notes for each workpad item should be included.
The standard parameters recognized by all Awasu API calls are listed here.
$/workpads/feed
Returns the items in a workpad as a feed.
Workpads can be specified either by ID (recommended) or by name.
Parameters:
id | Workpad ID. Use @ for the default workpad.
name (n) | Workpad name. Use @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re) | Flags if workpad names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
notes | Flags if the user notes for each workpad item should be included.
The standard parameters recognized by all Awasu API calls are listed here.
$/workpads/addItem
Adds a feed item to one or more workpads.
If this request is sent as an HTTP POST, user notes can be passed in as the POST data.
Workpads can be specified either by ID (recommended) or by name.
Parameters:
id | Comma-separated list of workpad ID's. Use * to add to all workpads or @ for the default workpad.
name (n) | Comma-separated list of workpad names. Use * to add to all workpads or @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re) | Flags if workpad names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
url (u) | URL of the new feed item.
title (t) | Title of the new feed item.
The standard parameters recognized by all Awasu API calls are listed here.
$/workpads/clear
Clears one or more workpads.
Workpads can be specified either by ID (recommended) or by name.
Parameters:
id | Comma-separated list of workpad ID's. Use * to clear all workpads or @ for the default workpad.
name (n) | Comma-separated list of workpad names. Use * to clear all workpads or @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re) | Flags if workpad names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
The standard parameters recognized by all Awasu API calls are listed here.
$/workpads/create
Creates a new workpad.
The workpad configuration must be passed in as the POST data. The format is the same as that returned by $/workpads/list.
Parameters: None
The standard parameters recognized by all Awasu API calls are listed here.
$/workpads/update
Updates one or more workpads.
Changes to the workpad configuration must be passed in as the POST data. The format is the same as that returned by $/workpads/list.
Workpads can be specified either by ID (recommended), or by name.
Parameters:
id | Comma-separated list of workpad ID's. Use * to return all workpads or @ for the default workpad.
name (n) | Comma-separated list of workpad names. Use * to return all workpads or @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re) | Flags if workpad names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
The standard parameters recognized by all Awasu API calls are listed here.
$/workpads/delete
Deletes one or more workpads.
Workpads can be specified either by ID (recommended), or by name.
Parameters:
id | Comma-separated list of workpad ID's. Use * to return all workpads or @ for the default workpad.
name (n) | Comma-separated list of workpad names. Use * to return all workpads or @ for the default workpad. Enable the regex switch to use regular expressions.
regex (re) | Flags if workpad names should be interpreted as regular expressions. Special characters such as , and & can be hex-encoded e.g. \x2C or \x26 respectively).
The standard parameters recognized by all Awasu API calls are listed here.
Read more about...
  • The Awasu API
  • Channel operations
  • Report operations
  • Feed item operations
  • Search operations
  • Miscellaneous operations


Feed item operations

$/feedItems/open
Opens one or more feed items in Awasu.
Parameters:
id Comma-separated list of feed item ID's.
The standard parameters recognized by all Awasu API calls are listed here.
$/feedItems/get
Returns one or more feed items from Awasu's archive database.
The response can be either generated from a template file (e.g. feedItems-get.xml or feedItems-get.json), or as a report (either by passing in the ID of an existing report, or sending a report configuration in the POST data).
Parameters:
id | Comma-separated list of item ID's.
report (r) | ID of a report to generate the response with.
contentType (ct) | MIME type to return the response as.
The standard parameters recognized by all Awasu API calls are listed here.
$/feedItems/update
Updates one or more feed items.
Parameters:
id | Comma-separated list of feed item ID's.
read (r) | Flags if items should be marked as read or unread.
The standard parameters recognized by all Awasu API calls are listed here.
Read more about...
  • The Awasu API
  • Channel operations
  • Report operations
  • Workpad operations
  • Search operations
  • Miscellaneous operations


Search operations

$/search/query
Submits a query to Awasu's search engine.
If you submit a blank search request in HTML format (i.e. $/search/query?f=html), you will get a web page that will allow search queries to be submitted.
Parameters:
query (q) | Query string.
advsyn | Flags if the query string is using advanced syntax.
age | How old search results may be (days).
locations (l) | Comma-separated list of where to search (url|title|content).
max | Maximum number of results to return.
minScore (ms) | Minimum score for search results (0-100).
page (p) | Page number (1-based) to return (if results are being paginated).
pageSize (ps) | Number of results to show per page.
feedItemDescriptionFormat (fidf) | Controls the presentation of feed item content (default|full|excerpt|plainText).
The standard parameters recognized by all Awasu API calls are listed here.
Read more about...
  • The Awasu API
  • Channel operations
  • Report operations
  • Workpad operations
  • Feed item operations
  • Miscellaneous operations


Miscellaneous operations

$/buildInfo
Returns information about the current version of Awasu.
Parameters:
verbose (v) Flags if verbose information should be returned.
The standard parameters recognized by all Awasu API calls are listed here.
$/userInfo
Returns information about the user's Awasu installation.
Parameters: None
The standard parameters recognized by all Awasu API calls are listed here.
$/logs/activity
Returns the Awasu Activity log.
Parameters:
lines (l) The number of lines to return.
Use -1 to return the entire log.
The standard parameters recognized by all Awasu API calls are listed here.
$/logs/error
Returns the Awasu Error log.
Parameters:
lines (l) The number of lines to return.
Use -1 to return the entire log.
The standard parameters recognized by all Awasu API calls are listed here.
$/bringToFront
Brings the Awasu main window to the front.
Parameters: None
The standard parameters recognized by all Awasu API calls are listed here.
$/openInDefaultBrowser
Opens a URL in the default browser.
Parameters:
url (u) URL to open.
The standard parameters recognized by all Awasu API calls are listed here.
$/openUrl
Opens a URL in an Awasu browser tab.
Parameters:
url (u) URL to open.
The standard parameters recognized by all Awasu API calls are listed here.
Read more about...
  • The Awasu API
  • Channel operations
  • Report operations
  • Workpad operations
  • Feed item operations
  • Search operations


Keyboard interface

Awasu has been designed to let you browse as quickly as possible from the keyboard.

Here are some of the default keyboard commands. You can always change them from the Keyboard page of the Customize dialog.

F4 | Shows the My Channels window.
F10 | Opens the next channel in My Channels.
Ctrl-O | Opens the currently-selected channel, search agent or plugin.
Ctrl-U | Gets the latest feed for the current channel.
Ctrl-N | Starts the Channel Wizard.

F9 | Shows the current channel's summary page.
F7 | Shows or hides the item pane.
Ctrl-F7 | Resizes the item pane.
F8 | Opens the next feed item.
Shift-F8 | Opens the previous feed item.
F6 | Switches focus between panes.
Ctrl-F9 | Shows or hides the navbar.

Ctrl-Alt-A | Shows all feed items for the channel.
Ctrl-Alt-U | Shows only unread feed items for the channel.
Ctrl-Alt-N | Shows only new feed items for the channel.

Ctrl-Alt-L | Shows complete feed items for the channel.
Ctrl-Alt-E | Shows extracts of each feed item for the channel.
Ctrl-Alt-P | Shows each feed item as plain-text for the channel.

Ctrl-Shift-W | Adds a URL to the default workpad from the clipboard.
Ctrl-L | Shows the Channel Filters dialog.

Ctrl-F4 | Closes the current window.
F11 | Switches in and out of full-screen mode.
F1 | Shows the online help.
Read more about...
  • Customizing your keyboard shortcuts


File layout

Awasu stores your data in two parts, roaming data and local data.

These directories can be quickly located from the System page of the About box.

By default, the data files are stored in the following directories [1] [2] [3]:

  • Windows Vista/7/8/10/11, Server 2008-2022
    Roaming data | C:\Users\YOUR-NAME\AppData\Roaming\Awasu\
    Local data | C:\Users\YOUR-NAME\AppData\Local\Awasu\
  • Windows XP/2000, Server 2003
    Roaming data | C:\Documents and Settings\YOUR-NAME\Application Data\Awasu\
    Local data | C:\Documents and Settings\YOUR-NAME\Local Settings\Application Data\Awasu\
If you started using Awasu prior to version 2.2.5 (Feb 2007), user data was stored in the Users sub-directory under the Awasu installation directory and Awasu will continue to use these data files in their existing location. The file layout is identical to that described here except that the roaming data and local data directories are one and the same e.g. C:\Program Files (x86)\Awasu\Users\YOUR-NAME\.

Roaming data

If your computer administrator has enabled folder redirection for your account, the information Awasu stores in this directory will be available on any computer that you log into.

config.ini | Stores all your user settings, channel reports, channel filters, etc.
Channels/ | One .CHANNEL file is created in this directory for each channel you are subscribed to. The name of the file will be similar to the channel's feed URL.

While all your Awasu configuration options are stored in the CONFIG.INI file, GUI-related settings such as where your docking windows are positioned, toolbar customizations, etc. are stored in the Registry. These will roam if your site administrator has enabled roaming profiles for your account.

Local data

The information Awasu stores in this directory is only available on that particular computer and will not roam.

archive.db | Stores the archived content for all of your channels. It is safe to delete this file (when Awasu is not running) if you want to delete your archived content. Awasu will see that the file needs to be recreated and will automatically recreate all the other necessary associated files. Your channels and their settings will remain unchanged.
archive2.db | Records which items have been marked as read and the contents of your workpads. It is safe to delete this file (when Awasu is not running). Awasu will see that the file needs to be recreated and will automatically recreate it.
archive-offline.db | Stores feed items and images that have been downloaded for offline reading. It is safe to delete this file (when Awasu is not running) if you want to delete your offline content.
Index\ | A fast-lookup index of your archived content maintained so that Awasu can carry out searches quickly. It is safe to delete the contents of this directory (when Awasu is not running) if you want to delete the search index. Awasu will no longer return any results if you perform a search, although the index will continue to be updated with new feed content as it arrives. You can rebuild the search index for your archived content by running the Awasu Administration program and choosing Rebuild index.
Logs\ | Contains a copy of the last feed received for each of your channels. A copy of the Activity and Error Logs are also kept in this directory, in AwasuActivity.log and AwasuError.log. If you have turned on logging for Awasu, log messages will be recorded in Awasu.log.
Resources\ | Contains user-specific resources.

If you are ever asked to create a DEBUG.INI file (that controls debugging features inside Awasu), it should be created in this directory.
Read more about...
  • Changing where Awasu stores your data

[1] By default, Windows does not show the Application Data nor Local Settings nor AppData directories in Windows Explorer so you may have type these in yourself in the address bar.
[2] These directory paths may differ if you have installed Windows to a non-standard location or your administrator has redirected the folders to another location.
[3] If your computer administrator has changed the name of your account, the directory name here will not match the name you use to logon. The directory name will be the name of the account when it was first used.


Online resources

  • Awasu web site
  • Awasu News (weblog)
  • Frequently Asked Questions
  • Awasu Forums (ask questions here)
  • Extensions (download Awasu plugins, templates, and other goodies)


Copyright

Copyright © Awasu Pty. Ltd. 2002. All rights reserved.

Awasu and the stylized Japanese character in the orange box are trademarks of Awasu Pty. Ltd. Other brands and product names are trademarks of their respective owners. Awasu Pty. Ltd. believes the information in this publication is accurate as of its publication date. Such information is subject to change without notice. Awasu Pty. Ltd. is not responsible for inadvertent errors.