Reading KBnow articles is very much like reading messages in your email application. A grey "header" at the top of the pane shows date, author and subject information; the text of the article is shown in the rest of the window. KBnow supports both plain text and HTML email, so articles can contain rich formatting such as fonts, styles, tables, images, and so forth.

KBnow also supports email attachments such as spreadsheets and images. Attachments will appear below the text of the article, tagged with a grey "document" icon. Note that while viewing and storing of attachments is completely supported, KBnow cannot index text stored within binary file formats. Make sure that articles have sufficient body text to help users find the information they're looking for.

In most installations, KBnow is configured to monitor one or more email addresses, for example "kb@yourcompany.com". You can either email articles to these addresses directly or "CC" them on mail between team members. KBnow will automatically add any messages it receives to the knowledgebase. It is also common to add the KBnow email addresses to key internal distribution lists (also known as "aliases") where important topics are discussed. For example, if you have an alias that you use to distribute important human resources or technical information, you can add the KBnow address to that alias and automatically create a searchable archive of all messages sent to it!

In versions 20020724 and later, KBnow can fetch articles from "RSS" syndication feeds. These feeds are generated by most popular weblog or knowledgelog software, as well as by literally hundreds of news and information sources on the Internet. Internally, RSS can be used to aggregate individual knowledgelog entries into a centralized, permanent, searchable archive. Contact your administrator for assistance in connecting your weblog to KBnow.

There is also a "Post Article" link in the left pane of the web interface. You can use this link to submit an article from your browser. This can be used when you don't have access to an email client or if you've chosen not to enable email/rss monitoring.

Finally, advanced installations may choose to submit articles as text files directly to the indexing engine. See the "Advanced Topics" section for more information on this option.

(Versions 20020911 and later)

KBnow provides a very basic mechanism for editing articles, using the "edit article" link on the right side of the message header bar. Editing is done in KBnow's native RFC822/MIME format, which can be somewhat cryptic for messages with attachments or complex formatting. However, for most articles it works well. Take care with the "mime type" box, only alter this if you are sure you understand the ramifications.

Also on the right side of the header bar is a link labelled "remove from kb". You can use this link to remove incorrect, outdated or irrelevant articles from the knowledgebase. Because the knowledgebase is a team resource, this option is available to all users in a default installation. Be careful!

If your administrator has enabled distribution list functionality, KBnow can forward you a copy of each new article added to the knoweldgebase. Click the "Email Updates" link in the left pane, enter your email address and click "Subscribe". To stop receiving updates, return to the Email Updates page and choose Unsubscribe.

Under Linux, the daemon is started by running the command "ezkb", either manually from a shell or at system startup in an rc.local file. By default, KBnow will look for data files in the same directory where ezkb resides; this can be altered by specifying "-d configdir" on the command line, where "configdir" is the full path to a directory containing your config.xml file. KBnow creates a file "ezkb.pid" in the config directory with the currently-running process id; you can terminate the daemon by sending a TERM signal to this process, as in "kill -TERM `cat ezkb.pid`".

KBnow registers itself as a service under Windows, so it may be started and stopped from the Services Control Panel. If you would like to provide an alternative data directory under Windows, create a registry key HKEY_LOCAL_MACHINE\Software\SoftwarePoetry\ezkb\args. Under this key, create a REG_SZ value with the name "d" and the value a full path to a directory containing your config.xml file.

KBnow looks in the config directory as outlined above for a file "config.xml". This file tells KBnow how to behave --- what mailboxes to monitor, what port to listen on for web requests, and so forth. A simple but complete config.xml file is created during installation, so many users will never need to touch config.xml. For those who do, a cursory knowledge of xml is useful. Global settings appear as children of a <settings> node under the root <ezkb> node; an exhaustive list of options follows can be found under Advanced Configuration below.

NOTE: All changes to config.xml require the KBnow daemon to be restarted before they will take effect.

KBnow can monitor as many email accounts as are appropriate for your situation. KBnow looks in the <mailboxes> section of config.xml for each tag of type <mailbox>. A <mailbox> tag should have the following child elements:

<mailboxes>
     <mailbox>
          <server>mail.company.com</server>
          <login>kb</login>
          <password>samplepassword</password>
     </mailbox>
</mailboxes>

(Versions 20020724 and later)

