diff options
Diffstat (limited to 'src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc')
| -rw-r--r-- | src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc | 177 |
1 files changed, 0 insertions, 177 deletions
diff --git a/src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc b/src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc deleted file mode 100644 index e014a9e9c..000000000 --- a/src/site-docs/adoc/fragments/howto-write-logic/task-logic.adoc +++ /dev/null @@ -1,177 +0,0 @@ -// -// ============LICENSE_START======================================================= -// Copyright (C) 2016-2018 Ericsson. All rights reserved. -// ================================================================================ -// This file is licensed under the CREATIVE COMMONS ATTRIBUTION 4.0 INTERNATIONAL LICENSE -// Full license text at https://creativecommons.org/licenses/by/4.0/legalcode -// -// SPDX-License-Identifier: CC-BY-4.0 -// ============LICENSE_END========================================================= -// -// @author Sven van der Meer (sven.van.der.meer@ericsson.com) -// - -== Writing APEX Task Logic - -Task logic specifies the behavior of an Apex Task. -This logic can be specified in a number of ways, exploiting Apex's plug-in architecture to support a range of logic executors. -In Apex scripted Task Logic can be written in any of these languages: - -* https://en.wikipedia.org/wiki/MVEL[`MVEL`], -* https://en.wikipedia.org/wiki/JavaScript[`JavaScript`], -* https://en.wikipedia.org/wiki/JRuby[`JRuby`] or -* https://en.wikipedia.org/wiki/Jython[`Jython`]. - -These languages were chosen because the scripts can be compiled into Java bytecode at runtime and then efficiently executed natively in the JVM. -Task Logic an also be written directly in Java but needs to be compiled, with the resulting classes added to the classpath. -There are also a number of other Task Logic types (e.g. Fuzzy Logic), but these are not supported as yet. -This guide will focus on the scripted Task Logic approaches, with MVEL and JavaScript being our favorite languages. -In particular this guide will focus on the Apex aspects of the scripts. -However, this guide does not attempt to teach you about the scripting languages themselves ... that is up to you! - -[TIP] -.JVM-based scripting languages -==== -For more more information on Scripting for the Java platform see: https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/index.html -==== - -[NOTE] -.What do Tasks do? -==== -The function of an Apex Task is to provide the logic that can be executed for an Apex State as one of the steps in an Apex Policy. -Each task receives some _incoming fields_, executes some logic (e.g: make a decision based on _shared state_ or _context_, _incoming fields_, _external context_, etc.), perhaps set some _shared state_ or _context_ and then emits _outgoing fields_. -The state that uses the task is responsible for extracting the _incoming fields_ from the state input event. -The state also has an _output mapper_ associated with the task, and this _output mapper_ is responsible for mapping the _outgoing fields_ from the task into an appropriate output event for the state. -==== - -First lets start with a sample task, drawn from the "My First Apex Policy" example: -The task "MorningBoozeCheck" from the "My First Apex Policy" example is available in both MVEL and JavaScript: - -.Javascript code for the `MorningBoozeCheck` task -[source,javascript,options="nowrap"] ----- -include::{adsite-examples-myfirstpolicy-dir}/main/resources/examples/models/MyFirstPolicy/1/MorningBoozeCheck.js[] ----- - -.MVEL code for the `MorningBoozeCheck` task -[source,java,options="nowrap"] ----- -include::{adsite-examples-myfirstpolicy-dir}/main/resources/examples/models/MyFirstPolicy/1/MorningBoozeCheck.mvel[] ----- - -The role of the task in this simple example is to copy the values in the incoming fields into the outgoing fields, then examine the values in some incoming fields (`item_id` and `time`), then set the values in some other outgoing fields (`authorised` and `message`). - -Both MVEL and JavaScript like most JVM-based scripting languages can use standard Java libraries to perform complex tasks. -Towards the top of the scripts you will see how to import Java classes and packages to be used directly in the logic. -Another thing to notice is that Task Logic should return a `java.lang.Boolean` value `true` if the logic executed correctly. -If the logic fails for some reason then `false` can be returned, but this will cause the policy invoking this task will fail and exit. - -[NOTE] -.How to return a value from task logic -==== -Some languages explicitly support returning values from the script (e.g. MVEL and JRuby) using an explicit return statement (e.g. `return true`), other languages do not (e.g. JavaScript and Jython). -For languages that do not support the `return` statement, a special field called `returnValue` must be created to hold the result of the task logic operation (i.e. assign a `java.lang.Boolean` value to the `returnValue` field before completing the task). - -Also, in MVEL if there is no explicit return statement then the return value of the last executed statement will return (e.g. the statement a=(1+2) will return the value 3). -==== - -Besides these imported classes and normal language features Apex provides some natively available parameters and functions that can be used directly. -At run-time these parameters are populated by the Apex execution environment and made natively available to logic scripts each time the logic script is invoked. -(These can be accessed using the `executor` keyword for most languages, or can be accessed directly without the `executor` keyword in MVEL): - -.The `executor` Fields / Methods -[width="100%",cols="10l,10d,30m,40a",options="header"] -|==================== -|Name | Type | Java type | Description - -|inFields | Fields | java.util.Map <String,Object> | -The incoming task fields. This is implemented as a standard Java (unmodifiable) Map. - -2+| 2+<a| -*Example:* -[source,javascript,options="nowrap"] ----- -executor.logger.debug("Incoming fields: " - +executor.inFields.entrySet()); -var item_id = executor.incomingFields["item_ID"]; -if (item_id >=1000) { ... } ----- - -|outFields | Fields | java.util.Map <String,Object> | -The outgoing task fields. This is implemented as a standard initially empty Java (modifiable) Map. -To create a new schema-compliant instance of a field object see the utility method `subject.getOutFieldSchemaHelper()` below - -2+| 2+<a| -*Example:* -[source,javascript,options="nowrap"] ----- -executor.outFields["authorised"] = false; ----- - -|logger | Logger | org.slf4j.ext.XLogger | A helpful logger - -2+| 2+<a| -*Example:* -[source,javascript,options="nowrap"] ----- -executor.logger.info("Executing task: " - +executor.subject.id); ----- - -|TRUE/FALSE | boolean | java.land.Boolean | 2 helpful constants. These are useful to retrieve correct return values for the task logic - -2+| 2+<a| -*Example:* -[source,javascript,options="nowrap"] ----- -var returnValue = executor.isTrue; -// functionally equivalent to: -var returnValueType = Java.type("java.lang.Boolean"); -var returnValue = new returnValueType(true); ----- - -|subject | Task | TaskFacade | - -This provides some useful information about the task that contains this task logic. -This object has some useful fields and methods : - -[options="compact"] -- *_AxTask task_* to get access to the full task definition of the host task -- *_String getTaskName()_* to get the name of the host task -- *_String getId()_* to get the ID of the host task -- *_SchemaHelper getInFieldSchemaHelper( String fieldName )_* to get a `SchemaHelper` helper object to manipulate incoming task fields in a schema-aware manner -- *_SchemaHelper getOutFieldSchemaHelper( String fieldName )_* to get a `SchemaHelper` helper object to manipulate outgoing task fields in a schema-aware manner, e.g. to instantiate new schema-compliant field objects to populate the `executor.outFields` outgoing fields map - -2+| 2+<a| -*Example:* -[source,javascript,options="nowrap"] ----- -executor.logger.info("Task name: " - +executor.subject.getTaskName()); -executor.logger.info("Task id: " - +executor.subject.getId()); -executor.logger.info("Task inputs definitions: " - +"executor.subject.task.getInputFieldSet()); -executor.logger.info("Task outputs definitions: " - +"executor.subject.task.getOutputFieldSet()); -executor.outFields["authorised"] = executor.subject - .getOutFieldSchemaHelper("authorised") - .createNewInstance("false"); ----- - -3+l|ContextAlbum getContextAlbum( - String ctxtAlbumName ) | -A utility method to retrieve a `ContextAlbum` for use in the task. This is how you access the context used by the task. The returned `ContextAlbum` implements the `java.util.Map <String,Object>` interface to get and set context as appropriate. The returned `ContextAlbum` also has methods to lock context albums, get information about the schema of the items to be stored in a context album, and get a `SchemaHelper` to manipulate context album items. How to define and use context in a task is described in the Apex Programmer's Guide and in the My First Apex Policy guide. - -2+| 2+<a| -*Example:* -[source,javascript,options="nowrap"] ----- -var bkey = executor.inFields.get("branch_ID"); -var cnts = executor.getContextMap("BranchCounts"); -cnts.lockForWriting(bkey); -cnts.put(bkey, cnts.get(bkey) + 1); -cnts.unlockForWriting(bkey); ----- -|==================== - |