Hyland Connect

resplin · ‎06-05-2015

The official documentation is at: http://docs.alfresco.com

JavaScript API
IMPORTANT: This document details the JavaScript API and Script Services for Alfresco 2.0 or 1.4. For more recent versions then please see this document: JavaScript API. Note that this page will no longer be maintained or updated except to correct any mistakes.

Introduction

From Alfresco 1.3, the Alfresco JavaScript API allows script writers to develop JavaScript1.5 compatible files that access, modify and create Alfresco repository Node objects. It provides a simple, clean and object-oriented API to well known Alfresco concepts such as Nodes, Properties, Associations and Aspects. The API is similar to the Alfresco Template API - with a significant difference that it allows modification and creation of nodes, aspects and properties.

Note that JavaScript API was significantly enhanced in Alfresco 1.4 - this document details the 1.4 API. Enhancements specific to Alfresco 2.0 are noted.

Using the API script writers can find nodes (via XPath), walk node hierarchies, perform searches (including Lucene full-text searches), examine and modify the value of node properties and modify the aspects applied to a node. In addition scripts can create new files and folder objects and copy/move/delete nodes. All the usual Alfresco security and ACL permissions apply.

As JavaScript is a standard language (also known as ECMA Script) there are many web resources, online tutorials and books to help developers in writing JavaScript files. It is suggested that potential script writers read up on JavaScript resources before diving in to scripting the Alfresco repository.

A good general JavaScript 1.5 reference can be found on the Mozilla site.

The integrated JavaScript engine in Alfresco utilises the Mozilla Rhino JavaScript Engine for Java. This allows JavaScript1.5 (ECMA Script) files to access Java objects using a 'bean' style notation and interpreted mode execution without compiling to external class files.

Executing Scripts in the Web-Client

Scripts can currently be executed in two different ways.

The first is to create a Content Rule and select 'Execute a Script' from the list of available actions for the rule. The scripts shown in the list are pre-loaded into the /Company Home/Data Dictionary/Scripts space - users with appropriate permissions can add create/modify the available scripts.

The second way is to use direct URL addressing for a REST-style of execution. The Alfresco web-client features a generic 'command' servlet that allows the execution of scripts directly via URLs. This feature allows direct access to scripts and the result of the script is returned as the HTML response stream. See Command Servlet docs for more info on this servlet.

Scripting API

Root Scope Objects

The API provides a set of scriptable 'Node' objects that wrap the Alfresco repository concepts such as nodes, aspects, properties and provide access to common services through a rich object-orientated API. If you are accessing the script engine either through a rule/action in the Web-Client or through the Script Command Processor then the following objects are available by default in the root scripting scope:

companyhome :The Company Home node.

userhome :Current user Home Space node.

person :Node representing the current user Person object.

space :The current space node (if any). Note that for a script executing from a rule, the space object will be the space that the rule resides in, this may not be the space you are expecting if the rule is inherited.

document :The current document template node (if any).

script :The node representing the script itself.

args :An associative array of any URL parameters passed via the Script Processor Servlet (only available if the script was executed via the servlet).

search :A host object providing access to Lucene and Saved Search results. See the Search API section.

people :A host object providing access to Alfresco people and groups. See the People API section.

actions :A host object providing invocation of registered Alfresco Actions. See the Actions API section.

logger :A host object providing access to console logging facilities for debugging of scripts. See the Logging API section.

session ession related information such as the current authentication ticket. See the Session API section.

classification :Access to the root elements of the classification API. See the Classification API section.

utils :Access to a library of useful helper functions not provided as part of generic JavaScript. See the Utility Functions section.

The default model objects can be accessed directly from the root of a script scope and follows the standard JavaScript pattern of property dot notation style syntax, for example:

var name = userhome.properties.name

Here the variable name is populated by accessing the properties property and the name value within it.

The node children/association/aspect etc. model is built dynamically as required. E.g. you can write statements that walk multiple node collections such as:

