Hyland Connect

resplin · ‎06-05-2015

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

IMPORTANT: This document details the JavaScript API and Script Services for Alfresco 3.2

if you are looking for details on Alfresco 3.3.X 3.3_JavaScript_API.
If you are looking for details on Alfresco 3.1.X 3.1_JavaScript_API.

Introduction

The Alfresco JavaScript API allows script writers to develop JavaScript (ECMA Script) 1.6 compatible files that access, modify, and create Alfresco repository objects. It provides a clean and simple 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 in that it allows modification and creation of nodes, aspects, and properties.

Using the API script writers can:

find nodes (via XPath and directly via NodeRef or path)
perform searches (including Lucene full-text searches, with sorted results)
walk node hierarchies
examine and modify the value of properties, aspects and associations
transform and manipulate content
process WCM Web Projects and AVM objects
create Groups, People and modify permissions

In addition, scripts can create new files, folders, or nodes of any type, copy/move/delete nodes and create/modify/remove child and target associations between nodes. All the usual Alfresco security and ACL permissions apply.

Scripts can also include (or 'import') other scripts. The developer can build libraries of scripts that are included at runtime to reduce copy/paste between script files.

As JavaScript is a standards based 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 attempting to script the Alfresco repository.

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

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

A mechanism for adding and configuring additional scripting engines exists. It is possible to completely replace or augment the existing script engines with others such as PHP or Ruby. The correct scripting implementation will be automatically selected by the ScriptService when executing a script file based on the file extension of the script being executed. If it cannot resolve the engine to use, then the developer can specify it explicitly when calling the ScriptService. By default only JavaScript is available and this is the API documented here. However a Java-based PHP scripting engine is also provided as an additional AMP download.

Note: There are many example scripts illustrating the API in the JavaScript_API_Cookbook.

JavaScript API for Web Scripts

Since Alfresco 2.1 JavaScript is the default scripting language for the Web Scripts REST API. The API detailed in this document is relevant for both plain JavaScript files executed in the original Alfresco Web Client (i.e. via folder Rules) and for Web Scripts that execute JavaScript within the repository.

In Alfresco 3.0 there is another way to execute Web Scripts. Web applications built on the new Alfresco SURF platform make extensive use of Web Scripts but they do not execute directly within the context of an Alfresco repository, instead they execute within a remote 'presentation tier' i.e. a new web application on a separate web-tier. The API available in the new presentation tier is completely different and more orientated towards managing remote invocations of data Web Scripts that live in the repository tier. Therefore it does not provide direct access to nodes and properties, but instead provides a mechanism to execute data Web Scripts remotely and retrieve and manipulate the data response.

The API available to JavaScript based WebScripts on the presentation tier is detailed in the SURF Platform - FreeMarker and JavaScript API page. A large number of presentation tier WebScript examples can be found in the Slingshot project at the path projects\slingshot\config\alfresco\site-webscripts. The Slingshot project can be found in the Alfresco public SVN server or downloaded via the Alfresco SDK SourceForge project page.

When creating Alfresco 3.0 repository tier data Web Scripts, new service based JavaScript APIs are available to the developer. They are detailed in the 3.0 JavaScript Services API page. A large number of repository tier data WebScripts examples can be found in the Remote API project in the path projects\remote-api\config\alfresco\templates\webscripts. The Remote API project can be downloaded from SVN or SourceForge.

Executing Scripts in the Alfresco Explorer Web Client

Script files can currently be executed in three 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, or 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 the Command Servlet documentation for more information on this servlet.

The third way is via a Web Script.

JavaScript can also be used to build business logic for Workflow.

Script Files

Script files can be stored either on the ClassPath (for example, in alfresco/extension/myscripts) or in a repository store. Scripts are generally stored in the default repository in the Company Home/Data Dictionary/Scripts location. Scripts in this location can be accessed directly by users via the Execute a script action. Scripts in any repository location can be accessed by any user via REST URL if they have the appropriate read permissions on the script document. Scripts on the ClassPath can be imported into other scripts but not executed directly in the web client.

Importing Scripts

This feature allows libraries of scripts to be built and used by other scripts at runtime. The syntax to import the scripts is specific to Alfresco and not a feature of standard JavaScript. For example, the <script src='...'> syntax you may be familiar with, as supported by most web browsers, is not part of standard ECMA JavaScript and will not work!

