Adding Custom Aspect Support in Alfresco Share

Since Alfresco 3.2 introduced the ability to configure the metadata forms used in the Document Library, there have been severalgoodarticles published on how to add support for custom document types.

One of the first questions people often ask when they see Share is how they can easily extend the metadata fields that are stored against a document. Whilst this can be done using custom document types, aspects often provide a more agile solution.

So this article should explain how Share can be easily extended to support custom aspects using good practice techniques, specifically

Ensuring all extended configuration is placed outside of the share webapp, so protecting it from upgrades and redeployments, and

Using i18n labels for all text strings that appear in the UI, thus allowing translation of the labels.

The example provides a number of files, all of which should be placed below the tomcat/shared/classes directory of your Alfresco installation. If you are not using the Alfresco-bundled version of Tomcat then you may need to create this directory yourself and configure Tomcat's shared classloader to use it.

First you will need to configure the repository with your custom model definition. In my case I am using a simple knowledge base model that defines a single aspect kb:referencable. The aspect adds a new text property that allows a unique KB reference number to be added to documents.

With the model added the repository should start up without errors and will know about the new aspect. In order to use it, we need to configure Share to show this aspect in the Manage Aspects dialogue and to display the KB Reference field in forms, when a node has the aspect applied.

The file alfresco/web-extension/share-config-custom.xml can be used to do both these things.

<alfresco-config>

<!-- Document Library config section -->

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

<!--

Used by the 'Manage Aspects' action

For custom aspects, remember to also add the relevant i18n string(s)

cm_myaspect=My Aspect

-->

<aspects>

<!-- Aspects that a user can see -->

<visible>

<aspect name='cm:generalclassifiable' />

<aspect name='cm:complianceable' />

<aspect name='cm:dublincore' />

<aspect name='cm:effectivity' />

<aspect name='cm:summarizable' />

<aspect name='cm:versionable' />

<aspect name='cm:templatable' />

<aspect name='cm:emailed' />

<aspect name='emailserver:aliasable' />

<aspect name='cm:taggable' />

<aspect name='app:inlineeditable' />

<aspect name='kb:referencable' />

</visible>

<!-- Aspects that a user can add. Same as 'visible' if left empty -->

<addable>

</addable>

<!-- Aspects that a user can remove. Same as 'visible' if left empty -->

<removeable>

</removeable>

</aspects>

</config>

<!-- cm:content type (existing nodes) -->

<config evaluator='node-type' condition='cm:content'>

<forms>

<!-- Default form configuration used on the document details and edit metadata pages -->

This configuration will add the KB reference field at the bottom of the main Edit Metadata form, the pop-up edit form used in the document list view and lastly the in-line edit form used for HTML, text and XML content (introduced in Alfresco 3.3).

Note: More advanced control is possible over the placement of the field within the form, but this requires copying over the full form definitions for the cm:content type from the file alfresco/web-framework-config-commons.xml (or alfresco/share-form-config.xml in 3.3 onwards) inside the Share webapp and adding the attribute replace='true' on the <config> element.

Now that you've configured Share, you must restart Tomcat so that the changes are picked up. The application should start up and you should be able to add the aspect to some content and see the document reference field appear in forms.

The last thing to do is to add an i18n label for the Knowledge Base aspect in the Manage Aspects dialogue. To do this we need to define a small bit of Spring configuration in the file alfresco/web-extension/custom-slingshot-application-context.xml, which will wire the knowledgebase.properties file we created earlier into Share.

This configuration tells Share to look in the file knowledgebase.properties for aspect labels, in addition to the core message bundles.

With that file added you should be able to restart Tomcat again and see the correct label in the Manage Aspects dialogue. You've now fully-customised Alfresco Share to support additional custom aspects.

Update: Thanks to Brian Ochs, who pointed out that the additional message aspect.kb_referencable is also required in knowledgebase.properties.

Update: The configuration files in this tutorial can now be downloaded in ZIP format. To use them directly extract the archive into tomcat/shared/classes and restart the server. Please do not use these files, which are now outdated.

I was missing how to define I18N message bundles, I now have that piece. However, I think you actually need to define appearance separately from node-type evaluator for aspects, else your aspect will show for that node regardless if it is added to the node or not. See my post http://loftux.se/en/2010/02/11/alfresco-forms-for-share/

Thanks Peter, good tip. I found that the node-type and aspect evaluators worked identically on my test system, but I'd be interested in any differences you see. The lack of docs for the latter makes it difficult to know which to use, when.

