snellspace.com

Asbjørn Ulsberg: “How do I get hold of the necessary tools to produce a W3C specification?”

Good question. This fundamental issue is why I’m such a strong supporter of the IETF process (despite it’s various issues). The tools are available for anyone and everyone, with no admission fee.

Sam Ruby: “Another way to address this would be to jettison for the moment features which don’t yet enjoy consensus”

One of the key lessons my experience with the Atompub WG drove home was the notion that any idea the WG does not have enough collective experience to standardize shouldn’t be standardized, even if that does mean leaving big glaring holes that will need to be fixed at some point in the future.

Lotus Connections version 1.0.x publishes quite a few Atom feeds and uses a pre-RFC version of the Atom Publishing Protocol. The Atompub API in Lotus Connections will be updated to conform to RFC 5023 in version 2.0. In the meantime, I figured it would be good to talk a bit about the various extensions and conventions used for the Atom feeds and entries.

Let’s start with some basics. Connections consists of five components: Activities, Blogs, Communities, Dogear, and Profiles. Each component publishes a number of feeds that serve a variety of purposes. The entries in those feeds can represent a number of different things including activities, chats, emails, files, messages, todos, comments, blog entries, communities, bookmarks, profiles, etc. While each of the components and feeds provide a variety of different types of information, a common set of conventions and extensions are used across the entire suite.

Note: I apologize for the organization of these notes, which is, at times, rather sloppy.

The first thing to understand is how Entry Types are represented. Within most (but not all) atom:entry elements published by Lotus Connections, you will find a special atom:category element using the “http://www.ibm.com/xmlns/prod/sn/type” scheme. The term attribute on this category element specifies the type of entry. That can be, at most, one atom:category using the “http://www.ibm.com/xmlns/prod/sn/type” scheme per entry. The current allowable values for term are: activity, bookmark, chat, email, file, message, link, todo, community, feed, and profile. Future versions of LC may add additional values.

Each type of entry has it’s own requirements for various LC extension elements and special atom:category schemes.

Activity Entries

An “Activity Entry” represents an Activity… which, according to the documentation is an artifact that allows “a team to collect, organize, share, and reuse work related to a project goal.” For all practical purposes, an Activity is a discussion forum focused on a particular task. A variety of different types of messages can be posted to an Activity. As far as the Lotus Connections API is concerned, Activities are managed just like any other type of resource — that is, you can use the Atom Publishing Protocol to manage your Activities, you can subscribe to Atom feeds listing your Activities, etc. Activity entries are only used by the LC Activities component.

An Activity Entry can contain the following information:

atom:id

Unique identifier for the activity

atom:title

Activity name. Must be plain text

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/type” term=”activity”/>

Identifies this entry as being an “Activity”.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”private”/>

Identifies this activity as being “private”. If this category is not present, the activity is “public”. Can appear only once.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”completed”/>

Identifies this activity as being “complete”. If this category is not present, the activity is “incomplete”. Can appear only once.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”deleted”/>

Activities supports the notion of “soft-deletes”. When any item has been deleted, it can be restored or purged. If this category is present, the entry has been soft-deleted. Can appear only once.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”template”/>

Indentifies this entry as being an “Activity Template”, that is, an entry that is used to create new Activities. Can appear only once.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/priority” term=”value” label=”label”/>

Specifies the priority of this activity. The category term attribute MUST be a non-negative numeric value. The value “0″ indicates that the activity has been “tuned out”. The value “1″ indicates “Normal” priority. The value “1001″ indicates “Medium” priority. The value “2001″ indicates “High” priority. All other values are accepted but do not have any specified meaning and are considered “reserved” for future use. Can appear only once

<atom:category term=”tag_word”/>

Every atom:category element that does not have a scheme attribute is considered a “tag”. Any number of tags can be specified.

<atom:link rel=”edit” type=”application/atom+xml” href=”edit_url”/>

Atompub edit link. Can appear only once.

