From 00eb55ff2bcd1119a64594a71d02a11c0f4ee5a7 Mon Sep 17 00:00:00 2001
From: pralav-25 <174412353+pralav-25@users.noreply.github.com>
Date: Fri, 23 Oct 2026 20:57:44 +0530
Subject: [PATCH 1/2] docs: explain inline template expression detection

---
 .../user-guide/process-engine/templating.md   | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/documentation/user-guide/process-engine/templating.md b/docs/documentation/user-guide/process-engine/templating.md
index f68b1a3d..43c9e3aa 100644
--- a/docs/documentation/user-guide/process-engine/templating.md
+++ b/docs/documentation/user-guide/process-engine/templating.md
@@ -145,6 +145,25 @@ payload of a `operaton:connector`.
 </bpmn2:serviceTask>
 ```
 
+For inline scripts in an input parameter, template engines other than JUEL are subject to
+dynamic script-source detection: if the script content starts with `${` or `#{` after
+leading and trailing whitespace is trimmed, Operaton treats it as an expression that resolves
+to a script source.
+If those characters are part of the template itself, prefix the content with a comment
+recognized by the template engine, or use an external resource instead. For example, an
+inline FreeMarker template can start with an escaped FreeMarker comment:
+
+```xml
+<operaton:inputParameter name="message">
+  <operaton:script scriptFormat="freemarker">
+    &lt;#-- Keep this as an inline FreeMarker template. --&gt;${name} likes:
+    &lt;#list icecreamtypes as ict&gt;
+      * ${ict}
+    &lt;/#list&gt;
+  </operaton:script>
+</operaton:inputParameter>
+```
+
 ## Use XSLT as Template Engine
 
 ### Use XSLT Template Engine with an embedded process engine

From 4c2a9b8d9e3793a25acf206ca9705f787b6489db Mon Sep 17 00:00:00 2001
From: pralav-25 <174412353+pralav-25@users.noreply.github.com>
Date: Sat, 7 Nov 2026 13:36:36 +0530
Subject: [PATCH 2/2] docs: clarify dynamic detection for all inline script
 sources

---
 .../user-guide/process-engine/templating.md   | 23 ++++++++++++-------
 1 file changed, 15 insertions(+), 8 deletions(-)

diff --git a/docs/documentation/user-guide/process-engine/templating.md b/docs/documentation/user-guide/process-engine/templating.md
index 43c9e3aa..1d1bbce3 100644
--- a/docs/documentation/user-guide/process-engine/templating.md
+++ b/docs/documentation/user-guide/process-engine/templating.md
@@ -145,18 +145,23 @@ payload of a `operaton:connector`.
 </bpmn2:serviceTask>
 ```
 
-For inline scripts in an input parameter, template engines other than JUEL are subject to
-dynamic script-source detection: if the script content starts with `${` or `#{` after
-leading and trailing whitespace is trimmed, Operaton treats it as an expression that resolves
-to a script source.
+:::caution
+
+For inline script sources (script tasks, listeners, conditions, and input/output parameters),
+script or template languages other than JUEL are subject to
+[dynamic script-source detection][script-source]. If the script content starts with `${` or
+`#{` after leading and trailing whitespace is trimmed for detection, Operaton treats it as
+an expression that resolves to a script source. The content is evaluated as an expression
+first, rather than passed directly to the script or template engine, which may cause errors
+or unexpected output.
+
 If those characters are part of the template itself, prefix the content with a comment
-recognized by the template engine, or use an external resource instead. For example, an
-inline FreeMarker template can start with an escaped FreeMarker comment:
+recognized by the script or template language, or use an external resource instead. For
+example, an inline FreeMarker template can start with an escaped FreeMarker comment:
 
 ```xml
 <operaton:inputParameter name="message">
-  <operaton:script scriptFormat="freemarker">
-    &lt;#-- Keep this as an inline FreeMarker template. --&gt;${name} likes:
+  <operaton:script scriptFormat="freemarker">&lt;#-- Keep this as an inline FreeMarker template. --&gt;${name} likes:
     &lt;#list icecreamtypes as ict&gt;
       * ${ict}
     &lt;/#list&gt;
@@ -164,6 +169,8 @@ inline FreeMarker template can start with an escaped FreeMarker comment:
 </operaton:inputParameter>
 ```
 
+:::
+
 ## Use XSLT as Template Engine
 
 ### Use XSLT Template Engine with an embedded process engine