Generating confluence documentation of Alfresco web scripts

If you are working with Alfresco, you may already know what web scripts are. Basically web script framework is a thin REST layer on top of repository and the web scripts are the RESTful services that runs inside this framework.

Web scripts are the services that allows you to interact with the repository and it is obvious that they should be documented properly for proper collaboration. Alfresco already has another web script to dump all the web scripts available in the system as html and wikimedia but not in confluence format. So I created a new freemarker template to render the documentation as confluence content. See the following snippet.


This page is rendered using Alfresco on Mar 1, 2015 8:00:04 PM and contains the latest web scripts and their definitions.

h2. Index of All Web Scripts
<#macro recursepackage package>
    <#if package.scripts?size &gt; 0>
h3. Package: ${package.path} ${url.serviceContext}/index/package${package.path}
        <#list package.scripts as webscript>
            <#assign desc = webscript.description>
h4. ${desc.shortName}
            <#if desc.description??>
h5. URI's
|| Method || URI ||
                <#list desc.URIs as uri>
| ${desc.method?html} | {noformat}${url.serviceContext}${uri?html}{noformat} |
h5. Properties
|| Property || Value ||
| Authentication | ${desc.requiredAuthentication} |
| Transaction | ${desc.requiredTransaction} |
| Format Style | ${desc.formatStyle} |
| Default Format | ${desc.defaultFormat!"Determined at run-time"} |
| Lifecycle | ${desc.lifecycle} |
| Id | ${url.serviceContext}/script/${} |
| Descriptor | ${url.serviceContext}/description/${} |
| Descriptor Path | ${desc.storePath}/${desc.descPath} |
    <#list package.children as childpath>
    <@recursepackage package=childpath/>

<@recursepackage package=rootpackage/>

All you have to do is to make this template available for that particular web script; means putting it to a proper place so that the web script framework can pick it up while rendering the output. You can put it on the classpath or directly in repository. See the following list for the possible locations.

  • repository folder: /Company Home/Data Dictionary/Web Scripts Extensions
  • repository folder: /Company Home/Data Dictionary/Web Scripts
  • class path folder: /alfresco/extension/templates/webscripts
  • class path folder: /alfresco/templates/webscripts

Don’t forget to put the template in the proper package, the package of this webscript is org.springframework.extensions.webscripts. Use indexall.get.text.ftl as the template name. See the all possible template paths below.

  • repository folder: /Company Home/Data Dictionary/Web Scripts/indexall.get.text.ftlExtensions/com/springframework/extensions/webscripts
  • repository folder: /Company Home/Data Dictionary/Web Scripts/org/springframework/extensions/webscripts/indexall.get.text.ftl
  • class path folder: /alfresco/extension/templates/webscripts/org/springframework/extensions/webscripts/indexall.get.text.ftl
  • class path folder: /alfresco/templates/webscripts/org/springframework/extensions/webscripts/indexall.get.text.ftl

You can invoke this web script via calling /alfresco/service/index/all.text. If you want to generate the documentation only for the web scripts developed by you, just include the package while calling otherwise it will generate the documentation for all the web scripts, e.g. /alfresco/service/index/all.text?package=/com/foo/my/extension.

After calling the service you can just copy the output and paste into your confluence page.

UPDATE: There are other webscripts in Alfresco source code that can be extended in the same way. However this particular webscript comes with Spring Surf API (spring-webscripts-api) –which is not in Alfresco source code– because of the Spring adoption of webscript api.

Leave a Reply

Your email address will not be published. Required fields are marked *