Alfresco SDK 3 beta 1 available

We are pleased to announce the first beta of Alfresco SDK 3.0!

This release has been in the works for a long time, and addresses a lot of the issues and limitations we currently experience with the latest SDK releases.

By releasing this first beta we wish to get feedback on the overall structure, setup, compatibility and hot reloading.
Please raise issues on Github or reach out to us directly.

We welcome all feedback.

What’s new

  • JAR first approach, standardised JAR project structure
  • All runner logic is centralized in the Alfresco Maven Plugin (no runner projects)
  • Flexible configuration: Enable Repository? Enable Share? Enable Solr? Enable H2? Enable Tomcat? All configurable via the plugin
  • No forced parent pom
  • Low impact on your project
  • AMP as an optional assembly
  • Install 3rd party addons (and control the order they are applied)
  • All-in-one, Repository and Share archetypes
  • Hot reloading via JRebel
  • Support for all releases from 5.0 to 5.2.a – across community and enterprise
  • Support for 4.2 (currently Share module requires you to add two dependencies by hand)
  • Standalone Repository archetype supports Solr4

What’s yet to come

How to get it

Martin Bergljung has written up an in-depth user guide that will walk you through all the jucy details, you can find it here.

If you just want to get it up and running here and now, here’s the steps you need:

The Alfresco SDK 3.0.0-beta-1 has been released to Maven Central’s staging area. You need to add this as a repository to your ~/.m2/settings.xml:

<settings>
  <profiles>
    <profile>
      <id>alfresco-dev</id>
      <repositories>
        <repository>
          <id>alfresco-sdk-staging</id>
          <url>https://oss.sonatype.org/content/repositories/orgalfresco-1037/</url>
        </repository>
      </repositories>
      <pluginRepositories>
        <pluginRepository>
          <id>alfresco-sdk-staging-plugin</id>
          <url>https://oss.sonatype.org/content/repositories/orgalfresco-1037</url>
        </pluginRepository>
      </pluginRepositories>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
    </profile>
  </profiles>
</settings>

Once you’ve added it, you can now create a new project based on the new archetypes using this command:

mvn archetype:generate -DarchetypeCatalog=https://oss.sonatype.org/content/repositories/orgalfresco-1037/archetype-catalog.xml

Select the archetype you want, enter the properties and execute run.sh (for Linux/Mac) or run.bat (for Windows).

Thoughts, comments or other feedback? Let us know on Github, comments below, email, IRC etc.

Aikau 1.0.76 – Form Runtime Support

One of the comments I had on my last blog post point out that one of the main problems with using Aikau is that it doesn’t support the XML-based Forms Runtime that Share uses to render forms using the old YUI2 controls.

I decided to take a look into this issue and see what could be done about it. The major issue with the existing implementation is that it the REST APIs return HTML fragments containing references to the YUI2 controls – it’s just not possible to extract the pure data from the API as it is not.

Fortunately one of the many great things about the WebScripts implementation is their ability to be extended and have multiple output formats defined for them. This meant that I was able to extend the FormUIGet Java controller for the WebScript to generate a pure JSON output for the forms data and then define a new WebScript descriptor to access that data.

Because the Forms Runtime only applies to Share and not to to standalone clients, it was necessary to package the Java class and Spring bean configuration into a separate JAR file. This means that to leverage this new capability of Aikau you now need to include an additional dependency in your AMP files (or simply download the JAR from our Maven repository and copy it into the “share/WEB-INF/lib” folder as I do in my demo video).

Now that we can access the forms runtime data we need to be able to convert the form definition into an Aikau forms model. This is capability is provided by the “alfresco/services/FormsRuntimeService” module. At the moment this module is not fully complete – but I wanted to get something working out to the Community as soon as possible in order to get feedback and hopefully some collaborative development.

At the moment only a couple of YUI2 controls are mapped to Aikau controls, but both edit and view modes are supported and the ability to configure in custom mappings is something that will be added in later. Constraints are also only partially handled, but the remaining constraints will be added soon.

The main objective for this first release was to get something out to the Community that demonstrated the end-to-end capability. A test page has been bundled with the Aikau that you can try out. Everything has been done to support multiple versions of both the Aikau and Forms-Runtime-Support JARs.

Take a look at the demo video and let me know what you think… please feel free to add comments to the JIRA epic or raise issues on GitHub to discuss where to take this next.

EDIT: Update for 1.0.77

We’ve made some more improvements that are shown here:

 

Improving Aikau Education

Introduction

