Adding Custom Aspect Support in Alfresco Share

cancel
Showing results for 
Search instead for 
Did you mean: 

Adding Custom Aspect Support in Alfresco Share

wabson
Active Member II
0 61 4,873
Since Alfresco 3.2 introduced the ability to configure the metadata forms used in the Document Library, there have been several good articles 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.



First, the Spring configuration defined in alfresco/extension/kb-model-context.xml

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>



<beans>



    <!-- Registration of new models -->

    <bean id='extension.kb.dictionaryBootstrap' parent='dictionaryModelBootstrap' depends-on='dictionaryBootstrap'>

        <property name='models'>

            <list>

                <value>alfresco/extension/kb-model.xml</value>

            </list>

        </property>

    </bean>



     <bean id='extension.kb.resourceBundle' class='org.alfresco.i18n.ResourceBundleBootstrapComponent'>

       <property name='resourceBundles'>

          <list>

             <value>alfresco.messages.knowledgebase</value>

          </list>

       </property>

    </bean>



</beans>


Then, define the model itself in alfresco/extension/kb-model.xml

<?xml version='1.0' encoding='UTF-8'?>



<!-- Definition of Knowledge Base Model -->



<model name='kb:knowledgebase' xmlns='http://www.alfresco.org/model/dictionary/1.0'>



   <!-- Optional meta-data about the model -->

   <description>Knowledge Base Model</description>

   <author>Will Abson</author>

   <version>1.0</version>



   <!-- Imports are required to allow references to definitions in other models -->

   <imports>

      <!-- Import Alfresco Dictionary Definitions -->

      <import uri='http://www.alfresco.org/model/dictionary/1.0' prefix='d'/>

      <!-- Import Alfresco Content Domain Model Definitions -->

      <import uri='http://www.alfresco.org/model/content/1.0' prefix='cm'/>

   </imports>



   <!-- Introduction of new namespaces defined by this model -->

   <namespaces>

      <namespace uri='http://www.alfresco.com/model/knowledgebase/1.0' prefix='kb'/>

   </namespaces>



    <aspects>

      <!-- Definition of new Content Aspect: Knowledge Base Document -->

      <aspect name='kb:referencable'>

         <title>Knowledge Base Referencable</title>

         <properties>

            <property name='kb:documentRef'>

               <type>d:text</type>

            </property>

         </properties>

      </aspect>

   </aspects>



</model>




The last file in our model definition adds some i18n labels for the aspect and property names. Add the following content to the file alfresco/messages/knowledgebase.properties.

# Custom knowledge base messages

kb_knowledgebase.property.kb_documentRef.title=KB Reference

kb_knowledgebase.aspect.kb_referencable.title=Knowledge Base Referencable

aspect.kb_referencable=Knowledge Base Referencable




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 -->

         <form>

            <field-visibility>

               <show id='kb:documentRef' />

            </field-visibility>

         </form>



         <!-- Document Library pop-up Edit Metadata form -->

         <form id='doclib-simple-metadata'>

            <field-visibility>

               <show id='kb:documentRef' />

            </field-visibility>

            <edit-form template='../documentlibrary/forms/doclib-simple-metadata.ftl' />

         </form>



         <!-- Document Library Inline Edit form -->

         <form id='doclib-inline-edit'>

            <field-visibility>

               <show id='kb:documentRef' />

            </field-visibility>

         </form>

      </forms>

   </config>



</alfresco-config>


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.

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>



<beans>



   <!-- Add Knowledge Base messages -->

   <bean id='webscripts.kb.resources' class='org.springframework.extensions.surf.util.ResourceBundleBootstrapComponent'>

      <property name='resourceBundles'>

         <list>

            <value>alfresco.messages.knowledgebase</value>

         </list>

      </property>

   </bean>



</beans>


In versions prior to Alfresco 3.3 (when some changes were made to the Share resource bundle classes) the following configuration must be used instead (note the different class name)

<?xml version='1.0' encoding='UTF-8'?>

