Worksheet

Complete this worksheet as you read to begin planning OpenSAM in your application.

A Scenario

We'll use the following scenario to anchor this discussion:

1. Kelly arrives at work and logs into her SaaS work-flow solution (the Home Application).
2. From there she seamlessly reads her email and receives a request for a business proposal.
3. She drags-and-drops the requester's email address into her SaaS work-flow solution which...
4. ...retrieves or builds a customer record.
5. Within that customer record she clicks a "Create Targa Proposal" link.
6. This launches a word processor and a spreadsheet (Productivity Applications),...
7. ...each primed with the right template filled with customer and proposal details.
8. She reviews, then enters additional details into the documents.
9. She clicks the Save button which ...
10. ...submits the documents back to her SaaS work-flow solution, along with associated meta data, and ...
11. ...forwards them to her superior for approval.

This entire scenario took place in Kelly's browser. Nothing was downloaded or uploaded. All templates, documents, and supporting materials are stored on the servers and are easily tracked, updated, and shared.

When everything works perfectly, this scenario is not difficult to implement. Keep in mind, however, that the user may want to pause, resume, or redirect the scenario at different points and that any system or user errors must be accurately reported to the user and recovered from.

But That Doesn't Fit My Model?

Some areas of this scenario may not fit your application's model. Web 2.0 applications do much more than open and close documents. OpenSAM supports other models which are discussed later in this document.

Recognizing the Roles

Each application described above performs several tasks behind the scene. Although it appears simple to the user, we practitioners know that if just one data item was not properly transmitted in just one step of the scenario, the whole sequence would fail.

The Home Application is both the starting point of the sequence and the recipient of the documents at the end of the sequence. This sandwiching of the Productivity Applications by the Home Application is a pivotal aspect of the OpenSAM framework. Because the Home Application launches the Productivity Applications (step e.), it is able to pass to the Productivity Applications credentials that grant them access to save the documents back to the Home application. 

In Complete Detail

Some data is transmitted behind the scenes during our scenario. Here it is in complete detail:

1. Kelly arrives at work and logs into her SaaS work-flow solution (the Home Application).
   This is the only log in that takes place.
2. From there she seamlessly reads her email and receives a request for a business proposal.
   The Home Application either contains a complete email solution or connects seamlessly to her email. No other applications contain email components, thus there are no duplication of address books or in-boxes. If an application wishes to send a document, it submits that request to the Home Application to fulfill. This mechanism is not yet part of SAM.
3. She drags-and-drops the requester's email address into her SaaS work-flow solution which...
   The email address can be the key to the record. Other information, such as a link to the original email message, can be transmitted as well, depending on the level of integration within the email system and the Home Application.
4. ...retrieves or builds a customer record.
   The Home Application manages CRM data itself or connects to a CRM system.
5. Within that customer record she clicks a "Create Targa Proposal" link.
   This link contains data that is associated with this scenario:
   • The Home Application's WebDAV URL, session ID, and perhaps user name or other account information.
   • The name of the document template to load into the application.
   • A suggested folder location, file name, and perhaps file type for the created document. The user can override these in the application's Save As dialog box.
   • Merge Field name and value pairs to populate the template with.
   • Storage Meta Data to pass-thru back to the WebDAV server along with the document. This data is usually opaque to the Productivity Application. This data enables the Home Application to associate the new document with the customer record and the work-flow sequence it is a part of.
   • Possibly cosmetic and presentation information such as skinning colors and which toolbars to display. And perhaps the URL of .png logos of the Home Application used to identify that storage location to the user in File Open and File Save dialog boxes.
6. This launches a word processor and a spreadsheet (Productivity Applications),...
   The Productivity Application server creates these instances of the applications according to the data and specifications within the launch URL. The Productivity Application associates with these instances of the applications session data that is stored on the server. Lengthy or sensitive data can be passed to the Productivity Application server via POST parameters and need not be stored within the browser session holding the Productivity Application.
