Give Alfresco a RESTful webscript

osCaddie RESTful API Integration

In our osCaddie solution, the REST API in JSON format has been used in but not limited for user, group management, share site management, tagging and workflow management. We have found REST API is an awesome supplement when CMIS API underpowers. As a matter of fact, the synergy of CMIS and REST API empowers the architecture of osCaddie being rich, extensible and flexible. "Alfresco RESTful API reference" section from Official Alfresco Documentation has documented all the out of box REST APIs that Alfresco provides. Furthermore, custom webscripts can be developed to satisfy individual project requirements ranging from user management to workflow. Continuing with my last blog Hands on CMIS with Alfresco, this blog will show how to write a RESTful API in JSON. In Alfresco, Webscriptis used for developing RESTful API in JSON. The workflow is chosen here as it is a popular demand that a front end WCM (Web Content Management) such as Drupal can start a workflow in a backend ECM system such as Alfresco.

Start Workflow Webscript

A webscript is developed to start a parallel document review workflow from Drupal. It can take group assignee and Alfresco noderef as parameters as shown below. For those who don't know much about webscript, Jeff Potts has written a good introduction Introduction to the webscript framework. I have deployed the following three artifacts in Alfresco's extension classpath, i.e.${ALF_HOME}/tomcat/shared/classes/alfresco/extension/templates/webscripts. 

Descriptor: wf.post.desc.xml

  Start workflow
  Start workflow via REST JSON
  /api/wf
  
  user
  required
  public_api

Controller in Javascript: wf.post.json.js

var nodeRef=null,
    assignee=null,
    groupAssignee=null,
    node=null;


if (json.has("assignee"))
{
    assignee= json.get("assignee");
    groupAssignee=people.getGroup("GROUP_"+assignee);
    if (groupAssignee == null)
    {
      status.setCode(status.STATUS_NOT_FOUND, "Not a valid assignee: " +assignee);      
    }
    
}


if (json.has("id"))
{
    nodeRef="workspace://SpacesStore/"+json.get("id");
                                   
    node= search.findNode(nodeRef);
    if (node == null)
    {
      status.setCode(status.STATUS_NOT_FOUND, "Not a valid nodeRef: " + nodeRef);
    }
}


logger.log("Getting noderef="+nodeRef+",assignee="+assignee);

var workflow = actions.create("start-workflow");
workflow.parameters.workflowName="activiti$activitiParallelGroupReview";
workflow.parameters["bpm:workflowDescription"] = node.name;
workflow.parameters["bpm:groupAssignee"]=groupAssignee;
var futureDate = new Date();
futureDate.setDate(futureDate.getDate() + 7);
workflow.parameters["bpm:workflowDueDate"] = futureDate;
workflow.parameters["sendEMailNotifications"] = true;
workflow.execute(node);
model.nodeRef=nodeRef;
model.name=node.name; 

Freemarker template:wf.post.json.ftl

<#escape x as jsonUtils.encodeJSONString(x)>
{
   "nodeRef": "${nodeRef}",
   "name": "${name}",
   "status":
   {
      "code": 200,
      "name": "OK",
      "description": "Workflow started successfully"
   }
}

Test the Alfresco REST API

Test with curl

Curl up with a good web script In this case, "curl -v -X POST "localhost:8080/alfresco/service/api/wf?alf_ticket=TICKET_e46107058fdd2760441b44481a22e7498e7dbf66" -H "Content-Type: application/json" -d @/home/vyang/wf_request.json wf_request.json {'id': '8b53bc34-02b5-4caa-99e6-bdbef50230ea' ,'assignee':'Reviewers'}

Test in your favorite programming language

Python is used below with an Alfresco module I have developed.

 wf_data={'id': '8b53bc34-02b5-4caa-99e6-bdbef50230ea'
                 ,'assignee':'Reviewers'}    
 pprint(alf_session.start_workflow(wf_data))

Play with the Alfresco REST API

As always I learn by getting my hands dirty. Python is my friend here again. The source code is located at GitHub. "git clone git@github.com:victordude/alfresco.git" will get the source code rest.py. In the code, I have shown how to create, delete user, group, share site, list and end workflow instances and tasks. There are many more for exploring. For developers who know Python, I have implemented the AlfSession class as a context manager so that "with" statement can be used. I feel it is cleaner this way. Alfresco Version: 4.0 Enterprise Python: 2.7+ Enjoy!