alfresco Web Scripts Folder Maker: A Web Script that handles POST

Example

The Hello World Web Script handles GET HTTP methods. But what if you want to create data on the server? For that your web script should handle POST.

Here is a simple example that creates new folders in Company Home. It is invoked by making a POST call with a JSON body that looks like:

{'name':'testfolder'}

Optionally, you could add a title or a description to the folder by passing those in as part of the body, like:

{
  'name':'testfolder',
  'title':'test title',
  'description':'test description'
}

The descriptor is called foldermaker.post.desc.xml:

<webscript>
  <shortname>Folder Maker</shortname>
  <description>Creates folders</description>
  <family>Examples</family>
  <url>/example/folders</url>
  <format default="json"></format>
  <authentication>user</authentication>
</webscript>

The optional "family" element is a convenient way to group web scripts in the web script index. The "format" element declares that this web script returns JSON.

The controller is called foldermaker.post.json.js:

var name = title = desc = null;

var name = json.get('name');

try {
  title = json.get('title');
} catch (err) {}

try {
  desc = json.get('description');
} catch (err) {}

var folder = companyhome.createFolder(name);

var needsSave = false;

if (title != null) {
  folder.properties['cm:title'] = title;
  needsSave = true;
}

if (desc != null) {
  folder.properties['cm:description'] = desc;
  needsSave = true;
}

if (needsSave) {
  folder.save();
}

model.id = folder.nodeRef.toString();
model.name = name;
model.title = title;
model.description = desc;

Notice that this controller has "json" in its name. This tells Alfresco to expect a JSON payload. Alfresco will automatically parse the JSON and put it in a root variable called "json".

The controller grabs the name, title, and description from the JSON and creates the folder using the root scope variable called "companyhome".

If a title or description is passed in those properties get saved.

The values that were passed in as well as the new folder's node reference get set on the model before handing control over to the view.

The view is named foldermaker.post.json.ftl:

{
  <#if title??>
  "title": "${title}",
  </#if>
  <#if description??>
  "description": "${description}",
  </#if>
  "id": "${id}",
  "name": "${name}"
}

This freemarker just echoes back the values set on the model as JSON. The title and description may not always be present, so the view uses the Freemarker null check built-in in an if statement to avoid returning those if they were not set.

Any HTTP client can be used to test this web script out. Here's what it would look like using curl:

jpotts$ curl -uadmin:admin -H "content-type: application/json" -X POST "http://localhost:8080/alfresco/s/example/folders" -d "{'name':'testfolder','title':'test title', 'description':'test desc'}"
{
  "title": "test title",
  "description": "test desc"
  "id": "workspace://SpacesStore/cc26a12f-306b-41f1-a859-668f11fc2a54",
  "name": "testfolder"
}

Note that curl is passing in basic auth credentials. In this case it is using "admin". Because this example creates items in Company Home, you must use a user that has the appropriate permissions to do that.

This web script has no real error checking. If you don't pass in a name or you pass in a name that has already been used you will see an error.