The syntax to import other scripts is very strict and must be followed exactly or the import may fail. Import directives must be the first lines in the JavaScript file - no code or comments are allowed above those lines. Only the following syntax variants are supported:

Import a script from the repository via name based path:

<import resource='/Company Home/Data Dictionary/Scripts/library.js'>

Import a script from the repository via a NodeRef reference:

<import resource='workspace://SpacesStore/6f73de1b-d3b4-11db-80cb-112e6c2ea048'>

Import a script from a Java ClassPath location:

<import resource='classpath:alfresco/extension/myutils.js'>

Multiple script import of the same script content and circular dependencies are dealt with. A script can import several other scripts from multiple different locations, that is, a script from the repository and another from the classpath.

After the import lines, usual JavaScript code and comments may begin - the imports must be first lines in the file.

Scripting API

The Alfresco JavaScript API provides a rich set of scriptable Java objects that are available to the script writer. Many 'root' scope objects (see below) are provided by default, such as access to the user home folder, company home folder, WCM Web Projects, search, People API and logging functionality. It is possible to configure in additional root scope objects for use by your own scripts, see the section on adding custom Script APIs.

Alfresco Script API design guidelines

Root Scope Objects

Most root objects are known as Script Node objects that wrap the common Alfresco repository concepts such as nodes, aspects, associations, and properties. They also provide access to common services through an object-oriented API.

If you are accessing the script engine either through a rule/action (Execute a Script) 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 Script Node.
userhome	Current user Home Space Script Node.
person	Script Node representing the current user Person object.
space	The current space Script 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 Script Node (if any).
script	The Script Node representing the script object itself. Not present if the script is loaded from the Java ClassPath. Other useful root scope objects provided by default.
args	An associative array of any URL parameters passed via the Script Processor Servlet (only available if the script was executed via the script 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	Session 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.
avm	Access to WCM objects such as AVM paths and searching within AVM stores and web projects. See the AVM API section.
crossRepoCopy	Cross repository copy support. See the Cross Repository Copy section.
webprojects	The root of the WCM Java Script api. Providing access to web-projects, sandboxes, wcm asset and wcm project membership. See the WCM Web Projects section.
invitations	The root of invitations api. Providing access to invitations for web sites (and in future other resources) Invitations
groups	The root of group authorities. Providing access to groups Groups

The default model objects can be accessed directly from the root of a script scope and follow 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 model is built dynamically as required. For example, you can write statements that walk multiple node collections such as:

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

ScriptNode API

The companyhome, userhome, document, space, and person objects represent Alfresco Node objects and provide access to the common Alfresco concepts such as properties, aspects, and associations. The following Node API is available to use within scripts:

properties :An associative array (map) of the properties for the node. For example userhome.properties.name. Each property is keyed by model 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 (for example, 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'];

A useful feature is that properties of type d:noderef are automatically converted into another ScriptNode object. This means the script writer can dynamically walk the object hierarchy for a node. For example, 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;

If you wish to retrieve the NodeRef value for a d:noderef property, then the following code will work:

var localeNoderef = document.properties.locale.nodeRef;

In addition, any properties of type d:content are converted to special ScriptContent objects that themselves feature an API to get or modify the content, mimetype, size and url for the content property. For example:

var mimetype = document.properties.content.mimetype;

var content = document.properties.content.content;

As most documents are derived from the default Content Model type cm:content, shortcut APIs are provided for content, mimetype, size and url for the cm:content property, for example:

document.content = 'some new text content';

var mimetype = document.mimetype;

var url = document.url;

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

children	A readonly JavaScript Array of the child nodes. For example mynode.children[0]. Note that since Alfresco 2.1, all methods that returns lists of data now return true JavaScript Array objects rather than simple Java lists. This means standard JavaScript 1.6 syntax for each and for each in can be used to iterate the results.
assocs	A readonly associative array (map) of the target associations of the node. Each named entry in the array contains an Array of the ScriptNode objects on the end of the association. For example: mynode.assocs['cm:translations'][0].
sourceAssocs	A readonly associative array (map) of the source associations to this node. Each named entry in the array contains an Array of the ScriptNode objects on the start of the association. For example: mynode.sourceAssocs['cm:translations'][0].
childAssocs	A readonly associative array (map) of the child associations of the node. Each named entry in the array contains an Array of the ScriptNode objects on the end of the association. For example: myforumnode.childAssocs['fm:discussion'][0].
parentAssocs	A readonly associative array (map) of the parent associations of the node. Each named entry in the array contains an Array of the ScriptNode objects on the end of the association. For example: Note: 3.2E and HEAD nightly builds after 15-July-2009 only (post Community V3.2) mynode.parentAssocs['cm:contains'][0].
aspects	A readonly array of the aspects (as fully qualified QName strings) applied to the node. (This is returned as a Java HashSet)
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.
downloadUrl	The readonly url to the content stream for this node as an HTTP1.1 attachment object.
webdavUrl	The WebDav cm:name based path to the content.
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. NOTE: care must be taken when accessing the display path if the current user does not have permissions to view all of it. A fix has been made in Alfresco 2.1.1E so that the display path can always be obtained safely for any user.
qnamePath	The readonly (qname) path to this node. (sorry, available 2.1 Enterprise onwards)
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. Otherwise, it is false.
id	GUID for the node.
nodeRef	NodeRef as a string for the node.
name	Shortcut access to the cm:name property.
type	Fully qualified QName type of the node.
typeShort	Prefix string, or 'short' QName type of the node.
parent	The primary parent node, can be null if this is the root node. NOTE: care must be taken when accessing the parent node if the current user does not have permissions to view it. Note that the parent node can always be obtained to allow a hasPermission() check to be applied before accessing properties etc. of it in a script.
parents	An array of the parent nodes. Note that the parent node can always be obtained to allow a hasPermission() check to be applied before accessing properties etc. of it in a script. Note: 3.2E and HEAD nightly builds after 15-July-2009 only (post Community V3.2)
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)	Performs 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)	Performs 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']/');*.
Array activeWorkflows	Returns an array of all active workflows this node is involved in. If the node is not part of an active workflow, null is returned. Items in the returned array are of type JscriptWorkflowInstance.
boolean isScriptContent(object obj)	Returns true if the supplied node property value is a ScriptContentData object.