<atom:link rel=”http://www.ibm.com/xmlns/prod/sn/member-list” type=”application/atom+xml” href=”"/>

The “member-list” link points to an Atom Feed Document listing the members allowed to access or update the Activity. The member-list is an Atompub collection meaning you can use the Atompub protocol to manage access to the activity. Can appear only once.

<atom:link rel=”http://www.ibm.com/xmlns/prod/sn/history” type=”application/atom+xml” href=”xxxxx”/>

The “history” link points to an Atom Feed Document describing the change history of the Activity. This is a subscription only feed that provides a summary of what changes have been made. Can appear only once.

<atom:link rel=”self” type=”application/atom+xml” href=”xxxxx”/>

Provides a link to the Atom Feed Document for this activity. Can appear only once.

<atom:link type=”application/xhtml+xml” href=”xxxx”/>

Provides a link to the Activity HTML page. Can appear only once.

<app:collection href=”…”>

Atompub collection element that points to the Atompub collection for this Activity. Can appear only once.

<snx:icon xmlns:snx=”http://www.ibm.com/xmlns/prod/sn” >

Provides a link to an icon that depicts the status of this activity. The value of this element is an IRI (relative or absolute). Extraneous leading/trailing whitespace should be omitted from the value. Can appear only once. This element is meaningful in the feed, source or entry elements, any other use is undefined and will be ignored by LC.

<atom:content type=”html”>

The formatted description of the activity. Will always assume type=”html”.

<atom:summary>

Short summary of the activity. Will always assume type=”text”.

<atom:published>

The date the activity was created

<atom:updated>

The date the activity was last updated

<atom:author>

Identifies the person who created the entry

<atom:contributor>

Identifies the person who last modified the entry.

Note the use of the “http://www.ibm.com/xmlns/prod/sn/flags” category scheme. This is a fixed scheme used by a number of the Connections components to specify boolean-flag values. Any given flag can only appear once within an entry. Each type of entry will have it’s own set of flags relevant to that entry. The flags can also vary depending on the Connections component. The flags allowed for an Activity Entry are “private”, “completed”, “deleted” and “template”. All Activity entry types can contain the “private” and “deleted” flags.

Another thing to keep in mind in the fact that Lotus Connections 1.0.x is based on a pre-RFC version of the Atom Publishing Protocol, so there are some discrepencies in the use of Atompub elements relative to RFC5023.

Bookmark Entries

A Bookmark entry is used by the Connections Activities, Communities and Dogear components to represent a link to another resource.

<atom:id>

The unique identifier of the bookmark

<atom:title>

Title for the bookmark. Will always be type=”text”.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/type” term=”bookmark”/>

Identifies this entry as a bookmark. Must appear exactly once.

<atom:category term=”tag_word”/>

Every atom:category element that does not have a scheme attribute is considered a “tag”

<atom:link href=”link_url”/>

e URL that the bookmark refers to. Must appear exactly once.

<atom:link rel=”edit” type=”application/atom+xml” href=”edit_url”/>

The Atompub edit link for this entry. Can appear only once.

<atom:content type=”html”>

HTML formatted description of the bookmark. May be empty.

<atom:published>

The date this entry was created

<atom:updated>

The date this entry was last modified

<atom:author>

The author of this entry

<atom:contributor>

In Activities, identifies the person who last modified the entry.

When used within the Activities component, the Bookmark entry may contain a “private” flag (<category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”private”/>) indicating that the bookmark is only visible to the creator. If not present, the bookmark is considered to be “public”. The bookmark entry can also contain exactly one thr:in-reply-to element identifying either the Activity to which the bookmark has been posted or another message to which the bookmark entry is a reply, and exactly one snx:icon element specifying a URL to an icon depicting the entry type.

When used within the Commmunities component, the Bookmark entry may contain an “important” flag (<category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”important”/>) indicating that the bookmark will appear as an “Important” link on the Communities homepage.