userhome.children[1].children[0].children[2].name

Node API

The companyhome, userhome and person default objects represent Alfresco Node objects, the JavaScript integration provides the following Node API available to use within scripts.

properties :a associative array (map) of the properties for the node. For example userhome.properties.name. Each property is keyed by QName - which can be written in the fully qualifed namespace form, the short form (such as cm:content) or just the property name if the default Content Model namespace is assumed (e.g. content). Therefore all the following statements are equivalent:


 var name1 = userhome.properties.name
 var name2 = userhome.properties['name'];
 var name3 = userhome.properties['cm:name'];
 var name4 = userhome.properties['{http://www.alfresco.org/model/content/1.0}name'];

One special feature is all properties of type NodeRef are automatically converted into another Node object. This means the script writer can continue to walk the object hierarchy for that node e.g. If a document node has a NodeRef property called 'locale' you could execute the following to retrieve the name of the node the property references:

var locale = document.properties.locale.properties.name;

In addition, any properties of type ContentData are converted to wrapper objects that feature an API to retrieve and set the content, mimetype, size and url on the content property. For example:

var mimetype = document.properties.content.mimetype;

Properties can be modified and new properties added, see the Modifying and Creating API section below.

children :a readonly array (list) of the child nodes. For example mynode.children[0].

assocs :a readonly associative array (map) of the associations of the node. Each named entry in the array contains an array of the Node objects on the end of the association. For example: mynode.assocs['cm:translations'][0].

aspects :a readonly array of the aspects (as fully qualified QName strings) applied to the node.

isContainer :returns true if the node is a folder node, false otherwise.

isDocument :returns true if the node is a content node, false otherwise.

content :the content of the node on the default cm:content property as a string value. This value can be modified to update the content of the node, see the Modifying and Creating API section below.

url :the readonly url to the content stream for this node.

mimetype :the mimetype encoding for content on the default cm:content property attached to this node.

size :the readonly size in bytes of content on the default cm:content property attached to this node.

displayPath :the readonly display path to this node.

icon16 :the readonly small icon image for this node.

icon32 :the readonly large icon image for this node.

isLocked :return true if the node is locked, false otherwise.

id :GUID for the node.

nodeRef :NodeRef as a string for the node.

name :shortcut access to the name property.

type :fully qualified QName type of the node.

parent :the parent node, can be null if this is the root node.

isCategory :true if this is a category node and false otherwise. See the Classification API section.

The following Node API functions are provided to help locate child nodes using an XPath or Name based path:

Node childByNamePath(string path) erforms an xpath based on the name property of the nodes and returns a Node found at the specified path. The path is relative to the current node. If the named node is found then it is returned, else null is returned. For example:

var testingFolder = userhome.childByNamePath('QA/Performance/Testing');.

Array childrenByXPath(string xpath) erforms an xpath based query search and returns an array of the nodes found. The XPath search is relative to the current node. An empty array will be returned if no results are matched. For example:

var nodes = userhome.childrenByXPath('*[@cm:name='Finance Documents']/*');.

Modifying and Creating API

Most of the available Node API returns read-only values, however the real power of the scripting API can be found in the support for writable Node objects and access to Alfresco services through this API. The Node object allows modification of existing properties, creating new file and folder nodes and of course updating and setting the text content for a node. It addition it is possible to perform powerful features such as deleting nodes and adding a new aspect to a node. In the future even more services will be made available through the scripting API.

properties :The property array can be modified to update or add new properties. For example:

// change the name of this document
document.properties.name = 'Backup of ' + document.properties.name;
// add a new property string
document.properties['cm:locale'] = mylocalenode;
// save the property modifications
document.save();

It should be noted that the node.save() API call is needed to persist the property modifications - all other modifications made using the API (e.g. content or adding aspects) take immediate effect.