RSS is an XML-based document format used to "syndicate" information on the Internet. RSS allows knowledge publishers to expose information in a structured way; an excellent overview and tutorial can be found at http://gils.utah.gov/rss/. KBnow can monitor any number of RSS feeds and integrate their contents into your permanent, searchable knowledgebase. You can draw content from relevant public weblogs, news headlines from sites such as moreover.com, or from internal "k-logs" or KnowledgeLogs maintained by your employees. K-logs can be a great way for employees to keep everyone updated about projects; KBnow is a great addition that adds aggregation, full-text search and a central repository.

KBnow looks in the <rss-feeds> section of config.xml for tags of type <rss-feed>. The <rss-feeds> tag should be a direct child of the <ezkb> tag. An <rss-feed> tag should have the following child elements:

<rss-feeds>
     <rss-feed>
          <url>http://www.slashdot.org/articles.rss</url>
     </rss-feed>
</rss-feeds>

RSS items are converted into an html email message format using the XSL stylesheet "fetch.xsl" in the web directory. You can alter the presentation of items by editing this file.

KBnow works the best with RSS feeds that contain full item text in their <description> or <fullitem> fields --- this gives KBnow the most text to index in the knowledgebase, and is the best choice if you're generating feeds from internal K-logs. However, it can still be very useful to integrate feeds that contain only abbreviated descriptions, or no description at all (for example, see the feed at slashdot.org). You can optimize your users' viewing experience by configuring KBnow to redirect to the original article, rather than the KBnow message file. Use the <rss-redirect-threshold> tag to specify a minimum description length that will cause the web interface to redirect to the original article. See the "config.xml" section of "Advanced Topics" for more details.

NOTE: KBnow tries to leverage the proposed <guid> item tag to identify unique items. However, some feeds that provide a <guid> tag erroneously change the tag over time, which can cause re-indexing of the same item multiple times. If you would like to index a feed that exhibits this problem, you can use the "force-content-match" attribute to disable use of the <guid> tag:

<rss-feed force-content-matching="yes">
     <url>http://www.scripting.com/rss.xml</url>
</rss-feed>

(Versions 20020724 and later)

You find an email list or rss feed that contains a mix of information, some which is relevant to your knowledgebase and some which is not. Keyword filtering allows you to archive and index only those articles that you care about. Filtering is accomplished by adding one or more <filter> tags underneath the <mailbox> or <rss-item> you want to filter. The filter tag has the following elements:

<rss-feed>
     ... normal rss feed tags omitted ...
     <filter>
          <text>James Dean</text>
     </filter>
</rss-feed>

<mailbox>
     ... normal mailbox tags omitted ...
     <filter match="all">
          <text>Web Services</text>
          <filter match="none">
               <text>SOAP</text>
          </filter>
     </filter>
</mailbox>

It may be useful to apply the same <filter> to more than one mailbox or feed. You can create a global filter by creating a <filters> tag under the root <ezkb> element and placing one or more <filter> tags within it. Give each <filter> in the <filters> section a "name" attribute. Then within the <mailbox> or <rss-feed> element, add a <use-filter> element with a matching "name" attribute. Be careful to close the <use-filter> tag properly!

<ezkb>
     <filters>
          <filter name="good-movies" match="any">
               <text>Breakfast at Tiffany's</text>
               <text>Joe Versus the Volcano</text>
               <text>Funny Face</text>
          </filter>
     </filters>
     ...
     <rss-feeds>
          <rss-feed>
               ...
               <use-filter name="good-movies" />
          </rss-feed>
     </rss-feeds>
</ezkb>

Note: filtering does not apply to articles posted from the web interface or directly submitted to the incoming directory (see "Submitting articles programmatically" under "Advanced Topics"). Articles submitted through these mechanisms will always be included in the knowledgebase.

(Versions 20020628 and later)

KBnow can easily be configured to forward new articles via email to a list of addresses. This feature on top of the permanent, searchable archive makes KBnow a great mailing list solution. Or just use the functionality so that members of your organization can see the latest updates without ever having to visit the web interface.

There are two steps to enabling distribution list functionality. First, add an <smtp-host> tag to the <settings> element of config.xml. The text of this tag should be the name of your email server, that KBnow can use to send outbound messages.

Next, copy and paste the following section into config.xml as a child of the root <ezkb> node:

<distribution-list>
     <list-address>kb@yourcompany.com</list-address>
     <list-name>KBnow distribution list</list-name>
     <reply-to-list>0</reply-to-list>
     <hide-subunsub-links>0</hide-subunsub-links>
     <subscribers>
          <address>ed@houseoffish.com</address> 
     </subscribers> 
</distribution-list>

Edit the text for your environment. Tags within the <distribution-list> element have the following meanings:

(Versions 20020702 and later)

