Skip navigation
All Places > Alfresco Content Services (ECM) > Blog > 2010 > April
2010
I've been working on CMIS at Alfresco for a very long time. After more than two years of specification definition, product development and preview releases, I can finally say 'go ahead, build your applications on Alfresco CMIS, it's ready for use'.



A few weeks ago, we released Alfresco 3.3 Community which introduced CMIS 1.0 among many other fine features. The specification itself is very close to becoming an official OASIS standard.



So, what do we provide? In a nutshell, an LGPL-licensed CMIS Repository with full support for the 1.0 specification including:



  • AtomPub and Web Service Bindings


  • CMIS Query Language for searching the repository


  • Navigation services for browsing the repository


  • Object services for create, update and delete of meta-data and content


  • Relationship services for creating and traversing associations


  • Versioning services for checkout / checkin and history


  • Type Definition services for describing meta-data and content


  • Access Control services for examining and applying permissions


  • Rendition services for accessing alternate views of content


  • Change Log services for determining what's changed in the repository



Unfortunately, Aspects did not make it into the CMIS 1.0 specification. Alfresco wouldn't be Alfresco without Aspects, so we decided to expose Aspects via the extension mechanism of CMIS, allowing the bindings to play with Aspect coolness. Hopefully, Aspects will appear in CMIS 2.0.



We also map many other Alfresco features through CMIS such as:


As has always been the case since our first CMIS release back in 2008, we're already receiving lots of great feedback on Alfresco 3.3 CMIS which I thank everyone for. We'll be releasing a follow-up to Alfresco 3.3 Community in May primarily to introduce the Google Docs integration, but this will also contain CMIS bug fixes and minor enhancements. A hosted version of Alfresco CMIS is continually updated to the latest 'in development' version at http://cmis.alfresco.com.



CMIS specifies a set of protocols, not a programming API. To make it as simple as possible to build applications on CMIS, the Apache Chemistry project provides a CMIS Java Client API, named OpenCMIS. You can think of it as the JDBC of CMIS. As well as contributing to OpenCMIS, we're also currently working on incorporating OpenCMIS into Spring Surf to provide a development environment for building CMIS based Web Applications. Of course, this environment can be used with Alfresco 3.3.



With all this in place, you can go ahead, build your applications on Alfresco CMIS, it's ready for use.
A lot has happened since my last post over a year ago!

Full support for metadata is now available in Share, forms are used in several key areas of Share including the datalists feature and the Web Editor product is centered around the forms capabilities.

With forms becoming more prevalent I thought it might be useful to have an easy way to find, run and learn from examples as well as providing utilities to help configure and customize your own forms.

The Forms Development Kit (FDK) was introduced in the 3.3 release, being fairly new it currently consists of a few example form configurations (using 3 custom types and a custom aspect), custom templates & controls and a 'Form Console' utility. One of the example forms is shown in the screenshot below.

Tabbed form example

The intention for the future is to provide working demonstrations of all the example configurations given in the Forms wiki pages, to host 'incubator' controls, provide a testing platform for our internal QA department, show how the forms engine can be customized to suit your needs and of course provide utilities to help you configure your own forms.

The FDK can be accessed from the 3.3 community release download page, full details on how to install and use it are given on the FDK wiki page.
With Alfresco 3.3, the Share content collaboration platform has never been easier to develop for! With the integration of SpringSurf in Alfresco 3.3, plus a number of improved debugging features, the edit->test->debug development cycle for Share pages and components is more rapid than ever. Once set-up, it can take literally seconds to see the results of changes to any WebScripts, templates, JavaScript or CSS files. This post is a collection of tips direct from Alfresco Engineering on how to set-up your environment, tweak the default Share configuration, debug scripts and enable the fastest possible development cycle.

Get the Tools You Need



Your favorite developers text editor. Obviously. But that's pretty much all you need to work with Alfresco WebScripts, FreeMarker templates and JavaScript text files - you don't need anything heavier, but something like Eclipse or IntelliJ will do nicely if you prefer.