In my last blog post I talked about the perspective I’d gained by working in another team at Alfresco that has been using Aikau. For the last 18 months the Aikau team has been so head down in development trying to provide features and fixes for internal teams, customers and the community that we’ve not had much opportunity to focus on reviewing and improving the educational material that is available for Aikau.

Interestingly with the advent of the new Angular based UI framework and the conclusion of a number of major Alfresco projects that use Aikau the heat is now off us and I’ve had some time to start looking at what resources are available and how we can improve the situation.

At this point I think it’s important to state that as far as I’m aware Aikau development is going to continue and that if you want to develop a user interface for Alfresco – particularly if you want to customize or add new pages to Share – then Aikau is still the recommended framework.

Alfresco is still actively using Aikau (most notably for Records Management in Share) which is hugely important for its business. The use of Aikau is never going to be the headline feature in an Alfresco release, but it’s usually there in the background getting the job done.

Eating Our Own Dog Food

I decided to have a go at reproducing some existing YUI2 based features of Share using Aikau to try and showcase how rapid development can be – but more importantly to try to understand where the gaps might be in available education.

I’ve started with the “People” page and you can watch me creating this page from scratch in a brand new client in the video below. It’s a bit rough around the edges, for which I make no apologies – but hopefully it will be informative.

 

Feedback Wanted !

The full disclosure is that the first time I went through the process I found that some of the JSDoc could be better, we could provide some additional widgets and that the UserService needed updating – and I took care of these issues before recording the demo.

However, I would urge that anyone attempting to do any development that has similar problems to report them as a GitHub issue so that they can be addressed.

I’d also love your feedback on whether or not this medium is effective or not, whether I should record more demos and what they should be focused on. I’ve already got an idea for a follow up in developing some custom widgets to go on the page – but it might be better to work through an entirely different use case – Data Lists perhaps?

I’d also welcome any suggestions on other approaches we could take to help people get up to speed with Alfresco development using Aikau.

Accessing the Code

I’ve created a GitHub repository containing the application that I built in the video. I’ve tagged the commit with the code (and will continue to tag each commit if I do more examples) so that it’s easy to try out the code and experiment with it yourself.

Announcing Alfresco NG2 Components

By bringing together content & process, Alfresco is a unique platform for building solutions and business applications.

As a platform company, it is critical for us to ensure that our developer ecosystem is successful and our community, customers, and partners can deliver applications on top of Alfresco as quickly as possible.

Earlier this year, we embarked on a customer, partner, and community consultation exercise and analysing market data and industry trends. We got a lot of feedback from customers, partners and community that they are focusing more and more on Angular. John Newton wrote a nice blog post in May about our direction to move towards Angular and focus on Experience Design.

To support our strategy Alfresco invested in a new development organisation dedicated to frameworks, tools, and APIs to help reduce the time to develop and deliver applications across both ECM (Alfresco One) and BPM (Activiti). The organisation is headed by John Sotiropoulos our VP of Developer Products who works closely with me to deliver our strategy .

Our Application Development Framework is our overall offering that helps our developer ecosystem build applications on top of Alfresco and Activiti and provide a rapid, consistent, and unified developer experience. We have articulated our strategy in a set of slides, but like any vision it will evolve.

We also want to break the habit of doing development “in the dark” and be open and transparent about the process, revitalising our community. This is why we’re making the source of our work so far available – and we want your feedback!

Today we are announcing a brand new Javascript API, a set of NG2 components and a couple of Yeoman generators to help bootstrap your Angular2 project and components.

Alfresco Javascript API
One thing we keep hearing over and over again is that developers spend a significant portion of time doing boilerplate code. Bootstrapping a project from scratch takes time. Dealing with APIs, authentication and the lower levels are key. To help ease all of this we’ve developed a new API that wraps around our new v1 REST APIs.

The Javascript API is not tied into any specific framework. This means you can use this in all javascript based applications, whether it is a node.js backend application or a plain vanilla javascript page.

The goal with the Alfresco Javascript API is simple – we want to provide a great developer experience for developers consuming our APIs.

Be sure to check it out – https://github.com/Alfresco/alfresco-js-api

Alfresco NG2 Components
Building on top of the Alfresco Javascript API we have built a core set of components that are easy to use, configure and extend to fit your needs.

Initially we have focused on a set of high level components:

  • ng2-alfresco-core – Core services and utilities to help power components
  • ng2-alfresco-datatable – A simple file list
  • ng2-alfresco-documentlist – An advanced list of documents
  • ng2-alfresco-login – A login component
  • ng2-alfresco-search – A basic search component
  • ng2-alfresco-upload – Advanced upload capabilities that integrates with lists
  • ng2-alfresco-viewer – A PDF.js based viewer to preview content

