The Alfresco Share Document Library provides a set of status indicators that can be used to indicate the state of of a document (or folder) in Alfresco. This can include indicator icons for attached Aspects as well (such as EXIF aspect for photos). There are a variety of indicators provided out of the box. Some example indicators include: documents attached to a workflow, documents checked out for editing, and documents that have been declared as records. Alfresco is also easily extensible to add your own status indicators. This article will walk through an example of adding a custom indicator for Alfresco documents.
Before providing an example of adding a custom status indicator, an example of some of the out of the box indicators is provided below. In the screen shot below, there is a document with EXIF metadata, a document associated with a workflow, and a document that has been locked for editing by the current user. Each of these documents has a status indicator next to the document thumbnail:
Example Document Status Indicators
The Alfresco documentation provides a description of custom indicators; however, this article will add to that to provide a step-by-step guide to make adding custom indicators easy. For reference, the Alfresco documentation may be accessed here:
The basic steps for adding a custom indicator are:
- Create a Java class that extends BaseEvaluator that implements the “evaluate” method.
- In the “evaluate” method, determine whether your test condition is true or false, and return the result.
- Configure your Java class as a bean in a context file so that it can be accessed via its bean ID.
- Add the custom indicator definition to the Share config XML file. Indicators are part of the “DocumentLibrary” condition.
- Create an icon to be used as the indicator. It should be a 16×16 pixel icon, and will need to be deployed to “share/components/documentlibrary/indicators”.
For this example, we will be adding an indicator that will display when a document (or folder) has its “Inherit Permissions” setting configured to be “false”. If a document or folder inherits permissions from its parent, no status indicator will be displayed. However, if inheritance is turned off, a small icon of a key will be displayed as the status indicator.
The first step for creating this custom indicator is to create the evaluator that will determine if the icon should be displayed. A Java class will be created that extends “org.alfresco.web.evaluator.BaseEvaluator”. The “BaseEvaluator” class has an abstract method named “evaluate” that must be implemented by the class.
The “evaluate” method has a parameter “jsonObject” which provides the metadata for the document (or folder) being evaluated. The JSON object that is passed to this method includes the metadata properties for the object, but it also includes information about security as well.
For this customization, we are trying to determine if the security inheritance has been turned off for the document or folder. If inheritance has been disabled, the method should return ‘true’ so that the icon will be displayed.
The root of the JSON object is ‘node’, and the field we are interested in, which is ‘inheritance’, is under the ‘permissions’ section of the JSON. An example snippet of the JSON is provided below:
"node":{
"permissions":{
"inherited":true,
"roles":[
"ALLOWED;GROUP_site_test_SiteConsumer;SiteConsumer;INHERITED",
"ALLOWED;GROUP_EVERYONE;ReadPermissions;INHERITED",
"ALLOWED;GROUP_site_test_SiteCollaborator;SiteCollaborator;INHERITED",
"ALLOWED;GROUP_site_test_SiteContributor;SiteContributor;INHERITED",
"ALLOWED;GROUP_EVERYONE;SiteConsumer;INHERITED",
"ALLOWED;GROUP_site_test_SiteManager;SiteManager;INHERITED",
],
"user":{
"Delete":true,
"Write":true,
"CancelCheckOut":false,
"ChangePermissions":true,
"CreateChildren":true,
"Unlock":false
}
}
For this document, the value of “inheritance” is “true”, so the icon would not be displayed.
The “BaseEvaluator” class provides a variety of methods for analyzing the JSON that has been passed to the method. This example will use “getJSONValue” to return the value of a specific JSON field. However, it is worth reviewing the source code of the “BaseEvaluator” class to see all of the methods provided:
For the Java class in this example, we will look for the value of the field ‘node.permissions.inherited’. If this value is ‘true’, we will return ‘false’, as the icon should not be displayed since inheritance is enabled. If the value is ‘false’, we will return ‘true’, so that the icon will be displayed since inheritance is disabled. The amount of code required for this example is very small, so the entire class is provided below:
package com.ArgonDigitalgroup.indicators;
import org.alfresco.error.AlfrescoRuntimeException;
import org.alfresco.web.evaluator.BaseEvaluator;
import org.json.simple.JSONObject;
public class InheritanceEvaluator extends BaseEvaluator {
private static final String INHERITED = "node.permissions.inherited";
@Override
public boolean evaluate(JSONObject jsonObject)
{
try{
Boolean isInherited = (Boolean)getJSONValue(jsonObject,INHERITED);
if (isInherited != null && !isInherited) {
return true;
}
else {
return false;
}
}
catch (Exception e){
throw new AlfrescoRuntimeException("Failed to run
Inheritance UI evaluator: " + e.getMessage());
}
}
}
Once the Java class has been created, it should be injected as a Spring bean into Alfresco Share via a context file. The code snippet below provides an example, this snippet would need to be in a context file that is loaded by Share at startup:
<bean id="evaluator.
doclib.indicator.inheritanceEvaluator"
class="com.ArgonDigitalgroup.indicators.
InheritanceEvaluator"/>
The next step is to define the indicator in the “DocumentLibrary” section of the Share configuration XML. This logic can be included in a standalone XML file that is bootstrapped with a context XML file (this is a better approach than overwriting the out of the box XML files). An example is provided below:
<config evaluator="string-compare"
condition="DocumentLibrary">
<indicators>
<indicator id="inheritance-off"
icon="icon-key-16.png" index="99"
label="Security Inheritance Off">
<evaluator>evaluator.doclib.
indicator.inheritanceEvaluator</evaluator>
</indicator>
</indicators>
</config>
As long as ‘override’ is not set to ‘true’ in the config element, the indicator will be added to the rest of the indicators defined in the out of the box XML configuration files.
In the ‘evaluator’ configuration, an ID value has been set, along with a reference to the icon that should be used. In addition, a label has been defined (in this example, we are hard coding the label, but it could be templatized to support localization if needed). Lastly, we provide a pointer to the Spring Bean that should be used as the evaluator for this indicator. In this case, we are pointing to our Java class.
The last step is to set up the deployment package so that the custom icon is deployed to “share/components/documentlibrary/indicators”. For this example, a PNG file named “icon-key-16.png” is deployed to that directory.
Once the code has been deployed, when we disable “Inherit Permissions” for a document or folder, we should see our key icon appear next to the document thumbnail or the folder icon. The screen shot below shows an example of disabling “Inherit Permissions” for a document named “LocalPermissionsOnly.txt”:
Inherit Permissions is Off
Once permissions have been disabled on the document, when it is viewed from the Document Library, the ‘key’ icon should appear. The screen shot below provides an example of this. The top document, “InheritedPermissions.txt” has “Inherit Permissions” enabled, so the icon is not displayed. However, for the second document, “LocalPermissionsOnly.txt”, “Inherit Permissions” has been disabled, and the icon is displayed for this document:
Custom Indicator
For this example, we are using the state of the content’s permissions to determine when to display our icon. However, the JSON also provides access to the attached aspects and the content metadata properties, too. So, these could also be used to determine if a status indicator should be displayed. Once this framework is set up, it is easy to add custom indicators to your Alfresco deployment.