Firefox plus the Firebug extension or Google Chrome - because of the nifty HTML, CSS inspection and JavaScript debugging features. Most Alfresco devs prefer the Firefox+Firebug combination as the features are currently stronger than the dev tools built into Chrome, and it gives more accurate and descriptive JavaScript errors - but Chrome is catching up with every release and it's certainly noticably faster at processing JavaScript and general rendering.

Setting up a Folder Structure



See this previous post on how to set-up your folder structure for creating Share pages, components and WebScripts. It also discusses using the SpringSurf resource servlet to easily access web assets such as images, CSS and client-side JavaScript in your templates and components from within the same folder structure.

During Development Deploy Files and Folders - not a JAR!



Create a quick shell or ant script to copy your working files and folder structure to your tomcat Share classes folder. You can then work on your assets easily and quickly deploy them all to a running Alfresco server. The previous post describes how to package them up for run-time deployment as a single JAR - but that isn't needed during development, and in fact isn't really desirable - having the files and folders expanded out ensures quicker deployment and ensures the various config options discussed below will work correctly.

share-config-custom.xml



Share is configured by various Spring config files and Alfresco format config files. These are easy enough to override. There's really only one file you need to worry about for most situations. The default config override file that Share is already set-up to look for is called share-config-custom.xml and should be placed in your $TOMCAT_HOME$/shared/classes/alfresco/web-extension folder. Here you can override various configuration settings and several of the most useful ones for development and debugging will be discussed here. If you do want to override Spring beans, then Share will look for a file called custom-slingshot-application-context.xml and it should be placed in the same folder. Generally unless you are modifying Surf internals you won't need to override the Spring beans.



A default installation of Alfresco will include a .sample version of these files in the above location, they can also be found in the source tree: HEAD/root/projects/slingshot/config/alfresco/web-extension

Debugging client-side JavaScript



Here's an example of a share-config-custom.xml file with the correct config to turn on client-side JavaScript debugging. You may be wondering why you need to do this, after all surely it's just a matter of turning on FireBug and getting on with it? But for performance reasons, Share will include minimized versions of its client-side JavaScript files during page rendering - it will even combine some of the files - which don't make for useful debugging. Turning on the client-debug flag forces Share to load the original uncompressed source with all comments and formatting intact, perfect for debugging into. It also ensures the various YUI library files are uncompressed - if you are feeling brave enough to poke around in them.

   <alfresco-config>



      <!-- Global config section -->

      <config replace='true'>

         <flags>

            <!-- Developer debugging setting - DEBUG mode for client scripts in the browser -->

            <client-debug>true</client-debug>



            <!-- LOGGING can be toggled at runtime when in DEBUG mode (Ctrl, Ctrl, Shift, Shift).

                 This flag automatically activates logging on page load. -->

            <client-debug-autologging>false</client-debug-autologging>

         </flags>

      </config>



   </alfresco-config>


Restarting the server is required if you make changes to this file. Force a refresh of Share in your browser and you will then be able to use FireBug or the Chrome debugger tool to set breakpoints and debug the client-side JavaScript of Share components.



You'll notice the client-debug-autologging flag in the example above. There is a logging feature in Share that allows a developer to make use of log4j style debugging methods in client-side JavaScript. It's not a commonly used feature as it's pretty low-level, but if you can't solve your issue with breakpoint style debugging then logging may be useful. The flag is used to automatically active the logging output window in Share rather than having to toggle it with a funky key combination.



To log from within your client-side JavaScript:

if (Alfresco.logger.isDebugEnabled())

   Alfresco.logger.debug('some string value');


The log4j info, warn, error and fatal levels can be used if required.

SpringSurf Development Mode



SpringSurf has a number of autowire configuration modes. By default Share is configured in the 'production' mode - this ensures that web-tier JavaScript and FreeMarker templates are compiled and cached for maximum performance. For development, it is much more useful to have JavaScript and templates not cached. As mentioned above this allows simple scripts to quickly copy over new versions of files and see the results immediately in the application - no restarts required.



