Neutron is an xml-based application level protocol for remote content authoring. Neutron provides a set of methods and configuration directives that allow for:
concurrent access to resources
basic file operations (move, delete)
creating resources based on templates
linking resources to datatype definitions
providing styling information for resources
metadata handling
accessing revisions
dealing with publishing workflow stages
custom authentication schemes
and more
Neutron has been been started as an effort to provide a generic API to what common Content Management Systems (CMS) support with respect to content authoring. CMS vendors usually implement their own frontend components for content authoring and/or implement a public API for third party component integration. Neutron is ment to be an open standard that leverages integration and reuse of third party components such as editing applications or standalone clients targeted at offline operation. While targeted at large scale content management systems, Neutron can also be used for accessing lightweight content repositories, datastores or remote file systems.
Neutron is typically used over HTTP. However, Neutron can be run on top of any other transport protocol if feasable.
Neutron provides a comprehensive set of instructions for dealing with xml-based resources. Usage of xml-based resources is not required though. Neutron also covers transactions of binary or custom formatted data while being extensible enough for integrators to deal with the data formats of their choice.
Compared to other open content authoring standards Neutron is higher-level than WebDAV and lower-level that ATOM, to name two prominent examples in that field. While WebDAV operates on Web resources Neutron operates on content servers that might expose their resources to the web. While ATOM is targeted at content syndication Neutron provides a generic API to content authoring.
For examples and usage patterns see Appendix I (Examples).
Basic terms and concepts
Neutron Methods
Neutron defines a set of methods and corresponding exception types for operating on remote resources:
open
save
lock
unlock
checkout
Convenience Mehod for open + lock
checkin
convenience method for save + unlock
These methods can be assigned to arbitrary commandURLs. If a content server must adhere to some url namespace policy, Neutron has been designed to be flexible enough to support it.
Example - Saving a resource over HTTP using PUT
Method: save
CommandURL: http://foo.bar.com/foo.html?neutron.cmd=save
Neutron representation:
]]>
Example - Saving a resource over HTTP by using POST. Single service endpoint
Method: save
CommandURL: http://foo.bar.com/neutron?cmd=save&file=somefile
Neutron representation:
]]>
Initiating a Neutron request/response chain
A Neutron request/response chain is initiated by issuing a set of configuration directives that contain:
commandURLs for the methods supported by the content server
datatype definitions for the requested resource(s) - if available
hinting directives regarding the preferred editing mode of the resource (forms based, WYSIWYG), including data that is needed to render the corresponding client-side application components.
These configuration directives are contained in a Neutron Introspection File and provided by the content server.
Example - Introspection file
]]>
The term "introspection file" accounts for the fact that remote resources are usually not self-contained in terms of data that is needed to edit them. This not only conscerns remote methods to access the resource. Resources might also lack embedded links to relevant datatype definitions and to styling information needed to edit them in WYSIWYG-mode. Further on, most content servers process resources before making them available to end-users. For instance, Web-based content management systems usually add document headers, navigation menus, resolve include directives on the fly etc. before sending the processed resource out to page visitors. Given that processed resources are the reference point of choice for content authoring, they are also a good entry point for editing the underlying static resources in terms of user interaction. Neutron supports embedding a link within a processed resource that refers to an introspection file, therefore allowing for initialization of a Neutron request/response chain by introspecting a processed resource. The notion of such introspection links is as follows:
]]>
Introspection links allow for browsing a website or document repository for instance, gathering information about how to edit the underlying data behind the scenes and let content authors initiate a neutron request/response chain on demand.
Note that using an introspection link that refers to an introspection file is only one way to initiate a Neutron request/response chain. Introspection files can also be provided as part of an Neutron archive (see below) or simply by letting users locate them directly from within a Neutron enabled client.
Linking resources to datatype definitions
Linking resources to datatype definitions is crucial for allowing clients to validate the resource during the authoring process or to provide for datatype-guided content insertion. With regards to XML-based resources, this information is often not self-contained but dealt with by the content server. Linking a resource to a datatype definition is achieved by adding a schema element to the introspection file. Neutron has support for three datatype languages: W3C Schema, RelaxNG and Schematron.
Example - Linking a resource to its datatype definition
]]>
Edit modes and styling information
Neutron supports a set of directives targeted at client-side view configuration. While these directives are somewhat XML-biased they are extendable to support data formats of choice. As noted earlier, content servers usually process resources by adding dynamic document parts like menus and headers or by resolving inclusion directives for instance. Moreover, XML-based systems often use custom datatypes that are transformed to xhtml before being served to end-users. With regards to authoring, editing pre-processed static resources based on their mime-types (as supported by most other content authoring protocols out there) is fine as far as source mode editing is conscerned. However, when considering WYSIWYG-editing (which is what content authors usually prefer) additional information has to be provided to the client-side application:
directives about how to style the resource
document parts that result from server side processing (header, menus, footer, ..) with regards to WYSIWYG editing
Neutron has support for both aspects while keeping integration cost as low as possible by leveraging reuse of existing server side code. In terms of styling a resource two modes are supported: styling by CSS and styling by XSLT. To declare a stylesheet for a given resource a style element has to be added to the introspection file.
Example - Declaring a css style for a resource
]]>
Example - Declaring a xslt style for a resource
]]>
Document parts needed for WYSIWYG-editing but resulting form server side processing such as headers, menus, footers etc. are provided to the client-side application by declaring a view template. View templates contain xi:include directives for inclusion of editable resources. A view template typically consist of custom data surrounding xi:include directives that reference static and therfore editable resources. Styling directives given in the introspection file are ment to be applied to the view template (if present) after the xi:include directives contained have been resolved by the client side application.
Example - View Template
A document title
]]>
Example - Declaring a View Template in a Introspection File
]]>
View templates can be shared between multiple resources. This is needed in situations where a processed resource consists of several otherwise unrelated resources - for instance a xml-based resource being transformed to a single html page after having aggregated a couple of rss-feeds. A view template is considered a shared template if the template directives of individual resources listed in the introspection file point to the same view template. Shared view templates need to include all relevant resources by providing xi:include directives for all those resources.
Example - shared View template
A document containinig a rss feed
]]>
Example - sharing a View template
]]>
Resource Sets
Neutron supports synchronized transactions of multiple resources by adding them to a resource set. A method call on any member of a resource set leads to executing the same method on all other members of the resource set. A method call on any member of a resource set can only be considered successful if the same method can be executed successfully on any other member of the resource set and otherwise will be reverted. A typical usecase for a resource set is when dealing with metadata contained in a seperate resource. For instance, given a resource set that contains resource A and another resource B that holds metadata of A, Neutron enabled applications can make sure that document and metadata are opened, locked, saved, unlocked together.
Example - Resource set
]]>
Introspection
The communication between the client and server can be initialized by
introspection. This also allows the server to tell the client of it's
capabilities (e.g. level 1, 2, 3 compliance). Also see the specification of Atom resp. http://bitworking.org/projects/atom/.
Finding the introspection file (auto-discovery)
]]>
An example of an introspection file
]]>
The version of introspection is given by the following namespace convention: http://www.wyona.org/neutron/VERSION
Backward Compatibility
If the client supports higher versions of the introspection spec than the server can deliver, but
the client still offers the lower version introspection parsers with the correct internal mapping.
Forward Compatibility
If the client introspection implementation version is lower than the introspection version which
is delivered by the server, then one would assume the client to throw a warning, but nevertheless the client should try to handle this newer version as good as possible. But this can only work if the spec is enhanced only (e.g. adding an attribute or element), and never really changed. Another solution might be that the client adds its supported introspection versions to the HTTP header of the GET request to retrieve the introspection from the server, e.g. OSR-101-Version: 1.0.
TODO: What about multi-stage/step process, e.g. first dialog to enter username and password and second dialog to enter a pre-generated random number?
Response from Server to Client
Authorization denied for "URL" ...Login for realm 'phoenix-demo' ...
]]>
Response from Client to Server
lenya
levi
]]>
New
The action "New" allows to create a new document by selecting a template.
The CMS/server needs to provide a template listing to the client such that
the client can provide a dialog in order to let the user select a template.
The "New" action entails a "Save As" action in order to allow specifying a
new document name when actually saving.
Request
...
Response
]]>
Open
The action "Open" allows to open an existing document.
If the client has already a document loaded and a new document will be
opened, then the loaded document might be closed automatically (please also
see "Close" and "Save All").
The CMS needs to provide a directory listing to the client such that the
client can provide a dialog in order to let the user select a document.
When a user attempts to open a document, then the server needs to check if
the document might have been locked already respectively opened by another
user. If it has already been locked respectively opened by another user,
then the CMS needs to communicate to the client that this document is
currently locked and maybe provide a functionality to break the lock.
Otherwise the document needs to be locked on the server side if the document
is being opened.
The document path needs to be kept within the client in order to allow
saving to the original document on the server side.
Usecases
Open from Local Desktop
Open from Server (server does not support locking)
Open from Server (checkout with lock)
Open from Server (checkout without lock although server does support locking)
Open from Server with locking/checkout implemented
Document has already been checked-out by ...Jimi Hendrix1969.10.03T15:34:26
]]>
How does the server respond to the "break-lock" request?
Server breaks lock, check-out for new user and returns content.
Server breaks lock and returns lock broken successfully, please retry opening again ...
Server responds breaking the lock failed for whatever reason.
Save
The "Save" action allows to save a document to the path which was selected
when loading the document with the "Open" action.
It might be assumed that no temporary copies are being used on the server
side, but rather the original document is being overwritten. This might lead
to the confusing situation, that changes on the server side can been seen,
which are only temporarily.
Usecases
Save to Local Desktop (default behaviour in case document has been opened from local desktop)
Save to Local Desktop (although document has been retrieved from server)
Save to Server (server does not support locking)
Save to Server temp version (in case server supports this functionality)
Save to Server (checkin, remove the lock)
If the server is able to save successfully, then it should return HTTP Status Code 200.
If the server cannot save the data, then it should return HTTP Status Code 500 and a message.
Checkin failed, because document has been checked-out by ...Jimi Hendrix1969.10.03T15:34:26
]]>
The "Exit" action allows to quit the client. If the user clicks on the
"Exit" menu item, then the client opens a dialog, where the user can select
the following buttons/options:
Save
Save As
Don't save (Exit but do not save)
Cancel (Do not exit)
If a lock has been created during opening, then this locks needs to be
removed at this point. In case the CMS would support breaking the lock by
another user, then the CMS should communicate a broken lock to the client.
Hypertext Link Lookup
The hypertext link lookup functionality allows to add a hypertext link to a
text. One selects part of a text and clicks on the link icon which is
triggering a request to the server(s) in order to provide the content resp.
interface for a link selecting dialog. One could imagine the following types
of dialogs:
Text Field to paste a link
Search Field
Simple resource list
Hierarchical resource listing (tree-view)
Topic Map with resource occurences (graph-view)
Response: Search Field
]]>
Response: Simple List
]]>
Search
In the case of OpenOffice.org one can add new search engines by clicking on
Tools --> Options --> Internet --> Search
As an exchange format one might want to use the OpenSearch RSS.
Workflow
...
Commentaries
April 20, 2006 Commentary (Andreas Wuest)
Sessions
"The communication between the client and server can be initialized by introspection.": it is not clear if this means that some kind of sessions is initiated between the client and the server. IMHO, introspection should NOT initiate a session, since this is simply a query operation on what capabilities the server has.
Save As
We need a way to upload a file to the CMS without having previously issued a New or an Open. (This with regard to the CMSConnector for uploading attachments from a mail client to the CMS.)
Directory Listing
It should be possible to query the directory tree, starting from the root. The server should not return the complete tree, but only the content of the queried directory node.
Asset Type Querying
I assume that the list of legal asset types is provided via the introspection file. What I am thinking about though is a way for the server to PROPOSE an asset type for a given MIME type. Example: CMSConnector wants to upload an attachment. Before saving, CMSConnector somehow communicates the MIME type of the attachment to the server, and the server then proposes a suitable asset type for this MIME type.
Authentication
Each operation should support authentication of the client.
Simple username/password tuple:
Ways of identification:
session cookie
pros:
authentication only once per session
cons:
needs sessions semantics
when does the session cookie expire if there is no normal exit