Apps Integrations

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

The dotCMS starter site includes several example Apps integrations, including:

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.

App Configuration

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.

Configuration Files

File Location

By default, all Apps configurations are stored in the /assets/server/apps/ folder within the dotCMS distribution (/dotserver/tomcat-X.x.xx/webapps/ROOT/assets/server/apps/).

• 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_KEY property to the dotmarketing-config.properties file.
  • To implement this change without using a config file, instead assign the desired value to the environment variable DOT_APPS_DIR_PATH_KEY.

File Format

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

File Header

Each App configuration file must contain the following fields in the file header:

Example

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

App-Specific Parameters

In the 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:

Example Parameter

    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.

Example:

    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 google-translate-app-descriptor.

Important!

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

Secrets Storage

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 /assets/server/secrets/ folder within the dotCMS distribution (/dotserver/tomcat-X.x.xx/webapps/ROOT/assets/server/secrets/).

Notes:

• Secrets within the storage are uniquely identified using all of the following:
  • The hostId (the unique Id of the Site).
  • The unique App Id.
  • The parameter key.
• 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 Secrets Storage

You can override the dotCMS secrets implementation with your own Secrets implementation using plugins. To override the secrets storage implementation:

1. Create your own Java class which implements the SecretsStore interface.
2. 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.
3. Add the SECRETS_STORE_IMPL property in the dotmarketing-config.properties file, with the value set to the path to your class.
   • Alternately, you can perform this step without interacting with the config file by using the environment variable DOT_SECRETS_STORE_IMPL.

Importing Secrets

dotCMS has a startup task to import secrets and incorporate them as if they were part of a starter. This task is executed automatically on every server start. It will look for an export file (typically generated via Rest API) located under assets/server/. The file name must match the following pattern: dotSecrets-import.

This file will be removed after the import task has completed.

The import task will run only if there are no secrets already stored in the local repository and also if a default password to decrypt the import file is set in the dotmarketing-config.properties under the entry APPS_IMPORT_EXPORT_DEFAULT_PASSWORD.

As with virtually all config-file properties, the above property can be assigned or overridden by way of an environment variable — in this case, DOT_APPS_IMPORT_EXPORT_DEFAULT_PASSWORD. Note that environment variables that contain the string “PASSWORD” are automatically obscured in the System Info pane.

Troubleshooting Imported Secrets

If the process encounters a validation error during the import, an exception will be thrown preventing dotCMS from starting normally. A validation problem can be:

• Attempting to import a secret for a non-existing host — for example, by exporting a secret on a node that has a site that no longer exists on the receiver node.
• Importing a secret that was generated for a YML file that no longer exists on the receiver.

In case of a validation error, one of the following actions can be taken:

• Replacing the file dotSecrets-import[.*] with a new one generated without the offending secrets.
• Removing the the property APPS_IMPORT_EXPORT_DEFAULT_PASSWORD from dotmarketing-config.properties.
  • Or removing the DOT_APPS_IMPORT_EXPORT_DEFAULT_PASSWORD environment variable, if the password was configured that way.
• Removing the problematic dotSecrets-import[.*] and starting dotCMS normally without attempting an import.

The Dot Velocity Secret App

Added in 23.07, the Dot Velocity Secret App is a built-in App that allows storing and passing secret strings — such as keys, tokens, passwords, etc. — to the Velocity context without having to expose them within the VTL file. For more information, see the documentation for the Secrets Viewtool.