<!DOCTYPE beans PUBLIC '-//SPRING//DTD BEAN//EN' 'http://www.springframework.org/dtd/spring-beans.dtd'>



<beans>



   <!-- Add Knowledge Base messages -->

   <bean id='webscripts.kb.resources' class='org.alfresco.i18n.ResourceBundleBootstrapComponent'>

      <property name='resourceBundles'>

         <list>

            <value>alfresco.messages.knowledgebase</value>

         </list>

      </property>

   </bean>



</beans>


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.
61 Comments
blog_commenter
Active Member
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/



Cheers, Peter
wabson
Active Member II
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.
blog_commenter
Active Member
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?











  

  

     

        

            alfresco.messages.webscripts

            alfresco.messages.slingshot

            alfresco.web-extension.messages.knowledgebase

        

     

  



blog_commenter
Active Member
Hi Will - was wondering if there were any plans to support this at the Site Level?  I would love to be able to display additional aspects to extend Site (folder) metadata, not just on documents.
wabson
Active Member II
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.
wabson
Active Member II
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?
blog_commenter
Active Member
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.



Cheers

Chris
wabson
Active Member II
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.
blog_commenter
Active Member
I checked aspects.get.js but it only accesses the local xml-configuration and not the global or scoped config. Too bad. Smiley Sad Seems I have to wait for 3.3 which hopefully won't take too long. Thank you very much for your help!
blog_commenter
Active Member
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.
wabson
Active Member II
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.
blog_commenter
Active Member
[...] Abson describes how to add a custom aspect and enable it in share in this blog post. Following is the definition of the filed aspect as it is defined in the something-model.xml [...]
blog_commenter
Active Member
Thanks for this post! I was able to get my first custom aspect working in no time.



However, I am using 3.3 and noticed that the aspect label would not appear correctly in the Share UI unless I used aspect.kb_referencable=Knowledge Base Referencable in the properties file.
blog_commenter
Active Member
This is a great post! It's been very helpful.



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?
blog_commenter
Active Member
Hey guys!

i wanted to ask if your custom properties are searchable..

Thanks,

Kyriakos
blog_commenter
Active Member
I Tried this. It worked at first. Then I had a problem, this is what I did:



1. Created the 'kn:referencable' aspect, just like indicated here (copy-paste). re-start. It Worked!



kb-model-context.xml

kb-model.xml

share-config-custom.xml



2. y Created a NEW aspect, basically modifying the kb files, (basically changed kb -> pk, and namespace knowledgebase -> primarykey) and add it to the aspects.



pk-model-context.xml

pk-model.xml

share-config-custom.xml



I get this error:



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



I try to rollback to the original aspect from this example and then I get:



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



I don't understand this error, Will, or anyone can pleasehelp with some guidance on this, I created the followinf topic for it:



https://www.alfresco.com/blogs/wabson/2010/02/25/adding-custom-aspect-support-in-alfresco-share/



Thannks in advance.
blog_commenter
Active Member
hi i am new in alfresco when i add customer details i get this error

Failed to create content due to error: 06050000 The aspect is invalid: {http://www.alfresco.org/model/content/1.0}Customer Details

please help me
wabson
Active Member II
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.
wabson
Active Member II
Kyriakos, your custom properties should be searchable via the search APIs, and you can also get the Advanced Search in Alfresco Explorer and the search box in Share to query these values.



If you want to change the default indexing behaviour, this article may be of interest - http://wiki.alfresco.com/wiki/Data_Dictionary_Guide#Additional_Property_Capabilities
wabson
Active Member II
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.
blog_commenter
Active Member
Great post, but the I18 part isn't working for me.

I don't see any errors, but it isn't picking up the properties I defined.  I'm using 3.3 and have the same code as you show above.

I changed web-extension/custom-slingshot-application-context.xml as per 3.3.

Is there a flag in log4j that I can set to see if it is picking up the new properties file on startup?
blog_commenter
Active Member
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.

Can you tell me what I'm doing wrong
wabson
Active Member II
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.
blog_commenter
Active Member
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?
blog_commenter
Active Member
Great post. I just created a custom aspect, and it works as promised.

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.



I use the latest 3.4 nightly, maybe that has something to do with it?

Does 3.4 have altered message bundles compared to 3.3?
blog_commenter
Active Member
Hi

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.
blog_commenter
Active Member
Hi Will,

I am new to alfresco and i am fecing some problem with customization approach.

I tried according to the procedure you have given here.



Its working fine upto i that aspect adding.After that when i tried to add the i18N label its showing some error in the custom-slingshot-application-context.xml file.



I followed the approach as.



in the custom-slingshot-application-context.xml file i copied







  

  

     

        

            webscripts.messages.webscripts

            alfresco.messages.common

            alfresco.messages.slingshot

            alfresco.web-extension.messages.knowledgebase

        

     

  







after that i created a properties file called knowledgebase.properties



and copied



# Custom knowledge base messages

label.kb_documentRef=KB Reference

kb_referencable=Knowledge Base Referencable

aspect.kb_referencable=Knowledge Base Referencable



when i am trying to run the alfresco .

after i will give login credintials its showing error like



ERROR[surf.render.RenderService] Unable to process template:slingshot-login

Error:[Extensions.surf.FrameworkUtil] Error occured while rendering the page:slingshot-login

org.springframework.extension.surf.exception.RendererExecutionException:WebTemplateProcessor failed to process template uriSmiley Surprisedrg/alfresco/gloabl/slingshot-login

...





plz tell me the way how to solve it.
blog_commenter
Active Member
Hi,



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?
blog_commenter
Active Member
Hi Will,



Thank you very much for this excellent post !



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.
blog_commenter
Active Member
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.
blog_commenter
Active Member
Thanks for an excellent article



I have been able to populate the metadata on the form. Please let me know if it is possible

to have more control over the appearance in the form (share-config-custom.xml file), such as drawing

a horizontal line etc.
blog_commenter
Active Member
Hi, I have a problem with accents. If I put accents inside the properties file in the messages folder they don't display correctly. Any ideas?
wabson
Active Member II
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.
blog_commenter
Active Member
Everything is fine except for the labels, the custom slingshot configuration may not be appliying ...



It's a pitty, because I'd like not to touch the official files.
wabson
Active Member II
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.
wabson
Active Member II
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.
wabson
Active Member II
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.
blog_commenter
Active Member
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
wabson
Active Member II
Steve - in the case of this example you'd just add the property to the search form for cm:content, or even better define a second form for cm:content items to keep the aspect-applied properties off the main search form. You'll need to force the field 'on' in the form, see http://wiki.alfresco.com/wiki/Share_Advanced_Search#A_property_that_would_normally_be_hidden_in_Edit.... for more info.
blog_commenter
Active Member
Hi,



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.



Regards,

Pavani
wabson
Active Member II
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/.
blog_commenter
Active Member
Thank you Will
blog_commenter
Active Member
Hi,



I am trying to create a folder and apply this aspect from code using

CMLAddAspect addaspect = new CMLAddAspect();

addaspect.setAspect('{kb:referencable}Knowledge Base Referencable');

I am getting the following error.

The aspect is invalid: {kb:referencable}Knowledge Base Referencable

expecting some help in this.



Regards,

Pavani
blog_commenter
Active Member
Sorry Will,



I got the solution Smiley Happy

addaspect.setAspect(“{namespace URI}Aspect name without prefix”);

i.e,

addaspect.setAspect('{http://www.alfresco.com/model/knowledgebase/1.0}referencable');



Regards,

Pavani
blog_commenter
Active Member
Hi

Will i configured the new aspect and display in share adding aspect to the document, but i cannot search by these properties of the new aspect
blog_commenter
Active Member
Hi Will, thanks for the post, I've configured everything correctly.

Could you give some guidance on how to bring up additional properties in the advanced search?

Thanks!
wabson
Active Member II
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.
blog_commenter
Active Member
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.
wabson
Active Member II
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.
blog_commenter
Active Member
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.

Thanks again