It is important to note that JavaScript objects are different to native Java objects. Property values in the repository must be of the correct object type as defined in the Data Dictionary and exposed by the content model. So a String property value expects a Java String and a multi-valued property expects a List. The Alfresco JavaScript API will perform the conversion of most object types between JavaScript and Java and visa-versa for you, e.g. Array (for a multi-value property), numbers, boolean and strings. But some properties may need to be explicity of the correct type. Note that in Alfresco 1.3 Date properties and some multi-value properties are not handled correctly, see JIRA bug AR-777 for work-around - this was fixed in Alfresco 1.4.

name :A helper property to get/set the name. This is just a shortcut for properties.name;

content :The content of the node can be modified by setting this property. For example mynode.content = mynode.content + 'append some text';. This is very powerful as it allows the content of a node to changed from within a script. However it is not recommended that nodes with binary content are manipulated in this way!

Node createFile(string name) :Creates a new file (cm:content) node with the specified name as a child of this node. The newly created Node is returned as the result of the function, or null is returned if the creation failed. For example: var myfile = userhome.createFile('newfile.txt');

Node createFolder(string name) :Creates a new folder (cm:folder) node with the specified name as a child of this node. The newly created Node is returned as the result of the function, or null is returned if the creation failed. For example: var myfolder = userhome.createFolder('New Folder');

Node createNode(string name, string type) :Creates a new node with the specified name of the specified type. Like all types specified in the JavaScript API, the type is a QName in either full or short form. For example: var node = userhome.createNode('myfolder', 'cm:folder');

boolean remove() eletes the node. Returns true on success, false otherwise. Note that any variable or references to the Node should be discarded! For example: mynode.remove();

Node copy(Node destination) :Copies the Node to the specified destination Node. The newly copied Node instance is returned on success or null is returned if the copy fails reason. Note that children of the source Node are not copied.

Node copy(Node destination, boolean deepCopy) :Copies the Node to the specified destination Node. If the deepCopy argument is true then all the child nodes of the source are copied also, else just the source node itself is copied. The newly copied Node instance is returned on success or null is returned if the copy fails reason. For example: var docCopy = document.copy(userhome);

boolean move(Node destination) :Moves the Node to the new parent destination. Returns true on success, false on failure to move.

boolean addAspect(string aspect) :Adds a new aspect to the node. Returns true if the aspect was added successfully, false otherwise. The type is a QName of the aspect to add in either fully qualified or short name form. For example: document.addAspect('cm:translatable');

boolean addAspect(string aspect, Array properties) :Adds a new aspect and properties to the node. This function exists to allow mandatory aspect properties to be supplied when the new aspect is applied. The properties argument should be an associative array of QName keyed properties. For example:

var props = new Array(1);
props['cm:template'] = myTemplateNode.nodeRef;
document.addAspect('cm:templatable', props);

boolean removeAspect(string aspect) :Removes the specified aspect from the node.

Permission and Security API

boolean hasPermission(string permission) :Returns true if the user has the specified permission on the node. The default permissions are found in org.alfresco.service.cmr.security.PermissionService. Most commonly used permission checks are 'Read', 'Write', 'Delete' and 'AddChildren'.

boolean inheritsPermissions() :Returns true if the node currently inherits its permissions from the parent space, false to indicate that the permissions are set specifically on the node.

void setInheritsPermissions(boolean inherit) et true to indicate that the node should inherit permissions from the parent node, or false to break the inheritance chain.

void setPermission(string permission) :Apply a permission for ALL users to the node.

void setPermission(string permission, string authority) :Apply a permission for the specified authority (e.g. username or group) to the node.

void removePermission(string permission) :Remove a permission for ALL users from the node.

void removePermission(string permission, string authority) :Remove a permission for the specified authority (e.g. username or group) from the node.

void setOwner(String userId): Set the owner of the node.

void takeOwnership(): Take ownership of the node.

String getOwner(): Get the owner of the node (as a uid).

owner: The owner of the node (as a uid)

Search API

