0004226: trigger template variables and example

symmetric-assemble/src/asciidoc/configuration/table-triggers.ad

@@ -55,19 +55,19 @@ ifdef::pro[]
 .Advanced Options
 endif::pro[]
 
-Sync On Insert:: Determines if changes will be captured for inserts.
-Sync On Update:: Determines if changes will be captured for updates.
-Sync On Delete:: Determines if changes will be captured for deletes.
+Sync On Insert:: Flag for installing an insert trigger.
+Sync On Update:: Flag for installing an update trigger.
+Sync On Delete:: Flag for installing a delete trigger.
 Reload Channel Id:: The channel_id of the channel that will be used for initial loads.
-Sync On Insert Condition:: Specify a condition for the insert trigger firing using an expression specific to the database.   On most platforms, it is added to an "IF" statement in the trigger text.  On SQL-Server it is added to the "WHERE" clause of a query for inserted/deleted logical tables. See Sync Condition Example.
-Sync On Update Condition:: Specify a condition for the update trigger firing using an expression specific to the database.   On most platforms, it is added to an "IF" statement in the trigger text.  On SQL-Server it is added to the "WHERE" clause of a query for inserted/deleted logical tables. See Sync Condition Example.
-Sync On Delete Condition:: Specify a condition for the delete trigger firing using an expression specific to the database.   On most platforms, it is added to an "IF" statement in the trigger text.  On SQL-Server it is added to the "WHERE" clause of a query for inserted/deleted logical tables. See Sync Condition Example.
-Sync Condition Example:: Sync Conditions can access both old values and new values of a field/column using "old_" and "new_" respectively. For example, if your column is id and your condition checks the value coming in to be 'test', your condition will be:
+Sync Conditions:: A procedure language expression included in the trigger text to determine whether a change is captured or not.  Most platforms include the condition inside an "IF" statement, while SQL-Server includes the condition in a "WHERE" clause.  Old and new values of a column can be referenced using "$(oldTriggerValue)" and "$(newTriggerValue)" aliases respectively.  See <<Trigger Variables>>.  For example, if a character column is named "STATUS" and the row should be captured when the value is "2", then the condition would be:
 +
 ----
- new_id = 'test'   
+ $(newTriggerValue).status = '2'
 ----
 
+Sync On Insert Condition:: Conditional expression for the insert trigger to determine if a change is captured or not.  See Sync Conditions.
+Sync On Update Condition:: Conditional expression for the update trigger to determine if a change is captured or not.  See Sync Conditions.
+Sync On Delete Condition:: Conditional expression for the delete trigger to determine if a change is captured or not.  See Sync Conditions.
 Custom Insert Trigger Text:: Specify insert trigger text (SQL) to execute after the SymmetricDS trigger fires.  This field is not applicable for H2, HSQLDB 1.x or Apache Derby.
 Custom Update Trigger Text:: Specify update trigger text (SQL) to execute after the SymmetricDS trigger fires.  This field is not applicable for H2, HSQLDB 1.x or Apache Derby.
 Custom Delete Trigger Text:: Specify delete trigger text (SQL) to execute after the SymmetricDS trigger fires.  This field is not applicable for H2, HSQLDB 1.x or Apache Derby.
@@ -129,4 +129,5 @@ This property is currently only supported on MySQL, DB2, SQL Server, and Oracle.
 
 include::table-triggers/wildcards.ad[]
 include::table-triggers/external-select.ad[]
+include::table-triggers/trigger-variables.ad[]
 include::table-triggers/load-only.ad[]

symmetric-assemble/src/asciidoc/configuration/table-triggers/external-select.ad

@@ -6,7 +6,8 @@ This data is typically needed for the purposes of determining where to 'route' t
 definition contains an optional "external select" field which can be used to specify the data to be captured. Once captured, this 
 data is available during routing in DATA 's external_data field. 
 
-For these cases, place a SQL select statement which returns the data item you need for routing in external_select. 
+For these cases, place a SQL select statement which returns the data item you need for routing in external_select.
+See <<Trigger Variables>> for a list of variables available for use.
 
 IMPORTANT: The external select SQL must return a single row, single column 
 
@@ -32,20 +33,6 @@ values ('orderlineitem', 'orderlineitem','orderlineitem',
 ====
 endif::pro[]
 
-.The following variables can be used with the external select
-[cols=".^2,8"]
-|===
-
-|$(curTriggerValue)|Variable to be replaced with the NEW or OLD column alias provided by the trigger context, which is platform specific. 
-For insert and update triggers, the NEW alias is used; for delete triggers, the OLD alias is used. For example, "$(curTriggerValue).COLUMN" 
-becomes ":new.COLUMN" for an insert trigger on Oracle.
-
-|$(curColumnPrefix)|Variable to be replaced with the NEW_ or OLD_ column prefix for platforms that don't support column aliases. This is 
-currently only used by the H2 database. All other platforms will replace the variable with an empty string. For example "$(curColumnPrefix)COLUMN" 
-becomes "NEW_COLUMN" on H2 and "COLUMN" on Oracle.
-
-|===
-
 WARNING: External select SQL statements should be used carefully as they will cause the trigger to run the additional SQL each time the trigger fires.
 
 TIP: Using an external select on the trigger is similar to using the 'subselect' router.  The advantage of this approach over the 'subselect' approach 

symmetric-assemble/src/asciidoc/configuration/table-triggers/trigger-variables.ad

@@ -0,0 +1,21 @@
+
+==== Trigger Variables
+
+The Sync Condition, External Select, and Custom Trigger Text configurations allow the user to provide
+procedure language text that is included inside the trigger.
+Variables can be used for configuration that works across different database platforms.
+When triggers are created, the variables are replaced with the syntax needed for that specific database.
+
+.Trigger Template Variables
+[cols=".^2,8"]
+|===
+
+|$(newTriggerValue)|New row alias for inserts and updates.  For example, "$(newTriggerValue).MYCOLUMN" becomes ":new.MYCOLUMN" for an insert/update trigger on Oracle.
+
+|$(oldTriggerValue)|Old row alias for updates and deletes.  For example, "$(oldTriggerValue).MYCOLUMN" becomes ":old.MYCOLUMN" for an update/delete trigger on Oracle.
+
+|$(curTriggerValue)|Current row alias for insert, updates, and deletes.  This variable acts like $(newTriggerValue) for inserts and updates, and it acts like $(oldTriggerValue) for deletes.
+
+|$(curColumnPrefix)|Column prefix only used by H2 database.  It is replaced with the NEW_ or OLD_ column prefix needed by H2.  All other platforms will replace the variable with an empty string
+
+|===