Once you start using these components you will notice that they are all styled with our new design guidelines based on Google Material Design.

Be sure to check it out – https://github.com/Alfresco/alfresco-ng2-components

Alfresco NG2 App Generator
To help you get started as quickly as possible we have created a Yeoman generator to scaffold and generate your project. The generator will ask you a set of questions, but also offer to include and wire in the components listed above.

Be sure to check it out – https://github.com/Alfresco/generator-ng2-alfresco-app

Get started today!
We have a bunch of good material to help you get up and running. This page gives you a brief dive on how the components and the javascript api ties together.

The biggest requirement to get up and running is the 201606 Community Edition since we rely exclusively on the new v1 REST APIs. On top of this you need to have CORS enabled.

Since the NG2 components are purely client side components you need to have the Alfresco Platform allow requests from other domains, otherwise your browser will not allow the javascript api to make XHR requests.

First you need to download 201606 Community Edition, then download the “enablecors” module here. Put the JAR file in $ALF_HOME/modules/platform. The module contains a web fragment that configures CORS for the repository. You can find more detailed information here.

While you’re at it, why not include the REST API Explorer? Grab the war file here and put it in $ALF_HOME/tomcat/webapps.

Start up Alfresco and leave it running.

Next up is making sure you have Node.js installed. You will need to have a minimum version of 5 – we recommend you use the latest.

Once Node.js is installed you need to install the Yeoman generator:
npm install -g yo
npm install -g generator-ng2-alfresco-app

Run the generator, followed by “npm start” and you’re good to go!

Components documentation
Now that you have everything up and running, it’s time to have a look the component catalog and figure out how to configure and extend the components. Go to http://devproducts.alfresco.com to browse the components and view the documentation. We make a point of having both sample code and documentation as part of the definition of done. This way we ensure we have up to date documentation for our developers from day one.

We want your feedback
We recognise this is early days for our new “Application Development Framework”, but we want to have an open and transparent development process. We are continuing to develop more components and improve on the existing ones, but we would love to hear your thoughts and ideas. We will also welcome any pull requests with new features, bug fixes, enhancements to documentation, samples or anything else you would like to contribute.

If you want to contribute we are all set up on Github, please make sure to read the code contribution acceptance criteria, our Code Style, Commit format and Definition of Done.

Next steps
We are planning a Tech Talk Live next week, Wednesday 6th of July where we will present and demo what we have and we have a series of blog posts planned on how to use the individual components. Stay tuned!

Writing for Alfresco

A year ago we published a survey, asking you if Alfresco products use User Interface (UI) terms and language that makes sense.

We had a great response from 200 Alfresco users, developers through to end users, and since then we’ve been busy putting the feedback you gave us to good use.

Survey Results
We’ll have a look at what we’ve been up to in a minute, but first (as promised previously) we’ll show you some of the survey results. We found that the feedback to the following statements was particularly useful in validating our thoughts behind conducting the survey in the first place.

survey2

survey3

It was clear from these results that we could make improvements to give real benefit to the day-to-day experience of Alfresco users.

When we looked at the detailed responses, many of you felt that the language and tone we used was perfectly ok. But there were plenty of useful comments, both general and specific, on what could be improved.
And one thing came up again and again; that the language in Alfresco products is

“too technical!”

This is something we were already aware of, and if you check this previous post then you’ll see that we’d been addressing it in recent new features and products. So it was great to see that we’ve been heading in the right direction.

What we did after the survey
Once we’d sifted through and evaluated the feedback, we chunked it into a backlog of areas to fix. There are a lot of words in Alfresco – the Alfresco platform and Alfresco Share alone contain well over 40,000 individual words, and that’s before we get on to Activiti, Records Management, Alfresco Mobile, etc.

Using the survey feedback we identified the key places where we could make improvements, and we now have a playbook in place to make these fixes.

Of course, at the same time as we were doing this our engineers continued to be busy developing new products and features, all the time adding new terminology.

Writing for Alfresco
As we built on how we wanted Alfresco terminology to be, we decided to set up some guidelines to ensure that we could develop consistency across the product range. We used a number of tools to decide what the Alfresco “voice” should be, including the survey results, a ton of analysis of other research data, user testing, and of course, looking at other products.

As we looked at the tone and voice guidelines for a well-known email app, Thomas De Meo, our VP of Product Management suggested that the app was “the kind of guy you want to hang out with”. That struck a chord and so we thought, well what do we want Alfresco to be? The answer was “the kind of person you want to work with”.