The Search API provides direct access to repository level Lucene search results and Saved Search results. It is accessable via the 'search' root scope object. Note that local searches can be performed using the Node APIs childByNamePath and childByXPath as detailed above.

Like the various node objects, the search object is part of the root scope available to script writers. The API provides the following functions:

Array luceneSearch(string search) :Returns an array of Node objects that were found by the Alfresco repository full-text search, for example: var nodes = search.luceneSearch('TEXT:alfresco');

Array savedSearch(Node node) :Returns an array of Node objects that were found by executing the Saved Search referenced by the supplied node object.

Array savedSearch(NodeRef noderef) :Returns an array of Node objects that were found by execting the Saved Search referenced by the supplied noderef string.

Node findNode(NodeRef noderef) :Returns a single Node as specified by the NodeRef for that node, null is returned if the search failed.

Node findNode(string noderef) :Returns a single Node as specified by the string form of the NodeRef for that node, null is returned if the search failed.

People API

Note: This API is only available in Alfresco 1.4 Enterprise (for now).

The People API provides access to Alfresco people and groups. The API provides the following functions:

Node getPerson(string username) :Returns a single (cmerson) Node associated with the specified username, or null if the person does not exist.

Note: This part of the API is from Alfresco 2.0.

Node getGroup(string groupname) :Returns a single (usr:authorityContainer) Node associated with the specified group name, or null if the group does not exist. Note: The groupname always starts with 'GROUP_' i.e. 'GROUP_MyGroup'

Node[] getMembers(Node group) :Returns a collection of people belonging to the specified group (including all sub-groups).

Node[] getMembers(Node group, boolean recurse) :Returns a collection of people belonging to the specified group. People of sub-groups are only returned if recurse is specified as true.

Checkin/Checkout API

The checkin/checkout Node API features methods for checkout, checkin and cancelling checkout of working copies. Note that you may wish to first add the cm:versionable aspect to a Node if you wish version history to be recorded when using these methods.

Node checkout() erforms a checkout of the Node, returning the resulting working copy Node.

Node checkout(Node destination) erforms a checkout of the Node to the specified destination, returning the resulting working copy Node.

Node checkin() erforms a checkin operation on a working copy Node. The current state of the working copy is copied to the original node, this will include any content updated in the working node. Returns the original Node that was previously checked out. Note that this method can only be called on a working copy Node.

Node checkin(String history) erforms a checkin operation on a working copy Node, applying the specified version history note text. Returns the original Node that was previously checked out.

Node checkin(String history, boolean majorVersion) erforms a checkin operation on a working copy Node, applying the specified version history note text and as a major or minor version increment as required. Returns the original Node that was previously checked out.

Node cancelCheckout() :Cancel the check-out of a working copy document. The working copy will be deleted and any changes made to it are lost. Note that this method can only be called on a working copy Node. Any reference to this working copy Node should be discarded. Returns the original Node that was previously checked out.

Transformation API

The following Node functions make use of the document transformation services available in Alfresco. The OpenOffice server is required for some document transformations.

Node transformDocument(string mimetype) :Transform a document to a new document mimetype format. A copy of the document is made and the extension changed to match the new mimetype, then the transformation is applied. The transformed document Node is returned if successful or null if the transformation failed.

Node transformDocument(string mimetype, Node destination) :Transform a document to a new document mimetype format. A copy of the document is made in the specified destination folder and the extension changed to match the new mimetype, then then transformation is applied. The transformed document Node is returned if successful or null if the transformation failed.

The following functions make use of the image transformation services available in Alfresco. The ImageMagick components will need to be installed correctly and working. Note that detailed information on the ImageMagick options mentioned in the methods below can be found on the ImageMagick website.

Node transformImage(string mimetype) :Transform an image to a new image format. A copy of the image document is made and the extension changed to match the new mimetype, then the transformation is applied. The transformed image Node is returned if successful or null if the transformation failed.