When used within the Dogear component, the Bookmark entry may contain a “private” flag (<category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”private”/>) and an “internal” flag (<category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”internal”/>). The “internal” flag is used to indicate whether the bookmark is linking to a resource inside an organizations protected internal network (Dogear will detect this automatically based on how it is configured).

Dogear bookmarks can also contain the following:

<link rel=”http://www.ibm.com/xmlns/prod/sn/same” type=”application/atom+xml” href=”same_url_feed”>

Points to an Atom Feed Document (subscription only) that lists other bookmarks pointing to the same resource. Can appear only once.

<snx:clickcount xmlns:snx=”http://www.ibm.com/xmlns/prod/sn” >

Dogear tracks the number of times a bookmark has been clicked via the browser UI. This element appears only once and is only meaningful within a Bookmark entry.

Chat Entries

A Chat entry is an Activities-only entry that represents an instant-messaging chat transcript.

<atom:id>

Unique identifier of a chat node

<atom:title>

The title of the chat. Always type=”text”

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/type” term=”chat”/>

Identifies this entry as a chat. Must appear exactly once.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”private”/>

Flag indicating this as a private entry

<atom:category term=”tag_word”/>

Every atom:category without a scheme attribute is considered a “tag”

<atom:link rel=”edit” type=”application/atom+xml” href=”…”/>

The atompub edit uri of this entry. Can appear only once.

<thr:in-reply-to type=”application/atom+xml” href=”parent_url”/>

Points to either the Activity this chat is a member of or an entry this chat post is a reply to. Can appear only once.

<atom:link rel=”alternate” type=”text/html” href=”…”/>

Use this URL to obtain a HTML representation of this chat node suitable for display in a browser. Can appear only once.

<atom:content type=”html”>

The formatted text content of the chat.

<atom:published>

The date this entry was created

<atom:updated>

The date this entry was last modified

<atom:author>

Identifies the person who created the entry

<atom:contributor>

Identifies the person who last modified the entry.

<snx:icon xmlns:snx=”http://www.ibm.com/xmlns/prod/sn” >

URL to an icon that visually indicates the entry type. The value of this element is an IRI (relative or absolute). Extraneous leading/trailing whitespace should be omitted from the value. Can appear only once. This element is meaningful in the feed, source or entry elements, any other use is undefined and will be ignored by LC.

Email Entries

An Email entry is an Activities-only entry that represents an email.

<atom:id>

Unique identifier of an email entry

<atom:title>

The title of the email. Always type=”text”

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/type” term=”email”/>

Identifies this entry as an email. Must appear exactly once.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”private”/>

Flag indicating this as a private entry

<atom:category term=”tag_word”/>

Every atom:category without a scheme attribute is considered a “tag”

<atom:link rel=”edit” type=”application/atom+xml” href=”…”/>

The atompub edit uri of this entry. Can appear only once.

<thr:in-reply-to type=”application/atom+xml” href=”parent_url”/>

Points to either the Activity this email is a member of or an entry this email post is a reply to. Can appear only once.

<atom:link rel=”alternate” type=”text/html” href=”…”/>

Use this URL to obtain a HTML representation of this email suitable for display in a browser. Can appear only once.

<atom:content type=”html”>

The formatted text content of the email.

<atom:published>

The date this entry was created

<atom:updated>

The date this entry was last modified

<atom:author>

Identifies the person who created the entry

<atom:contributor>

Identifies the person who last modified the entry.

<snx:icon xmlns:snx=”http://www.ibm.com/xmlns/prod/sn” >

URL to an icon that visually indicates the entry type. The value of this element is an IRI (relative or absolute). Extraneous leading/trailing whitespace should be omitted from the value. Can appear only once. This element is meaningful in the feed, source or entry elements, any other use is undefined and will be ignored by LC.

File Entries

A File entry is an Activities-only entry that represents an file uploaded to the Activity

<atom:id>

Unique identifier of a chat node

<atom:title>

The title of the chat. Always type=”text”

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/type” term=”file”/>

Identifies this entry as a file. Must appear exactly once.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”private”/>