We built on that and have now published a set of guidelines – “Alfresco Voice – writing for the user interface”. This covers all aspects of product language including what tone to use and what words to avoid, how to write for a global audience, keeping it simple, and how to make that error message useful instead of an overly-technical nightmare.

The style and tone in this guide is how future Alfresco products and features will sound. And we’re gradually working through the existing terminology to bring it in line.

User Assistance and Experience Design representatives now work with the Alfresco Engineering agile teams to design the terminology in parallel with feature development. This means that the words you read in our products have been carefully designed and considered to compliment the UI and user level, and to make Alfresco products simple to use.

We hope that you’ll notice the difference, and see how we’ve taken all your feedback on board. And if you’re an Alfresco developer, then go ahead and use the guidelines for your own add-ons or customizations – docs.alfresco.com/writing-for-alfresco.

writing for alfresco

Developing With Aikau – Another Perspective

I’ve recently been moved out of the Aikau team in order to provide some assistance to a feature team that are using Aikau. This change in role has given me a very useful insight into the problems that developers have when using Aikau. When working on Aikau I only ever get to see a fragment of the overall implementation – I get very little context so I never know if the overall implementation is being done in a sensible way.

It’s important to remember that we never think of Aikau as being “done”. Our widgets are always open to further iteration to either add more capabilities, refactor them for better performance, improve the design and fix any bugs. We also don’t consider them to be an exhaustive set by any means – we know that more widgets will be needed.

What we don’t know is what bugs exist, what features could be added and what widgets are missing. We rely on our feature teams, customers, partners and community to tell us what is required.

When I started working on the feature I was given in the new team I almost immediately identified one bug and 3 features (1,2,3) that were required. This wasn’t a brand new requirement for my new feature team but these requirements hadn’t been identified.

Trying to act like a good community citizen I raised these as issues on JIRA and then being a model community citizen I created pull requests to fix the problem and add the features following the well defined acceptance criteria.

Of course it’s much easier to do this when you have an awareness of what is available and how things are meant to work in a framework when you have been involved in the development of that framework. Having said that I really want to encourage you to just ask the question and start the dialog with us.

It should hopefully be clear from the closed issues that we’re more than happy to answer questions when they’re asked.

The flip side of the coin is to not start a dialog but to simply complain about something without trying to dig into the details like with this blog post published last week. Whilst I understand that something might not be immediately obvious when trying to use Aikau (we’re well aware that documentation could be improved, we just haven’t been allocated the resources to do enough about it) we will try and help you if we can – even if that help is simply explaining why something is the way it is.

We aren’t promising to implement all your feature requests (far from it in fact!) but we are committed to genuine bugs in our coding (meaning a defect in the intended behaviour of an individual widget or service).

We’re starting to see increased Community interaction – more issues raised, more traffic, more GitHub stars. What we’d really like to see is more pull requests – and if something is blocking you from making a pull request then we’d like to know what that impediment is so that we can remove it.

This is going to be especially important during my reassignment as it means that we might not be able to implement community requested features as we have in the past – but we will endeavour to try to stay on top of the bugs that you raise.

Thanks again for your ongoing support !

Separating Platform and Share in Alfresco 5.1

The content of this post is mostly based on the talk I gave at the amazing BeeCon 2016 conference, in Brussels.

Alfresco One 5.1, released in March 2016, introduced a separation in the packaging between Alfresco One Platform and Alfresco One Share. I want to explain a bit behind the motivations for this; how we did it and what’s in it for you.

Why separate?

The main reason was to have different release lifecycles between Platform and Share. That means we can now, for instance, release versions of Share more often, without having to retest the whole Platform (which is very costly with all the databases, application servers, etc.)

The releases are also smaller and more incremental. We hope it makes it easier to upgrade the Platform while keeping a heavily modified Share: this seems to be a common use case!

From a more “Alfresco Engineering” point-of-view, there are more reasons to split: the combined codebase was huge, and we couldn’t really assign it to a single team. Now, we have reorganised our teams, and we have proper Platform and Share teams, each taking responsibility for their own codebase. Ownership is simpler, the issue backlog is smaller, and we are overall more agile.

Where to cut?

We needed to decide where to draw the line between Platform and Share code.

An initial idea was to create one codebase for each artifact (jar or war): alfresco-core.jar, alfresco-data-model.jar, etc. But that would have been a bit too many to handle.

The most obvious was to simply cut between the two war files: alfresco.war and share.war. However, that meant that we couldn’t update the Share APIs (webscripts, etc.) when we update Share, since they are actually delivered in alfresco.war.

We got inspiration from this blog post from Netflix. The idea is explained in this picture, which I have shamelessly reused here:

Slide04

Netflix has to support a lot of very different devices: browsers, Wii, XBox, iPhones, …
To add some flexibility to their server-side code, they created this notion of Client Adapter Code. It is delivered at the same time as the client, but actually sits on the server-side, allowing each client to evolve and manage their own API within their own lifecycle. This is exactly what we needed!

The Share codebase therefore produces a Platform-side component, called Share Services, which is packaged as an AMP. It contains the /slingshot webscripts, the sample site bootstrap, and the datalist and wiki services. The alfresco-share-services.amp is applied to alfresco.war: its source is in Share, but it runs in the Platform.

SeparatingShare-shareservices

Separating common pieces

Some components are used by both Platform and Share. We needed to separate each of them into their own codebase too, otherwise we couldn’t release Share without releasing Platform. So we extracted these components, and now they have their own lifecycle:

All these are kept in the same Subversion server. This is much more convenient when we need to merge fixes from old branches to and from 5.1. We may move these to Git in the future.

Of course, we also had to cut a few cyclic dependencies, but it wasn’t too bad…

What do we package?

Community Edition

We had discussions on whether we should provide Platform and Share packages for the Community Edition. We decided not to, because Community is typically used on single node installations. Also, it’s quite often an entry point for people researching Alfresco, so we wanted to keep things simple there. (I had people complaining about this at BeeCon, but I’m still looking for a valid use case…)

Since it will contain components with different versions, we had to find a different versioning convention. We settled on a version based on the year and month: 201605. We also add a -GA (General Availability) or -EA (Early Access) suffix, to make clear the level of testing it had. For instance, the latest version of Community is called 201605-GA, and it contains:

  • Alfresco Platform 5.1.g (a security issue fix from 5.1.f)
  • Alfresco Share 5.1.f
  • GoogleDocs integration 3.0.3
  • Alfresco Office Services 1.1

Share separation does benefit Community Edition though, because we can ship more often, and include only what has changed, as with 201605-GA

Enterprise Edition

For clusters and complex setups, as supported by Alfresco One, it is useful to install Platform and Share separately, so we have provided separate installers for each of them. The Share one installs a separate Tomcat instance and just deploys share.war in it. It also copies the Share Services AMP into the installation folder, but you will need to apply it yourself to the Platform installation it connects to – see the documentation.

We thought a “full” installer, with both Platform and Share, was still needed. It is convenient for people who want to try Alfresco without knowing much about its architecture, or simply for standalone instances. The version of this all-in-one installer for Alfresco One still reflects the version number of the Platform, i.e. 5.1. We are waiting to see what people think of the Community Edition naming before we change the naming for Alfresco One.

In summary, here are the different packages we offer for the Enterprise Edition:

SeparatingShare-overview

What next?

We didn’t go as far as we had planned. For 5.1.x, the source codebases are separated, but we are still going to release Platform and Share at the same time, with the same version number. We lacked time to test each component individually. Previously, Alfresco could be tested as a whole and it was fine. For instance, JLan was mostly tested by integration tests in the Platform. Now, we need to make sure JLan works on its own, before we release it, because we may have to release it just for a Share version, without running the Platform tests against it.

We also didn’t think we could ensure that Platform 5.1.X would work with Share 5.1.Y – once again due to the lack of tests and of clear public APIs between the components. (Although this improved in 5.1 – see the BCK project for instance, or the documentation on extension points.)

In the near future, we are planning to separate more components from the Platform. The most likely candidates are currently:

  • Search, as part of the upgrade to Solr 6
  • More of Share: there are parts of the Platform that we think should belong to Share, such as calendars, blogs, … And we still want to release it separately in the future!
  • Enterprise extensions, to upgrade from a Community Edition

I’m not making promises of course, but this is on the roadmap, so it looks good!

Adding the Aikau Document Library as a Site Page in Share

Introduction

In previous blog posts I’ve shown examples of how the Aikau version of the Document Library can be used both within Share and in standalone clients. In this blog post I thought it might be useful to provide a more in-depth guide on how to add the Aikau Document Library as a site page in Share, as well as to provide a general status update on progress.

Background

It’s important to understand that the Aikau team is a “Component Team” and not a “Feature Team”. This means that we provide the components (in this case Aikau widgets and services) for other teams to deliver features or products.

