4.0 JavaScript API

cancel
Showing results for 
Search instead for 
Did you mean: 

4.0 JavaScript API

resplin
Intermediate
0 0 22.5K

Obsolete Pages{{Obsolete}}

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



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


Java Script Services API

JavaScript API
4.0


Table of Contents



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

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.




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
transfer
The root of transfer service.  Providing access to the transfer service Transfer
sites
The root of sites service.  Providing access to the sites service Sites

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 contentmimetype, 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 contentmimetype, 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:
    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.
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.
string getSiteShortName()
Returns the short name of the site this node is located within. If the node is not located within a site null is returned.

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. If you want to update binary content, you can use the write()-method,  e.g.: document.properties.content.write(otherDocument.properties.content);

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() Smiley Very Happyeletes 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, Object 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 = {};
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.
guessEncoding()
Guess and apply the encoding to the content based on the current content. Uses the ContentCharsetFinder service.
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) Smiley Frustratedet 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() Smiley Tongueerforms a checkout of the node, returning the resulting working copy node.

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

ScriptNode  checkin() Smiley Tongueerforms 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) Smiley Tongueerforms 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) Smiley Tongueerforms 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


Repository and REST service for automatic  thumbnailing of content The ScriptNode object allows JavaScript access to CRUD operations for thumbnailing.  See the Thumbnail  Services API page for full details.




Tagging API


Repository and REST service for Web 2.0 style  tagging of content is available. The ScriptNode allows 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) Smiley Frustratedpecialise 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 nodepath, 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

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.

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, cmis-alfresco, cmis-strict - defaults to 'lucene'
   templates: [],          optional, Array of query language template objects (see below) - if supported by the language
   sort: [],               optional, Array of sort column options (see below)
   page: object            optional, paging information object (see below) - if supported by the language
   namespace: string,      optional, the default namespace for properties (default is 'cm')
   defaultField: string,   optional, the default field for query elements when not explicit in the query
   onerror: string         optional, result on error - one of: exception, no-results - defaults to 'exception'
}

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
}

template
{
   field: string,          mandatory, custom field name for the template
   template: string        mandatory, query template replacement for the template
}

Note that only some query languages support the query template feature, such as 'fts-alfresco'.
See the following documentation for more details http://wiki.alfresco.com/wiki/Full_Text_Search_Query_Syntax#Templates

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.


Array selectNodes(stringsearch): Returns an array of ScriptNode objects that  were found by a SelectNodes XPath search. Default store (workspace://SpacesStore) is used.

Array selectNodes(string store, string search): Returns an array of ScriptNode objects that  were found by a SelectNodes XPath search on the given store.

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 (cmSmiley Tongueerson) with the given username. Returns the person node created or null if the username already exists.

ScriptNode createPerson(String username, String firstName, String lastName, String emailAddress, String password, boolean setAccountEnabled) :  Create a Person  (cmSmiley Tongueerson) with the given username. 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, boolean notifyByEmail) :  Create a Person   (cmSmiley Tongueerson) with the given username. 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 (cmSmiley Tongueerson) 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


4.0_JavaScript_Services_API


Sites


4.0_JavaScript_Services_API


Transfer


4.0_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) Smiley Tongueads 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.

string longQName(string) :Returns the long version, of short prefixed QName.

boolean moduleInstalled(string) :check if a module is installed - module name (e.g. 'org.alfresco.module.foo')

string toISO8601(long): Format time in milliseconds to ISO8601 formatted string

string toISO8601(Date): Format date time to ISO8601 formatted string

Date fromISO8601(string): Parse a Date from ISO8601 formatted string

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