Skip to content

Update the notifications config article #7557 #2026

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: 5
Choose a base branch
from
Draft

Update the notifications config article #7557 #2026

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f683bed
Update the notifications config article #7557
alhambrav Jun 2, 2025
6f24f11
Update updated version
alhambrav Jun 9, 2025
e49fbfd
Add new property for workflow notifications #7557
alhambrav Jun 10, 2025
930f2a9
Merge with master
Sep 25, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
224 changes: 163 additions & 61 deletions source/reference/modules/studio.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
:is-up-to-date: True
:last-updated: 4.4.3
:last-updated: 5.0.0

.. highlight:: xml

Expand Down Expand Up @@ -97,10 +97,12 @@ In this section, we will highlight some of the more commonly used properties in
- Configure capabilities for CloudFormation stack
* - :ref:`Validations Regex <studio-validations-regex>`
- Configure the regex used for validating various inputs
* - :ref:`Notification Service Configuration <notification-service-configuration>`
- Configure the notification service for workflow
* - :ref:`Disk Monitoring <studio-disk-monitoring>`
- Configure the disk monitoring notifications and thresholds
* - :ref:`Workflow Notification Configuration <notifications-configuration>`
- Configure the workflow notifications
- Configure the HTML notifications sent at each point in the workflow
* - :ref:`Commit Message <studio-commit-message>`
- Configure the commit messages used by Crafter Studio
* - :ref:`Audit Log <studio-audit-log>`
Expand Down Expand Up @@ -2878,7 +2880,7 @@ All configuration for the notification system is done by a site admin (on a per
Where
'''''
.. code-block:: xml
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notifications.xml*
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notification-config.xml*

Comment on lines +2883 to 2884
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Fix path: notification config location inconsistent with defaults

Captions point to config/studio/notification-config.xml but the default property below uses workflow/notification-config.xml. Align to workflow/… to prevent confusion.

Apply this diff:

-    :caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notification-config.xml*
+    :caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/workflow/notification-config.xml*

Also update the sentence above that references “Notification Configuration” if it implies the old path. Based on learnings

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notification-config.xml*
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/workflow/notification-config.xml*
🤖 Prompt for AI Agents 
In source/reference/modules/studio.rst around lines 2883-2884, the caption path
currently points to config/studio/notification-config.xml while the default
property and intended location use workflow/notification-config.xml; update the
caption line to use
*CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/workflow/notification-config.xml*
and also edit the nearby sentence above that references “Notification
Configuration” so its example/path text reflects the
workflow/notification-config.xml location to keep both descriptions consistent.

<notificationConfig>
...
Expand Down Expand Up @@ -2956,7 +2958,7 @@ Configure Who Gets Notifications
Configure who gets notifications by entering the email addresses of the people you want to send notifications to, in between the tags ``<deploymentFailureNotification>`` and/or ``<approverEmails>``

.. code-block:: xml
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notifications.xml*
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notification-config.xml*
:linenos:

<notificationConfig>
Expand All @@ -2979,7 +2981,7 @@ Configure Studio Workflow Dialog Messages
Below is a sample of Studio workflow dialog messages defined in our notifications configuration file.

.. code-block:: xml
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notifications.xml*
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notification-config.xml*
:linenos:

<notificationConfig>
Expand Down Expand Up @@ -3018,10 +3020,16 @@ Below is a sample of Studio workflow dialog messages defined in our notification
~~~~~~~~~~~~~~~~~~~
Configure Templates
~~~~~~~~~~~~~~~~~~~
Below is an example of a configured email messages for each point in the workflow, found in between the tag <emailTemplates> in the notifications configuration file.
Below is an example of a configured email messages for each point in the workflow, found in between the tag
``<emailTemplates>`` in the notifications configuration file.

.. raw:: html

<details>
<summary><a>Configured email messages in the notifications configuration file</a></summary>

.. code-block:: xml
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notifications.xml*
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notification-config.xml*
:linenos:

Comment on lines +3032 to 3034
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Fix path in caption (same inconsistency as above)

Update to workflow/notification-config.xml.

-    :caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notification-config.xml*
+    :caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/workflow/notification-config.xml*
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notification-config.xml*
:linenos:
:caption: *CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/workflow/notification-config.xml*
:linenos:
🤖 Prompt for AI Agents 
In source/reference/modules/studio.rst around lines 3032 to 3034 the :caption:
path is incorrect (it currently points to
*CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/notification-config.xml*);
update the caption to the correct path
*CRAFTER_HOME/data/repos/sites/SITENAME/sandbox/config/studio/workflow/notification-config.xml*
so it matches the intended location.

<notificationConfig>
Expand All @@ -3040,23 +3048,23 @@ Below is an example of a configured email messages for each point in the workflo
The following content was unable to deploy:
<ul>
<#list files as file>
<li>${file.internalName!file.name}</li>
<li>${file.action}: ${file.path} from package ${file.packageId}.
<#if file.liveError != 0>Live error: ${file.liveError?c}</#if><#if file.stagingError != 0>Stage error: ${file.stagingError?c}</#if></li>
</#list>
</ul>
Error:<br/>
${deploymentError.toString()}
<#if deploymentError?has_content>
Error:<br/>
<pre>${deploymentError}</pre>
</#if>
Comment on lines +3055 to +3058
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Prefer explicit string conversion for deploymentError

Earlier docs say deploymentError must be addressed via toString(); template uses ${deploymentError}. Make it explicit to avoid renderer surprises.

-                            <pre>${deploymentError}</pre>
+                            <pre>${deploymentError?string}</pre>

Alternatively: ${deploymentError.toString()}.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<#if deploymentError?has_content>
Error:<br/>
<pre>${deploymentError}</pre>
</#if>
<#if deploymentError?has_content>
Error:<br/>
<pre>${deploymentError?string}</pre>
</#if>
🤖 Prompt for AI Agents 
In source/reference/modules/studio.rst around lines 3055 to 3058, the template
directly interpolates ${deploymentError} but earlier docs require using
toString(); update the template to perform an explicit string conversion (e.g.,
call deploymentError.toString() or otherwise coerce to a string) before
rendering so the renderer receives a definite string and avoids surprises;
ensure you guard for null/undefined (call toString() only when deploymentError
is present) consistent with the surrounding has_content check.

<br/><br/>
<a href="${liveUrl}" >
<img style="max-width: 350px; max-height: 350px;" src="${liveUrl}/static-assets/images/workflow-email-footer.png" alt="" />
</a>
</p>
</body>
</html>
]]></body>
</emailTemplate>

<emailTemplate key="contentApproval">
<subject><![CDATA[<#if scheduleDate??>Content Scheduled <#else>Content Approved</#if>]]></subject>
<subject><![CDATA[<#if publishPackage.schedule??>Content Scheduled <#else>Content Approved</#if>]]></subject>
<!-- Timezone can/is being overwritten in the following template -->
<body><![CDATA[
<#setting time_zone='EST'>
Expand All @@ -3066,29 +3074,37 @@ Below is an example of a configured email messages for each point in the workflo
</head>
<body style=" font-size: 12pt;">
<p>
<#if scheduleDate??>
The following content has been scheduled for publishing on ${scheduleDate?string["MMM dd, yyyy 'at' hh:mm a"]} Eastern Time.
<#if publishPackage.packageType == 'INITIAL_PUBLISH'>
${reviewer.first_name!submitter.username} ${reviewer.last_name} has approved your initial publish request.
<#elseif publishPackage.packageType == 'PUBLISH_ALL'>
${reviewer.first_name!submitter.username} ${reviewer.last_name} has approved your publish all request.
<#else>
The following content has been reviewed and approved by ${approver.firstName!approver.username} ${approver.lastName!""}:
</#if>
<ul>
<#list files as file>
<#if file.page>
<a href="${liveUrl}/${file.browserUri!""}">
</#if>
<li>${file.internalName!file.name}</li>
<li>
<#if file.page>
<a href="${liveUrl}/${file.browserUri!""}">
</#if>
${file.internalName!file.name}
<#if file.page>
</a>
</#if>
</li>
</#list>
</ul><br/>
Site: ${siteName}
<br />
<#if scheduleDate??>
<a href="${liveUrl}">Click Here to View Your Published Content</a>
<br/>
Scheduled date: ${publishPackage.schedule?datetime.iso?string["MMM dd, yyyy 'at' hh:mm a"]} Eastern Time.
<br />
</#if>
<a href="${authoringUrl}/site-dashboard" >
<img style="max-width: 350px; max-height: 350px;" src="${liveUrl}/static-assets/images/workflow-email-footer.png" alt="" />
</a>
Target: ${publishPackage.target}
<br/>
Reviewer comment:<br/>
${publishPackage.reviewerComment!""}
<br/>
</p>
</body>
</html>
Expand All @@ -3105,28 +3121,44 @@ Below is an example of a configured email messages for each point in the workflo
</head>
<body style=" font-size: 12pt">
<p>
${submitter.firstName!submitter.username} ${submitter.lastName} has submitted items for your review:
<ul>
<#list files as file>
<#if file.page>
<a href="${authoringUrl}/preview/#/?page=${file.browserUri!""}&site=${siteName}">
</#if>
<li>${file.internalName!file.name}</li>
<#if file.page>
</a>
</#if>
</#list>
</ul>
<#if submissionComments?has_content>
<#if publishPackage.packageType == 'PUBLISH_ALL'>
${submitter.first_name!submitter.username} ${submitter.last_name} has submitted a 'publish all' request for your review.
<#elseif publishPackage.packageType == 'INITIAL_PUBLISH'>
${submitter.first_name!submitter.username} ${submitter.last_name} has submitted an 'initial publish' request for your review.
<#else>
${submitter.first_name!submitter.username} ${submitter.last_name} has submitted items for your review:
</#if>
<#if files?? &amp;&amp; files?size gt 0>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Fix Freemarker operator inside CDATA: use &&, not &&

Inside you must use raw “&&”. The escaped form won’t be parsed by FTL.

-                           <#if files?? &amp;&amp; files?size gt 0>
+                           <#if files?? && files?size gt 0>
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
<#if files?? &amp;&amp; files?size gt 0>
<#if files?? && files?size gt 0>
🤖 Prompt for AI Agents 
In source/reference/modules/studio.rst around line 3131 the Freemarker
boolean-and operator is incorrectly escaped as "&amp;&amp;" inside a CDATA
block; replace the escaped sequence with the raw operator "&&" so Freemarker
will parse the condition correctly (i.e., change "&amp;&amp;" to "&&" within the
<![CDATA[ ]]> context).

<ul>
<#list files as file>
<li>
<#if file.page>
<a href="${authoringUrl}/studio/preview/#/?page=${file.browserUri!""}&site=${siteName}">
</#if>
${file.internalName!file.name}
<#if file.page>
</a>
</#if>
</li>
</#list>
</ul>
</#if>
<br />
Site: ${siteName}
<br />
<#if publishPackage.submitterComment?has_content>
Comments:<br/>
${submissionComments!""}
${publishPackage.submitterComment!""}
<br/>
</#if>
<#if publishPackage.schedule??>
Scheduled date: ${publishPackage.schedule?datetime.iso?string["MMM dd, yyyy 'at' hh:mm a"]} Eastern Time.
<br/>
</#if><br/>
<a href="${previewUrl}/site-dashboard">Click Here to View Content Waiting for Approval</a>
</#if>
Target: ${publishPackage.target}
<br/>
<a href="${authoringUrl}/studio/site-dashboard">Click Here to View Content Waiting for Approval</a>
<br/><br/>
<a href="${liveUrl}" >
<img style="max-width: 350px; max-height: 350px;" src="${liveUrl}/static-assets/images/workflow-email-footer.png" alt="" />
</a>
</p>
</body>
</html>
Expand All @@ -3143,24 +3175,40 @@ Below is an example of a configured email messages for each point in the workflo
</head>
<body style=" font-size: 12pt;">
<p>
The following content has been reviewed and requires some revision before it can be approved:
<ul>
<#list files as file>
<#if file.page>
<a href="${authoringUrl}/preview/#/?page=${file.browserUri!""}&site=${siteName}">
</#if>
<li>${file.internalName!file.name}</li>
<#if file.page>
</a>
</#if>
</#list>
</ul>
<#if publishPackage.packageType == 'INITIAL_PUBLISH'>
${reviewer.first_name!submitter.username} ${reviewer.last_name} has reviewed your initial publish request and it requires some revision before it can be approved:
<#elseif publishPackage.packageType == 'PUBLISH_ALL'>
${reviewer.first_name!submitter.username} ${reviewer.last_name} has reviewed your publish all request and it requires some revision before it can be approved:
<#else>
${reviewer.first_name!submitter.username} ${reviewer.last_name} has reviewed the following content that requires some revision before it can be approved:
</#if>
<#if files?? &amp;&amp; files?size gt 0>
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Fix Freemarker operator inside CDATA here too

Same issue as above; switch to “&&”.

-                           <#if publishPackage.schedule??>
+                           <#if publishPackage.schedule??>

Note: And change:

-                           <#if files?? &amp;&amp; files?size gt 0>
+                           <#if files?? && files?size gt 0>

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In source/reference/modules/studio.rst around line 3185, the Freemarker logical
AND operator is HTML-escaped as "&amp;&amp;" inside the CDATA; replace the
escaped sequence with the literal "&&" so the conditional reads "<#if files?? &&
files?size gt 0>" (ensure it remains inside CDATA unescaped).

<ul>
<#list files as file>
<li>
<#if file.page>
<a href="${authoringUrl}/studio/preview/#/?page=${file.browserUri!""}&site=${siteName}">
</#if>
${file.internalName!file.name}
<#if file.page>
</a>
</#if>
</li>
</#list>
</ul>
</#if>
<br />
Site: ${siteName}
<br />
<#if publishPackage.schedule??>
Scheduled date: ${publishPackage.schedule?datetime.iso?string["MMM dd, yyyy 'at' hh:mm a"]} Eastern Time.
<br/>
</#if>
Target: ${publishPackage.target}
<br/>
Reason:<br/>
${rejectionReason!""}
<br/><br/>
<a href="${authoringUrl}/site-dashboard" >
<img style="max-width: 350px; max-height: 350px;" src="${liveUrl}/static-assets/images/workflow-email-footer.png" alt="" />
</a>
${publishPackage.reviewerComment!""}
<br/>
</p>
</body>
</html>
Expand All @@ -3170,6 +3218,10 @@ Below is an example of a configured email messages for each point in the workflo
</lang>
</notificationConfig>

.. raw:: html

</details>

|hr|

.. _studio-validations-regex:
Expand Down Expand Up @@ -3212,6 +3264,56 @@ The following section of Studio's configuration overrides allows you to configur

|hr|

.. _notification-service-configuration:

""""""""""""""""""""""""""""""""""
Notification Service Configuration
""""""""""""""""""""""""""""""""""
CrafterCMS can send out notification emails on each point of the workflow.
The following allows you to configure the notification service:

.. list-table:: Notification Service Properties
:header-rows: 1

* - Property
- Description
* - studio.workflow.notification.maxItemCount

.. version_tag::
:label: Since
:version: 5.0.0

- The maximum number of items included in the notification messages

* - studio.workflow.notification.enabled
- Enables/disables notification messages on workflow events
* - studio.notification.configurationFile
- The location of the workflow notifications configuration file
* - studio.notification.timezone
- The timezone used in the notification emails

|

The notification service properties listed above can be customized by overriding them using one of the override
files. Here are the default values configured:

.. code-block:: yaml

##############################################################
## Notification Service ##
##############################################################
# Maximum number of items to include in the workflow notification messages
studio.workflow.notification.maxItemCount: 10
# Enable/disable notification messages on workflow events
studio.workflow.notification.enabled: true
# Path where the notification configuration is located
studio.notification.configurationFile: workflow/notification-config.xml
# Timezone for the email template engine (which determines how FreeMarker interprets `now` etc.)
studio.notification.timezone: UTC

To learn more on configuring the workflow notification emails being sent, see
:ref:`Workflow Notification Configuration <notifications-configuration>`.

.. _studio-disk-monitoring:

"""""""""""""""
Expand Down