Using Files to Configure Module Components

Liferay DXP uses Felix File Install to monitor file system folders for new/updated configuration files, and the Felix OSGi implementation of Configuration Admin to let you use files to configure module service components.

To learn how to work with configuration files, first review Understanding System Configuration Files.

Configuration File Formats

There are two different configuration file formats:

  • .cfg: An older, simple format that only supports String values as properties.
  • .config: A format that supports strings, type information, and other non-string values in its properties.

Although Liferay DXP supports both formats, use .config files for their flexibility and ability to use type information. Since .cfg files lack type information, if you want to store anything but a String, you must use properties utility classes to cast Strings to intended types (and you must carefully document properties that aren’t Strings). .config files eliminate this need by allowing type information. The articles below explain the file formats:

Naming Configuration Files

Before you create a configuration file, follow these steps to determine whether multiple instances of the component can be created or if the component is intended to be a singleton:

  1. Deploy the component’s module if you haven’t done so already.

  2. In Liferay DXP’s UI, go to Control PanelConfigurationSystem Settings.

  3. Find the component’s settings by searching or browsing for the component.

  4. If the component’s settings page has a section called Configuration Entries, you can create multiple instances of the component configured however you like. Otherwise, you should treat the component as a singleton.

Figure 1: You can create multiple instances of components whose System Settings page has a Configuration Entries section.

Figure 1: You can create multiple instances of components whose System Settings page has a *Configuration Entries* section.

All configuration file names must start with the component’s PID (PID stands for persistent identity) and end with .config or .cfg.

For example, this class uses Declarative Services to define a component:

package com;
class Foo {}

The component’s PID is com.Foo. All the component’s configuration files must start with the PID com.Foo.

For each non-singleton component instance you want to create or update with a configuration, you must use a uniquely named configuration file that starts with the component’s PID and ends with .config or .cfg. Creating configurations for multiple component instances requires that the configuration files use different subnames. A subname is the part of a configuration file name after the PID and before the suffix .config or .cfg. Here’s the configuration file name pattern for non-singleton components:

  • [PID]-[subname1].config
  • [PID]-[subname2].config
  • etc.

For example, you could configure two different instances of the component com.Foo by using configuration files with these names:

  • com.Foo-one.config
  • com.Foo-two.config

Each configuration file creates and/or updates an instance of the component that matches the PID. The subname is arbitrary—it doesn’t have to match a specific component instance. This means you can use whatever subname you like. For example, these configuration files are just as valid as the two above:

  • com.Foo-puppies.config
  • com.Foo-kitties.config

Using the subname default, however, is Liferay DXP’s convention for configuring a component’s first instance. The file name pattern is therefore


A singleton component’s configuration file must also start with [PID] and end with .config or .cfg. Here’s the common pattern used for singleton component configuration file names:


When you’re done creating a configuration file, you can deploy it.

Resolving Configuration File Deployment Failures

The following IOException hints that the configuration file has a syntax issue:

Failed to install artifact: [path to .config or .cfg file] Unexpected token 78; expected: 61 (line=0, pos=107)

To resolve this, fix the configuration file’s syntax.

Great! Now you know how to configure module components using configuration files.

Understanding System Configuration Files

« Sort Order Changed with a Different Database
Was this article helpful?
0 out of 0 found this helpful