This is an example of the config required for share-config-custom.xml:

   <alfresco-config>



       <config evaluator='string-compare' condition='WebFramework'>

           <web-framework>

               <!-- Autowire Runtime Settings -->

               <autowire>

                   <!-- Pick the mode: development, preview, production -->

                   <mode>development</mode>

               </autowire>

           </web-framework>

       </config>



   </alfresco-config>


Web-Tier JavaScript debugging



Share SpringSurf components are simply a special case of an Alfresco WebScript - with a few additional rules and restrictions on what objects are available and what presentation templates can output. The web-tier JavaScript controller associated with a WebScript can be debugged via the Rhino debugger window. Once 'development' mode is activated as mentioned above, the script debugger will be able to break on JavaScript functions and breakpoints. To turn on the debugger, use the browser to navigate to /<yourserver>/share/service/index - this will display the WebScripts index page. Click the Alfresco JavaScript Debugger link and then Enable. A Java GUI window will appear, this is the Rhino debugger interface. The easiest way to get into the web-tier JavaScript is to select Debug->Break On Function Enter from the menus. The next WebScript that is executed in the app will break in the debugger. Once the appropriate source files are loaded breakpoints can be added and the Break On Function Enter can be disabled to reduce the noise during debugging.

Web-Tier Javascript Logging



Logging from within WebScript code can be another useful debugging aid. On both the Repository and Web-Tier, the 'logger' root scoped JavaScript object is available for simple logging tasks. The output is directed to the App-Server console window.



logger object API:

boolean logger.isDebugEnabled() - returns true/false to indicate if debug logging output via log4j is active,

this can be used to ensure performance isn't degraded when console logging is inactive.


void logger.log(string message) - output a log message to the console


To turn on logging for your application, modify the log4j.properties file and set the following class to debug:

log4j.logger.org.alfresco.repo.jscript.ScriptLogger=debug


Note that the same logging class name is used by the Alfresco repository and SpringSurf - it is maintained for backward compatibility.

Refreshing WebScripts



On a production deployed instance of Share or any instance where all the various debug settings noted above are not applied, most caching and refresh issues can be quickly resolved without restarting the app-server. The Refresh WebScripts option in the Share WebScript index page can be used to clear the caches for all components and compiled scripts. It also means that additional WebScripts can be deployed or removed at runtime without restart. Use the browser to navigate to /<yourserver>/share/service/index - this will display the WebScripts index page. Click the Refresh Webscripts button to clear the caches and refresh the list of available WebScripts.

Separate Alfresco and Share Server Instances



Since Alfresco 3.0, the Share client is a stand-alone web-application and the share.war can be deployed on a separate TomCat instance to the Alfresco repository, on another server entirely if required. This is recommended for development and production. For development, it enables the Share application to be restarted quickly (a few seconds on a modern laptop or server) without interfering with the main Alfresco repository instance. For production, it allows proxies and clustering to be implemented.



The configuration to do this is simple, but first it requires the set-up of a new TomCat instance, with appropriate tweaks as recommended for an Alfresco server such as; JVM memory settings, server URIEncoding set to UTF-8, web-extension folder etc. The easiest way to do this is to take a copy of the Alfresco installed TomCat instance and remove the alfresco.war. If you are running the new TomCat instance on the same machine as the Alfresco repository instance then modify the port settings in tomcat/conf/server.xml to ensure Share can be started at the same time as Alfresco. Developers at Alfresco generally use port 8080 for Alfresco and port 8081 for Share.