I can't seem to get the i18 stuff to work in 3.2r. Below is my current config on which Alfresco starts properly. However, Share generated new errors. What is the correct content of custom-slingshot-application-context.xml?

Jan - it looks like the Spring configuration I had for version 3.2 was slightly incorrect, as I was using the wrong bean class. If you use the updated configuration above then you should find that gets rid of your errors.

Ray, I assume you mean the Create/Edit Site form? Right now that involves modifying the hard-coded form in the presentation tier web-scripts, plus the web-tier and repository-tier scripts that are responsible for creating the site structure.

What sort of information would you like to record against the site node that currently isn't there?

Hi Will - thanks for the great tutorial! Unfortunately it didn't completely work for me until I configured the visible aspects in tomcat\webapps\alfresco\WEB-INF\classes\alfresco\templates\webscripts\org\alfresco\slingshot\documentlibrary\aspects.get.config.xml instead of share-config-custom.xml. Honestly I have no idea why this is the case for my installation as it is the current 3.2r2 CE. Do you have an idea? I further dislike the fact that I have to edit an existing config file instead of overwriting the configuration in a seperate one.

Chris, I think the mechanism should work in 3.2r2, but the place to check is the aspects.get.js script. You should see that the script attempts to look up the global aspect config that the example places in share-config-custom.xml, and if that is not found it falls back to the web script config.

I checked aspects.get.js but it only accesses the local xml-configuration and not the global or scoped config. Too bad. Seems I have to wait for 3.3 which hopefully won't take too long. Thank you very much for your help!

I have the same result as feedler. The custom aspects are not displayed when placed in share-config-custom.xml in the web-extension folder. I don't see a reference to global or scoped config in aspects.get.js. I am using v3.2 community. When I move to 3.3 I'll move the customizations. Thanks for your article.

Steve, feedler, you may be able to port over the additional logic from aspects.get.js in 3.3. I'm pretty sure the scoped config was supported in version 3.2, but that particular web script did not implement it.

But, it's not quite working for me. I'm using 3.3, but can't get the aspect title to appear in the 'Manage Aspects' dialog. Instead, it just shows 'aspect.my_myaspect'. I've tried setting aspect.my_myaspect in tomcat/shared/classes/alfresco/web-extension/messages/myproject.properties, but it still doesn't. What am I missing?

Mary, as Brian says above you need to add the message aspect.my_myaspect to the properties file in the post. I've updated the post accordingly now, so those instructions should work fully now. Thanks for the feedback.

azade, it looks like you've specified an invalid name for your model to me. Best to stick to lowercase letters only and no spaces, i.e. customerdetails. You should also define your own namespace rather than using the Alfresco content model. See http://wiki.alfresco.com/wiki/Data_Dictionary_Guide for more details.

Hi Will, I try to add a custom aspect using your tips, I put your customization file(kb-model-context.xml, kb-model.xml, share-config-custom.xml ) in alfresco folders but I can't see anything in Alfresco Share. No errors.

Ciprian, it's difficult to tell what the problem may be from the information you've posted. So instead, I would suggest you post a complete copy of your configuration (ideally in ZIP format) in the Share user forum - http://forums.alfresco.com/en/viewforum.php?f=47.

Hi Will, thanks for your reply. I'm newbie in Alfresco. For about a month I try to customize Alfresco to show any custom metadata in 'Edit Metadata' page, but without any succes. What I'm doing is just to install Alfresco CE v3.2R2 and to copy/paste your three configuration files in this locations: \tomcat\shared\classes\alfresco\extension\kb-model-context.xml; \tomcat\shared\classes\alfresco\extension\kb-model.xml and \tomcat\shared\classes\alfresco\web-extension\share-config-custom.xml. I need to do more settings or steps in order to show me something in Edit Metadata form?

One problem though: the i18n labels don't work. I followed the steps you described, but in Share I see 'label.kb_documentRef' instead of 'KB reference'. The same goed for the Aspect selection-screen, where I see 'aspect.kb_referencable'.

When I make a rule to add the aspect to certain files, I get the right description. So I don't know what's happening.

Is it possible in any way to configure new message bundles without overriding the original webscripts.resources bean? If not, it is hard to deploy several Share customizations that all include messages. I have tried to create my own org.springframework.extensions.surf.util.ResourceBundleBootstrapComponent bean but the messages I load is not picked up by Share.

I'm using 3.4.b Community Edition and everything worked fine until I tried adding the i18n labels. Perhaps I just don't know enough about how Alfresco is setup yet...

custom-slingshot-application-context.xml didn't exist, so I created it, and then I created knowledgebase.properties. When I restarted the server, all Share pages were broken and only displayed the following error message:

A problem has occurred.

This page could not be rendered:

[any page I entered the URL for]

Please notify your system administrator.

I can get by without the i18n labels for now, so it isn't the end of the world, but does anyone know what might be causing my issue?

In Alfresco community edition 3.3g, if you put all existing aspects in the aspects/visible element in web-extension/share-config-custom.xml, you will end up with duplicates of existing aspects in the aspect selection dialog. I had to only add my own aspects as visible in the visible list to get everythings fine.

Fez, I was getting the error when trying to view the metadata in Share:

org.alfresco.service.namespace.NamespaceException: Namespace prefix xyz is not mapped to a namespace URI

I eventually found the solution, after much frustration. I even resorted to installing a completely fresh install of Alfresco 3.4.b after I first encountered the problem with Alfresco 3.4.a.

Every example and reference on the web that I found had the following bean declaration, which presumably must have worked at some point, since it is so ubiquitous.

However, no matter what garbage I put in the model context file it was silently ignored and the bean was never registered. It wasn’t until I stumbled across a correction to the 'Alfresco Developer Guide' that I saw what was wrong with ALL the other examples. Even the downloadable examples from the author of the book were wrong.

tl;dr You can't use a bean id of 'extension.dictionaryBootstrap'. Change the 'extension' part to something else.

Jordi, I suspect that is because Java message bundles do not support non-ASCII characters. If you have accented characters, you must convert your file using the native2ascii tool supplied with Sun's JDK. A quick Google on the subject should turn up a beginner's guide.

Elessar, I've updated the post to make it clearer but you must have the right configuration for your version of Alfresco in custom-slingshot-application-context.xml, or your labels will not display properly.

If you still have problems then I've also added a ZIP file containing the complete set of files to the bottom of the post.

Lyle, the issue with the 'extension.dictionaryBootstrap' bean ID is that you cannot have more than one bean with the same ID in Spring. So, if you already have another customisation installed using that ID then any others that re-use it will not work.

I've updated the bean IDs in the code listings above to work around this, now.

Ashok, you can customise the appearance of the form further if you copy over the form definitions for the cm:content types from WEB-INF/classes/alfresco/web-framework-config-commons.xml into your share-config-custom.xml. See http://wiki.alfresco.com/wiki/Forms for more information.

Will -- can you confirm that you've been able to use the advanced search function in Share to find documents based on a property value that is part of a custom aspect? If so, how do you define the advanced search form 'search' for an aspect? Thanks

I am very new to Alfresco. The example you provided worked for files uploaded to a folder in document library. When I apply this aspect to a folder it is not displaying the fields added. Can you please help me in what to do.This is my requirement I need a folder to created with couple of customizable meta data fields. Now when ever a file is uploaded into that folder the meta data of folder should be inherited. Appreciate any guidance.

Hi Pavani, that's a good question and to apply the custom form configuration to folder items you would need to change the attribute value 'cm:content' in the share-config-custom.xml file above to 'cm:folder'. Alternatively as Peter suggests in his post you can base this configuration on the aspect rather than the type - see http://loftux.se/en/2010/02/11/alfresco-forms-for-share/.

Fracesco, mspier, you should find some information on configuring the new Advanced Search screens on the wiki here: http://wiki.alfresco.com/wiki/Share_Advanced_Search. Once you're happy with the basic form configuration used in this example you should find this easy, as it re-uses the same approach to configure forms for different types/aspects.

Exactly the tutorial I'm after, many thanks, however, I'm having the same problem as Zach (above). I'm using 3.4.d, it just breaks the whole site setup. The site would load correctly before adding the 'share-config-custom.xml' file, then it broke.

Hi Chris, I would check that you are definitely declaring an instance of org.springframework.extensions.surf.util.ResourceBundleBootstrapComponent in your Spring config in custom-slingshot-application-context.xml - this is the first snippet provided in the post. The second snippet will likely not work as it uses the old org.alfresco class which was used in v3.2 and earlier but has now been replaced by the Spring class.

many thanks Will, I performed a clean installation and all was fine. This has saved my ass, really appreciate the tut. I had a go at the SDK/Eclipse and FDK methods but, being a newbie to this, had all sorts of problems.

We use cookies on this site to enhance your user experience

By using this site, you are agreeing to allow us to collect and use cookies as outlined in Alfresco’s Cookie Statement and Terms of Use (and you have a legitimate interest in Alfresco and our products, authorizing us to contact you in such methods). If you are not ok with these terms, please do not use this website.