Settings Enforcer Utility

What the Settings Enforcer Utility module adds to your project

Settings Enforcer allows projects to externalize configuration values in Sites & Settings and Singletons into a properties file or context.xml via the Settings API.

Settings that are “forced” in this way are no longer allowed to be edited in the CMS. If the value is set to null (an empty string), the field on the Sites & Settings page will also be hidden. If the value is set to something other than null, the field will be read only.

Sites & Settings values that should be the same across all environments (production, lower environments, local dev) can be set in the project’s settings.properties using this syntax:

force/global/enableTrailingSlashNormalization=true

# RTE settings we don't want editors to change
force/global/legacyHtml=
# 4.2
force/global/enableCodeMirrorRichTextEditor=
# 4.1
force/global/enableProseMirrorRichTextEditor=true
# Collections
force/global/listField/0=first
force/global/listField/1=second

Settings that should be different across environments can be set in each environment’s context.xml file using this syntax:

<Environment name="force/global/express.cmsToolModification.defaultTaskHost" value="task.brightspot.service.${brightspot.environment}.my-project.internal" type="java.lang.String"/>

Installation 

api('com.psddev.component-lib:util-settings-enforcer')

Programmatically Detecting Whether a Setting is Enforced

Sometimes it is useful to know whether a setting is enforced. For example, when synchronizing Site settings in Stage Preview, any setting that is enforced should not be part of the calculation to determine whether the field values are in sync. If different servers have different enforced settings, copying enforced settings from one server to the other will result in an infinite loop! In order to avoid this, the SettingsEnforcer Modification<SiteSettings> has a getFields() method that returns all of the internal field names of settings that have been enforced on the Site or CmsTool.

CmsTool tool = Query.from(CmsTool.class).first();

if (tool.as(SiteSettingsEnforcer.class).getFields().contains("fieldInternalName")) {
  // fieldInternalName is handled via Settings Enforcer; do not modify!
}

Scope and Syntax

Each setting name has multiple parts separated by slashes:

  1. The force prefix
  2. One of either global, all, sites, site, or the fully qualified class name of any Singleton.
  3. If (2) is site, the name of a site or group of sites. This can be any string you want, and will populate the “Enforced Settings” dropdown on Site. Otherwise skip to (4).
  4. The internalName of the setting you wish to force.
  5. Optional for collections only - an integer value indicating the list item order. For example /0, /1, /2.

Examples:

  • force/global/defaultPreviewUrl will set the defaultPreviewUrl on the CmsTool singleton.

  • force/all/broadcastMessage will set the broadcastMessage on the CmsTool singleton as well as all Sites.

  • force/sites/allowSiteCopy will set allowSiteCopy on all Sites, but not the CmsTool singleton.

  • force/site/groupOne/cmsCssClass will set the cmsCssClass on all Sites that have selected “Group One” on the “Enforced Settings” dropdown in the “Advanced” cluster. Note that settings enforced at a per-site level like this will not be hidden or read only unless a default is supplied in global, all, or sites.

  • force/com.psddev.migration.MigrationTool/taskHost will set the taskHost of the MigrationTool Singleton.

  • force/global/debuggingToEmails/0 and force/global/debuggingToEmails/1 will set debuggingToEmails list to a list of 2 values on the CmsTool singleton.

Adding the Settings Enforcer Utility module to your project

Follow these steps:

  1. Add the package dependency to the appropriate pom.xml files. Using a released version is advised. 
     <dependency>
     <groupId>com.psddev.component-lib</groupId>
     <artifactId>util-settings-enforcer</artifactId>
 </dependency>

or build.gradle:

api 'com.psddev.component-lib:util-settings-enforcer'
  1. Create or modify a settings.properties file in your project.

A common location for this file is ./site/src/main/resources/settings.properties

Known Limitations

Only boolean, string, numbers, and collections of same are supported.

Examples

Here are several common settings that should be enforced.

The following settings can be copied into your project as ./site/src/main/resources/settings.properties:

# Deprecated / unnecessary / dangerous settings that users shouldn't touch
force/global/allowInsecureAuthenticationCookie=
force/global/alwaysGeneratePermalinks=
force/global/disableAutomaticallySavingDrafts=
force/global/disableEditFieldUpdateCache=
force/global/disableFrontEndUploader=
force/global/disableInvisibleContentPreview=
force/global/disableRtc=
force/global/disableSmartUploader=
force/global/disableToolChecks=
force/global/disableViewers=
force/global/disableWorkInProgress=
force/global/disabledPlugins/0=developerBackgroundTasks
force/global/disabledPlugins/1=developerBulkOperations
force/global/disabledPlugins/2=developerSqlDebug
force/global/displayTypesNotAssociatedWithJavaClasses=
force/global/enableAjaxSaves=
force/global/enableAnnotations=
force/global/enablePaddedCrop=
force/global/legacyHtml=
force/global/singleGeneratedPermalink=
force/global/useLegacySettingsSiteSwitching=
force/global/useNonMinifiedCss=
force/global/useNonMinifiedJavaScript=
force/global/useOldDirectoryPathsPredicate=
force/global/useOldHistoryIndex=
force/global/useOldTaxonomyChildrenDetection=
force/com.psddev.migration.MigrationTool/url=