By default the Share web-application will attempt to communicate with the Alfresco server via HTTP on port 8080. There should be no additional configuration required if you use those settings. However if your Alfresco instance is not running on this port then the following example of configuration for share-config-custom.xml can be used to modify the endpoint settings, change the endpoint-url values as appropriate:

   <!-- Overriding endpoints to reference a remote Alfresco server -->

   <config evaluator='string-compare' condition='Remote'>

      <remote>

         <endpoint>

            <id>alfresco-noauth</id>

            <name>Alfresco - unauthenticated access</name>

            <description>Access to Alfresco Repository WebScripts that do not require authentication</description>

            <connector-id>alfresco</connector-id>

            <endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>

            <identity>none</identity>

         </endpoint>



         <endpoint>

            <id>alfresco</id>

            <name>Alfresco - user access</name>

            <description>Access to Alfresco Repository WebScripts that require user authentication</description>

            <connector-id>alfresco</connector-id>

            <endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>

            <identity>user</identity>

         </endpoint>



         <endpoint>

            <id>alfresco-feed</id>

            <name>Alfresco Feed</name>

            <description>Alfresco Feed - supports basic HTTP authentication via the EndPointProxyServlet</description>

            <connector-id>http</connector-id>

            <endpoint-url>http://localhost:8080/alfresco/s</endpoint-url>

            <basic-auth>true</basic-auth>

            <identity>user</identity>

         </endpoint>

      </remote>

   </config>


Conclusion



Hopefully this list of tips should help speed up development and improve your experience when customising and working with Alfresco Share components. In the next post we will explore the architecture of SpringSurf components, templates and page rendering.

Over the past few months I have talked to lots of people interested in the Alfresco Records Management solution. There are a number of reoccurring themes and topics that have come up. I thought I would share some of this advice, so below is a list of things to think about when considering adopting a Records Management solution.



1) Technology is Not the Answer



Many companies think that technology is the solution to provide them with a ‘quick fix’ to their compliance needs. The reality is that compliance is more complex than traditional Document Management or Collaboration. It is very easy to roll out a DM or Collaboration solution, allowing your end users to use it to manage the content that they are creating each day. But Compliance, the art of identifying and managing vital company records, is more complex.



Companies need to understand their legal obligations and put in place policies and procedures to address their compliance needs. Technology can help but it is not the answer. 



2) Understand your Legal Obligations



Compliance requirements will be different for each company and these are typically based on legislation and industry regulations. Companies need to research what their legal obligations are and develop a plan for how they are going to address their compliance needs. Things to consider include:





  • What types of document need to be managed (e.g. Financial Reports, HR files, Standard Operating Procedures, Email)?


  • How long do records need to be kept?


  • Do records need to be reviewed, and if so how often?


  • What should happen to records at the end of their life (transfer, destroy)?


  • Who should have access to file and declare records?



Only when they have a good understanding of these legal obligations should they start to develop policies and procedures that define your records management strategy.



3) Put in Place Policies and Procedure



Companies need to develop policies and procedures that can be communicated to the rest of the organisation. These policies and procedures need to be understood and easy to follow. It is no longer acceptable to state that a procedure was in place but that the company was not liable because an employee failed to follow it. It is the company’s legal responsibility to make sure all policies are being followed.



4) Make it Simple



Any compliance solution that is difficult to use is going to fail. When choosing a Records Management solution make sure that it is easy to use and can be used by any employee without disrupting the way that they work. One way of working will not necessarily work for every employee; in fact some employees may use multiple means to file records depending on what they are doing at the time. The way that employees want to interact with the compliance system will include:





  • Desktop access – Using drag ‘n drop to file records directly from the desktop


  • Email access – Using standard email clients to file emails and their attachments


  • The Web – Providing RM specific web clients


  • From DM or Collaboration – Content has a lifecycle before it needs to be filed as a record, make it easy to file once it is approved


  • Scanning – We are still waiting for the paperless office, so being able to capture and file paper is important



5) Try Alfresco



Having said that technology is NOT the answer it is part of the solution. Companies are looking for an easy to use, lower cost solution that will fit into their existing environment and business practices. By designing the Alfresco Records Management Solution on top of the Open Source Alfresco content management platform, Alfresco provides a single solution to allow companies to easily address their Document Management, Collaboration, Web Content Management, Imaging and Compliance needs through one simple system.



But don’t take my word for it, try it for yourself... take the Records Management challenge – start filing records with Alfresco in under 10 minutes...








Filter Blog

By date: By tag: