The Apps feature enables you to integrate and manage information used to integrate with external sites, services, and applications, such as translations using Google Translate, or single sign-on authentication using SAML. Apps integrations are performed via a combination of App Configuration, Secrets Storage, and the Apps API.
- Built-in Apps Integrations
- Configuration Files
- Secrets Storage
Built-in Apps Integrations
The dotCMS starter site includes several example Apps integrations, including:
- Amazon Rekognition (automated classification and tagging of images)
- Google Translate
- Edit Mode Anywhere (support for proxy requests for Single Page Apps)
- SAML Authentication
Though some of these Apps may be used as examples throughout the rest of this document, this document does not describe any of these built-in integrations, or how to use them, in detail.
You can configure each App in the Apps Tool. When you select the Apps Tool, all of the Apps currently installed are displayed in a card view, with one card for each installed App. You can configure individual Apps by clicking on the App.
Editing App Properties
There is a separate configuration for each Site on your dotCMS instance, for each installed App. In addition, there is also a configuration for the System Host for each App. When you select any App, the display will change to show one line will be shown for each Sites. To configure a Site, click on it in this view.
The properties which can be configured for each Site are determined by the App (as defined in the App configuration file). For more information on the properties available for each given App, please view the Hint fields for each property, and any documentation provided by the App developer.
By default, all Apps configurations are stored in the
/assets/server/apps/ folder within the dotCMS distribution (
- All files containing valid App configurations will be used.
- If any errors are encountered when reading any App configuration, that configuration file will be ignored, but all other valid files will continue to be read.
- You can change the location where Apps configuration files are stored by adding the
APPS_DIR_PATH_KEYproperty to the dotmarketing-config.properties file.
The App configuration (also called an App descriptor) is a simple file in YAML format that describes the structure of the application from the perspective of the user (such as a dotCMS administrator).
Each App configuration file must contain the following fields in the file header:
|The user-facing name of the Application.|
|A description of the App, which is displayed in the Apps Tool.|
|The URL of an icon to display in the Apps Tool.|
|If set to |
|A section containing the parameters defined by the application.||Please see the examples below.|
The following shows a sample file header. For a complete App configuration file, please see the example below.
--- name: "Google Translation" description: "Google's translation services can be integrated through this set of configurations." iconUrl: "/google.png" --- allowExtraParameters: false
params section of the App configuration, you must define all parameters which a user will be able to configure within the Apps Tool in dotCMS.
Each parameter has a unique key (specified as a section name within the
params section of the configuration file. The parameter key is case-sensitive.
Each parameter requires the following properties:
|The default value for the property.|
Note: Null values are not allowed; to specify no default value, use an empty string.
|If set to |
|The data type of the property.|
|The name of the field displayed in the Apps Tool.|
|A hint string displayed to the user in the Apps Tool for this property.||`“hint”|
|If set to |
(otherwise they may leave it blank).
param-key: value: "default-value" hidden: false type: "STRING" label: "label" hint: "hint" required: true
SELECT Type Properties
If a parameter is set to the SELECT type, it defines a drop-down list giving a user a pre-defined set of values to choose from. When the SELECT type is used, the
value property supplies all the values to include in the drop-down list, instead of the default value.
secret: hidden: false type: "SELECT" label: "secret" hint: "secret" required: true value: - label: "--" value: "" - label: "one" value: "1" - label: "two" selected: true value: "2" - label: "three" value: "3"
Full Example Configuration File
The following is a complete example of an App configuration file, including the header, and parameters of multiple types.
name: "Slack" description: "This allows you to integrate with Slack (Select field) " iconUrl: "https://upload-icon.s3.us-east-2.amazonaws.com/uploads/icons/png/4200790421556105333-512.png" allowExtraParameters: false params: secret: hidden: false type: "SELECT" label: "secret" hint: "secret" required: true value: - label: "--" value: "" - label: "one" value: "1" - label: "two" selected: true value: "2" - label: "three" value: "3" xmlParam: hidden: false type: "STRING" label: "xml" hint: "xml" required: false value: "" jsonParam: hidden: false type: "STRING" label: "json" hint: "json" required: false value: "" boolPara: hidden: false type: "BOOL" label: "bool" hint: "bool" required: false value: true
Unique App Identifier
An identifier is automatically created for each App configuration, to uniquely identify the application within dotCMS. The unique key is generated from the file name of the configuration file. This both ensures that the identifier is unique, and ensures that the identifier remains the same, even if the contents of the configuration file are changed.
The unique identifier is created from the file name without the file extension. For example, if the configuration file for the Google Translate Apps integration is named
google-translate-app-descriptor.ymlm then the unique app identifier will be
The secrets in the Secrets repository are tied to this unique identifier, and can not be retrieved if the identifier changes.
Therefore, if you change the name of the configuration file after you have stored any secrets, you will not be able to retrieve those secrets.
It is important, then, that you do not change the names of the Apps configuration files after you have configured the Apps within dotCMS
The Secrets repository securely stores App configuration on an encrypted file on your dotCMS server. The secrets are stored separately from the dotCMS database, and are both encrypted and tied to the specific Site the configuration is for.
Secrets Repository Location and Format
The built-in Secrets repository stores secrets using the PKCS#12 format.
The Secrets file is stored in the
<<<location>>> folder within the dotCMS distribution (
- Secrets within the storage are uniquely identified using all of the following:
- Use of the Site name in the secrets repository ensures that each Secret within the storage is unique.
- However this also means that Secrets only work on the Site on which they were created;
- You can not share Secrets among Sites unless the Sites have the same Site Id - such as across hosts in a cluster, or with a Push Publishing sender and receiver.
- Secrets can be shared across a cluster.
- There are no size or length restrictions on values stored in the secrets repository.
Custom Secreats Storage
You can override the dotCMS secrets implementation with your own Secrets implementation using plugins. To override the secrets storage implementation:
- Create your own Java class which implements the
- Add your Java class to your dotCMS installation.
- Although you can provide this file directly on the server, it is recommended that you add this class to dotCMS via a plugin.
- Add the
SECRETS_STORE_IMPLproperty in the dotmarketing-config.properties file, with the value set to the path to your class.