Node transformImage(string mimetype, string options) :Transform an image to a new image format, applying the supplied ImageMagick options. A copy of the image document is made and the extension changed to match the new mimetype, then the transformation is applied. The transformed image Node is returned if successful or null if the transformation failed.

Node transformImage(string mimetype, Node destination) :Transform an image to a new image format. A copy of the image document is made in the specified destination folder and the extension changed to match the new mimetype, then the transformation is applied. The transformed image Node is returned if successful or null if the transformation failed.

Node transformImage(string mimetype, string options, Node destination) :Transform an image to a new image format, applying the supplied ImageMagick options. A copy of the image document is made in the specified destination folder and the extension changed to match the new mimetype, then the transformation is applied. The transformed image Node is returned if successful or null if the transformation failed.

The following functions make use of the FreeMarker template processing services available in Alfresco. The result of the template execution is returned as a string from each function. Note that the node is used as the context to the template. If this node is a document, it will be setup as the 'document' context object for the template, with the parent space setup as the 'space' context object for the template, if it is a folder then it will be setup only as the 'space' context object for the template. An argument list can also be passed to the template - and will be available as the 'args' object, see Template Default Model page for more information on template models and the 'args' object.

string processTemplate(Node template) :Execute a FreeMarker template file against the node. The node is used as the context for the 'document' or 'space' object in the templating default model. The result of the template execution is returned as a string.

string processTemplate(Node template, Array args) :Execute a FreeMarker template file against the node, passing the supplied array of name/value pair arguments to the template. The node is used as the context for the 'document' or 'space' object in the templating default model. The result of the template execution is returned as a string.

string processTemplate(string template) :Execute a FreeMarker template against the node. The template is supplied directly as a string. The node is used as the context for the 'document' or 'space' object in the templating default model. The result of the template execution is returned as a string.

string processTemplate(string template, Array args) :Execute a FreeMarker template against the node, passing the supplied array of name/value pair arguments to the template. The template is supplied directly as a string. The node is used as the context for the 'document' or 'space' object in the templating default model. The result of the template execution is returned as a string.

Workflow API

Details of the API to workflow can be found in the Workflow documentation.

Miscellanous API Functions and Properties

boolean hasAspect(string type) :Returns true if an aspect has been applied to the node. For example: var isTemplatable = document.hasAspect('cm:templatable');

mimetype :The mimetype property value can now be modified to update or set the mimetype of the content. This property is also available on the ContentData wrapper object of custom content property.

boolean specializeType(string type) pecialise the type of a node. Return true on success, false otherwise. The type name supplied must be a sub-type of the current type as defined in the Data Dictionary.

Actions API

A root level object 'actions' is provided that allows invocation of Alfresco Actions registered with the Repository.

registered :Returns an array of String objects representing the names of all registered Actions.

ScriptAction create(String name) :Returns the action for the given action name. If the action name is not registered, null is returned.

ScriptAction API

A ScriptAction represents an Alfresco Action registered within the Repository.

name :Returns the name of the action.

parameters :an associative array (map) of the parameters for the action. For example mail.parameters.subject. Each parameter is keyed by a String. Parameters can be modified and new parameters added.

execute(Node node) :Executes the action against the specified node. The action (and its parameters) may be re-used against many nodes by repeatedly invoking execute. Between invocations, the parameters of the action may be changed. An example of executing the 'mail' action follows:

  // create mail action
  var mail = actions.create('mail');
  mail.parameters.to = 'davidc@alfresco.com';
  mail.parameters.subject = 'Hello from JavaScript';
  mail.parameters.from = 'davidc@alfresco.com';
  mail.parameters.template = root.childByNamePath('Company Home/Data Dictionary/Email Templates/notify_user_email.ftl');
  mail.parameters.text = 'some text, in case template is not found';
  // execute action against a document    
  mail.execute(document);

Logging API

A root level object 'logger' is provided that provides functions to aid debugging of scripts.

