Last update: Jan 10, 2008 by SRB

UI 

• RA-DOC: need to set our embeddable UI strategy.  For those services that may offer a UserServiceAdminUI noun, we should have a consistent way of implementing this embeddable UI
• RA shared: create a standardized appearance and layout for the admin_ui

Service Characteristics 

• RA element: all services will implement soft-deletes
• RA element: all services will attempt to implement an undo protocol. 
• RA-DOC: the bootstrap / startup pattern for services and apps
• RA-DOC: the unique identification algorithm for services and apps.  Complete utility for creation of unique id
• RA-DOC: pattern for master to slave data synch, including adds, updates, deletes, conflict resolution, and prohibited request handling (app attempts operation barred by the service)

Protocol / Naming 

• RA element:  each service has:
  • noun, REST interface to the service
  • noun_admin, REST interface to the service admin
  • noun_admin_ui, web interface to administer the service (noun_admin_ui will NOT use the REST service it will be direct to the store; in the case of multi-noun services there will be only one admin_ui; when dealing with slave data, use the local provisioner to jump to the other admin_ui)
  • In SVN the service shall be named "service_noun"
  • On the net, the default installation shall be http://noun.bsgplatform.com/noun/... (as above)
• RA element: creation via PUT will not be supported.  All creates will be via a POST and will return a GUID. 
  • Clients are expected to store this GUID if the wish to retrieve a specific resource. Clients who do not can still use the resource's search interface
  • All services will support GET retrieval and PUT update using this GUID
  • Services may optionally support GET retrieval and PUT update using the applications unique identifier in those instances where the app id is reasonably unique 
• RA element: standard list of supported HTTP result codes
  • RA-DOC: writeup the meaning and usage of each result code
  • RA-DOC: writeup best practice for populating the response body
• RA element: all return bodies (even those returning a single element) will be wrapped in XML
• RA element: all return values will be in the XML inner text rather than as attributes on the XML:
  • GOOD:  <guid>a-b-c-defg</guid>
  • BAD: <guid id="a-b-c-defg"/> 
• RA element: all resources have a canonical form, introduction of additional resource synonyms should return a 303 ("See Also"). Ref: REST pg 84. 
• RA element: naming of resource URIs (Ref. REST pg 117):
  • Use path to encode hierarchy (e.g. /parent/child)
  • Use punctuation in path to avoid implying hierarchy (e.g. /parent/child;child2)
    • Use commas when the order is important and semicolons when it is not
  • Use query vars to imply inputs to algorithms (e.g. /search?q=jelly)
• RA-DOC: getting token, passing, reauthenticating, encryption (of token and HTTP traffic)
• RA-DOC: sample app

Misc 

• RA-DOC: installing app plugins provided by services
• RA element: when using ruby:
  • Encode for the URI using URI.escape
  • Encode for the body using CGI::escape

TODO

• TODO – define the architecture-wide method for doing undo 
• POLICY: All services will implement sample “views” and functional tests in the sample app. 

Purpose 

Interest Groups support a wide range of use cases.  This is done by tailoring the properties of the Interest Group, as shown and discussed below:

(Click image to enlarge)

Discussion 

First, we'll cover the descriptors:

• Name of the interest group.  The name must be less than 30 characters and not duplicate any existing group or tag.  This last restriction may be surprising, but it's necessary because every interest group has a matching tag.  We may use this tag to search for or secure content.
• Description gives you a space for introducing the purpose and membership of the interest group.  The field is free text and supports graphics, hyperlinks, and whatever content you need.
• Avatar permits the association of a graphic or icon with the interest group.

Second, we can personalize the display of interest group content:

• Number of Conversations limits the quantity of conversations shown in the "Discussion" section of the group page. 
• Days of Conversation to Show limits the timeframe shown in the "Discussion" section.  Enter the number of days or leave blank for unlimited. 

In both cases, further conversations, may be viewed by clicking the "View Remaining..." or "Show All" links found beneath the "Discussion" list.

Third, we can set the e-mail alerts we receive, e.g. notification whenever a user requests membership.

Last, we come to the most important choices:  the membership and visibility of the group. 

(Click image to enlarge)

