An ActivityStream Implementation - feedback please

[Jonathan Dugan]

Hi All--

We recently deployed ActivityStreams to the beta site for
LegalTorrents. This site is built using Ruby on Rails, and the plan
is to release the full code and tests as a plugin after the next few
weeks once we complete the remaining features, integrate feedback from
the DISO community, and fix any bugs. I'm CC'ing Rama McIntosh who
designed and implemented most of this.

We would very much appreciate any feedback/ criticism/ suggestions/
thoughts people have on the design and if what we put out to the
community will work with other implementations and systems.

Attached are the Rails migrations that generate the data models (in
Ruby) and some initial dev data we used for testing, and one model
showing some logic. Not attached here are the views, the controllers,
the rest of the models, and the tests - all of which are done in Ruby.

Describing how we did it in English: - we made an ActivityStream class
to store the activities, and a class for the definitions: a "template"
for each stored Activity. Definitions consist of a selection from
each of 2 typed data dictionaries, an Actor, an Object, and the
"Controller/Action" pair, and a code template for the human readable
rendered string.

Specifically, each ActivityStream Definition has 6 things:
1- Actor - where to get the Class and id doing the action
2- Object - where to get the Class and id of the social thing
3- "Controller/Action" - the Rails controller (the class) and method
called when the activity is done

4- The first typed class is a local dictionary of verbs, and provide
the human-readable text for how we display each action. These verbs
correspond almost 1-1 a Definition, except in cases where there are
more than one way to accomplish the same effect on the site, in which
case the same verb is used in different definitions (because then the
definition has a different controller and method, a different place in
the code that performs the same human "verb".)

5- The second typed class is a local dictionary of "activities" used
for groupings and statistics throughout the site. For example
following and not following a Content Creator are part the same
"activity", and (see below) using statistics one has a +1 for following
and the other a -1 for following on statistics for the social object.

6- The "hr_string" stands for human-readable string: it is a code
snippet that gets evaluated for each logged activity, in the local
variable scope, to create the HTML used when rendering that activity.

Verbs, Activities and definitions are defined in migration 063.

Every Activity logged on the site is defined by one activity
definition.

The actual activities are defined in a separate table defined in
migration 064. The logs the actor, the object, the definition of the
activity, a count of how many times we've recently seen that activity,
and the rendered HTML for the action. Right now the count is not
being used, but we're doing that soon. It will prevent multiple
identical activities from being printed - instead login a new activity
will allow the rendered string to become: "Actor did verb Object (XX
times)".

There are also statistic definitions and statistics (065 and 066)
which (in a similar way to activity definitions and activities) define
a pattern to calculate (against a definition) and then to record (for
each activity class) each time an activity is generated. You can see
the migrations for the data model.

Finally, for preferences, we opted for 2 things: having all the
ActivityStreams turned on (published) initially for each user, and to
give the user a significant amount of control over where their
activities were published. Preferences are a matrix of activity
definitions vs outputs. Current (3) outputs include the LegalTorrents
public site, logged in users on the site, and their personalized Atom
feed.

Several screenshots are linked below as well. Signups are open on the
LegalTorrents beta still, so please try it out if you can!

The near future plan includes:

1-
Using count to remove identical (and very similar) activities and
replace with "counted" ones, like did that 6 times.

2-
Giving the Actor the ability to "X" out a single Activity which will
remove it from being published anywhere.

3-
Additional outputs for the ActivityStream - Facebook, Twitter,
FriendFeed, others? suggestions welcome!

4-
Getting as much feedback as possible from our own community members
and from other people making DISO activity stream systems and making
changes so the code works well with others

And then we plan on publishing and maintaining all the code as a Rails
Plugin under a good community-friendly OSI license (bsd-ish or
similar).

Regards,
Jonathan

--

Jonathan Dugan, PhD
Matson Systems, Inc.
(650) 799-5369
http://www.matsonsystems.com

Current ScreenShots:

Listing activity_stream_definitions
http://208.69.42.194/scpfiles/1217828319.jpg

New activity_stream_definitions
http://208.69.42.194/scpfiles/1217828768.jpg

Editing an activity_stream_definition
http://208.69.42.194/scpfiles/1217828826.jpg

Defined activity_stream_definition
http://208.69.42.194/scpfiles/1217828359.jpg

Activity listing on a content page
... on http://beta.legaltorrents.com/torrents/146-ghosts-i-iv
http://208.69.42.194/scpfiles/1217828538.jpg