Advanced ScriptNode API

The following values are available but are only required for special use cases. You can safely ignore these if you do not know what they mean.

primaryParentAssoc :Returns the ChildAssociationRef instance for the node.

Modifying and Creating API

Most of the available ScriptNode API returns read-only values, however the real power of the scripting API can be found in the support for writable objects and access to Alfresco Repository services through this API. The ScriptNode object allows modification of properties, adding new properties, adding aspects, creating new files, folder, and custom type nodes, and of course, updating and setting the text content stream for a node. In addition, it is possible to perform powerful features such as deleting nodes, transforming content, executing templates, and modifying the associations for a node.

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();

Important: The node.save() API call is needed to persist the property modifications - all other modifications made using the API (such as content or adding aspects) take immediate effect.

It is important to note that JavaScript objects are different to native repository 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, for example Array (for a multi-value property), numbers, dates, boolean, and strings. The conversion code handles all common type conversions and recursive lists of those types.

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

content :The text 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.

ScriptNode 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 an exception will be thrown if the creation failed. Alfresco puts the file mimetype of the content (with createNode function, there is no mimetype). For example: var myfile = userhome.createFile('newfile.txt');

ScriptNode 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 an exception will be thrown if the creation failed. For example: var myfolder = userhome.createFolder('New Folder');

ScriptNode createNode(string name, string type) :Creates a new node 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');