# Whole-project defaults - review these and decide per project
force/global/disableVideoEditorUI=
force/global/displaySiteInSearchResult=true
force/global/enableCrossDomainInlineEditing=true
force/global/enableTrailingSlashNormalization=true
force/global/express.cmsToolModification.autoIncrementPermalinks=
force/global/removeTrailingSlashes=
force/global/searchCarouselDisplay=DISABLED
force/global/useLegacySearchWithContent=

# Disallow Global as a site
force/global/allowGlobalEditing=
force/global/defaultSiteUrl=
force/global/siteMapDefaultUrl=
force/global/sitemap.generateSiteMapTypeClassNames=
force/global/url=

# RTE
force/global/enableCodeMirrorRichTextEditor=
force/global/enableProseMirrorRichTextEditor=true

# Disallow Content Locking
force/global/allowDisableUnlocking=
force/global/contentLocking=
force/global/hardLockTimeout=
force/global/inactivityLockTimeout=
force/global/networkLockTimeout=

These settings should be configured per environment in context.xml.

  • Substitute instances of MY-PROJECT with appropriate values
  • Substitute value for TASK-HOST from the following options:
    • Normal task host - all environments (prod, qa, uat) (legacy infrastructure): task.brightspot.service.${brightspot.environment}.MY-PROJECT.internal
    • Dedicated job host - production only (legacy infrastructure): master.job.service.${brightspot.environment}.MY-PROJECT.internal
    • Dedicated job host - production only (cloud infrastructure): brightspot-task.MY-PROJECT.svc.cluster.local
    • Brightspot Docker: ${brightspot.hostname}
  • Substitute https://cms.example.com/ with your CMS URL.
  • Find the appropriate values for all AWS integration settings - many of them will be different per environment!
  • Any AWS setting that is enforced in production should also be enforced in lower and local environments. This will avoid accidentally connecting to the production AWS service after doing a production copydown!
  • Note that you may or may not need all of these options based on your project requirements.
<!-- Task Hosts -->
<Environment name="force/global/express.cmsToolModification.defaultTaskHost" value="TASK-HOST" type="java.lang.String" />
<Environment name="force/global/analytics.pageViews.taskHost" value="TASK-HOST" type="java.lang.String" />
<Environment name="force/global/google.taskHost" value="TASK-HOST" type="java.lang.String" />
<Environment name="force/com.psddev.migration.MigrationTool/taskHost" value="TASK-HOST" type="java.lang.String" />

<!-- Per environment settings -->
<Environment name="force/global/environment" value="${brightspot.environment}" type="java.lang.String" />
<Environment name="force/global/defaultPreviewUrl" value="https://cms.example.com/" type="java.lang.String" />
<Environment name="force/global/defaultToolUrl" value="https://cms.example.com/" type="java.lang.String" />

<!-- Mail Publishing -->
<Environment name="force/global/s3Region" value="" type="java.lang.String" />
<Environment name="force/global/queueName" value="" type="java.lang.String" />

<!-- AWS integration settings -->
<Environment name="force/global/aws.ses.enableNotificationService" value="true" type="java.lang.String" />
<Environment name="force/global/aws.ses.bounceNotificationQueueName" value="" type="java.lang.String" />
<Environment name="force/global/aws.ses.complaintNotificationQueueName" value="" type="java.lang.String" />
<Environment name="force/global/aws.sqs.region" value="" type="java.lang.String" />
<Environment name="force/global/aws.comprehend.region" value="" type="java.lang.String" />
<Environment name="force/global/bsp.elemental.region" value="" type="java.lang.String" />
<Environment name="force/global/bsp.elemental.mediaConvertRole" value="" type="java.lang.String" />
<Environment name="force/global/bsp.elemental.mediaConvertQueueName" value="" type="java.lang.String" />
<Environment name="force/global/bsp.elemental.mediaLiveRole" value="" type="java.lang.String" />
<Environment name="force/global/aws.rekognition.region" value="" type="java.lang.String" />
<Environment name="force/global/rekognitionVideo.queueName" value="" type="java.lang.String" />
<Environment name="force/global/rekognitionVideo.topicArn" value="" type="java.lang.String" />
<Environment name="force/global/rekognitionVideo.roleArn" value="" type="java.lang.String" />
<Environment name="force/global/aws.textract.queueName" value="" type="java.lang.String" />
<Environment name="force/global/aws.textract.topicArn" value="" type="java.lang.String" />
<Environment name="force/global/aws.textract.roleArn" value="" type="java.lang.String" />
<Environment name="force/global/aws.transcribe.queueName" value="" type="java.lang.String" />
<Environment name="force/global/aws.transcribe.region" value="" type="java.lang.String" />