• Membership of the interest group controls who can join.  "Open" allows walk up users to join immediately.  "Closed" requires a group member send an invitation or the group owner can approve a user's membership request. 
• Visibility controls who can view content associated with the group.  "Public" visiblity imposes no restrictions on visible conversations.  "Private" restricts content to only group members.  A few short notes:
  • The association between content and groups is made by tagging.  No tag, no association with the group!  The group tags will be applied automatically whenever you create the content from the "Participate" section of the group page, but it's always a good idea to double check (especially in the case of private groups).
  • Regardless of the membership and visibility settings, only group members can author new group content.

    By using other tags, you can easily tailor the security of individual group conversations.  Because security limits access to the intersecting subset these combinations can be used with both "public" and "private" visibility.
• Group Visibility can be restricted by checking this box.  This limits where the group itself appears, NOT the content associated with the group.

(Below is an outline. Details forthcoming...)

The initial release of the user service API is listed below. Any mention of a URI path is expected to be  qualified with the final productioon or integration URI of http://user.bsgplatform.com or usertest.bsgplatform.com, respectively). All calls to any resource requires that the http_authorization header be set (we're using Basic authentication). 

Common HTTP Status Code responses (any response statuses that are different/expanded from these, inluding payloads, are detailed in the individual api method sections)

200 Ok

401 Unauthorized

404 Not Found

415 Unsupported Media Type

409 Conflict

500 Server Error

503 Service Unavailable 

Retrieving/Creating users

GET /users/emailhash.xml (TODO /users/guid.xml)

• Returns an xml representation of a user. An example format follows. The method expects a hash of the email (as part of the resource name) and the users' password as part of the query string. [srb] What kind of hash?  MD5?  Is there something in ruby I can call to get the right kind of hash?
• <user>
    <created_at>2007-11-08T15:02:22-06:00</created_at>
    <email>tech-support@kalivo.com</email>
    <guid>e68fdf50-8e3d-11dc-87b4-001b7744e275</guid>
    <updated_at>2007-11-09T16:04:58-06:00</updated_at>
    <active_persona>
      <company_name>BSG Alliance, yo</company_name>
      <created_at>2007-03-23T14:17:56-05:00</created_at>
      <display_name>BSG Support</display_name>
      <full_name></full_name>
      <ip></ip>
      <job_title>Technical Support, yo</job_title>
      <updated_at>2007-11-09T16:04:58-06:00</updated_at>
      <uri>http://www.bsgalliance.yo</uri>
    </active_persona><activated_at></activated_at>
  <is_banned>false</is_banned>
  <about_me>i am fancy.</about_me>
  <yahoo_name></yahoo_name>
  <activation_code></activation_code>
  <aim_name></aim_name>
  <id>1</id>
  <rank></rank>
  <has_avatar>false</has_avatar>
  <password></password>
  <jabber_name></jabber_name>
  </user>

[srb] I'm surprised to not see some of these fields grouped as ~ <attributes/> and just a bunch of name/value pairs (e.g. jabbar_name or aim_name) ?

POST /users.xml

• Creates new user. An xml representation of the user is expected as an input parameter (paramater name is 'user'). The xml representation is returned as part of the 200 OK response. If the user can not be created, the xml representation is returned along with a collection of error messages.  [srb] Shouldn't this be 201 Created ?
• An example is below:

<user>
  <created_at>2007-11-05T10:59:02-06:00</created_at>
  <email>iampeakoiltheory@gmail.com</email>  <updated_at>2007-11-05T11:01:02-06:00</updated_at><errors>
  <error>User personas is invalid</error>
</errors>
</user>

[srb] Where's the GUID?

PUT /users/emailhash.xml (TODO /users/guid.xml)

• Update a user profile. The service takes a parameter named 'user' that is an xml representation of the user and the updated profile. The xml representation is returned along with the 200 OK status response.  A 409 conflict status is returned is the user attempts to change their email to an already existing one. Any other error returns the user xml representation along with a collection of errors 
• [srb] Think we want some discussion of personas here...

TODO: DELETE /users/emailhash.xml

[srb] TODO: DELETE /users/guid

Importing users (Bulk create)

POST /user_imports.xml