7. ...each primed with the right template filled with customer and proposal details.
   Template loading and Merge Field incorporation can happen on the Productivity Application server or in the browser.
8. She reviews, then enters additional details into the documents.
   The Productivity Application and templates are carefully crafted to make this as easy and functional as possible.
9. She clicks the Save button which ...
   Although it looks like a Save button it might just commit previously auto-saved data. There is also a Save As button that allows her to choose a different file name, title, folder, file format, etc. A location is available for her to save her work but not submit to the work-flow engine. She can then later re-open these documents once she has obtained additional information for the customer, for example.
   If the save to the WebDAV server fails for any reason (over quota, session time out, incorrect folder, etc.), the Home Application's WebDAV server returns very detailed information about the failure within the HTTP failure response body. This information is displayed to the user by the Productivity Application. The information should include instructions on how to overcome the problem or who to contact.
   This illustrates that the Home Application knows the most about the user, their organization, and the details of operation. The Productivity Application is a relatively dumb participant. This is a big win because there are usually very few Home Applications and many more Productivity Applications.
10. ...submits the documents back to her SaaS work-flow solution, along with associated meta data, and ...
    The Productivity Application's server has all the needed data from the Productivity Application's browser and the server stored session data. The server transmits pass-thru Meta Data via WebDAV PROPPATCH on the newly stored file. The Productivity Application server probably maintains a cached copy of the user's document to speed up subsequent opens, conversions, searches, etc. As discussed below, the Productivity Application's server may permanently store the document or data and submit only link data to the file to the Home Application's server.
11. ...forwards them to her superior for approval.
    Her superior can click a link in the Home Application to launch the Productivity Application editor. In this way they can modify the document immediately without having to switch modes or launch another program.
    They can also manage aspects of the work-flow process directly within the Productivity Application. For example, they can enter comments directly into the Save As dialog box. Such comments are transmitted back to the Home Application via WebDAV PROPPATCH and attached to the document's history within the Home Application. This is one of SAM's design goals: that activities (recording comments, ...) take place in-situ with the document within the Productivity Application. This is more intuitive for the user and allows them to view and review the entire document while they edit their comments.

Other Models

Online solutions are more complex than the document centric example given above. Online solutions operate on a wider variety of data, utilize more tools and components, and involve more participants than document centric desktop solutions do.

Users are accustomed to the files and folders paradigm, however, and think of their data and their processes in those terms. To bridge the powerful solution ⇔ document centric gap, we recommend you strive to wrap your solution in a "Document Veneer." By doing so and working with SAM, your solution will be interoperable with more online Home and Productivity applications.

Document Veneer

Document veneer for an online system consists of three elements:

Define Documents and Collections

Your application undoubtably groups user's data in various ways. Spreadsheets have workbooks. Databases have tables. Photo collections have albums and photos. A first step to a Document Veneer is to define precisely what documents and document collections your application offers. Although your definition of a document and document collections may establish some artificial borders between components of your system, this is neccessary for other SAM applications to work with subsets of your user's data.

Collection is the WebDAV term for folder or directory.

Define and Map Document Identifiers

Desktop systems and HTTP use the folder/filename hierarchy to organize documents. Online systems may use alternatives such as tags, projects, keywords, UniqueIDs, and/or a search-for-everything model. The challenge is that for SAM applications to work together, they need a single way to browse and refer to documents and document collections.

Because HTTP and it's successor WebDAV are so broadly supported, we recommend you map your document naming and organization scheme to HTTP's folder/filename hierarchy. This way all other SAM and even non-SAM applications can browse and manipulate your documents. The perma-link mechanism used by blogs, however, is not sufficient.

WebDAV has the ability to do a 'dir' on a folder and return a very detailed list of files, subfolders, and their metadata. This allows a user operating in one SAM application to browse their documents and collections in another SAM application. Users find this direct access to their documents accross portions of the system very appealing.

You can choose to support this to varying degrees. You may already support access to your document via a

domainname.com/get.cgi?id=1234

query. For other SAM applications to browse a user's documents, however, they will want to view them as:

