Category: cmislib

Seven Options for Scripting Against Alfresco

It is often necessary to perform bulk operations against the data in your Alfresco repository. Frequently, writing a quick script, rather than a full application, is the best approach. Sometimes those scripts need to be scheduled, like with a cron job, or given to power users to run ad hoc.

The good news is that there are many options available depending on what you need to do and personal preference.

All of these options can be used to develop full-blown applications, but the focus in this post is on how well each option works specifically for the scripting use case.

JavaScript Console
License: Apache 2.0
Link: https://github.com/share-extras/js-console
Install: Repo and Share AMPs, requires restart

The JavaScript Console provides a user interface within Share to interactively run server-side scripts that leverage the Alfresco JavaScript API. The UI features syntax highlighting and code completion.

This is a must-have tool for both developers and administrators. It is the fastest way to perform bulk tasks or to test out JavaScript logic before using it in something harder to debug or change, such as in the controller of a web script. I install this on every server I touch. I suppose that, eventually, as Share falls out of favor, this will be less of a go-to option, but, for now, it is essential.

The JavaScript Console is only available to administrators, so this is not an option if you are developing something that will be invoked by non-admins.

Apache Chemistry CMIS Workbench
License: Apache 2.0
Link: https://chemistry.apache.org/java/developing/tools/dev-tools-workbench.html
Install: On your own desktop, no server config/restart required

The Apache Chemistry CMIS Workbench is a desktop application that uses pure CMIS calls to communicate with the repository. It contains a lot of useful features such as a CMIS Query Language console, a node browser, a data dictionary browser, and a Groovy console. The Groovy console is similar to the JavaScript console in that it can be used to quickly script repetitive tasks, but instead of JavaScript it uses Apache Groovy. If you aren’t familiar with Groovy but you know Java, you can use Java in the Groovy console–Groovy is a JVM language and is happy to interpret your Java syntax.

This tool is particularly useful if you are writing code that leverages CMIS. If you can do it in the Workbench you can be confident you can do it from your CMIS-based application. However, it is also useful when you just need to execute some repetitive tasks, especially if the server in question does not have the JavaScript Console installed.

Unlike the JavaScript Console, however, you are limited by what is supported in the CMIS specification. For example, you cannot manage users, groups, or workflows, just to name a few. It is pretty much limited to documents, folders, and items (content-less objects). Custom content models, however, are fully-supported.

The Swing-based UI of the workbench has a face only a mother could love so this is definitely not something you’d put in the hands of typical end-users.

Apache Chemistry cmislib (Python client)
License: Apache 2.0
Link: https://chemistry.apache.org/python/cmislib.html
Install: Client library, no server config/restart required

If what you need to do is covered by the CMIS specification but you prefer Python, then Apache Chemistry cmislib might be a good choice. It is a client library that you can use from your own Python scripts and applications. For example, if I need to generate a bunch of folders or documents, I’ll often just write a quick Python script to do it.

The library has the same limitation as the Workbench in that it only makes CMIS calls, but if that’s all you need it should work well. The current release requires Python 2.7 but a new release that supports Python 3.x is being tested now.

If you are giving the script to power users who might want to make tweaks this can be a good choice if they already have Python installed.

Apache Chemistry OpenCMIS (Java client)
License: Apache 2.0
Link: https://chemistry.apache.org/java/opencmis.html
Install: Client library, no server config/restart required

Rounding out my CMIS-related recommendations is Apache Chemistry OpenCMIS. Like cmislib, it is a client library, but this one is written in Java and is much more mature and more widely-used. For quick scripts you can use Groovy on the command-line to make CMIS calls against Alfresco via OpenCMIS. Often, I already have my Java IDE open anyway, so it can be just as quick to write a little runnable Java class that uses OpenCMIS to carry out some tasks.

I use Groovy scripts and OpenCMIS when I want to automate tasks that power users are going to run from the command-line that they may want to tweak, but who do not have Python installed.

When a single script needs to perform operations that are a mix of CMIS and non-CMIS, I use Groovy’s HTTP client to call the Alfresco REST API (more on that, below).

Alfresco Web Script Framework
License: LGPL v3
Link: https://docs.alfresco.com/5.2/concepts/ws-framework.html
Install: For quick scripts, copy to Data Dictionary

Strictly speaking, web scripts weren’t built to be a “quick scripting” option, but they’ll work in a pinch. Basically, you just write a web script that does what you need it to do, but instead of packaging the web script into an AMP like you would for a production extension, you deploy the web script to the running repository by copying the web script related files into the Data Dictionary’s Web Scripts folder. The next step is to refresh the web scripts via the web script console. After that the web script can be invoked in a browser, via CuRL, or Postman.