At the time of writing there is no feature team driving the replacement of the old YUI2 Document Library with the Aikau version – nor indeed has there ever been. Aikau has always predominantly been about re-use and the Document Library has progressed because other features have required Document Library related widgets.

There are two epics in JIRA that list the current tasks required to achieve feature parity with the YUI2 Document Library: one for general features and one for action support. Reviewing these epics should give an overview of what work remains.

In general the Document Library is quite functional and should be more than adequate for covering a large number of use cases. The following steps and code is available within the following GitHub repository and all of the files described before are linked to the specific files in that repository.

Create the Aikau Document Library Page

The first step is to create the WebScripts for the new page. Create the WebScript descriptor file…

DocLib.get.desc.xml

<webscript>
  <shortname>Document Library Example </shortname>
  <description>This provides an example of building the standard Document Library using the doclib.lib.js library file.</description>
  <family>Aikau</family>
  <url>/DocLib</url>
</webscript>

Now let’s create the template…

DocLib.get.html.ftl

<@processJsonModel/>

The properties file is slightly more involved…

DocLib.get.properties

surf.include.resources=org/alfresco/share/imports/share-header.lib,org/alfresco/aikau/{aikauVersion}/libs/doclib/doclib.lib

This file just contains an instruction to import two other properties files:

  • org/alfresco/share/imports/share-header.lib
  • org/alfresco/aikau/{aikauVersion}/libs/doclib/doclib.lib

This process is described in more detail in this previous blog post.

The last WebScript file required is the JavaScript controller… this is where most of the code goes:

DocLib.get.js

The first thing is to import the required controller files…

<import resource="classpath:/alfresco/site-webscripts/org/alfresco/share/imports/share-header.lib.js">
<import resource="classpath:/alfresco/site-webscripts/org/alfresco/share/imports/share-footer.lib.js">
<import resource="classpath:alfresco/site-webscripts/org/alfresco/aikau/{aikauVersion}/libs/doclib/doclib.lib.js">

Now you need to import the services and widgets that the header uses…

var services = getHeaderServices();
var widgets = getHeaderModel(msg.get("aikau.doclib.title"));

The header services need to be combined with the services required by the Document Library. These can be retrieved by calling getDocumentLibraryServices.

services = services.concat(getDocumentLibraryServices());

Now use the getDocLib function to create the model for the Document Library. The main data to provide is the site id which is available from a template argument and the name of the folder in which the Document Library files can be found within the site folder (typically “documentLibrary”).

var docLib = getDocLib({
  siteId: page.url.templateArgs.site, 
  containerId: "documentLibrary"
});

This model needs to be added to the header model….

widgets.push(docLib);

Finally we need to call getFooterModel passing in the header and Document Library services and widgets. This is required because the footer model wraps everything else on the page.

model.jsonModel = getFooterModel(services, widgets);

Make the Document Library a Site Page

In this previous post I describe the process for adding Aikau pages in general – so please refer to that for a slightly more in-depth description of the process.

Create a new Surf Page definition that will provide the title and description of the page as shown when customizing sites.

AikauDocLib.xml

<?xml version='1.0' encoding='UTF-8'?>
<page>
  <title>Aikau Document Library</title>
  <description>The Aikau Document Library</description>
</page>

Now create an extension module to ensure that the site page is an option when customizing sites.

Aikau-document-library.xml

<extension>
  <modules>
    <module>
      <id>Aikau Document Library Site Page</id>
      <auto-deploy>true</auto-deploy>
      <evaluator type="default.extensibility.evaluator"/>
      <configurations>
        <config evaluator="string-compare" condition="SitePages" replace="false">
          <pages>
            <page id="AikauDocLib">dp/ws/DocLib</page>
          </pages>
        </config>
      </configurations>
    </module>
  </modules>
</extension>

Now you need to pull these files together into a single JAR and copy them to the “share/WEB-INF/lib” folder.

AikauDocLib4

Restart Share and go to any site and customize it – you should see the “Aikau Document Library” in the list of available pages:

AikauDocLib1

Drag it into the “Current Site Pages” list and click “OK”

AikauDocLib2

Now you should have a new link for the “Aikau Document Library” (if you have a lot of site pages, try looking under the “More” drop-down menu!). Click on the link and you’ll be taken to your the Aikau Document Library:

AikauDocLib3

What Are The Benefits and Limitations?

One of the main reasons for creating an Aikau version of the Document Library was to make customization much simpler. Through the use of the Aikau model it is significantly easier to make fine-grained changes to the Document Library. Some things you could do for example would be:

  • Add custom views
  • Edit existing views (add or remove the metadata that is displayed)
  • Filter the displayed actions or add entirely new actions
  • Render only specific sections of the Document Library (the tree, breadcrumb trail or list for example)
  • Edit the menu options that are displayed