• Bulk creation of users. Service expects a list of users in xml format. Example below    <users>
      <user>
  <salt/>
  <last_login_at/>
  <job_title>Technical Support, yo</job_title>
  <uri>http://www.bsgalliance.yo</uri>
  <updated_at>2007-11-09T16:03:57-06:00</updated_at>
  <is_banned>false</is_banned>
  <activated_at/>
  <guid>e68fdf50-8e3d-11dc-87b4-001b7744e275</guid>
  <crypted_password/>
  <company_name>BSG Alliance, yo</company_name>
  <yahoo_name/>
  <previous_last_login_at/>
  <num_of_logins>0</num_of_logins>
  <about_me/>
  <activation_code/>
  <rank/>
  <password_reset_code/>
  <id>1</id>
  <aim_name/>
  <immutable>false</immutable>
  <ip/>
  <has_avatar>false</has_avatar>
  <display_name>BSG Support</display_name>
  <full_name/>
  <deletable>true</deletable>
  <jabber_name/>
  <email>tech-support@kalivo.com</email>
  <created_at>2007-03-23T14:17:56-05:00</created_at>
  </user>
  <user>
  <salt>f7549d346b3613952b8ae31467f3855a4eacb071</salt>
  <last_login_at/>
  <job_title/>
  <uri>http://www.kalivo.com</uri>
  <updated_at>2007-03-23T14:17:59-05:00</updated_at>
  <is_banned>false</is_banned>
  <activated_at>2006-07-18T17:27:26-05:00</activated_at>
  <guid/>
  <crypted_password>026dd03e5b00e4a56807792200bb3ddc2763ac3b</crypted_password>
  <company_name>Kalivo</company_name>
  <yahoo_name/>
  <previous_last_login_at/>
  <num_of_logins>0</num_of_logins>
  <about_me/>
  <activation_code>59c31e4b6d5c915bc3e0ce00a28d197db8cb226a</activation_code>
  <rank>Member</rank>
  <password_reset_code/>
  <id>2</id>
  <aim_name/>
  <immutable>true</immutable>
  <ip/>
  <has_avatar>false</has_avatar>
  <display_name>Anonymous User</display_name>
  <full_name/>
  <deletable>false</deletable>
  <jabber_name/>
  <email>anonymous@kalbsgivo.com</email>
  <created_at>2007-03-23T14:17:59-05:00</created_at>
  </user></users>
• Any fields passed to the service that are not required are stored as additional attributes
• Return response includes a body element that describes detailof the export including any failed users with a reason as to their failure. Example below.
• <import_details>
  <user_import>
    <created_at>2007-11-11T17:54:47-06:00</created_at>
    <domain>http://localhost:3000</domain>
    <failure_count>4</failure_count>
    <ip>127.0.0.1</ip>
    <success_count>152</success_count>
  </user_import>
  <failures>
  <user>
    <created_at>2007-11-08T15:02:22-06:00</created_at>
    <email>tech-support@kalivo.com</email>
    <guid>e68fdf50-8e3d-11dc-87b4-001b7744e275</guid>
    <updated_at>2007-11-09T16:04:58-06:00</updated_at><errors>
    <error>User personas is invalid</error>
  </errors>
   </user>
  <user>
    <created_at>2007-11-05T10:59:02-06:00</created_at>
    <email>iampeakoiltheory@gmail.com</email>
    <guid></guid>
    <updated_at>2007-11-05T11:01:02-06:00</updated_at><errors>
    <error>User personas is invalid</error>
  </errors>
  </user>
  <user>
    <created_at>2007-11-08T00:21:32-06:00</created_at>
    <email>iampeakoiltheory2@gmail.com</email>
    <guid>d947de90-8dc2-11dc-85f3-001b7744e275</guid>
    <updated_at>2007-11-08T00:21:33-06:00</updated_at><errors>
    <error>User personas is invalid</error>
  </errors> 
  </user>
  <user>
    <created_at>2007-11-08T15:49:08-06:00</created_at>
    <email>mike@roeder.com</email>
    <guid>6f29efd0-8e44-11dc-b7c6-0019d1039198</guid>
    <updated_at>2007-11-08T15:50:46-06:00</updated_at><errors>
    <error>User personas is invalid</error>
  </errors>
   </user>
  </failures>
  </import_details>

