AttachFS PUT to Projects and Tasks

AttachFS allows operations to be performed on BLOB content using simple HTTP operations such as GET and PUT; without much of the complexity [or the features!] of WebDAV. Most significantly AttachFS allows BLOBs (aka documents) to be manipulated by id rather than path – a simpler approach for a variety of clients and types of applictions. The ability to create and update project documents has been available since the original addition of the AttachFS presentation to the OpenGroupware Coils protocol bundles.

But for applications that may be focused on Projects and Tasks, rather than Folders and Documents, even manipulation of documents by id can require the application to keep track of additional information (such as the Folder where a document is stored) and require additional UI for interaction with the user – such as where they want a document stored. To streamline these types of operations AttachFS now allows upload [HTTP PUT] of documents directly to a Project or Task object. If the target of an upload is a Project or a Task then the AttachFS will automatically determine where to store the uploaded document as well as create object links on behalf of the client application in order to persist the relationship between the document and the targetted object.

AttachFS upload URLs remain unchanged:

/attachfs/objectId/filename

When the objectId is that of a Project object how the document will be saved to the Project is determined by a bit of server configuration. If no configuration has been performed the document is simply saved to the root folder of the project. The files are always created, or updated, using the provided filename. If a file already exists in the target folder with the provided filename than a new version of the document is created (the document is updated). The obvious downside of this approach is that the root folder of a Project can quickly become very cluttered and content uploaded in this way becomes indistinguishable from content saved deliberately to that path via a WebDAV or zOGI client.

An alternative is to set the ProjectINBOXFolderPath server default; when this default is defined it specifies a folder name to which uploaded documents will be saved, beneath the root folder of the project. For example if ProjectINBOXFolderPath is set to a value of “INBOX” then all documents uploaded to a Project via AttachFS will be created in the project folder “/INBOX”. If no folder by that name exists in a Project the server will create it the first time a document is uploaded to the project via AttachFS. This makes documents uploaded in this manner distinct from other documents and avoids cluttering the Projects's root folder. Users, client applications, or workflows can then relocate and rename these documents. Additionally a per-project path can be specified using an object property created on the Project; if set this will override any value provided by the ProjectINBOXFolderPath server default. The object property is inboxPath in the “57c7fc84-3cea-417d-af54-b659eb87a046” namespace. The value may be any string which is a legal Folder name.

adam> set-property –objectid=1234567 --namespace=57c7fc84-3cea-417d-af54-b659eb87a046 –attribute=inboxPath –value=MyProjectsINBOXFolder
Setting the INBOX folder name on Project OGo#1234567

If an upload folder is specified by server default the functionality can also be disabled by setting this object property's value to indicate the project's root folder [“/”].

Redirected uploads, such as uploading a document to a Project via an associated Task, provide an additional feature for automatic categorization. If the server default ProjectINBOXSubdirEnabled has a value of “YES” then in the target folder a subfolder will be created whose name is the object id of the object through which the document was uploaded – in the case of a Task this will be the object id of the Task, in the case of a Project the object id of the Project, etc... This feature can be enabled, or disabled, per Project by creating an object property on the Project named useINBOXSubfolders in the "57c7fc84-3cea-417d-af54-b659eb87a046" namespace. The value of the property should be “YES” or “NO”; existence of the property will always override the server's default, a value of “YES” enables the subfoldering feature, any other value evaluates to false and will disable the feature.

adam> set-property –objectid=1234567 --namespace=57c7fc84-3cea-417d-af54-b659eb87a046 –attribute=useINBOXSubfolders –value=YES

Enabling the use of INBOX subfolders in Project OGo#1234567

When a document is uploaded to a Task which is assigned to a Project the upload will be proxied to the associated Project and the upload will be processed as if the Project was the target of the upload. If an upload is attempted on a Task that is not assigned to Project an exception will be raised and an error returned to the client [the server has no obvious location to store the document - Documents exist in Folders and Folder hierarchies exist within Projects].

If completely generalized uploading of BLOB content is desired the client application can upload content as object attachments; the downside being that attachments do not exist in the server's Document hierarchy and thus cannot be accessed via the WebDAV presentation.

Regardless of INBOX or subfolder mode any document uploaded by proxying through another object such as a Project or Task, will be linked to the proxy object by an object link. The source of the link will be the object through which the upload was proxied and the target of the link will be document itself. If a Task was the target of the upload an object link will be created from the task to the uploaded Document. This persists the relationship between the object and the Document; these links will be apparent to clients using the Omphalos/zOGI representation of the object.

For example: a Task OGo#888888 is assigned to Project OGo#777777. The object properties on the Project are:

{57c7fc84-3cea-417d-af54-b659eb87a046}inboxPath = attachments

{57c7fc84-3cea-417d-af54-b659eb87a046}useINBOXSubfolders = YES

A document named "fred.txt" is uploaded to Task OGo#888888 will be saved as “/attachments/888888/fred.txt” in the Project OGo#777777. If the folder(s) do not exist they will be created automatically. If the path including the file-name already exists the contents of the document will be updated. An object link will be created from Task OGo#888888 to the new or updated Document.

A document can be uploaded to this Task using just the command like curl command:

curl -u username -T myfile.txt http://coils.example.com/attachfs/777777/fred.txt

Whatever the development or scripting environment - performing this operation is simple, which is the entire point of AttachFS.