The Aikau version also has a few features that are not included with the original Document Library:

  • Drag-and-drop upload new version
  • Inline document preview
  • Inline commenting
  • Inline content creation

As of Aikau 1.0.68 the Document Library uses a new non-modal upload file design. See screenshot below:

AikauDocLib5

The main limitation is that there is not yet support for all the actions that you would find in the existing Document Library (you can review the missing actions in the previously linked epic).

The other potential limitation is the lack of integration with the forms runtime. This means that when editing properties for custom types the XML forms configuration will not be represented.

Despite these issues the Aikau Document Library should still be useful for many use cases – especially where serious customization of the existing Document Library is required.

Alfresco REST API Explorer is now live!

We’ve been discussing REST APIs at Alfresco for a while now. If you haven’t already seen Gavin Cornwell’s Tech Talk Live session “The Future of REST APIs”  I highly recommend you check it out now.

It’s hard to sum up Gavin’s presentation, but the gist is that we are working on a new set of REST APIs that all follow a common set of guidelines. They are consistent, well tested, versioned which makes them extremely easy to consume. We call these “the v1 REST APIs”, however this concept is not new. We introduced the foundation for these APIs back in 4.2 along with our Cloud offering. The idea back then was to fill the missing features of CMIS so a combination of these APIs + CMIS would give you everything you need. These APIs have been documented in our official docs, however they were a bit hard to navigate and hard to consume.

This raises the question of how do we do API documentation in an efficient way. OpenAPI Specification (formerly known as Swagger) seems to do the trick in terms of describing our APIs. The cherry on the top is Swagger UI – a cool project that generates interactive documentation from an OpenAPI Specification – that even allows you to test out the APIs directly from the API Explorer.

We’ve put a lot of work into documenting our existing API’s, which is what we’re releasing today. The new “v1 APIs” are now marked up with OpenAPI Specification (you can find the source here). We do realise that these API’s don’t look like much – but as mentioned above, the scope of the existing APIs was to fill the gap.

As we’re adopting an “API First” approach, we’re also moving to a “contract first” approach. This means that before we start coding any APIs we mock them up in OpenAPI Specifications, then have a review. Once the review is complete and we have ensured it conforms to our standards and guidelines we will start the work. We hope to see proposals for new APIs following this approach in the future.

We’ve made much progress on additional APIs, and we’re continuing to invest heavily in stable, rich and powerful REST APIs this year. We already have a great set of APIs that cover file and folder operations, trashcan, renditions, live search, ticket authentication and site creation. We’re adding new APIs every week and we’re hoping to release a great set of APIs to community edition over the next couple of months.

We are working on a “bleeding edge” version of the REST API Explorer – this will be a snapshot of the latest development. We hope this will be a great tool for our developer ecosystem to test the API’s and provide feedback. We don’t currently have a fixed date for the “bleeding edge” version, but we will make sure to make some noise when it’s ready. In case you can’t wait, you can clone the REST API Explorer source on GitHub and check out the “develop” branch. Run “mvn tomcat7:run-war” to get it up and running, however you will not be able to interact with the APIs.

You can find the online version of the REST API Explorer here: https://api-explorer.alfresco.com. It also comes bundled with the Alfresco SDK 2.2, be sure to check it out!

To report a bug please open an issue in the ALF project over at http://issues.alfresco.com, please set the “REST API” component if possible.

Top 10 JQL Tips – from first steps to seasoned traveler


By Joe Emett

In this post, I’d like to give some tips on some useful JIRA Query Language (JQL) queries.  By no means exhaustive, they are things I’ve come to use and love in Jira.  It will focus on getting started with JQL and is not meant as a Jira tutorial.  Syntax rules are outside the boundaries of this blog.  Rather than giving descriptions on JQL keywords I hope this acts as a quick-start guide for you to build your own queries.

These tips assume the user is able to navigate to a Jira project backlog and range from rookie to more seasoned advice.

1.  Create your own JQL with 2 character presses

In the top right of any Jira screen is the QuickSearch text box:

1QuickSearch

When you enter my, you will redirected to the Issue Navigator and be presented with Jira issues that are currently assigned to you.

You can then tweak your JQL to refine the set of results, for example if you want just the open issues you could modify the query by including AND status = “Open” :
1CreateYourOwnJQL