TODO: PUT /user_imports.xml (Bulk update users)

As of Oct 31, 2007

:archives, lists the past X months and the count of conversations created during each. Links from each month list that month's conversations

:author_profile, shows the large avatar for the author of the current conversation (usually used in conjunction with the "show" view).  Includes links to their profile and author RSS feed

:by_type, unused

:calendar, displays a small monthly calendar. Each day numeral will link to any conversations published that day or any events occuring during that timeframe

:clipboard, currently unused

:event_by_type, displays a list of the X most recent events

:featured, display a single conversation body tagged with tag X

:flipper, shows the advertising graphics

:job_listing_by_type, displays a list of the X most recent job listings

:most_active, displays the X conversations with the greatest number of replies

:my_groups, displays the interest groups of which you are a member

:participate, displays shortcuts for creating new content or, joining an interest group

:poll_by_type, displays a list of the X most recent polls

:popular, displays the X conversations with the greatest number of views

:popular_by_xyz, displays the X conversations tagged with XYZ with the greatest number of views

:recent, displays the X conversations in reverse date order

:recent_by_xyz, displays the X conversations tagged with XYZ in reverse date order

:replied_by, displays the replies created by user X

:signup, allows for signup from the sidebar

:since_last_login, displays the conversations published today OR since user X's last login

:started_by, displays the X conversations created by user X

:subscribe, displays links to the RSS feeds found on a given page

:tag_cloud, displays the personal and popular tag cloud

:top_authors, displays a table of the X most prolific starters of conversations

:top_groups, displays a table with the interest groups ordered by number of members and number of conversations 

Purpose 

This writeup covers becoming a Hub member.  While some actions and content do not require membership, many useful features and high-value articles are reserved for Hub members.  Becoming a member requires a simple registration and verification process.

Methodology 

First, locate the "Sign Up" or "Join" option.  In some Hubs this will appear as a link, in others it will appear as a button.  Either way, it will usually be located in the upper-right hand corner of the screen, as shown in these two examples:

Clicking the Sign Up button or Join link brings you to the registration page.

Next, on the registration page provide your contact information and any personal details you feel comfortable supplying.  A few pointers:

• Some fields act as confirmation for data already supplied, e.g., your e-mail address and password.  The information in the original field must exactly match the confirmation field or you will be asked to retype.  Confirm fields have a label beginning with the word "Confirm", as shown on this "E-mail" field:

• Some fields are optional.  The field label will indicate when you can omit a field, as shown on this "Job Title" field:  

• Because these Collaboration Hubs operate in a professional environment, it's recommended that you include as much personal and corporate information as you can.  You will be representing both yourself and your employer so transparency is beneficial.
• Lastly, note that your e-mail address and password will never be shared by the Hub.

Next, you should consider each element of the "Important Notices" section.  This usually includes (1) reading Hub's Terms of Use and Privacy Policy and (2) making sure your e-mail reader has the Hub's web address in its Junk E-mail Safe List.  After doing so, you must check the I acknowledge reviewing... box, thereby accepting these terms.  Once checked, a Sign Up button will appear so you can complete the process, as shown below:

Verification

Most Hubs verify your identity by sending an e-mail to the address you supplied when registering.  This e-mail contains a link you must click before you are considered a Hub member.

The e-mail will look similar to the one shown below.  The link you must click is bordered here in red:

(Click image to enlarge)

Watch the tutorial 

This Primer is unfinished, these are notes for the final product.

Three uses for tags:

1. security
2. organization (and therefore tagged items can be – categorized, searched, browsed, or filtered)
3. site placement (both at the structural level when a tag is a Hub menu and at the data level when an item is tagged, and consequently appears in an area of a Hub)
   

There is not a notion of being in an interest group.  In fact, the existing feature just makes an 80/20 guess that if you start a conversation while viewing a group then you intend that group as the audience, therefore, the group tag is applied by default to the new conversation.

Purpose

This HowTo describes steps for conversing using your Kalivo Hub.  Conversation styles can vary, from thorough position pieces, to blog entries, to discussion threads; fortunately, with Kalivo you use the same tools when creating an editing any style.  As an aside, we highly recommend these writing style and conversation style references.