Activity Listings on a User page
http://208.69.42.194/scpfiles/1217828573.jpg

ActivityStream Preferences
http://208.69.42.194/scpfiles/1217828630.jpg

A User's rendered Atom feed of their Activities
http://208.69.42.194/scpfiles/1217829126.jpg
and raw...
http://208.69.42.194/scpfiles/1217829174.jpg

Admin / Debug Screen showing a list of activities
http://208.69.42.194/scpfiles/1217828219.jpg

# Copyright 2007-2008 (c) by Matson Systems, Inc. All rights reserved.
#
# This software is the confidential and proprietary information
# of Matson Systems, Inc. This software may not be used for any
# purpose without prior written permission from Matson Systems, Inc.
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied. See the License for the specific language governing
# permissions and limitations under the License.

[Stephen Paul Weber]

> We recently deployed ActivityStreams to the beta site for
> LegalTorrents. This site is built using Ruby on Rails, and the plan
> is to release the full code and tests as a plugin after the next few
> weeks once we complete the remaining features, integrate feedback from
> the DISO community, and fix any bugs. I'm CC'ing Rama McIntosh who
> designed and implemented most of this.

First, the basics. Why is the activity stream presented as a table?
Is it somehow tabular data and I'm just missing it?
Second: microformats. hAtom (with hCard for item authors, as is
normal in hAtom) for sure.
Third: be POSH. Mark up the activity verb with its own tag at the
very least - preferably give it some semantic class name (like
"activity" or "verb" - can't remember what I use on my plugin output)

--
Stephen Paul Weber, @singpolyma
Please see <http://singpolyma.net> for how I prefer to be contacted.

[Steve Ivy]

+1 to Stephen's comments. As well, you might take a look at the output
from the wordpress plugin [1] and the config.yaml [2] shared by the
ordpress and movabletype implementations.

--Steve

[1] http://code.google.com/p/diso/source/browse#svn/wordpress/wp-diso-actionstream/trunk%3Fstate%3Dclosed
[2] http://code.google.com/p/diso/source/browse/wordpress/wp-diso-actionstream/trunk/config.yaml

--
Steve Ivy
http://redmonk.net // http://diso-project.org
This email is: [ ] bloggable [x] ask first [ ] private

[chris....@gmail.com]

Jonathan, this is great -- hopeful that this concrete works helps move
this discussion forward!

I second Stephen and Steve's suggestions, but think we can address
output semantics once we take more time to consider your overall
approach and architecture. That is, unless it's flawless and all
that's left is markup! ;)

Hopefully we can provide you with deeper feedback, and discuss the
Action Streams plugins and why they're designed as they are and how
they could be improved,

Jonathan -- have you reviewed the existing plugins? Any thoughts to
the use of the YAML config file?

Chris

--
Chris Messina
Citizen-Participant &
Open Source Advocate-at-Large
factoryjoe.com # diso-project.org
citizenagency.com # vidoop.com
This email is: [ ] bloggable [X] ask first [ ] private

[face]

Stephen Paul Weber wrote:
>> We recently deployed ActivityStreams to the beta site for
>> LegalTorrents. This site is built using Ruby on Rails, and the plan
>> is to release the full code and tests as a plugin after the next few
>> weeks once we complete the remaining features, integrate feedback from
>> the DISO community, and fix any bugs. I'm CC'ing Rama McIntosh who
>> designed and implemented most of this.
>>
>
> First, the basics. Why is the activity stream presented as a table?
> Is it somehow tabular data and I'm just missing it?
> Second: microformats. hAtom (with hCard for item authors, as is
> normal in hAtom) for sure.
> Third: be POSH. Mark up the activity verb with its own tag at the
> very least - preferably give it some semantic class name (like
> "activity" or "verb" - can't remember what I use on my plugin output)
>
>

Hi Stephen,

Thanks for the feed back. The table is simply to store the
activities. The output is either to render them on our own site,
or, publish them as an Atom feed. For now, we are simply rendering
basic Atom but the goal is to have it be hAtom compliant. Here
is a sample of the existing basic Atom stream:

http://beta.legaltorrents.com/feeds/your_activities/37795c644583b6cb18b5f7cb034b08d6bcfca9b8

Based on your feedback I see I need to make the above Atom stream
hAtom compliant and add a verb tag to the Atom stream. (Please let me know
If I missed something.)

Thanks again,
-Rama McIntosh
ra...@matsonsystems.com || fac...@gmail.com

[Stephen Paul Weber]

> Thanks for the feed back. The table is simply to store the
> activities. The output is either to render them on our own site,
> or, publish them as an Atom feed. For now, we are simply rendering
> basic Atom but the goal is to have it be hAtom compliant. Here
> is a sample of the existing basic Atom stream:
>

> Based on your feedback I see I need to make the above Atom stream
> hAtom compliant and add a verb tag to the Atom stream. (Please let me know
> If I missed something.)

Having some sort of POSH tag ("verb tag") in the ATOM could be cool.
I think you misunderstand about the hAtom - hAtom goes in your HTML,
it's a microformat. Same with the table question. If data is not
tabular, it should not be in an HTML table. I recommend <ol>

[face]

Stephen Paul Weber wrote:
> Having some sort of POSH tag ("verb tag") in the ATOM could be cool.
> I think you misunderstand about the hAtom - hAtom goes in your HTML,
> it's a microformat. Same with the table question. If data is not
> tabular, it should not be in an HTML table. I recommend <ol>
>
>

Yes I did misunderstand. So to answer your original question,
the rendered activities in our site are in a table because the
engineer on the team responsible to code the view has not begun
work on the views yet. I put it in a table because it is a quick
and dirty way to prototype a view.

I am new to microformats and read about using hCard embedded in
Atom. I was focusing on the Atom feed being useful for a user
to render their activities in a third website (i.e. render your
Legaltorrents activities on your Wordpress page).

But you have opened my eyes to a completely missing feature of our
activity stream... embedding the hCard in our html for firefox
plugins and the like.

So this brings up a couple questions:

1) Is there a plan to have a specification of a pure XML stream
of activities like our Atom feed (in addition to a specification for
the hAtom cards embedded in a html page)?

2) What is the minimum set of properties/fields in hCard I need to
include in my html or Atom stream?