Just like the JavaScript Console, you are limited to what the Alfresco JavaScript API can do, but that is definitely a broader set of capabilities than a CMIS-based solution.

Files in the Data Dictionary can only be edited by administrators, so if the folks running this script need to make changes and aren’t administrators, this won’t work. You can always build that flexibility into the web script and let them control various options by what they pass to the web script.

For more information on Web Scripts, see the documentation link above or check out my tutorial.

Alfresco Client-side JavaScript API
License: Apache 2.0
Link: https://github.com/Alfresco/alfresco-js-api
Install: Node Package Manager

A relatively new kid on the block is the Alfresco Client-side JavaScript API, aka, alfresco-js, which is part of the Alfresco Developer Framework (ADF). Of course you can use it to develop custom user interfaces in your favorite JavaScript framework, but you can also use it for quick scripting needs. For example, you could write a Node.js script and run it from the command-line.

The alfresco-js library relies on the Alfresco REST API that was created in 5.2, so if you need to work with an older Alfresco version, this isn’t an option. The alfresco-js library and the REST API are both under active development, so there could be gaps and some instability, but it is still worth taking a look, especially if you are already invested in the Node.js and NPM ecosystem.

Alfresco Content Services REST API (And others)
License: LGPL v3
Link: https://api-explorer.alfresco.com
Install: Your favorite REST client

Last, but not least, is the Alfresco Content Services REST API. If none of the other options in this list appeal to you, grab your favorite REST client or import your preferred scripting language’s HTTP client library, head over to the Alfresco API Explorer, and get busy.

As mentioned above in the alfresco-js description, this option relies on Alfresco 5.2 or higher (5.2.d Community Edition, distributed as 201612).

If the Alfresco Content Services REST API doesn’t have what you need or you aren’t yet running 5.2 or higher, you could always hit the CMIS browser (JSON) binding, the CMIS atompub (XML) binding, out-of-the-box web scripts, or custom web scripts.

Depending on what you need to do, using a lower-level REST API may not be the fastest option in terms of development time because instead of working with higher-level wrapper classes it is up to you to issue the REST calls and parse the responses.

Summary

Hopefully you see some options in the above list that will work for you and your environment. I definitely recommend you get a few of these in place now (especially the JavaScript Console) because if you ever need them in a hurry (oh, if this keyboard could talk!), you’ll want to have a quick scripting option you are comfortable and proficient with.

Photo Credit: Quality Quick Cleaning by GmanViz, by-nc-nd 2.0

Apache Chemistry cmislib 0.6.0 released

It has been far too long since our last Apache Chemistry cmislib release, but we finally managed to get one out. The new release, 0.6.0, features support for the browser binding as well as many fixes contributed by the community.

If you make no changes to your code the library will continue to use the Atom Pub binding, by default. But, the browser binding, which communicates with CMIS 1.1-compliant repositories using HTML forms and JSON, is often preferable because it may be more performant than the XML-based Atom Pub binding.

To use the new browser binding, import it, then pass it to the CmisClient constructor, like this:

from cmislib.browser.binding import BrowserBinding
client = CmisClient('http://localhost:8081/chemistry/browser',
   'admin',
   'admin',
   binding=BrowserBinding())

From there everything works like it always has.

For more information, please see the docs. If you have issues, please file a Jira with as much detail as possible, including the vendor and version of the repository you are working with. And if you have a fix, include that in your Jira. Contributions are welcome!

 

Announcement: Apache Chemistry cmislib 0.5.1 now available

The Apache Chemistry project is pleased to announce that cmislib 0.5.1 is now available (home, docs). Developers can use cmislib to write Python applications against any CMIS-compliant repository such as Alfresco, SharePoint, Nuxeo, and FileNet. You can download the client library from the Apache Chemistry cmislib home page or use Setup Tools to install the library quickly and easily.

This release features support for renditions, so if your repository supports things like thumbnails, you can retrieve a list of those for a given object. The new release also supports passing in arbitrary HTTP headers. That is one way to enable authentication scenarios beyond basic authentication such as OAuth2, which is the authentication mechanism Alfresco in the Cloud uses.

If you are brand new to CMIS, here are a few links to get you started:

In addition, I’ve been working on an Apache Chemistry and CMIS in Action book with Jay Brown and Florian Mueller. The book is available now through Manning’s early-access program.

The Public Alfresco API is Now Live: How to Get Started

At JavaOne this morning, Alfresco announced the general availability of the public Alfresco API. The public Alfresco API allows developers to create custom applications (desktop, mobile, or cloud) that persist content to Alfresco in the Cloud. The API includes CMIS plus some Alfresco REST calls that provide functionality CMIS does not cover.

