You are here

Building Your First Webscript

Webscripts are fast becoming the main development tool for those who are seeking to extend and enhance Alfresco. In this article I'm going to try and detail how to build a webscript. This is as much for my own documentation needs as it is for public consumption. So if you notice any errors, then please let me know!

Webscripts can sit in a variety of places, from directly in the Alfresco repository, to sitting within their own SpringSurf apps. However, no matter where you put them, they all have a similar structure.

  • XML descriptor file that tells describes important aspects of the webscript (Required)
  • Javascript file that does some processing etc (Optional)
  • Freemarker template file that returns some nicely presented information to the user. (Optional)

Although the second and third of the above elements are optional, you need to have one or the other, otherwise your webscript wont do anything.

Purpose of the Webscript

We're going to design a webscript that sits within the Webscript Extension area of the Data Dictionary. This could in theory be added to the classpath, but putting it in the data dictionary means you don't have to do a server restart everytime you change it. The webscript itself is fairly basic, and all it does is return back the structure of a given area within the repository. This kind of script can be used as the basis for site tree, or something similar.

The Descriptor File

This is perhaps one of the easiest parts of developing the webscript, and yet it can inself cause problems if you enter the wrong information. There are specific naming conventions that need to be observed for all webscript files. First comes the name of the webscript, then the type of HTTP call that is being made (GET, POST, etc), then the type of information that is being returned (HTML, JSON, etc), and finally the file extension. So for our webscript, we'll create a file called getsitetree.get.desc.xml. Here's the contents of the file.

<webscript>
<shortname>Get Site Tree</shortname>
<description>Retrieve the site tree from Alfresco</description>
<url>/alfrescocms/getsitetree</url>
<format default="json">extension</format>
<authentication>user</authentication>
</webscript>

Tags: