[unomi] branch master updated: [UNOMI-508] - Updated the documentation to include Groovy Actions (#347)

[jk...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

jkevan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/unomi.git


The following commit(s) were added to refs/heads/master by this push:
     new 6106e95  [UNOMI-508] - Updated the documentation to include Groovy Actions (#347)
6106e95 is described below

commit 6106e95eb9bb1e16d47c6803b2e2184aef376059
Author: Francois G <f....@gmail.com>
AuthorDate: Fri Oct 1 09:47:31 2021 -0400

    [UNOMI-508] - Updated the documentation to include Groovy Actions (#347)
    
    * Updated the documentation to include Groovy Actions
    
    * Minor typo changes
---
 manual/src/main/asciidoc/configuration.adoc | 162 ++++++++++++++++++++++++++--
 1 file changed, 156 insertions(+), 6 deletions(-)

diff --git a/manual/src/main/asciidoc/configuration.adoc b/manual/src/main/asciidoc/configuration.adoc
index c299569..357ca13 100644
--- a/manual/src/main/asciidoc/configuration.adoc
+++ b/manual/src/main/asciidoc/configuration.adoc
@@ -376,14 +376,164 @@ org.apache.unomi.security.properties.useOGNLScripting=${env:UNOMI_SCRIPTING_USE_
 org.apache.unomi.security.personalization.sanitizeConditions=${env:UNOMI_SECURITY_SANITIZEPERSONALIZATIONCONDITIONS:-true}
 ----
 
-==== Scripting roadmap
+==== Groovy Actions
+
+Groovy actions offer the ability to define a set of actions and action types (aka action descriptors) purely from Groovy scripts defined at runtime.
+
+Initially submitted to Unomi through a purpose-built REST API endpoint, Groovy actions are then stored in Elasticsearch. When an event matches a rule configured to execute an action, the corresponding action is fetched from Elasticsearch and executed. 
+
+===== Anatomy of a Groovy Action
+
+To be valid, a Groovy action must follow a particular convention which is divided in two parts:
+
+* An annotation used to define the associated action type
+* The function to be executed
+
+Placed right before the function, the “@Action” annotation contains a set of parameter detailing how the action should be triggered.
+
+.@Action annotation
+|===
+|Field name|Type|Required|Description
+
+|id
+|String
+|YES
+|Id of the action
+
+|actionExecutor
+|String
+|YES
+|Action executor contains the name of the script to call for the action type and must be prefixed with “*groovy:*”. The prefix indicates to Unomi which dispatcher to use when processing the action. 
+
+|name
+|String
+|
+|Action name
+
+|hidden
+|Boolean
+|
+|Define if the action is hidden or not. It is usually used to hide objects in a UI.
+
+|parameters
+|List<https://github.com/apache/unomi/blob/master/extensions/groovy-actions/services/src/main/java/org/apache/unomi/groovy/actions/annotations/Parameter.java[Parameter]>
+|
+|The parameters of the actions, also defined by annotations
 
-Scripting will probably undergo major changes in future versions of Apache Unomi, possibly replacing MVEL with a
-more secure implementation of a scripting language, or possibly even removed completely (see Groovy actions below).
+|systemTags
+|List<String>
+|
+|A (reserved) list of tags for the associated object. This is usually populated through JSON descriptors and is not meant to be modified by end users. These tags may include values that help classify associated objects.
+
+|===
+
+The function contained within the Groovy Action must be called `execute()` and its last instruction must be an integer.
+
+This integer serves as an indication whether the values of the session and profile should be persisted. In general, the codes used are defined in the https://github.com/apache/unomi/blob/master/api/src/main/java/org/apache/unomi/api/services/EventService.java[EventService interface].
+
+Each groovy actions extends by default a Base script 
+https://github.com/apache/unomi/blob/master/extensions/groovy-actions/services/src/main/resources/META-INF/base/BaseScript.groovy[defined here]
+
+===== REST API
+
+Actions can be deployed/updated/deleted via the dedicated `/cxs/groovyActions` rest endpoint.
+
+Deploy/update an Action:
+[source,bash]
+----
+curl -X POST 'http://localhost:8181/cxs/groovyActions' \
+--user karaf:karaf \
+--form 'file=@"<file location>"'
+----
+
+A Groovy Action can be updated by submitting another Action with the same id.
+
+Delete an Action:
+[source,bash]
+----
+curl -X DELETE 'http://localhost:8181/cxs/groovyActions/<Action id>' \
+--user karaf:karaf 
+----
+
+Note that when a groovy action is deleted by the API, the action type associated with this action will also be deleted.
+
+===== Hello World!
+
+In this short example, we’re going to create a Groovy Action that will be adding “Hello world!” to the logs whenever a new view event is triggered.
+
+The first step consists in creating the groovy script on your filesystem, start by creating the file `hello-world.groovy`:
+
+[source,groovy]
+----
+@Action(id = "helloWorldGroovyAction",
+        actionExecutor = "groovy:helloWorldAction")
+        parameters = [@Parameter(id = "location", type = "string", multivalued = false)])
+def execute() {
+    logger.info("Hello {}", action.getParameterValues().get("location"))
+    EventService.NO_CHANGE
+}
+----
+
+As the last instruction of the script is `EventService.NO_CHANGE`, data will not be persisted. 
+
+Once the action has been created you need to submit it to Unomi (from the same folder as `hello-world.groovy`).
+[source,bash]
+----
+curl -X POST 'http://localhost:8181/cxs/groovyActions' \
+--user karaf:karaf \
+--form 'file=@hello-world.groovy'
+----
+
+Finally, register a rule to trigger execution of the groovy action:
+[source,bash]
+----
+curl -X POST 'http://localhost:8181/cxs/rules' \
+--user karaf:karaf \
+--header 'Content-Type: application/json' \
+--data-raw '{
+ "metadata": {
+   "id": "scriptGroovyActionRule",
+   "name": "Test Groovy Action Rule",
+   "description": "A sample rule to test Groovy actions"
+ },
+ "condition": {
+     "type": "eventTypeCondition",
+     "parameterValues": {
+       "eventTypeId": "view"
+     }
+ },
+ "actions": [
+   {
+     "parameterValues": {
+       "location": "world!"
+     },
+     "type": "helloWorldAction"
+   }
+ ]
+}'
+----
+
+Note that this rule contains a “location” parameter, with the value “world!”, which is then used in the log message triggered by the action.
+
+You can now use unomi to trigger a “view” event and see the corresponding message in the Unomi logs.
+
+Once you’re done with the Hello World! action, it can be deleted using the following command:
+[source,bash]
+----
+curl -X DELETE 'http://localhost:8181/cxs/groovyActions/helloWorldGroovyAction' \
+--user karaf:karaf 
+----
+
+And the corresponding rule can be deleted using the following command:
+[source,bash]
+----
+curl -X DELETE 'http://localhost:8181/cxs/rules/scriptGroovyActionRule' \
+--user karaf:karaf
+----
+
+==== Scripting roadmap
 
-It is recommended that scripting be avoided as in most cases it could be replaced by custom action implementations,
-which are also possible using the Groovy Scripting language. The main difference is in the deployment mechanism,
-Groovy actions or Java actions must be deployed as plugins, which require system administrator access and permissions.
+Scripting will probably undergo major changes in future versions of Apache Unomi, with the likely retirement of MVEL in favor of Groovy Actions detailed above. 
 
 These changes will not happen on maintenance versions of Apache Unomi, only in the next major version. Maintenance
 versions will of course maintain compatibility with existing scripting solutions.