Eventually, this public, versioned API will work against Alfresco in the Cloud as well as Alfresco running on-premise. For now, it is only for Alfresco in the Cloud, although the CMIS calls will work against both. (For example, on my flight to California I worked on an example using CMIS and my local repository. When I got to the hotel, I added in the OAuth authentication and my example worked against Alfresco in the Cloud).

To use the Alfresco API, all you have to do is become a registered developer at http://developer.alfresco.com. Once you’ve verified your email address, you can add applications to your profile. Each application has a unique authentication key and a secret. OAuth2 is used to handle authentication.

Once you have your authentication key and secret, you can start making calls against the API. Calls that hit the Alfresco REST part of the API return JSON. Calls that leverage CMIS return AtomPub XML. If you already know how to make CMIS calls, you already know how to use the Alfresco API–just grab the latest version of your favorite CMIS client, like OpenCMIS or cmislib, and pass in the authorization header. I believe you must use the 0.8.0-SNAPSHOT of OpenCMIS. If you are using cmislib, you’ll definitely need 0.5.1dev.

Here are some resources to help you get started:

If you want to discuss the public Alfresco API, use this forum and any of our other normal community channels like #alfresco on IRC or the Alfresco Technical Discussion Google Group.

Of course we’ll be talking about the API at DevCon in both Berlin and San Jose this November, so don’t forget to register!

Also, Peter Monks and I will be doing this month’s Tech Talk Live on the new API, so if you weren’t lucky enough to be in San Francisco for our session at JavaOne or our booth, you can catch the details there as well.

cmislib extension supports Alfresco aspects

I can’t believe I didn’t know about this sooner. It completely passed me by. Patrice Collardez created an extension for cmislib that gives it the capability to work with aspects. Patrice’s version works with cmislib 0.4.1. I cloned it and made the updates necessary for it to work with cmislib 0.5.

What this means is that you can now use Python and cmislib to work with Alfresco aspects. Patrice’s extension adds “addAspect”, “removeAspect” and “getAspects” to Document and Folder objects. It also allows you to call getProperties and updateProperties on Folders and Documents even when those properties are defined in an aspect.

Check it out:

properties = {}
properties['cmis:objectTypeId'] = "D:sc:whitepaper"
properties['cmis:name'] = fileName

docText = "This is a sample " + TYPE + " document called " + NAME

doc = folder.createDocumentFromString(fileName, properties, contentString=docText, contentType="text/plain")

# Add two custom aspects and set aspect-related properties
doc.addAspect('P:sc:webable')
doc.addAspect('P:sc:productRelated')
props = {}
props['sc:isActive'] = True
props['sc:published'] = datetime.datetime(2007, 4, 1)
props['sc:product'] = 'SomePortal'
props['sc:version'] = '1.1'
doc.updateProperties(props)

Also, if you saw the webinar yesterday you know I showed some Python examples in the shell, but I then switched over to some OpenCMIS Java examples in Eclipse that I included in the custom content types tutorial. I didn’t want my fellow Pythonistas to feel neglected, so I ported those OpenCMIS examples to Python. Grab them here.

The examples assume you also have Patrice’s extension installed (my clone if you are using cmislib 0.5). If you don’t want to use Patrice’s extension for some reason, just comment out the “import cmislibalf” statement as well as the lines in the createTestDoc method that deal with aspects and aspect-defined properties. You should then be able to run the examples in straight cmislib.

If you don’t have cmislib you can install it by typing “easy_install cmislib”.

Webinar: Getting Started with CMIS

If you are brand new to CMIS or have heard about it but aren’t sure how to get started, you might want to join me in a free webinar on Thursday, January 26 at 15:00 GMT. I’m going to give a brief intro to the Content Management Interoperability Services (CMIS) standard and then I’m going to jump right in to examples that leverage Apache Chemistry OpenCMIS (Java), Apache Chemistry cmislib (Python), and Groovy (via the OpenCMIS Workbench).

UPDATED on 1/26 to fix webinar link (thanks, Alessandro). See comments for a link to webinar recording and slides.

Apache Chemistry cmislib 0.4 incubating now available

Apache Chemistry LogoThe Apache Chemistry development team is pleased to announce that the 0.4 incubating release of cmislib, the Python client API for CMIS, is now available for download. You may have to use one of the backup servers until the mirrors fully update. Alternatively, you can use easy_install to install cmislib by typing “easy_install cmislib”.

This release has various fixes and enhancements that the community has contributed since cmislib joined the Apache Chemistry project with its 0.3 release. If you are using Alfresco, you might be interested in an enhancement in cmislib 0.4 that makes it possible to use ticket-based authentication instead of basic auth.

For those who haven’t used it, cmislib makes it easy to work with CMIS-compliant repositories from Python.