Flag indicating this as a private entry

<atom:category term=”tag_word”/>

Every atom:category without a scheme attribute is considered a “tag”

<atom:link rel=”edit” type=”application/atom+xml” href=”…”/>

The atompub edit uri of this entry. Can appear only once.

<thr:in-reply-to type=”application/atom+xml” href=”parent_url”/>

Points to either the Activity this file is a member of or an entry this file post is a reply to. Can appear only once.

<atom:link rel=”alternate” type=”text/html” href=”…”/>

Use this URL to obtain a HTML representation of this chat node suitable for display in a browser.

<atom:link rel=”enclosure” type=”…” href=”…”/>

URL used to retrieve the file

<atom:link type=”mime_type” href=”xxxxx”/>

Alternative link that can be used to retrieve the file.

<atom:summary>

A short description of the file. Assumed to be type=”text”

<atom:published>

The date this entry was created

<atom:updated>

The date this entry was last modified

<atom:author>

Identifies the person who created the entry

<atom:contributor>

Identifies the person who last modified the entry.

<snx:icon xmlns:snx=”http://www.ibm.com/xmlns/prod/sn” >

URL to an icon that visually indicates the entry type. The value of this element is an IRI (relative or absolute). Extraneous leading/trailing whitespace should be omitted from the value. Can appear only once. This element is meaningful in the feed, source or entry elements, any other use is undefined and will be ignored by LC.

Message Entries

An Message entry is an Activities-only entry that represents a simple post.

<atom:id>

Unique identifier of a message entry

<atom:title>

The title of the message. Always type=”text”

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/type” term=”message”/>

Identifies this entry as a message. Must appear exactly once.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”private”/>

Flag indicating this as a private entry

<atom:category term=”tag_word”/>

Every atom:category without a scheme attribute is considered a “tag”

<atom:link rel=”edit” type=”application/atom+xml” href=”…”/>

The atompub edit uri of this entry. Can appear only once.

<thr:in-reply-to type=”application/atom+xml” href=”parent_url”/>

Points to either the Activity message is a member of or an entry this message post is a reply to. Can appear only once.

<atom:link rel=”alternate” type=”text/html” href=”…”/>

Use this URL to obtain a HTML representation of this message suitable for display in a browser. Can appear only once.

<atom:content type=”html”>

The formatted text content of the message.

<atom:published>

The date this entry was created

<atom:updated>

The date this entry was last modified

<atom:author>

Identifies the person who created the entry

<atom:contributor>

Identifies the person who last modified the entry.

<snx:icon xmlns:snx=”http://www.ibm.com/xmlns/prod/sn” >

URL to an icon that visually indicates the entry type. The value of this element is an IRI (relative or absolute). Extraneous leading/trailing whitespace should be omitted from the value. Can appear only once. This element is meaningful in the feed, source or entry elements, any other use is undefined and will be ignored by LC.

Related Activity Entries

An Related Activity entry is an Activities-only entry that represents a reference to another Activity. These are essentially identical to Activity entry types but with <atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/type” term=”link”/>. The Related Activity entry can contain exactly one <thr:in-reply-to type=”application/atom+xml” href=”parent_url”/> element that points to either the Activity this email is a member of or an entry this email post is a reply to.

Todo Entries

An Todo entry is an Activities-only entry that represents a simple post.

<atom:id>

Unique identifier of a message entry

<atom:title>

The title of the message. Always type=”text”

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/type” term=”todo”/>

Identifies this entry as a task. Must appear exactly once.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”private”/>

Flag indicating this as a private entry

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/flags” term=”completed”/>

Flag indicating this as being completed.

<atom:category term=”tag_word”/>

Every atom:category without a scheme attribute is considered a “tag”

<atom:link rel=”edit” type=”application/atom+xml” href=”…”/>

The atompub edit uri of this entry. Can appear only once.

<thr:in-reply-to type=”application/atom+xml” href=”parent_url”/>

Points to either the Activity message is a member of or an entry this message post is a reply to. Can appear only once.

