We used cookies to ensure that we give you the best experience on our website. If you continue to use this site we will assume that you are happy with it. What For?

« Back to Blogs

Transition from portlet preferences to the Configuration API

To store portlet level configuration data, we are mostly using Portlet preferences. There is also another way available to configure Liferay Portal CE 7.0 applications which is Configuration API. I am going to show how we can move from portlet preferences to Configuration API.

The main benefit of using the Configuration API is we can configure default settings of portlet through System Settings UI.

Here is a complete guide for how we can switch from the traditional way to store portlet preferences to the new way with Configuration API. Below are detailed steps to do so:

Step - 1

Create a jsp to get inputs of configuration,

Give it a name configuration.jsp

Add all configuration input fields in this configuration jsp


<liferay-portlet:actionURL portletConfiguration="<%= true %>" var="<%= configurationActionURL %>" />
<liferay-portlet:renderURL portletConfiguration="<%= true %>" var="<%= configurationRenderURL %>" />

<aui:form action="<%=configurationActionURL%>" method="post" name="fm" />

<aui:input name="redirect" type="hidden" value="<%= configurationRenderURL %>" />
<aui:input name="<%=Constants.CMD%>" type="hidden" value="<%=Constants.UPDATE%>" />
<aui:input name="displayCountry" label="Country" value="<%= portletInstanceConfiguration.displayCountry() %>"/>
<aui:button type="submit"></aui:button>



Step - 2

Create a jsp to get inputs of configuration, Give it a name configuration.jsp Add all configuration input fields in this configuration jsp

There are mainly three kinds of portlet configuration Scopes:

  • Portlet Instance
  • Group
  • Company

Create a Java interface for the configuration

  • As per Liferay, Interface name should be
    • [Portlet name]PortletInstanceConfiguration for the Portlet Instance scope
    • [Portlet name]GroupServiceConfiguration for the Group scope, However you can choose different names
  • This interface will use two annotations: @ExtendedObjectClassDefinition and @Meta.OCD.
    • @ExtendedObjectClassDefinition is used to specify the desired scope and to specify the category in System Settings where these preferences are displayed.
    • @Meta.OCD is used to add id which is used to identify the configuration interface and it must be the fully qualified class name of the interface. Another two properties are localization (to localize portlet configuration) and name (to specify the name of the configuration as it will appear in System Settings)
    • Example:

          category = "[category]",
          scope = ExtendedObjectClassDefinition.Scope.PORTLET_INSTANCE
          id = "[package].[PortletName]PortletInstanceConfiguration",
          localization = "content/Language", 
          name = "[name]"
      public interface [PortletName]PortletInstanceConfiguration {
          @Meta.AD(required = false)
          public String displayCountry();
  • Replace [category] with a category name of your choice (You can give an existing category of System Settings or provide a custom category name which will be added to System Settings in Liferay Portal).
  • Localization is used to translate it to several languages
  • Replace [name] with a configuration name of your choice
Step - 3

Override the processAction method so that it reads a URL parameter from the action request, sets the value as a portlet preference, and invokes the processAction method of the SettingsConfigurationAction ancestor class


public class [PortletName]ConfigurationAction extends DefaultConfigurationAction {
	public String getJspPath(HttpServletRequest request) {
		return "/configuration.jsp";
	public void processAction(PortletConfig portletConfig, ActionRequest actionRequest, ActionResponse actionResponse) throws Exception {
		String displayCountry = ParamUtil.getString(actionRequest, "displayCountry");
		setPreference(actionRequest, "displayCountry", displayCountry);
		super.processAction(portletConfig, actionRequest, actionResponse);
		target = "(osgi.web.symbolicname=[symbolic_name])", unbind = "-"
	public void setServletContext(ServletContext servletContext) {
  • Replace [symbolic_name] by the bundle’s symbolic name which you can find in bundle’s bnd.bnd file
Step - 4

Create one class that implements the ConfigurationBeanDeclaration interface to know about the Configuration class.


public class [PortletName]PortletInstanceConfigurationBeanDeclaration
        implements ConfigurationBeanDeclaration {
    public class getConfigurationBeanClass() {
        return [PortletName]PortletInstanceConfiguration.class;
Step - 5

Now, Change the configuration JSP by adding following code to retrieve the configuration using the Configuration API. If the portlet configuration scope is Portlet Instance the configuration can be retrieved from portletDisplay.


[PortletName]PortletInstanceConfiguration portletInstanceConfiguration = 

After getting configuration object, you can retrieve preferences as follow:

String displayCountry = portletInstanceConfiguration.displayCountry();
Step - 6

In case where the portletDisplay is not available, or when the scope is Group or Company then use the PortletProvider class.

  • In OSGI component, we can obtain reference to the ConfigurationProvider by following code:
    @Component(service = Entity)
    public class Entity {
    protected void methodWhichNeedsConfiguration() {
     [PortletName]GroupServiceConfiguration.class, groupId);
                private ConfigurationProvider _configurationProvider;
  • To use configuration data in services which are created by Service Builder then use below code
    public class EntityServiceImpl {
    	protected void methodWhichNeedsConfiguration() {
    			[PortletName]GroupServiceConfiguration.class, groupId);
    	private ConfigurationProvider _configurationProvider;
  • For any other cases other than above, We can use ConfigurationProviderUtil to obtain the configuration.
    [PortletName]GroupServiceConfiguration groupConfiguration =   
    ConfigurationProviderUtil.getGroupConfiguration([PortletName]GroupServiceConfiguration.class, groupId);

That's it..!! You are ready to go with Configuration API.

contact-us Request a callback WhatsApp