Thanks,
-Rama McIntosh

[Stephen Paul Weber]

> 1) Is there a plan to have a specification of a pure XML stream
> of activities like our Atom feed (in addition to a specification for
> the hAtom cards embedded in a html page)?

I think that the steps we need to get there are kind of what the
discussion on this list are about :)

> 2) What is the minimum set of properties/fields in hCard I need to
> include in my html or Atom stream?

So, your hAtom itself needs to include just the required properties (I
believe they are title, entry-content, and published/updated - I could
be wrong though). Your hCards are just for the author (mostly) so will
probably just be fn, fn and n, or fn n and url. That's what mine are.
Then for relevant things I sometimes use other microformats (if the
action is about a song, I use hAudio, for instance). Then in both the
HTML *and* the Atom description I would make up a POSH verb tag. This
is not a standard, it's just a good idea in general and it gives us
more 'in the wild' data to work with.

[Chris Messina]

Stephen -- could you supply us with a code snippet for a given activity given your proposal and the desire to use hAtom (I think entry-author is required, which kind of sucks, especially for combined activities (i.e. "Chris and Stephen are now friends with Will"). hSlice in Internet Explorer 8 is basically hAtom but dispenses with the author requirement.)

I think we may need to think a little harder about this, especially for embedding objects in datastreams... it will be highly inefficient if we pass around activities without the social object itself (i.e. a photo, event, video, etc -- which could be an enclosure of known types... doesn't work so well when you're talking about torrents and adding friends though).

I'll bring this up at tonight's microformats dinner. Really we need to spend more time documenting actual use cases in the wild -- and the different array of activities, actors, objects and verbs that make up the universe of collective "activities".

We started here but need to flesh it out further:

http://diso-project.org/wiki/activity-streams

Chris

[Stephen Paul Weber]

> Stephen -- could you supply us with a code snippet for a given activity
> given your proposal and the desire to use hAtom (I think entry-author is
> required, which kind of sucks, especially for combined activities (i.e.
> "Chris and Stephen are now friends with Will").

Always happy to show in code!

<ol class="activity-stream hfeed">
<li class="hentry">
<span class="author vcard"><a class="fn url"
href="http://factoryjoe.com">Chris</a></span>
and
<span class="author vcard"><a class="fn url"
href="http://singpolyma.net">Stephen</a></span>
are <abbr class="updated" title="2008-07-06">now</abbr>
<span class="verb friended added-to-roster">friends</span>
<span class="entry-title target object vcard"><a
href="http://will.norris.name" class="fn url">Will</a></span>
</li>
</ol>

That's hAtom + POSH. Permalink at <http://pastie.org/248449>