<atom:link rel=”alternate” type=”text/html” href=”…”/>

Use this URL to obtain a HTML representation of this message suitable for display in a browser. Can appear only once.

<atom:content type=”html”>

The formatted text content of the message.

<atom:published>

The date this entry was created

<atom:updated>

The date this entry was last modified

<atom:author>

Identifies the person who created the entry

<atom:contributor>

Identifies the person who last modified the entry.

<snx:icon xmlns:snx=”http://www.ibm.com/xmlns/prod/sn” >

URL to an icon that visually indicates the entry type. The value of this element is an IRI (relative or absolute). Extraneous leading/trailing whitespace should be omitted from the value. Can appear only once. This element is meaningful in the feed, source or entry elements, any other use is undefined and will be ignored by LC.

<snx:assignedto xmlns:snx=”http://www.ibm.com/xmlns/prod/sn” >

Email address of the person this task is assigned to.

General Activities Extensions

All entries in the Activities component can have the following:

<snx:permissions xmlns:snx=”http://www.ibm.com/xmlns/prod/sn”>

A comma-separated list of permissions the requesting user has for the specified item. Every Activities feed is customized for the requesting user; none of the feeds are publicly cacheable. The permissions element can appear within atom:feed and atom:entry and is meaningless outside the Connections Activities component. It can appear exactly once within any of the Activities entries or feeds.

<link rel=”http://www.ibm.com/xmlns/prod/sn/service” type=”application/atomsvc+xml” href=”…” />

Points to the Atompub Service Document. Can appear exactly once in the atom:feed element

<os:totalResults>

OpenSearch totalResults element indicating the total number of entries in the feed. Can only appear within the atom:feed element.

<snx:activity>

Specifies the application-specific unique identifier of the activity to which the entry belongs. Is only meaningful within atom:entry elements and within the Activities component. Can appear only once.

<snx:position xmlns:snx=”http://www.ibm.com/xmlns/prod/sn”>

Application-specific element. Can appear only once, only meaningful to the Activities component in atom:entry. Value must be non-negative integer.

<snx:depth xmlns:snx=”http://www.ibm.com/xmlns/prod/sn”>

Application-specific element. Can appear only once, only meaningful to the Activities component in atom:entry. Value must be a non-negative integer.

Blog Entries

The Lotus Connections Blog component supports three types of entries: Blog posts, Media entries and Blog comments. Media entries are basic Atompub Media Link entries with no special extensions. Blog comments are simple atom:entry elements with no special extensions.

Blog posts can contain an app:control element containing a single <snx:comments days=”n” enabled=”yes|no” /> element that indicates whether or not comments are enabled on the entry. The days attribute is a non-negative integer specifying the number of days comments will be supported. The value “0″ indicates that the configured default should be used. The enabled attribute is self explanatory.

Community Entries

A “Community” entry is specific to the Connections Communities component.

<atom:id>

Unique identifier of a Community Entry

<atom:title>

Community title. type=”text” assumed.

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/type” term=”community”/>

Identifies an Community entry. Must appear exactly once.

<atom:category term=”tag_word”/>

Repeat for each community tag

<atom:link rel=”self” href=”…”/>

Link to the Community Atom feed

<atom:link rel=”edit” type=”application/atom+xml” href=”edit_url”/>

Atompub edit link.

<atom:link rel=”alternate” type=”text/html” href=”…”/>

Use this URL to obtain a HTML representation of this Community Entry suitable for display in a browser.

<atom:link rel=”http://www.ibm.com/xmlns/prod/sn/logo” href=”…”/>

Use this URL to obtain an image that represents the Communities’ logo.

<atom:link rel=”http://www.ibm.com/xmlns/prod/sn/member-list” type=”application/atom+xml” href=”…”/>

This link references the list of Community members.

<atom:link rel=”http://www.ibm.com/xmlns/prod/sn/bookmarks” type=”application/atom+xml” href=”…”/>

This link references the Community’s list of bookmarks.