domainname.com/foldername/usersfilename.ext

instead. We recommend that you take the document organization paradigm you present to your users (folders, projects, tags, etc.) and expose it directly in your HTTPS and WebDAV URLs. For example, if a user is a member of Group A and works with documents within Project B there, then enable them to browse and find their documents at:

domainname.com/GroupA/ProjectB/documentname.ext.

Define Document Commit Points

Commit Points are actions and points in time when changes to a document are committed to the system and become the current authoritive version of the document. Since multiple participants of a SAM mashup manage and manipulate documents, we must define when a document changes from the perspective of outside participants.

For example, as users open, modify, and save their data within your solution, you've defined points when the data is "committed" and becomes the current version. For collaborative or other reasons, you may commit their data upon an auto-save or automatic submission. Or you may autosave to a temporary copy and only commit it when the user clicks the Save button. Either way, define for your application's precise actions or conditions that commit a user's data to the current version of their document. Your Document Commit Points define when a newer version of a document is made available across SAM applications.

If your application follows the desktop model, the Document Commit Points would operate as follows:

1. Dave opens his document MYDOC and begins editing.
2. Every NN seconds your application autosaves MYDOC to a temporary location on the server.
3. Dave clicks the Save button. This updates the authoritative version of the document on the server.
4. Dave makes additional edits.
5. Additional autosaves are perfomed.
6. Dave clicks the Close button.
7. Your application prompts Dave to see if he wishes to save or discard his changes.
8. Dave chooses to discard his changes.

RESULT: The authoritative version of the document remains the one saved in step c.

A more dynmic model might proceed as follows:

1. Dave and Bob each open the document SHAREDOC and begin collaborative editing.
2. The system saves their edits in real time. New versions of SHAREDOC are continually being created.
3. Dave and Bob close their browser window, leaving their edits in the authoritative version of the document.

In this case, artificial Commit Points are established. For example, you could establish that every 10 minutes of continuous editing defines a commit point. You'll want to synchronize these commit points with your version recoverying or rollback scheme. You'll also want to define these commit points so they are not too granular. The other SAM applications in your mashup do not want to manage 100s over versions created during a single editing session.

This resulting Document Veneer enables a wide variety of other components to browse and manipulate your documents without custom coding to your API or your paradigm. This last point is, by far, the biggest benefit of SAM and serves as a guiding principal for SAM.

The preceding discussion is conceptual. We now switch gears and discuss Document handling in SAM in more concrete terms.

Documents: Authoritative, Cached, References, and Just-in-time

Combining applications into a SAM mashup means that documents will be managed and displayed by several applications, runing on several servers. For performance reasons, some serves will wish to cache copies of a document. To support unique features, some servers will maintain additional data associated with a document.

There are several techniques in SAM to maximize efficiency and to ensure that out-of-date documents or data are never presented to a user. SAM works with these four types of document instances:

These four document instance types help us build powerful and efficient application mashups. Mashups can be extended or rewired without dramatic changes to the implementations or UI. Here is example wiring of a SAM mashup. There are many variations.

Documents: Deciding Authoritative Storage

The first step in designing a SAM mashup is to identify which application will provide Authoritative Storage.

Home Applications frequently provide Authoritative Storage. The Home Application appears to be a central storage repository to the user. Home Applications can, however, manage references, cached, or just-in-time document types with no apparent difference to the user.

Heavy weight Productivity Applications often provide the Authoritative Storage for their documents, especially if the documents require special storage processing such as databases, broadly inter-connected community or workflow applications, or bulky data services such as video hosting.

Your searching infrastructure also impacts the choice of Authoritative Storge. Users wish to search in one place — their Home Application — for all their documents. A Productivity Application, however, may offer specialized search features and utilize specialized indexing technology for their document type. If a Productivity Application is to serve as Authoritative Storage, they should offer search federation services so they can execute a search on behalf of a Home Application. The details of this mechanism have not yet been defined.

Copyright © 2006-2007, the authors.