ScriptNode createNode(string name, string type, string assocType) :Creates a new node of the specified type as a child of the current node with the given child association type. The assocType parameter is the QName of the child association type to create. For example: var node = myforum.createNode('My Discussion', 'fm:forum', fm:discussion');

ScriptNode createNode(string name, string type, Array properties) :Creates a new node as a child of the current node with the specified properties. The properties parameters is an associative array of the properties to be added to the node upon creation - this is useful when you have a type that requires mandatory properties to be set.

ScriptNode createNode(string name, string type, Array properties, string assocType) :Creates a new node as a child of the current node with the specified child association name with the specified properties with the given child association type.

ScriptNode createNode(string name, string type, Array properties, string assocType, string assocName) :Creates a new node as a child of the current node with the specified child association name with the specified properties with the given child association type and given child association name.

addNode(ScriptNode node) :Adds an existing node as a child of this node.

removeNode(ScriptNode node) :Removes all parent-child relationships between two nodes. The child node will be cascade deleted if one of the associations was the primary association, that is, the one with which the child node was created.

createAssociation(ScriptNode target, string assocType) :Creates a new target association to the specified node with the given association type QName.

removeAssociation(ScriptNode target, string assocType) :Removes the association to the specified node with the given association type QName.

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

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

ScriptNode copy(ScriptNode 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 ScriptNode instance is returned on success or null is returned if the copy fails reason. For example: var docCopy = document.copy(userhome);

boolean move(ScriptNode 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.

ScriptContent API

The ScriptContent API provides several functions and properties related to node properties of type d:content, for example, document.properties.content.

content	A read/write value that represents the content as a string.
write(ScriptContent content)	Copy the content from the specified ScriptContent.
mimetype	A read/write string value that represents the mimetype of the content.
guessMimetype(string filename)	Guess and apply the mimetype to the content based on the given filename.
encoding	A read/write string value that represents the encoding of the content.
size	A readonly long value that represents the size in bytes of the content.
url	A readonly string representing the download url for the content.
downloadUrl	A readonly string representing the download (as attachment) url for the content.

Permission and Security API

The ScriptNode API features several functions and properties related to permissions in the repository. It is a common use case to check for the appropriate user permissions on a node before attempting to access or modify it.

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 'CreateChildren'.

String[] getPermissions() :Returns a String[] of the permissions attached to a node. Strings returned are of the format [ALLOWED|DENIED];[USERNAME|GROUPNAME];PERMISSION for example ALLOWED;kevinr;Consumer so can be easily tokenized on the ';' character.

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 property of the node (as a uid)

Check in/Check out API

The checkin/checkout ScriptNode 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.

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

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

ScriptNode 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.

ScriptNode 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.

ScriptNode 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.

ScriptNode 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.

Versions API

The ScriptNode versions API provides functions and properties for managing and retrieving the versions of a document.

isVersioned : Read-only boolean property for determining if the document versioned.

ScriptVersion[] versionHistory : Read-only property for listing all versions of the document (in descending version created date order).

ScriptVersion getVersion(label) : Retrieve specific version of document identified by 'label', or null if the label does not exist.

ScriptVersion createVersion(history, major) : Creates a version snapshot of the current document.

The ScriptVersion API represents a specific version snapshot of a document.

createdDate : Read-only property representing the date at which the version was created.

creator : Read-only property representing the username of the person who created the version.

label : Read-only property representing the version label.

type : Read-only property representing the type of version ('MAJOR', 'MINOR').

description : Read-only property representing the description (history comment) of the version.

nodeRef : Read-only property representing the node reference of the document that was versioned.

ScriptNode node : Read-only property representing the node as it was versioned.

Transformation API

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

ScriptNode 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.

ScriptNode transformDocument(string mimetype, ScriptNode 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 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.

ScriptNode 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.

ScriptNode 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.

ScriptNode transformImage(string mimetype, ScriptNode 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.

ScriptNode transformImage(string mimetype, string options, ScriptNode 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(ScriptNode 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(ScriptNode 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.

Thumbnailing API

In Alfresco 3.0 a new Repository and REST service for automatic thumbnailing of content is available. The ScriptNode object has been extended to allow JavaScript access to CRUD operations for thumbnailing. See the Thumbnail Services API page for full details.

Tagging API

In Alfresco 3.0 a new Repository and REST service for Web 2.0 style tagging of content is available. The ScriptNode object has been extended to allow JavaScript access to CRUD operations for tagging. See the Tagging Services API page for full details.

Miscellanous ScriptNode 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');

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.

boolean isSubType(string type) :Returns true if this node is a sub-type of the specified type(or itself of that type)

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 ScriptNode 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 query) :Returns an array of ScriptNode objects that were found by the Alfresco repository full-text search, for example: var nodes = search.luceneSearch('TEXT:alfresco');

Array luceneSearch(string store, string query) :Returns an array of ScriptNode objects that were found by the Alfresco repository full-text search in the given store, for example: var nodes = search.luceneSearch('workspace://sitestore', 'TEXT:site');

Array luceneSearch(string query, string sortColumn, boolean asc) :Returns an array of ScriptNode satisfying the search criteria sorted by the specified sortColumn (the property name to sort on) and asc (true => ascending order, false => descending order). For example var nodes = search.luceneSearch('TEXT:alfresco', '@cm:modified', false);

Array luceneSearch(string store, string query, string sortColumn, boolean asc) :Returns an array of ScriptNode satisfying the search criteria and sorted in the given store.

Array xpathSearch(string xpath) :Returns an array of ScriptNode objects that were found by the Alfresco repository xpath search.

Array xpathSearch(string store, string xpath) :Returns an array of ScriptNode objects that were found by the Alfresco repository xpath search in the given store.

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

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

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

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

ScriptNode findNode(string referenceType, string[] reference) :Helper to convert a Web Script Request URL to a Node Ref. ReferenceType can be one of node, path, avmpath or qname. The reference elements supplied depend on the reference type:

node - {store_type}/{store_id}/{node_id} : Resolve to node via its Node Reference.
path - {store_type}/{store_id}/{path} : Resolve to node via its display path.
avmpath - {store_id}/{path} : Resolve to AVM node via its display path
qname - {store_type}/{store_id}/{child_qname_path} : Resolve to node via its child qname path.

string ISO9075Encode(string value) :Helper to encode a value into ISO9075 encoded format - used to encode Lucene PATH statements.

string ISO9075Decode(string value) :Helper to decode a value from ISO9075 encoded format.

Array tagSearch(string store, string tag) :Returns an array of ScriptNode objects that represent the nodes within the given store that have the given tag applied. Default store (SpacesStore) will be used if null value supplied.

In 3.2 a new search API was added to encapsulate several of the above APIs into a single method call and also to provide a more future proof and JavaScript friendly interface.

Array query(object search): Returns an array of ScriptNode objects representing the search results. The 'search' object defines the search to be executed as is constructed in this way:


search
{
   query: string,          mandatory, in appropriate format and encoded for the given language
   store: string,          optional, defaults to 'workspace://SpacesStore'
   language: string,       optional, one of: lucene, xpath, jcr-xpath, fts-alfresco, sql-cmis-strict - defaults to 'lucene'
   sort: [],               optional, Array of sort column options (see below)
   page: object            optional, paging information object (see below) - if supported by the language
}

sort
{
   column: string,         mandatory, sort column in appropriate format for the language
   ascending: boolean      optional, defaults to false
}

page
{
   maxItems: int,          optional, max number of items to return in result set
   skipCount: int          optional, number of items to skip over before returning results (NOT IMPLEMENTED YET)
}

The search definition object an be as simple to use as:

  var results = search.query({query: 'TEXT:alfresco'});

Or as richly defined as:

  var sort1 =
  {
     column: '@{http://www.alfresco.org/model/content/1.0}modified',
     ascending: false
  };
  var sort2 =
  {
     column: '@{http://www.alfresco.org/model/content/1.0}created',
     ascending: false
  };
  var paging =
  {
     maxItems: 100,
     skipCount: 0
  };
  var def =
  {
     query: 'cm:name:test*',
     store: 'workspace://SpacesStore',
     language: 'fts-alfresco',
     sort: [sort1, sort2],
     page: paging
  };
  var results = search.query(def);

Multi-column sorting and any of the Alfresco search languages are supported through this interface. The search definition objects may be extended with additional properties in future versions of the API but backward compatibility will be maintained.

People API

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

ScriptNode createPerson(String userName) :Create a Person (cmerson) with the given user name. Returns the person node created or null if the user name already exists.

ScriptNode createPerson(String userName, String firstName, String lastName, String emailAddress) : Create a Person (cmerson) with a generated user name. Returns the person node created or null if the user can't be created.

ScriptNode createPerson(String userName, String firstName, String lastName, String emailAddress, String password, boolean setAccountEnabled) : Create a Person (cmerson) with a generated user name. Returns the person node created or null if the user can't be created.

ScriptNode deletePerson(String username) : delete a Person with the given user name.

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

ScriptNode getGroup(string groupname) :Returns a single (usr:authorityContainer) node associated with the specified group name, or null if the group does not exist.

deleteGroup(ScriptNode group) :Removes a Group from the system.

ScriptNode createGroup(String groupName) :Create a new top-level Group, groupName is the unique group name to create - NOTE: do not prefix with 'GROUP_'.

ScriptNode createGroup(ScriptNode parentGroup, string groupName) :Create a new Group as a child of the specified parent group node - can be null for a top-level group.

addAuthority(ScriptNode parentGroup, ScriptNode authority) :Add an authority (User or Group) to the specified parent Group.

removeAuthority(ScriptNode parentGroup, ScriptNode authority) :Remove an authority from a Group.

Array getMembers(ScriptNode group) :Returns an Array of people nodes belonging to the specified group (including all sub-groups).

Array getMembers(ScriptNode group, boolean recurse) :Returns an Array of people nodes belonging to the specified group. People of sub-groups are only returned if recurse is specified as true.

Array getContainerGroups(ScriptNode person) :Gets the groups that contain the specified authority.

boolean isAdmin(ScriptNode person) :Return true if the specified user is an Administrator authority.

changePassword(String oldpassword, String newpassword): Changes password for the current user only, old password must be supplied.

setPassword(String userName, String password): Set the password for the given user - only executable by an admin authority.

Workflow API

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

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(ScriptNode 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(doc);

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.ScriptLogger 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 manipulating the categories that they contain. A root level object 'classification' is provided to return category nodes. The CategoryNode objects returned from the functions are extended from the standard JavaScript ScriptNode model to include category manipulation.

CategoryNode[] 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).

CategoryNode 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.

CategoryNode[] 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.

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

CategoryNode[] 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)

CategoryNode[] 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.

AVM API

{{AVMWarning}}
The Alfresco Versioning Machine (AVM) API provides access to Web Content Management (WCM) stores and their associated file and folder nodes. A WCM project is divided into 'stores' such as the Staging Store and various User Sandbox stores and the child nodes of these stores. The store contents has a well defined structure and developers should read the associated wiki pages to get familar with the structure and the naming convention used for staging and user stores.

avm.stores :returns an Array of all store objects in the AVM

avm.lookupStore(storeid) :function to returns the store object for the specified store id

avm.lookupStoreRoot(storeid) :function to return the root node for the specified store

avm.lookupNode(path) :function to return a single avm node given the full path including store to the node

avm.webappsFolderPath :returns the well known root path to the avm webapp folder for a store

AVM Store API

The Store objects returned by the methods above have the following additional API:

store.id :internal ID of the store.

store.name :store name.

store.creator :user who created the store.

store.createdDate :creation date of the store.

store.lookupRoot :returns store root node.

store.lookupNode(path) :function to return an AVM node within the store given the store relative path (relative to AVM webapp folder root).

store.luceneSearch(query) :function to execute a Lucene search against the store and return an Array of AVM nodes as the result.

AVM Node API

The AVM specific node objects returned by the methods above extend the ScriptNode object as detailed above, they also have the following additional API:

node.version :Version of the node, generally this will be -1 == HEAD revision.

node.path :Fully qualified AVM path to the node

node.parentPath :Fully qualified AVM path to the parent of this node.

node.isDirectory() :Returns true if this AVM node is a directory.

node.isFile :Returns true if this AVM node is a file.

node.isLocked :Returns true if the node is currently locked.

node.isLockOwner :Returns true if the node is locked and current user is the lock owner.

node.hasLockAccess :Returns true if this user can perform operations on the node when locked. This is true if the item is either unlocked, or locked and the current user is the lock owner, or locked and the current user has Content Manager role in the associated web project.

node.rename(name) :Rename the node (this is a special operation in AVM, it cannot be performed by simply changing the cm:name property value).

Cross Repository Copy

A root level object 'crossRepoCopy' is provided to enable copy of nodes between document management spaces (ADM) and WCM spaces (AVM).

ScriptNode copy(ScriptNode source, ScriptNode destination, String name) :Copy a source node to the specified destination folder. The source or destination node can be in any repository store such as an AVM Store or the SpaceStore. When copying between stores of different types, the aspects and properties of the node will remain intact but the node type may be downgraded and all associations will be lost.

WCM Web Projects

Root level object webprojects is provided to provide Script access to WCM functionailty.

The WebProjects object API.

WebProject createWebProject(String dnsName, String name, String title, String description ) : create a new web project.

WebProject getWebProject(String webProjectRef) : get a web project.

WebProject[] listWebProjects() : list all web projects.

WebProject[] listWebProjects(String userName) : list all web projects for which the specified user has membership.

The WebProject object API.

webproject.name : name of this web project.

webproject.title : display name for this web project.

webproject.description : description of web project

webproject.isTemplate : is this web project a template ?

webproject.webProjectRef : the unique reference for this web project

ScriptableHashMap<String, String> getRoles() : get the roles for a web project.

save() : update this web project.

deleteWebProject() : delete this web project and all contents.

void addMembership(String userName, String role) : add the specified user with the specified role to this web proect.

void removeMembership(String userName) : remote the specified user from a web project

ScriptableHashMap<String, String> listMembers() : lists the members of this project.

Sandbox createSandbox(String userName) : Create a user sandbox, if the user already has a sandbox does nothing.

ScriptableHashMap<String, Sandbox> getSandboxes(String userName) : getSandboxes for this web project and this user.

ScriptableHashMap<String, Sandbox> getSandboxes() : getSandboxes for this web project.

The Sandbox object API.

sandbox.name : the name of this sandbox

sandbox.sandboxref : the unique reference of this sandbox

sandbox.creator : the unique reference of this sandbox

sandbox.storeNames : the store names.

sandbox.isStagingSandbox : is this a staging sandbox?

sandbox.isAuthorSandbox : is this an author sandbox?

sandbox.createdDateAsISO8601 : date that this sandbox created in ISO8601 format.

deleteSandbox() : delete this sandbox.

submitAll(String submitLabel, String submitComment) : submit the modified items directly to staging (WARNING: bypasses any workflows that may have been configured for the Web Project).

submitAllWebApp(String webApp, String submitLabel, String submitComment) : submit the modified items for the specified webApp directly to staging (WARNING: bypasses any workflows that may have been configured for the Web Project).

submitAssets(Asset[] files, String submitLabel, String submitComment) : submit the specified assets directly to staging (WARNING: bypasses any workflows that may have been configured for the Web Project).

submit(String[] files, String submitLabel, String submitComment) : submit the specified paths directly to staging (WARNING: bypasses any workflows that may have been configured for the Web Project).

revertAll() : revert the modified items.

revertAllWebApp(String webApp) : revert the modified items for the specified webApp.

revertAssets(Asset[] assets) : revert the specified assets.

revert(String[] files) : revert the specified paths.

Asset[] getModifiedAssets() : get the modified assets within this sandbox.

Asset[] getModifiedAssetsWebApp(String webApp) : get the modified assets for the specidied webApp within this sandbox

Asset getAsset(String path) : get the asset;

Asset getAssetWebApp(String webApp, String path); get the asset. Path is relative to WebApp.

The WCM Asset object API.

asset.creator : the userid of the creator of this asset.

asset.createdDate : when was this asset created

asset.fileSize : for a file, how big is the content? In bytes.

asset.name : the name of this asset.

asset.path : the path of this asset. Absolute, not relaqtive to WebApp e.g. /www/avm_webapps/root/index.html

asset.isFile : is this asset a file?

asset.isFolder : is this asset a folder?

asset.isDeleted : has this asset been deleted?

asset.isLocked : has this asset been locked?

asset.lockOwner: who owns the lock on this asset?

asset.createdDateAsISO8601: when was this asset created as a string in ISO8601 format.

asset.modifier : the userid of the modifier of this asset.

asset.modifiedDate : when was this asset last modified?

asset.modifiedDateAsISO8601: when was this asset modified as a string in ISO8601 format.

Asset rename(Sting newName) : rename this file or folder.

Asset move(String newPath) : move this asset.

Invitations

Groups

3.2_JavaScript_Services_API

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.

ScriptNode getNodeFromString(noderef) :Returns a ScriptNode representing the supplied NodeRef string. Note that the node is not confirmed to exist in the repository.

boolean toBoolean(string) :Returns a boolean object from a string value.

string shortQName(string) :Returns the short, or prefix, version of a long QName.

Example Scripts

Example Scripts Page.

Alfresco JavaScript Debugger

The Alfresco Server provides a built-in server-side JavaScript debugger which allows line by line step through, variable inspection and arbitrary script execution.

Note:

The debugger executes in the Java VM of the Alfresco Server. It must be executed on the same machine as the Alfresco Server - remote debugging is not supported.
The debugger does not function correctly on early SunJDK1.6 series JVMs - enabling it will crash the entire JVM.

To enable and disable the JavaScript debugger use the following URL (you must be logged in as an administrator):

http://<host>:<port>/alfresco/service/api/javascript/debugger

This URL displays the current status of the debugger and allows you toggle between enabled and disabled.

When enabled, the JavaScript Debugger window is displayed. Upon execution of any server-side JavaScript, the debugger will intercept and stop execution at the first JavaScript statement. You can then step through, view variables etc or resume execution. When disabled, server-side JavaScript is executed without interruption.

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 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 available scripting engines can be configured in the Alfresco Spring config file script-services-context.xml. You should download the Alfresco SDK to examine the structure of this file.

As of Alfresco 2.1 a mechanism for adding additional scripting engines has been available. It is possible to completely replace or augment the existing JavaScript implemenation with others such as PHP or Ruby. The correct script engine implementation will be automatically selected by the ScriptService when executing a script based on the file extension of the script being executed. If it cannot resolve the engine to use, then the developer can specify it explicitly when calling the ScriptService.

Further engines can be added by developers. Examining the script-services-context.xml for configuration examples. The engine must implement org.alfresco.service.cmr.repository.ScriptProcessor interface and it is recommend to extend the org.alfresco.repo.processor.BaseProcessor abstract class and override the various execute() methods.

A Java based PHP engine has been integrated and is a good example of this, it is available as an AMP download for addition into an existing Alfresco installation.

Adding Custom Script APIs

It is possible to create and add custom script API's implemented in Java and accessible as root objects in JavaScript. This provides an integration point for Alfresco extensions to provide custom API's where appropriate.

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.processor.BaseProcessorExtension. 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 baseJavaScriptExtension parent bean definition in order to ensure your object is automatically registered with the ScriptService framework. The name of the object as it will appear to script writers must also be specified in the bean definition.

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

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

Since this is a standard Spring bean definition any additional services that are required can be injected as properties into the bean definition in the usual way.

Once this bean have been loaded the custom API object will be accessible directly in JavaScript by calling the public methods on the named 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.');
...

Native Java API Access

In some cases you may find that you're unable to satisfy a requirement using the Javascript API, but that a Java API (perhaps the Alfresco Foundation Services API or AVMService for our WCM module) contains facilities that would allow you to do so.

Using the method described in Adding Custom Script APIs, it is possible to add additional root scope objects to Javascript. In the case of the Alfresco Foundation Services API the only object that needs to be injected is the ServiceRegistry (or a proxy of it) - an example implementation of this may be found at Configuring the ServiceRegistry as a Javascript Root Object.

As of Alfresco 2.1.3, Javascript scripts stored in the classpath (e.g. in the file system at the extension directory) can also leverage the Rhino Javascript interpreter's native Java integration facilities (see the Rhino documentation for more details).

However, for security reasons these mechanisms are completely disabled for Javascript scripts that are stored in the repository. This means that the Javascript file has to be stored in the filesystem to be able to access the Native Java API.

Note that there are some important things to keep in mind when calling native Java APIs from Javascript:

Mixing the standard JavaScript APIs and Alfresco Java APIs is not recommended - the JavaScript API caches some values which may not be reflected when using Java APIs and vice-versa.
Extreme care must be taken when using certain Alfresco APIs, for example the transaction APIs. This is because in many cases the Alfresco scripting framework includes logic that handles some of these 'plumbing' concerns automatically - for example the Javascript script for a Web Script is automatically executed within an Alfresco transaction - programmatic transaction handling within the Javascript is not required and may interfere with the default behaviour.
Native Java collections (Arrays, Maps, Lists etc.) do not get translated into their Javascript equivalents, so you cannot use Javascript idioms when accessing them. For example, instead of accessing a java.util.Map using code such as:

var value1 = javaMap['key1']
var value2 = javaMap.key2

You must call the underlying Java methods instead:

var value1 = javaMap.get('key1')
var value2 = javaMap.get('key2')

Please note that these techniques are solely intended for developers who wish to take advantage of the productivity benefits of a scripted language while still having access to the full power of native Java APIs. They should not be used for end user scripting scenarios (eg. end user developed custom actions uploaded to the repository, workflow scripts, etc.).

Return to Developer Guide