<atom:link rel=”http://www.ibm.com/xmlns/prod/sn/feeds” type=”application/atom+xml” href=”…”/>

This link references the Community’s list of subscriptions to feeds.

<snx:membercount xmlns:snx=”http://www.ibm.com/xmlns/prod/sn”>

Contains the number of members of this community. Can appear with atom:feed and atom:entry elements. Value must be non-negative integer

<snx:communityType xmlns:snx=”http://www.ibm.com/xmlns/prod/sn”>

Indicates whether community is public (visible to all users) or private. Allowed values are “public” and “private”. Can appear within atom:feed and atom:entry elements.

<atom:content type=”html”>

A description of this community; may be empty

<atom:summary type=”text”>

A plain text summary of the description of this community; provided in feeds instead of the full description

<atom:published>

The date this entry was published, as defined in the Atom specification.

<atom:updated>

The date this entry was updated, as defined in the Atom specification.

<atom:author>

The author of this community, as defined in the Atom specification.

Profile Entries

A Profile entry represents a profile record.

<atom:id>

Unique identifier of a profile

<atom:title>

The name of the user this profile represents

<atom:category scheme=”http://www.ibm.com/xmlns/prod/sn/type” term=”profile”/>

Identifies a profile entry. Must appear exactly once.

<atom:category term=”tag_word”/>

Repeat for each profile tag

<atom:link rel=”related” type=”text/html” href=”html_view”>

A link to an HTML formatted view of this profile

<atom:link rel=”alternate” type=”text/directory” href=”vcard_view”>

A link to VCARD formatted view of this profile

<atom:summary type=”text”>

A summary text description of this profile

<atom:content type=”type”>

When type=”xhtml”, this element contains a hCard formatted representation of this profile. When type=”text”, this element contains a VCARD representation of this profile. Only type=”text” is supported for input.

<atom:updated>

The date this entry was updated, as defined in the Atom specification.

Other Stuff

Across all of the Connections components, atom:links with rel=”http://www.ibm.com/xmlns/prod/sn/tag-cloud” point to Atompub Categories Documents that contain a listing of atom:category elements. Each atom:category element will contain a snx:frequency attribute whose value is a non-negative integer indicating the number of times the tag has been used.

Each of the components generally support the OpenSearch totalResults, startIndex and itemsPerPage and elements.

Generally speaking, all of the snx: elements are allowed to appear only once within either atom:feed, atom:entry or atom:source. The snx:comments element is only allowed within app:control, and must appear only once. The snx:frequency attribute is only meaningful within atom:category elements that have no scheme attribute.

Also, with the exception of snx:comments and snx:communityType elements, pretty much all of the snx: elements are generated by the server and are used for informational purposes only. Clients that do not understand those elements can still utilize the feeds and entries.

The Connections specific category schemes are also optional, however, not using them will imply default values that may not be intended by clients.

All atom:title and atom:summary elements are assumed to be type=”text”. atom:content elements can be type=”text|html|xhtml” depending on the component.

The atom:generator element is used in atom:feed and app:service elements to identify the version of Lotus Connections being used.

FYI… I’ve started including adsense ads in my individual entry pages.

Joe Gregorio: “I’ve submitted the next version of the URI Templating specification”

Spec here. Track status here.

I’ve updated my Java implementation and have merged it into the Abdera trunk. The implementation goes one step beyond Joe’s current draft to enable IRI Templates.

There are a couple of different ways to expand a template. For example, here we use an ordinary Java object.

  // immutable and threadsafe
  private static final Template template =
    new Template("http://example.org{-opt|/~|user}{user}{-opt|/-/|categories}{-listjoin|/|categories}{-opt|?|foo,bar}{-join|&|foo,bar}");

  // matches public fields and getters on the object to varnames in the template, e.g. getUser(), getCategories(), isBar(), etc
  MyObject myObject = new MyObject();
  System.out.println(template.expand(myObject));

The implementation will continue to evolve as the URI Template spec evolves.