BLOG

RAD! Alfresco SDK 3.0. Upgrade and enjoy!

Why upgrade SDK 3.0?

  • Support for RAD (Rapid Application Development) and TDD (Test Driven Development) via HotswapAgent and JRebel
  • Simpler SDK layout
  • Jar packaging by default
  • Support for Alfresco version 4.2 to 5.2
  • Integration testing webscripts

TL;DR

  • Update your pom.xml
  • Remove all SDK modules, except for your jar/amp project modules.
  • Update your Integration tests.
  • Add integration-tests project module, and copy src directory.
  • Re-organize your Integration tests into the integration-tests project module, and rename to *IT.java.
  • Search and replace default project name with your project name where exists.

Upgrade Notes

The instructions provided in this article is based on an SDK upgrade from Alfresco SDK 2.1.1 to Alfresco SDK 3.0

Vanilla for Reference

To get started with the upgrade, we’ll need a vanilla version of the 3.0 SDK project to get some of the new files and configurations that we’ll need.

Do this by using one of the following maven commands to generate an all in one project:

 

If you don’t see the option for SDK 3.0, then use this command as per Ohej’s note

Update our poms

First pom.xml to update would be the main pom.xml of our project.

In this pom, we will remove the alfresco-sdk-parent. With SDK 3.0, we no longer need a parent project.

Main pom.xml

Update the properties in this pom.xml with the properties from our vanilla project

Instead of Java 7 source/target, I prefer Java 8 targets.

Next we update the dependencyManagement section with the elements from the vanilla template

In the build section, we will update the pluginManagement, and the plugins section.

For the plugins section, copy and paste the section from our vanilla pom.xml, and update the moduleDependency to include your project’s modules. Your repository module will be under the <platformModules> section, and your Share modules will be under the <shareModules> section.

Add the resources section

We will then add the resources section that will provide access to the 3.0 SDK dependencies.

Finally, for this pom.xml, we will remove the <profile> section, and update our <modules> section so that we remove the old SDK module dependencies, and add the new integration-tests module. The update will look like this:

pom.xml for your repository projects

If you’re changing your packaging type, like I did from amp to jar, then, update your packaging type here

Remove the following dependency, as it’s no longer needed

Remove the profiles section

And add the build section from the vanilla template

Next pom.xml for Share project modules

Again, if you’re switching from amp to jar, then you can update the <packaging> section

Update the dependencies section, to remove the integration test suite dependencies, like selenium, etc.

Then add the build section, and we’re good to go:

 

Copy some files

Copy the top level src directory over

Copy the src directory from the vanilla project over to your project at the same level.

From the files we copied, update the platform-hotswap-agent.properties, and share-hotswap-agent.properties, and do a search and replace for the name of your vanilla-project-share-jar, and vanilla-project-platform-jar. For example, my vanilla project was named my-aio-project.

and replace with the name of your shareui project module.

Do the same for

and replace with the name of your repository project module.

Copy the integration-tests module over

From the files you copied over, remove the sample IT test cases and package, and add your own.

Additionally, update the parent settings in the pom.xml so that the parent is your main project.

Migrating our Integration Tests

In migrating our IT tests, we’ll need to ensure that the test names end in IT. For example MyTest should be MyTestIT.

Next, we’ll remove the old RunWith dependency, and add the new ones.

For example

Will become

Our IT test, will then need to extend the following class.

Different approaches for setting up our integration tests can be found in the vanilla package that we generated. Use the way that best fits your model.

In this approach, @Autowire will not work, so we’ll need to update our @Before method to initialize our service dependencies.

For example:

 

Spin it up

Next, start up your project with the following command

If you have the JRebel plugin in intellij, run your command using the jrebel executors

 

Troubleshooting

 

http connection errors when you attempt to start up the repository

For example:

Connect to localhost:8080 [localhost/127.0.0.1, localhost/0:0:0:0:0:0:0:1, localhost/fe80:0:0:0:0:0:0:1%1] failed: Connection refused

Review your integration tests and verify that their names end in IT.java. For example MyTestIT.java Test cases that end in *IT.java will not be executed through the maven test phase. Also verify that you’re using the correct version of maven: mvn 3.3.3

 

References

Smart Lighting

Overview

Smarter automated lighting can be achieved a few different ways, but the end result could all be similar. In that, lights can respond in hue, lumens and brightness based on time of the day, events such as motion, open/closed door, temperature, music, waking up, mood, etc.

Automated lighting can be implemented with one or more of the following, connected z-wave/zigbee switches, wifi/z-wave/zigbee smart plugs, wifi/zwave/zigbee bubls, or bulbs integrated via a bulb controlling hub.

In my implementations I use various of each, as each version has different implementation pros/cons. All applications can be integrated with Google Home via Smartthings.

 

Smart Bulbs

Philips Hue 3rd Generation A19
Osram Lightify

The average price for these bulbs is around $30 for a single color dimmable A19 bulb; or $40 for a RGB dimmable A19 bulb. Since the price for these bulbs are pretty high, I would use them in a 1 switch to bulb applications; such as a bedroom light, or overhead office light.

GE Connected Bulb

 

This is because the price for a z-wave switch is about $35, and installation of these bulbs are much simpler than a switch. The cons with this approach, is that it can be expensive to set up smart bulbs in a light cluster, such as kitchen lights. And although these bulbs promise a very long lifespan, if they were to be replaced, it increases the cost of the application.

 

Smart Switch

GE Z-Wave switch

Light switches are great for controlling light clusters, where you would want all the bulbs in the cluster to respond in unity; such as kitchen lights, or bathroom mirror lights. There’s also 3 way z-wave switches that can be used to replace an existing 3 way switch setup; however this can be a little complex, as you’d have to know how your 3 way switch is wired, and re-design the wiring to work with your smart 3 way switch.

Z-Wave 3 way switch

The cons here, is that this approach is more complex to install, as you’d have to remove your existing switch, and replace with these.

 

Smart Plugs

GE Dimmable Smart Plug

Smart plugs, are by far the simplest to install and use. You generally plug them into your outlet, then plug your device into them. The device that you plug in should be ones that are controlled by a manual on/off switch, and these can include lamps, heaters, humidifiers, dehumidifiers, etc.

iHome Smart Plug

The smart plugs also come in 2 versions, a regular on/off smart plug, and a dimmable smart plug; so you can turn your plain old lamp, with a dimmable bulb into a dimmable lamp. Smart plugs are generally a bit pricier than in-wall smart outlets, and can run at about $40 per plug. If you don’t have a Smart hub yet, then there are wifi based models, that can work directly with an app on your smart phone, and can also be programmable.

Smart Outlets

GE Z-Wave Outlet

Smart outlets can be used in very similar applications to that of Smart plugs. The differences being that they’re installed flat into the wall, and don’t protrude like the wall plugs, and they’re mostly z-wave, or zigbee and needs a smart hub to be programmed. They’re also generally cheaper, but needs to be installed.

 

Lighting Hubs

Lighting hubs are smart hubs specifically designed to control bulbs. These include Philips Hue Bridge, and Osram Wireless Gateway. These hubs are useful if you would like to have your lights respond to music, moves, where each bulb or cluster changes hue, temperature, and brightness.

SYLVANIA LIGHTIFY by Osram – Wireless Gateway / Hub / Bridge
Philips Hue Starter Kit

The Smart Hub

Overview

The next phase to a smarter home is to select a smart hub. There are quite a few on the market, which includes: Smart Things by Samsung, Wink 2, Hue Bridge etc. And there are a ton of reviews out there to help chose the right one.

After a lot of reviews and research, I decided that the Smart Things starter pack was the best fit for my use cases. My requirements were z-wave, zigbee, wifi, Google Home, and an open source SDK, and enough gadgets to get started.

The Smart Things starter kit comes with a motion sensor, 2 open/close + temperature sensor, and a smart plug which also acts as a z-wave and zigbee repeater. The gadgets are very small, and can be easily installed out of sight.

A lot of the rules, and configurations are very simple out of the box. With this package you will have access to program one device for now; not much to start, so we’ll have to upgrade a few more devices in the home to make full use of the hub.

Installation

Installing the Smart Things hubs and associated gadgets are very simple. It’s pretty much:

  • Plug into router
  • Download App
  • Walk through setup on app.

Use Cases

Here are some use cases that can be achieved with the Smart Things hub.

  • Automatically turn on lights when you come home
  • Automatically turn on/turn off heating/cooling based on presence; time of day; or based on motion. For instance, fall asleep at cooler temperature, and wake up to a warmer room, that slowly brightens like the sun rising, while music of your preference also rise to an acceptable level in the back ground; all this as your coffee maker kicks on to start making your morning brew.
  • Automatically turn on lights to a specific level when doors are opened, or motion is sensed at a specific time of day or night. So that when you wake up for a glass of water, the lights turn on at 10% brightness, so that it doesn’t wake you up, and you have enough light to make it to your kitchen.
  • Automatically turn off all lights when you leave home, as your phone acts as a presence sensor.
  • Control the humidity in rooms
  • And more

 

Smart Home Level 1: Automatic Lighting

Overview

Another cheap easy way to automate lighting in your home, is to use motion sensed or occupancy sensed switches. These switches are good for places like laundry rooms, half bathrooms, boiler rooms, walk in pantries, etc.

  • Time to implement 30mins
  • Complexity: Easy
  • Cost: < $20

Safety First

Always remember when working with electricity, to turn off the breaker or fuse to the area that you’ll be working in. Additionally, wear rubber gloves, and use well insulated tools to avoid any accidental contact with a live wire. When joining wires always secure them with wire nuts, splicing sleeves or electrical tape.

 

Requirements

Instructions

  • Turn off power to switch that you’re changing
  • Remove wall plate for the switch
  • Remove screws that hold the switch in its housing
  • Remove wiring from current switch
  • Wire up new occupancy sensor — the sensor pins should be self explanatory; red, black, and ground. Incase the wiring isn’t clear from first glance, be sure to read the instructions that comes with the switch.
  • Mount your new switch back into the housing
  • Cover up with the wall plate

Power on, and enjoy the hands free motion activated switch!

Smart Home Level 1: Simple Automatic Lighting

Overview

Light automation can be the simplest and cheapest forms of automation that can be implemented in your home. This guide will provide a way for you to implement a closet light that turns on when the closet door is opened; and off when the door is closed.

  • Time to implement: 30 mins to 1 hour
  • Complexity: Easy
  • Cost: less than $30

Safety First

Always remember when working with electricity, to turn off the breaker or fuse to the area that you’ll be working in. Additionally, wear rubber gloves, and use well insulated tools to avoid any accidental contact with a live wire. When joining wires always secure them with wire nuts, splicing sleeves or electrical tape.

Requirements

Instructions

Locate the outlet that will provide power to your lights. It’s preferable if this source is hidden, and away from view. In my installation a hole was drilled to the back of an exiting power outlet, and the wires to the power supply were spliced and joined to this circuit.

Next, the wires for the light were spliced and connected to the magnetic switch, such that when the magnetic switch is apart, the switch is opened; and when the magnets are close, the switch is closed. This would be the Normally Closed Configuration.

Review your wiring, light, switch, and power source layout, so that when the light is installed, the connector is available to the magnetic switch; and the magnetic switch is within reach of the power source, while positioned on the door and door frame so it can open/close with the door. Open door = closed switch; Closed door = open switch.

Proceed to install the light by sticking it in position. I stuck mine against the door frame so that It’s out of view, and the focus into the closet.

 

Connect the end of the light to the switch, and install the switch against the door/door frame; followed by connecting the switch to the power source.

Turn your breaker/fuse back on, and if all was aligned properly, your closet should light up when you open the door; and go dark when you close the door.

Cooking an ECM Solution

cooking-an-ecmIT departments today manage a massive amount of information, via a plethora of interconnected software components to provide businesses with the mission critical results that they need. To ensure the quality of these systems, IT departments are heavily invested in the testing, tuning and validation of these systems. The thought of validating these systems are already overwhelming, as a typical large-scale ECM system may consist of around 10 components, of which infrastructures must be provisioned, system configurations must be deployed, and all tasks must be repeated in at least four environments: development, staging, quality assurance and production. However, to alleviate the burden of this daunting procedure, allow me to introduce you to Alfresco Boxes, an open source project that is dedicated to building recipes for deploying Alfresco into many complex environments, including Amazon Cloud, VMware data centers, physical hardware, or a mixture of these environments.

Alfresco Boxes is an open source project that was started by and maintained by an Alfresco consultant, Maurizio, and has since gained contributions from other members of the community. The project, which can be found on Github, consists of JavaScript Object Notation (JSON) configurations files that are known as recipes, for deploying Alfresco and all its prerequisites onto preconfigured platforms. The tools that support this project are Vagrant, Packer, Chef, and Docker.

Like the preparation of a Thanksgiving dinner, the recipe for installing Alfresco, is dependent on many other recipes that were provided by the open source community, such as Apache Tomcat, Ubuntu, CentOS, Java, etc. And like a Thanksgiving dinner, users can adapt the recipes to their requirements. For instance, the recipe can be modified to use JBoss instead of Tomcat, adding more memory to the Java Heap, or changing Database configurations.

Once the recipes for your Alfresco deployment are tested and validated, they can be packaged into Virtual Box, VMware or Amazon images for deployment. If deployment is on physical hardware, then chef-solo can be used for implementing the recipes on those machines.

With recipes in hand, system administrators and operators can easily replicate their Alfresco ECM solution on as many environments that they may need. Such as, development, staging, quality assurance, load testing, and production.

For more information on this project:

Visit the Alfresco Summit where Maurizio will be presenting on this topic.

Visit the Github project: Alfresco Boxes,

Visit this Alfresco Boxes blog where Luis presents step by step instructions and his experience with the project.

Alfresco:/Sites/Smart/Document/Structure

site-rules-js-stUsing Alfresco One, it is very simple to extend the document structure that is deployed upon a Site creation. An automatic structure deployment can allow for a group of rules, folder structure and documents and other functionalities to be created within a site, when the site is instantiated. The nice thing about this functionality, is that it can be implemented from the GUI with the use of Rules, Scripts and Space Templates.

To implement this functionality, first we will define our  folder structure under /Data Dictionary/Space Templates. The folder structure that we define can be simple structures, or smart structures with additional rules and actions. For the purposes of this project, we’ll use the example template for a Software Engineering Project, as depicted in the following photo.Space Templates The Software Engineering Project template is provided by the default installation of Alfresco, and contains a subdirectory structure for maintaing artifacts of a typical Software Engineering project.

Next we will define the Javascript that will provide the routines for implementing the template import into the Site when it is created.

This script will be defined under /Data Dictionary/Scripts/. The name of the javascript must end in .js, and the mimetype of the script’s properties should be set to “Javascript.” In our example we will define a script as follows:

Import Software Engineering Space Template.js

In the last step oAlfresco » Folder Rulesf our configurations, we will add a rule to the /Sites folder, where all sites in the system are created. This rule will listen for onCreate events within the directory, and execute whenever a folder with the Component Id property of the Site Container Aspect is set to documentLibrary. Which is one of the unique properties that identifies the Document Library within a site. This attribute can be selected by selecting “Show More” of the “If all criteria are met” section of the Rules definition form.
Alfresco_»_Folder_Rules 2

Selecting this option will open a modal window with a list of categories to choose from. In that list, choose “Aspects” on the left, and followed by “Site Container.” When Site Container is selected, you will have the option to select the Component Id property of the aspect to utilize in your rules criteria.

Once the Component Id is selected, set the validator expression to say “Equals” and fill in “documentLibrary” for the value. This rule will now execute when a folder with the Aspect of SiteContainer and Container Id property set to “documentLibrary.”

The last step of the rules definition form would be to add an action to perform when the rule is triggered. In this case, we’ll select the “Execute Script” as our action, followed by select the Javascript Import Software Engineering Space Template.js that we previously added.

Finally, select the checkbox “Rule applies to subfolders” and hit “Create.”

Our configurations are now completed, and we can test it by creating a new site and validating that our templates were copied.

Alfresco_»_User_Dashboard

Alfresco_»_Document_Library

Adding an evaluation filter to Alfresco’s form config

The Surf based Alfresco Share web application provides a highly customizable framework that allows you to override and customize the user interface via the share-config-custom.xml file. In this file, an evaluator element <config evaluator=”” condition=””> is used to target the elements for customization. These evaluators are managed by the SpringSurf XmlConfigService. This service is extended by the Alfresco web client framework to include the following default evaluators:

In addition to these you can implement your own evaluators. For example a StringRegexEvaluator that uses a regex to match any pattern defined in your share-custom-config.xml to override an element in the Share application. The two items needed for registering a custom evaluator is an evaluator plugin registration, along with the Java class that defines the Evaluator. For example:

 

And in your share-custom-config.xml, register the evaluator in the plug-ins element, as follows

Once this is in place, you can continue to to define your customizations in the share-config-custom.xml file using the string-regex evaluator with a regular expression as the condition. For example:

 

 

And in your pom.xml, you will need the following dependency:

 

To see a working example of this configuration, review the Alfresco Workflow Form Upload project, which uses this evaluator to add the upload functionality to all the activiti forms.

 

Note: This evaluation filter is not a spring wired bean. It will be instantiated when used.

Space Cleanup: Rules, Space Templates and Action!

Sometimes you may want a work space or directory to be deleted when it becomes empty. For instance, you may have a temporary directory to share files for review or collaboration. The workspace or folder will remain available until the reviews and collaborations have been completed and the documents filed or moved into their designated spaces. Once the documents are moved out of the workspace, it would be best practice to remove the folder to keep your document management system clean, organized and manageable.

One of the many ways to achieve this behavior in Alfresco, would be to add a custom Action, and attach it to a rule. Another way, may be to add a behavior policy on the directories that need to be monitored and removed. Alternatively, you may write a cron job to routinely purge unused folders. Or maybe, you may regularly remind your users to clean up after themselves. In this article however, we’ll examine how to achieve this functionality in Alfresco, via Rules, Space Templates and Actions.

The Alfresco Services used for this are:

The inherited classes and interfaces are:

When this action is included as part of a rule, with criterions set to listen for items leaving or being deleted from the target directory, it will execute to delete the target directory.

Alfresco_»_Folder_RulesThe Custom ActionExecuter in this example was named rmdir and bound to the class  RemoveFolderExecuter as defined in the class example below:

 

 

This class will then be wired into the Spring IOC bean configuration as follows:

 

A working example of this functionality can be found in the Alfresco workflow upload functionality module. In this referenced project, the Action and rule will be automatically added to the Alfresco Templates directory; so that folders based on this templated behavior can be easily created.