boolean isLoggingEnabled() :Return true if console logging is enabled. To enable console logging the Log4J category of log4j.logger.org.alfresco.repo.jscript should be set to DEBUG. This can be applied in the log4j.properties file (TomCat) or log4j.xml file (JBoss) on the Alfresco server.

void log(string) :Log a string message to the console.

Session API

A root level object 'session' is provided to access to the current logged in user session ticket as a string value.

ticket :Get the current authentication ticket.

string getTicket() :Get the current authentication ticket.

Classification API

There are two parts to the API: manipulating classifications and manipultaing the categories that they contain. A root level object 'classification' is provided to return category nodes. The nodes returned from the functions are extended from the standard JavaScript Node model to include category manipulation.

Node[] getAllCategoryNodes(String aspect): Get an array of all the category nodes in the given classification.

string[] getAllClassificationAspects(): Get an array of all the QNames (in prefix:localName form).

void createRootCategory(string aspect, string name): Create a new root category in the given classification.

CategoryNode[] getRootCategories(string aspect): Get all the root category nodes as an array for a given classification.

The CategoryNode object API.

boolean isCategory: Supported by all nodes types - true if this is a category node and false otherwise.

Node[] categoryMembers: Get an array of all the members of this category at any depth.

CategoryNode[] subCategories: Get an array of all the subcategories of this category at any depth.

Node[] membersAndSubCategories: Get an array of all the subcategories and members of this category at any depth.

Node[] immediateCategoryMembers: Get an array of all the immediate members of this category (only direct members of this category and not via sub categories)

CategoryNode[] immediateSubCategories: Get an array of all the immediate subcategories of this category (only direct subcategories of this category and not via subcategories)

Node[] immediateMembersAndSubCategories: Get an array of all the immediate subcategories and members of this category (only direct subcategories and members of this category and not via subcategories)

CategoryNode createSubCategory(String name): Create a new subcategory from the current category node.

removeCategory(): Delete the current category node.

Utility Functions

A root level object 'utils' is provided as a library of helper functions that are missing from generic JavaScript.

string pad(s, length) ads a string with leading zeros to the specified length and returns the new string.

Example Scripts

Example scripts can be found in the Company Home/Data Dictionary/Scripts folder in a default Alfresco 1.3 installation.

Creates a backup of a document as it is added to a space:


// find the backup folder - create if not already exists
var backupFolder = space.childByNamePath('Backup');
if (backupFolder == null && space.hasPermission('CreateChildren'))
{
   // create the folder for the first time
   backupFolder = space.createFolder('Backup');
}
if (backupFolder != null && backupFolder.hasPermission('CreateChildren'))
{
   // copy the doc into the backup folder
   var copy = document.copy(backupFolder);
   if (copy != null)
   {
      // change the name so we know it's a backup
      copy.name = 'Backup of ' + copy.name;
      copy.save();
   }
}

Creates a backup of a document and logs the doc properties to a log text file:


// find the backup folder - create if not already exists
var backupFolder = space.childByNamePath('Backup');
if (backupFolder == null && space.hasPermission('CreateChildren'))
{
   // create the folder for the first time
   backupFolder = space.createFolder('Backup');
}
if (backupFolder != null && backupFolder.hasPermission('CreateChildren'))
{
   // copy the doc into the backup folder
   var copy = document.copy(backupFolder);
   if (copy != null)
   {
      // change the name so we know it's a backup
      var backupName = 'Backup of ' + copy.name;
      copy.name = backupName;
      copy.save();
   }
   
   // record the time of the backup to a log file
   var logFile = backupFolder.childByNamePath('backuplog.txt');
   if (logFile == null)
   {
      logFile = backupFolder.createFile('backuplog.txt');
   }
   if (logFile != null)
   {
      logFile.content += 'File: ' + backupName +
                         '\tDate: ' + new Date().toGMTString() +
                         '\tSize: ' + copy.size + '\r\n';
   }
}

Appends a copyright line of content to plain text and HTML files:


if (document.hasPermission('Write'))
{
   if (document.mimetype == 'text/plain')
   {
      document.content += '\r\n\r\nCopyright (C) 2006';
   }
   else if (document.mimetype == 'text/html')
   {
      document.content += '

Copyright &copy; 2006';
   }
}

Adding several aspects to a document:


var props = new Array(1);
props['cm:template'] = document.nodeRef;
document.addAspect('cm:templatable', props);

props = new Array(1);
props['cm:lockIsDeep'] = true;
document.addAspect('cm:lockable', props);

props = new Array(1);
props['cm:hits'] = 1;
document.addAspect('cm:countable', props);

Finds all the documents containing the text 'Alfresco' using a Lucene search and records the results to a log file:


// log the docs that currently contain the word 'Alfresco' to a log file
var logFile = userhome.childByNamePath('alf docs.txt');
if (logFile == null)
{
   logFile = userhome.createFile('alf docs.txt');
}
if (logFile != null)
{
   // execute a lucene search across the repo for the text 'alfresco'
   var docs = search.luceneSearch('TEXT:alfresco');
   var log = '';
   for (var i=0; i

Returning a result value. This is useful for scripts that are processed using URLs via the Script Command Servlet, as the results are returned as the HTML response from the servlet:


function result()
{
   return 'The name of my home space is: ' + userhome.name;
}
result();

The following solution will also return a value if placed at the end of a script:


// script here
// ...
var result = 'some results...';
result;

Creates a document, makes it versionable, checks it out, modifies the content of the working copy, checks it in again and then repeats the process but checks in the document with a version history note and as a major version increment:


// create file, make it versionable
var doc = userhome.createFile('checkmeout.txt');
doc.addAspect('cm:versionable');
doc.content = 'original text';

// check it out and update content on the working copy
var workingCopy = doc.checkout();
workingCopy.content = 'updated text 1';

// check it in
doc = workingCopy.checkin();

// check it out again
workingCopy = doc.checkout();
workingCopy.content = 'updated text 2';

// check it in again, but with a version history note and as major version increment
doc = workingCopy.checkin('a history note', true);

Changes the mimetype of a document after setting the content:


var file = userhome.createFile('testfile.html');
file.content = 'some HTML here';
file.mimetype = 'text/html';

Creates document content and converts it to new formats using the transformation API:


// create a plain text doc and convert to PDF
var doc1 = userhome.createFile('transform_me1.txt');
doc1.mimetype = 'text/plain';
doc1.content = 'This is plain text';
var trans1 = doc1.transformDocument('application/pdf');

// create an HTML doc and convert to plain text
var doc2 = userhome.createFile('transform_me2.html');
doc2.mimetype = 'text/html';
doc2.content = 'This is an HTML document!';
var trans2 = doc2.transformDocument('text/plain', companyhome);

Converts an image document to other formats:


// convert an image document to GIF format and place it in company home
var gifImage = document.transformImage('image/gif', companyhome);

// convert an image to JPG format and resize to thumbnail image
var thumbImage = document.transformImage('image/jpeg', '-resize 120');

Executes a template from the repository against the current Document node:


var template = companyhome.childByNamePath('/Data Dictionary/Presentation Templates/doc_info.ftl');
if (template != null)
{
   var result = document.processTemplate(template);
   // output result to the console - could just as easily save the content into a new node...
   logger.log(result);
}

Builds a FreeMarker template directly in the script, also builds up an argument list for the template. The result of the template is saved to a new node as the content:


var template = 'Document name is ${document.name}
' +
               'The ID argument: ${args['id']}';
var args = new Array()
args['id'] = '01234-56789';
var result = document.processTemplate(template, args);
// save the template result content to a new node in my home space
var outputFile = userhome.createFile('output.txt');
outputFile.content = result;

How is Scripting integrated into Alfresco?

The Script Service is a typical Alfresco repository service accessed via a Spring managed bean with the name of ScriptService.

Only repository developers will be interested in accessing the ScriptService directly, those more interested in simply writing scripts themselves should skip this section and jump to Scripting API.

The ScriptService features the following interface:


/**
 * Script Service.
 * 
 * Provides an interface to services for executing a JavaScript engine script file against a
 * Java object based scripting data-model.
 * <p>
 * The script file can either be in the repository (passed as NodeRef string) or on the classpath.
 * Also a script String can be passed directly to the service via the executeScriptString() methods.
 * Java objects are passed into the scripting engine and methods can be accessed directly from the script. 
 * <p>
 * A script is executed within a single transaction, any modifications to nodes or properties that fail
 * and cause a rollback which will rollback all repoistory modifications made by the script.
 * 
 * @author Kevin Roast
 */
public interface ScriptService
{
    /**
     * Process a script against the supplied data model.
     * 
     * @param scriptClasspath   Script location as qualified classpath name
     * @param model             Object model to process script against
     * 
     * @return output of the script (may be null or any valid wrapped JavaScript object)
     * 
     * @throws ScriptException
     */
    public Object executeScript(String scriptClasspath, Map<String, Object> model)
        throws ScriptException;
    
    /**
     * Process a script against the supplied data model.
     * 
     * @param scriptRef    Script NodeRef location
     * @param contentProp  QName of the property on the node that contains the content, null can
     *                     be passed to indicate the default property of 'cm:content'
     * @param model        Object model to process script against
     * 
     * @return output of the script (may be null or any valid wrapped JavaScript object)
     * 
     * @throws ScriptException
     */
    public Object executeScript(NodeRef scriptRef, QName contentProp, Map<String, Object> model)
        throws ScriptException;
    
    /**
     * Process a script against the supplied data model.
     * 
     * @param script       Script content as a String.
     * @param model        Object model to process script against
     * 
     * @return output of the script (may be null or any valid wrapped JavaScript object)
     * 
     * @throws ScriptException
     */
    public Object executeScriptString(String script, Map<String, Object> model)
        throws ScriptException;
}

The Service API provides three similar looking methods, they each take a script (either as a Alfresco NodeRef location, Java ClassPath location or the script content itself as a String) and a data-model to make available to the script. The data-model objects are made available to the script by placing them into the global root variable scope. For example, if an String object with the map key name of 'mystring' is provided in the data-model then the JavaScript being executed can access the object simply by name:
var s = mystring;
The default data-model API is described in Scripting API below.

Adding custom Script APIs

Note: this feature is available in the 2.0 release of Alfresco

It is possible to create and add custom script API's implemented in Java and accessable in JavaScript. This provides an integration point for Alfresco extensions to provide custom API's where appropraite.

In order to implement a custom JavaScript API it is recommended that you develop a POJO (Plain Old Java Object) that extends the base class org.alfresco.repo.jscript.BaseScriptImplementation. The public methods of your class will be those that will be accessable from JavaScript. (For example see org.alfresco.repo.jscript.ScriptLogger)

Once complete, you must then configure your bean in Spring. Make use of the baseScriptImplementation parent bean in order to ensure your script is automatically registered with the JavaScript framework. The name of the script as it will appear in the JavaScript API must also be specified in the bean definition.

The following example shows the bean defintion for the ScriptLogger custom API.

<bean id='loggerScript' parent='baseScriptImplementation' class='org.alfresco.repo.jscript.ScriptLogger'>
   <property name='scriptName'>
      <value>logger</value>
   </property>
</bean>

Since this is a standard bean defintion any additional services that are required can be injected by extending the bean defintion in the usual way.

Once this bean have been loaded the custom API will be accessable directly in JavaScript by calling the methods on the named Java Script object. For example the following shows how the log method can be called on the logger API we have defined above.

...
logger.log('This is a log message.');
...

Return to Developer Guide