After reading this HowTo you'll have the steps for both formal and informal communication using your Kalivo Hub.  For a general orientation about Kalivo Hub's, we recommend our Kalivo Hub Introduction.

Methodology 

First, locate the "Start a Conversation" link or icon.  Since this is a fundamental operation you'll find them conveniently located throughout your Hub.  For example, on the sidebar in the Participate Widget:

Or from your Community or Home page:

When conversing within an Interest Group, you'll find it front and center of the Discussion section:

Lastly, there's always the shortcut link from your My Page:

(Click image to enlarge)

Whichever link you click you'll find yourself on the Start a Conversation page, as shown next.  The page has several major feature areas, each located in its own bordered box:

• The Conversation box holds the Subject and Body text fields.  These are your main workspaces when writing your content.  The Body field is a full WYSIWIG editor that offers toolbar buttons similar to those found in the MS Office Suite of applications.  With them you can style, size, color and format your content.  Also, you can include hyperlinks and multi-media content.
• The Tags and Options box offers three tabs repleat with valuable options.  Some of these options include:
  • tagging your conversation for organizational, security, and locational reasons
  • telling others about your conversation or receiving e-mail alerts
  • saving as a draft or future publishing

Follow the Related Tasks links at the bottom of this HowTo for complete details.

• The Attach Documents and Images box allows for uploading of files into your conversation and personal repository.  Read all about your repository in this HowTo.

(Click image to enlarge)

Once you have reached the Start a Conversation page you've only two mandatory steps remaining:

• First, write your content using the Subject and Body fields.
• Then, click the Post button. 

Related Collateral 

Watch the tutorial  

Related Tasks 

• Attaching Documents or Images gives your readers the rich-media experience they expect.  Read our HowTo for directions.
• Advanced Options including important topics like:
  • Tagging lets you organize conversations, apply security, and locate them within your Hub.  Read our Tagging Primer for details. 
  • Telling a Colleague or Friend
  • Receiving E-mail Alerts
  • Working on a Draft or Publishing in the Future

Learn about all four by watching our Advanced Options Tutorial

This is my first shot at a rough API for the Kalivo/JCR interface. I've tried hard to be Restful, but doubtless failed in numerous ways. Comments please. Not included here are the search API and the docType API. They'll be forthcoming.

initialization
==============================================
POST /account/<acct #> (secure)
POST /account?delete

put/get
==============================================
POST /item/item_name => head
GET /item/item_id => head
GET /item/item_id/version => version
POST /item/item_id?delete
GET /directory/node_id => returns XML containing files, timestamps, sizes, ACLs, metadata, version data

statistics - do we need this?
==============================================
GET /stats/count
GET /stats/count/node_id => file count by app
GET /stats/usage
GET /stats/usage/node_id => usage by app
GET /stats/cost => not sure this data is available
GET /stats/cost/node_id => cost by app

Search - TBD

==============================================
 

Document Type - TBD
==============================================

Taxonomy - for extensibility only - not in initial releases
==============================================
POST /node/path => generates full path (i.e. a/b/c creates a, a/b and a/b/c)
POST /node/path?delete => removes full path (i.e. a/b/c removes a/b/c, a/b and a)
GET /node/path

security - not in initial releases
==============================================
POST /acl/node_id/<acl>

Purpose

Kalivo offers security along two important dimensions:  (1) functional security, which answers the question "who can perform what operation?" and (2) data security, which answers the question "who can view what content?".  This primer address this second dimension, data security.

Methodology 

All security in Kalivo is described using tags (yes, the same tags that use can use to organize and search content!).  Even private interest groups use tags in the background to define their privacy restrictions. 

Securing Content 

By using tags, securing content becomes a very simple operation, simply add the "secured tag" to your conversation, event, poll, etc.  In the screen clipping below, we see the tag "BSGLock" has been applied.  The gold padlock beside the lock name indicates the tag carries security restrictions:

(Click image to enlarge)

For any subsequent reply, the security settings of the conversation root will hold.  Therefore, if the root (aka beginning) of a conversation is secure, then all replies are.  And vice versa.  Attempting to secure a reply has no effect. 

When creating or e