While KBnow is most often used in a collaborative setting, it can be a great solution for one-way publishing as well. You can use the <read-only-webui> config.xml setting to remove editing functionality from the web interface. See the config.xml section for other values you can use to customize your installation.

If you would like to use KBnow to maintain a permanent, searchable archive of your Internet-based email newsletter, you may be eligible to receive a free unlimited license for KBnow. Contact us at sales@softwarepoetry.com for more information.

By default, KBnow installs itself with no authentication required. In many corporate environments, there is little need for user-level authentication for tools of this type. If you can reasonably avoid using authentication for KBnow, we encourage it, at least at first. KBnow is about removing barriers to important information. However, there are certainly circumstances in which authentication is critical.

If you would like to enable authentication, add an <authentication> element as a child of the root <ezkb> node. It is important to note that the simple presence of this tag, even if there are no users accounts defined, will cause the web interface to present a login dialog.

For each user, create a <user> tag, with the following child elements:

<authentication>
     <user>
          <login>steve</login>
          <password>6f1ed002ab5595859014ebf0951522d9</password> 
     </user> 
     <user> 
          <login>bob</login>
          <password>#mycleartextpassword</password> 
     </user> 
</authentication>

All article text and the full-text catalog are stored in a subdirectory "data" within the config directory. You should back up this data regularly to protect it from catastrophic failure. It is usually a good idea to back up the config.xml file as well.

Articles removed using the "remove" link on the web interface are deleted from the index, but the body of the article is not actually purged. Instead, it is moved to a subdirectory "removed" within the "data" directory. This is to protect against accidental data loss; simply move articles back to the "incoming" directory and they will be reindexed automatically.

We've tried hard to make KBnow simple to use and maintain. The same goes for uninstalling if you decide to do so. On Linux, simply stop the application, delete the files in the kbnow directory and you're finished. Under win32, run the command "ezkb -s remove" to delete the Service Control Manager entry, then delete the files in the kbnow directory.

Email is a great submission mechanism, and posting from the web interface is sufficient for one-off additions. However, it can be very useful to take information from external systems and index it within a KBnow knowledgebase. Just a few examples of this could be:

Any data that you can represent in text or html can be submitted to KBnow. Your scripts should place files into RFC822 format into the "incoming" subdirectory under the KBnow "data" directory. KBnow will automatically index all documents it finds in the incoming directory. RFC822 format implies that "header" information appears first in the file. Use the following template for your submissions:

Note that the "From" and "Subject" headers are important; they are used to populate the articles lists KBnow shows in the web interface. The "Content-Type" field tells KBnow if the article is in plain text (text/plain) or html (text/html) format. Finally, the blank line betwen the "header" information and the body is very important.

This is the standard format for Internet email messages. It is very easy to create from script; the possibilties for using KBnow as an information repository are significantly increased with this sort of integration.

KBnow exposes its query engine as a REST-style web service. Using this interface, you can easily integrate the results of KBnow queries within your other corporate applications. For example, your team portal could display the 10 most recent additions to a KBnow knowledgebase, or a web page describing an internal tool could automatically display links to the most relevant KBnow articles related to that tool. If members of your organization use a news aggregator, KBnow ships with support for returning results as an RSS feed.

<ezkb version="1.0"> 
     <item> 
          <id>7ea575af70a5bd2c0e57caa0d4dd568a</id> 
          <link>/form/show?id=7ea575af70a5bd2c0e57caa0d4dd568a</link> 
          <title>Some title</title> 
          <author>Some author</author> 
          <date>Mon Jun 17 09:05:49 2002</date> 
     </item> 
     ... 
</ezkb>

The KBnow web interface can be easily customized to fit your needs. Look in the config.xml section for settings you can use to perform minor customization.

You can also edit the web files directory to add corporate logos, links to other parts of your intranet, change the way articles are displayed, and so forth. However, be aware that performing too much customization may make it difficult to upgrade your copy of KBnow in the future. We will do our best to support customizations, but the responsibility for merging in new versions remains with you.

KBnow web support files are of three types: stock HTML files that are simply delivered to the client browser, XSL files that are used for executing transforms on native XML (see the web services section), and TMPL "template" files that have special meaning to the KBnow engine. The structure of all of them is sufficiently close to HTML that you should be able to do much of your customization with a working knowledge of markup. Just be careful of the {[ ]} tags in the TMPL files!

If you do customize your web files, it's probably a good idea to create copies of them rather than working directly on the files in the distribution. This makes it easy to "go back", and also allows you do have different customizations for different knowledgebase instances. When it starts up, KBnow does the following to determine which web files to use: