Tag: Alfresco SDK

Alfresco Developer Series Tutorials for SDK 4.0

Back in February, when SDK 4.0 was still in beta, I upgraded the Alfresco Developer Series tutorials on a branch to help early adopters learn how to use the platform. I was holding off on merging the branch into master until SDK 4.0 was out of beta and until I was seeing more end-user adoption of Alfresco 6.x.

Since then, SDK 4.0 has left beta. The vast majority of my customers are still running 5.2, but I’m seeing enough interest in 6.x on StackOverflow and in the forums that I decided it was time to merge to master.

If you are looking for the older tutorials based on SDK 3.0, they are still there–just use the SDK-3.0.1 tag.

In addition to the source code projects, the tutorial content itself also changed slightly. Those HTML pages have been re-generated, published, and linked to from the Alfresco Developer Series home page.

Now when developers come across the tutorials they’ll be referencing source code and instructions that are up-to-date with the latest SDK.

Alfresco Maven SDK: Declaring other AMPs as dependencies

5634268846_9c59682a42_mI’ve seen a few questions about how to configure an Alfresco project to depend on other add-ons when using the Alfresco Maven SDK, so I thought I’d do a quick write-up on that.

When you use the Alfresco Maven SDK Archetypes to bootstrap a project, you can select one of three project types:

  1. alfresco-allinone-archetype: Referred to simply as “All-in-One”, this type, as the name implies, gives you a project that facilitates creating both a repository tier AMP and a Share tier AMP, plus it includes a working Solr installation.
  2. alfresco-amp-archetype: This sets up a project that generates only a repository tier AMP.
  3. share-amp-archetype: This sets up a project that generates only a Share tier AMP.

In my Alfresco Maven SDK Tutorial I use both the alfresco-amp-archetype and the share-amp-archetype but I don’t really talk about the All-in-One archetype at all. The reason is two-fold. First, I think for most beginners, the smaller, more focused archetypes are less confusing. Second, on the vast majority of my client projects, that’s the setup I use. Usually, I feel like the All-in-One archetype is overkill.

However, there is an advantage the All-in-One archetype has over the other two. It is able to pull in other AMPs as dependencies. With the single-purpose archetypes, your goal is simply to build an AMP. You can run integration tests against that AMP using the embedded Tomcat server, but if you want to test the AMP with other AMPs, you have to deal with that manually. Usually I just deploy the AMPs to a test Alfresco installation that already has the other AMPs deployed.

But with the All-in-One archetype, you can declare those other AMPs as dependencies, and Maven will go grab them from a repository and install them into your local test environment using something called an “overlay”.

Here’s an example. Suppose you are developing some customizations that you know will be deployed to an Alfresco server that will be running the following add-ons: Share Site Creators, Share Site Space Templates, Share Login Announcements, and Share Inbound Calendar Invites. You’d like to test your code alongside these add-ons.

One approach would be to go grab the source for each of these projects and build them locally to produce their AMPs (or download pre-built AMPs), then deploy all of those AMPs to a test server, then deploy your custom AMP and test.

But all of those add-ons happen to live on a public Maven artifact repository called Maven Central. So a better alternative might be to simply list those modules as dependencies and let Maven take care of the rest.

Here’s how it works. When you generate an all-in-one project, the structure includes not only folders that contain your repo and Share AMP source, but also folders representing the Alfresco and Share web applications. For example, here are the files and folders in the root folder of a project called “test-allinone-220”:

pom.xml
repo
run.bat
run.sh
runner
share
solr-config
test-allinone-220-repo-amp
test-allinone-220-share-amp

In our example, your custom code for the repo tier would go in test-allinone-220-repo-amp and your Share tier code would go in test-allinone-220-share-amp.

The repo and share directories are used to build the respective WAR files and they each have their own pom.xml. So to add the other add-ons to our setup, first edit repo/pom.xml. You need to add the add-ons as dependencies, like:

<dependency>
    <groupId>com.metaversant</groupId>
    <artifactId>inbound-invites-repo</artifactId>
    <version>1.1.0</version>
    <type>amp</type>
</dependency>
<dependency>
    <groupId>com.metaversant</groupId>
    <artifactId>share-site-space-templates-repo</artifactId>
    <version>1.1.2</version>
    <type>amp</type>
</dependency>
<dependency>
    <groupId>com.metaversant</groupId>
    <artifactId>share-login-ann-repo</artifactId>
    <version>0.0.2</version>
    <type>amp</type>
</dependency>
<dependency>
    <groupId>com.metaversant</groupId>
    <artifactId>share-site-creators-repo</artifactId>
    <version>0.0.5</version>
    <type>amp</type>
</dependency>

Then, add them again to the overlays section (without the “version” element), like this:

<overlay>
    <groupId>com.metaversant</groupId>
    <artifactId>inbound-invites-repo</artifactId>
    <type>amp</type>
</overlay>
<overlay>
    <groupId>com.metaversant</groupId>
    <artifactId>share-site-space-templates-repo</artifactId>
    <type>amp</type>
</overlay>
<overlay>
    <groupId>com.metaversant</groupId>
    <artifactId>share-login-ann-repo</artifactId>
    <type>amp</type>
</overlay>
<overlay>
    <groupId>com.metaversant</groupId>
    <artifactId>share-site-creators-repo</artifactId>
    <type>amp</type>
</overlay>

That covers the Alfresco WAR. Now for the Share WAR, edit share/pom.xml and add the Share tier dependencies, like:

<dependency>
    <groupId>com.metaversant</groupId>
    <artifactId>share-login-ann-share</artifactId>
    <version>0.0.2</version>
    <type>amp</type>
</dependency>
<dependency>
    <groupId>com.metaversant</groupId>
    <artifactId>share-site-creators-share</artifactId>
    <version>0.0.5</version>
    <type>amp</type>
</dependency>

And then the overlays:

<overlay>
    <groupId>com.metaversant</groupId>
    <artifactId>share-login-ann-share</artifactId>
    <type>amp</type>
</overlay>
<overlay>
    <groupId>com.metaversant</groupId>
    <artifactId>share-site-creators-share</artifactId>
    <type>amp</type>
</overlay>

Now you can run the whole thing–your custom AMPs plus all of the dependencies–by running ./run.sh. As part of the build, you should see the dependencies being downloaded from Maven Central. As the server starts up, if you watch the log, you’ll see the modules get initialized. And when you log in, you’ll be able to test all of the functionality together.

When you are ready to deploy to one of your actual server environments, you have a choice. You can either copy all of your AMPs to the amps and amps_share directories, then run bin/apply_amps.sh. Or you can deploy the WAR files that are now sitting under repo/target and share/target. Personally, I think re-applying the AMPs against a fresh WAR on the target server is less confusing and less error-prone, but I’ve seen it done both ways.

If the add-ons you want to depend on are not on a public Maven artifact repository like Maven Central, you can still build them locally, run “mvn install” to install them into your local Maven repository, then depend on them as shown.

New Alfresco community project: Refactor the Alfresco SDK

Veere: tools by DocmanOne of the best things a community can do for its members is to make it easy for newcomers to get started. In the Alfresco community, we’ve made some improvements rather recently such as:

Those all help people get pointed in the right direction. Now it is time to focus on the specific tools people use to write code for their Alfresco projects.

When someone wants to customize or extend Alfresco they often start with the downloadable SDK. The downloadable SDK includes dependencies (Alfresco & third-party), source for Alfresco dependencies, JavaDoc, and sample projects.

There’s nothing necessarily wrong with the downloadable SDK. It has existed in pretty much the same state since it was originally created and has served us well. But there are newer tools available. For example, thanks to the hard work of Gab Columbro and some of his cohorts, there is now a set of officially-supported artifacts for both Community Edition and Enterprise Edition. That means you can use a tool like Maven to resolve dependencies for you. There are also Maven archetypes that make it easy for you to start a new Alfresco project with the appropriate folder structure for the type of customization you need to do, complete with a ready-to-import Eclipse project.

So all of this great work has been done on the Maven-based SDK but the “last mile” is making it easily consumable by brand new developers. The best way to do that, I think, is to refactor and revitalize the downloadable SDK. I think we need to:

  • Remove old sample projects that are no longer relevant
  • Add new sample projects for areas of the platform that may currently be missing
  • Convert all sample projects to builds that leverage the Alfresco Maven SDK
  • Provide a light set of documentation that explains how to use the Alfresco Maven SDK and how to build the sample projects. This should not replace any formal official documentation on customizing Alfresco. Instead, it should be just enough to understand what’s in the SDK, how to build and run the samples, and how to use the Alfresco Maven SDK to start a new project.

Toward this end, I’ve grabbed the Alfresco SDK source out of Alfresco SVN and used it to create an Alfresco SDK project on Github. If the community leaves it up to me, I’ll work on it in fits and starts as I am able and it will get done in a few years. Instead, I’m hoping that a few of you who are excited about this idea will fork the project and start giving me pull requests. We can discuss this effort in #alfresco on freenode IRC. If enough people are interested we could also have a regular Skype call to coordinate efforts.

Thanks ahead of time for any time you are able to put in to this project. I’m hoping that if we work together we can get this looking great by Alfresco Summit, but that depends on you!

Alfresco 3.0 Surf Code Camp Boston Wrapped Up

We hosted a good crowd of folks at Optaros headquarters in Boston today for our second Code Camp around Alfresco 3.0 Surf. Alfresco’s own Dr. Yong Qu was on hand to provide an early gift to campers–a live demo of Alfresco’s browser-based site designer tool, Web Studio. It looked like it was coming along nicely. The new tool is in Labs head but I haven’t had a chance to take a look so it was great that Yong was able to show us how it worked.

Yong showed a quick demo in which he stepped through a site creation wizard. Behind the scenes, Web Studio was creating a new web project in the Alfresco WCM store and configuring a user sandbox. Once the site was created, Yong put the site in edit mode. It makes more sense when you see it but what happens is a tray opens up that contains various lists of templates, components, and assets that can be dragged-and-dropped onto regions on the site’s pages. Once put in place, the component can be configured. Again, behind the scenes, Web Studio is creating the Surf model objects in the Alfresco WCM store (Code Campers become painfully aware of the variety and number of model objects required to build a Surf site because they do it by hand all day in the labs).

It’ll be a while (multiple months?) before Web Studio makes it into Enterprise. Until then, try it out. And while you’re in there, look at the library of components. Alfresco is hoping you will be inspired to create and submit additional components that can be similarly shared with the community.

The next Optaros-led Alfresco 3.0 Surf Code Camp will be in Munich on January 13th. I’ll be there as well as some of my other Optaros teammates, Alfresco will be there, and we’re hoping you will be there too. Read more details on the Munich event and sign up here.