You will find other smart query shortcuts here, at the very least QuickSearch offers fast access to the Issue Navigator and by entering free text into QuickSearch, this will search all Jira projects for instances of the text in these fields: Summary, Description and Comments.

This blog now assumes you are comfortable with accessing the Issue Navigator.

2.  Build on what is there already

Every backlog has an associated Jira query.  If you have access to a Jira project backlog, you are looking at the results of a JQL query.  On every Jira Scrum board, there is a ‘Board’ dropdown list:

BoardConfigure

On pressing ‘Configure’, on the ‘General’ tab there are the filter details the board is based on:2FilterQuery

Even though you may not have privileges to edit the query, you will be able to press View Filter Query, change the JQL query and Save as, as you wish.

Jira Reports and Gadgets on Dashboards, are other good places to look, as these are based on existing JQL queries you can dip into and change.

Look out for View in Issue Navigator to see more JQL.

3.  Just created an issue and you’ve forgotten the Key?

3ForgottenKey

You’ve created an issue, gone and made a cup of coffee and can’t remember the Key, and it’s not on your board.

In the Issue Navigator enter:

project = ACE and created >= startOfDay() ORDER BY Key DESC3OrderKeyDescending

4.  Use Empty to find forgotten issues

Find issues with no fix version.  In the Issue Navigator enter:

project in (ACE, MNT) AND status = Open AND fixVersion is EMPTY ORDER BY created DESC4Empty

5.  Commented by a colleague

You know the project and the colleague who commented on an issue, you’re just not sure which issue. You think the comment was made in the last 30 days, but you query 60 days back, just in case:  In the Issue Navigator enter:

project = ACE and issueFunction in commented(by cthompson after startOfDay(-60d))5CommentedBy

Please note, you require the ‘Adaptavist SciptRunner for Jira’ plug-in to include issueFunction in your query. issueFunction is a search mechanism allowing you to perform searches that you would not be able to do with ‘out of the box’ JQL.

6.  Tracking Assignee

You need to locate a Jira Issue that was assigned to a member of your team, but you’re not sure who. In the Issue Navigator enter:

project = ACE AND fixVersion in versionMatch(5.1) AND assignee WAS IN (cthompson, tbagnall, vhemmert, jemett) ORDER BY Rank6AAssignee
You can subscribe to any filter, where Jira will run the search and email you the results.  This is particularly useful when your project is in a stabilization phase and you would like daily updates containing the latest bugs.  In the filter view, click on Details then New subscription:

6CSubscribeToFilter

7.  Multiple teams in one project

You are sharing a project with another team, but want your own board, sprints and version control. Create some JQL that will track your Epics, Stories and Sub-Tasks.  In the Issue Navigator enter:

project = SHA AND (key in (sha-847, sha-856, sha-860, sha-445) OR Epic Link in (sha-847, sha-856, sha-860, sha-445)) OR issueFunction in subtasksOf(\Epic Link\=sha-847) OR issueFunction in subtasksOf(\Epic Link\=sha-856) OR issueFunction in subtasksOf(\Epic Link\=sha-436) OR issueFunction in subtasksOf(\Epic Link\=sha-445) ORDER BY Rank ASC7MultipleTeams

8.  Bugs fixed after a certain date

You would like to track the bugs where status has been changed to Review or Verify after a date and want to exclude issues that have been pinged back to the Developers.  In the Issue Navigator enter:

project = SHA AND fixVersion in versionMatch(5.1) AND (status changed to Review after 2015/11/29 OR status changed to Verify after 2015/11/29) AND Status != Open AND status != In Progress ORDER BY priority DESC8BugsFixed

9.  More on Empty

For some fields, such as ‘Labels’ you need to explicitly query if the field is ‘Empty’ as part of your criteria, for example .. (labels !=CMM) .. will only return issues with the label field that has been populated, ignoring issues with no labels.  To fully capture the set of records you’re really after use: .. (labels is empty or labels != CMM) ..

Incorporating this logic into a larger query, in the Issue Navigator enter:

project = SHA and fixVersion=5.1 and (labels is empty or labels !=CMM) and type in (Story,Task,Bug) order by rank9MoreEmpty

10.  Aggregate Expressions

JQL is not great for aggregation, but I find totaling points of stories that fall into certain sprints useful. In the Issue Navigator enter:

project = SHA and sprint in(CMM Sprint 5, CMM Sprint 6, CMM Sprint 7) and issueFunction in aggregateExpression(Total points, storyPoints.sum())10AggregateExpressions

As elsewhere in this post, you need the ‘Adaptavist SciptRunner for Jira’ plug-in to include issueFunction in your query.