diff options
Diffstat (limited to 'docs/apex/APEX-Policy-Guide.rst')
| -rw-r--r-- | docs/apex/APEX-Policy-Guide.rst | 2133 |
1 files changed, 2133 insertions, 0 deletions
diff --git a/docs/apex/APEX-Policy-Guide.rst b/docs/apex/APEX-Policy-Guide.rst new file mode 100644 index 00000000..392f31c7 --- /dev/null +++ b/docs/apex/APEX-Policy-Guide.rst @@ -0,0 +1,2133 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + + +APEX Policy Guide +***************************** + +.. contents:: + :depth: 3 + +APEX Policy Matrix +^^^^^^^^^^^^^^^^^^ + +APEX Policy Matrix +------------------ + + .. container:: paragraph + + APEX offers a lot of flexibility for defining, deploying, + and executing policies. Based on a theoretic model, it + supports virtually any policy model and allows to + translate legacy policies into the APEX execution format. + However, the most important aspect for using APEX is to + decide what policy is needed, what underlying policy + concepts should be used, and how the decision logic + should be realized. Once these aspects are decided, APEX + can be used to execute the policies. If the policy + evolves, say from a simple decision table to a fully + adaptable policy, only the policy definition requires + change. APEX supports all of that. + + .. container:: paragraph + + The figure below shows a (non-exhaustive) matrix, which + will help to decide what policy is required to solve your + problem. Read the matrix from left to right choosing one + cell in each column. + + .. container:: imageblock + + .. container:: content + + |APEX Policy Matrix| + + .. container:: title + + Figure 1. APEX Policy Matrix + + .. container:: paragraph + + The policy can support one of a number of stimuli with an + associated purpose/model of the policy, for instance: + + .. container:: ulist + + - Configuration, i.e. what should happen. An example is + an event that states an intended network configuration + and the policy should provide the detailed actions for + it. The policy can be realized for instance as an + obligation policy, a promise or an intent. + + - Report, i.e. something did happen. An example is an + event about an error or fault and the policy needs to + repair that problem. The policy would usually be an + obligation, utility function, or goal policy. + + - Monitoring, i.e. something does happen. An example is + a notification about certain network conditions, to + which the policy might (or might not) react. The + policy will mitigate the monitored events or permit + (deny) related actions as an obligation or + authorization. + + - Analysis, i.e. why did something happen. An example is + an analytic component sends insights of a situation + requiring a policy to act on it. The policy can solve + the problem, escalate it, or delegate it as a refrain + or delegation policy. + + - Prediction, i.e. what will happen next. An example are + events that a policy uses to predict a future network + condition. The policy can prevent or enforce the + prediction as an adaptive policy, a utility function, + or a goal. + + - Feedback, i.e. why did something happen or not happen. + Similar to analysis, but here the feedback will be in + the input event and the policy needs to something with + that information. Feedback can be related to history + or experience, for instance a previous policy + execution. The policy needs to be context-aware or be + a meta-policy. + + .. container:: paragraph + + Once the purpose of the policy is decided, the next step + is to look into what context information the policy will + require to do its job. This can range from very simple to + a lot of different information, for instance: + + .. container:: ulist + + - No context, nothing but a trigger event, e.g. a string + or a number, is required + + - Event context, the incoming event provides all + information (more than a string or number) for the + policy + + - Policy context (read only), the policy has access to + additional information related to its class but cannot + change/alter them + + - Policy context (read and write), the policy has access + to additional information related to its class and can + alter this information (for instance to record + historic information) + + - Global context (read only), the policy has access to + additional information of any kind but cannot + change/alter them + + - Global context (read and write), the policy the policy + has access to additional information of any kind and + can alter this information (for instance to record + historic information) + + .. container:: paragraph + + The next step is to decide how the policy should do its + job, i.e. what flavor it has, how many states are needed, + and how many tasks. There are many possible combinations, + for instance: + + .. container:: ulist + + - Simple / God: a simple policy with 1 state and 1 task, + which is doing everything for the decision-making. + This is the ideal policy for simple situation, e.g. + deciding on configuration parameters or simple access + control. + + - Simple sequence: a simple policy with a number of + states each having a single task. This is a very good + policy for simple decision-making with different + steps. For instance, a classic action policy (ECA) + would have 3 states (E, C, and A) with some logic (1 + task) in each state. + + - Simple selective: a policy with 1 state but more than + one task. Here, the appropriate task (and it’s logic) + will be selected at execution time. This policy is + very good for dealing with similar (or the same) + situation in different contexts. For instance, the + tasks can be related to available external software, + or to current work load on the compute node, or to + time of day. + + - Selective: any number of states having any number of + tasks (usually more than 1 task). This is a + combination of the two policies above, for instance an + ECA policy with more than one task in E, C, and A. + + - Classic directed: a policy with more than one state, + each having one task, but a non-sequential execution. + This means that the sequence of the states is not + pre-defined in the policy (as would be for all cases + above) but calculated at runtime. This can be good to + realize decision trees based on contextual + information. + + - Super Adaptive: using the full potential of the APEX + policy model, states and tasks and state execution are + fully flexible and calculated at runtime (per policy + execution). This policy is very close to a general + programming system (with only a few limitations), but + can solve very hard problems. + + .. container:: paragraph + + The final step is to select a response that the policy + creates. Possible responses have been discussed in the + literature for a very long time. A few examples are: + + .. container:: ulist + + - Obligation (deontic for what should happen) + + - Authorization (e.g. for rule-based or other access + control or security systems) + + - Intent (instead of providing detailed actions the + response is an intent statement and a further system + processes that) + + - Delegation (hand the problem over to someone else, + possibly with some information or instructions) + + - Fail / Error (the policy has encountered a problem, + and reports it) + + - Feedback (why did the policy make a certain decision) + +APEX Policy Model +^^^^^^^^^^^^^^^^^ + +Introduction +------------ + + .. container:: paragraph + + The APEX policy model is shown in UML notation in the + figure below. A policy model can be stored in JSON or XML + format in a file or can be held in a database. The APEX + editor creates and modifies APEX policy models. APEX + deployment deploys policy models, and a policy model is + loaded into APEX engines so that the engines can run the + policies in the policy model. + + .. container:: paragraph + + The figure shows four different views of the policy + model: + + .. container:: ulist + + - The general model view shows the main parts of a + policy: state, state output, event, and task. A task + can also have parameters. Data types can be defined on + a per-model basis using either standard atomic types + (such as character, string, numbers) or complex types + from a policy domain. + + - The logic model view emphasizes how decision-making + logic is injected into a policy. There are essentially + three different types of logic: task logic (for + decision making in a task), task selection logic (to + select a task if more than one is defined in a state), + and state finalizer logic (to compute the final output + event of a state and select an appropriate next state + from the policy model). + + - The context model view shows how context is injected + into a policy. States collect all context from their + tasks. A task can define what context it requires for + the decision making, i.e. what context the task logic + will process. Context itself is a collection of items + (individual context information) with data types. + Context can be templated. + + - The event and field model view shows the events in the + policy model. Tasks define what information they + consume (input) and produce (output). This information + is modeled as fields, essentially a key/type tuple in + the model and a key/type/value triple at execution. + Events then are collection of fields. + + .. container:: imageblock + + .. container:: content + + |APEX Policy Model for Execution| + + .. container:: title + + Figure 2. APEX Policy Model for Execution + +Concepts and Keys +################# + + .. container:: paragraph + + Each element of the policy model is called a + *concept*. Each *concept* is a subclass of the + abstract *Concept* class, as shown in the next figure. + Every concept implements the following abstract + methods: + + .. container:: imageblock + + .. container:: content + + |Concepts and Keys| + + .. container:: title + + Figure 3. Concepts and Keys + + .. container:: ulist + + - ``getKey()`` - gets the unique key for this concept + instance in the system + + - ``validate()`` - validates the structure of this + concept, its sub-concepts and its relationships + + - ``clean()`` - carries out housekeeping on the + concept such as trimming strings, remove any + hanging references + + - ``clone()`` - creates a deep copy of an instance of + this concept + + - ``equals()`` - checks if two instances of this + concept are equal + + - ``toString()`` - returns a string representation of + the concept + + - ``hashCode()`` - returns a hash code for the + concept + + - ``copyTo()`` - carries out a deep copy of one + instance of the concept to another instance, + overwriting the target fields. + + .. container:: paragraph + + All concepts must have a *key*, which uniquely + identifies a concept instance. The *key* of a subclass + of an *Concept* must either be an ``ArtifactKey`` or + an ``ReferenceKey``. Concepts that have a stand-alone + independent existence such as *Policy*, *Task*, and + *Event* must have an ``ArtifctKey`` key. Concepts that + are contained in other concepts, that do not exist as + stand-alone concepts must have an ``ReferenceKey`` + key. Examples of such concepts are *State* and + *EventParameter*. + + .. container:: paragraph + + An ``ArticactKey`` has two fields; the *Name* of the + concept it is the key for and the concept’s *Version*. + A concept’s name must be unique in a given + PolicyModel. A concept version is represented using + the well known *major.minor.path* scheme as used in + semantic versioning. + + .. container:: paragraph + + A ``ReferenceKey`` has three fields. The *UserKeyName* + and *UserKeyVersion* fields identify the + ``ArtifactKey`` of the concept in which the concept + keyed by the ``ReferenceKey`` is contained. The + *LocalName* field identifies the contained concept + instance. The *LocalName* must be unique in the + concepts of a given type contained by a parent. + + .. container:: paragraph + + For example, a policy called ``SalesPolicy`` with a + Version of ``1.12.4`` has a state called ``Decide``. + The ``Decide`` state is linked to the ``SalesPolicy`` + with a ``ReferenceKey`` with fields *UserKeyName* of + ``SalesPolicy``, *UserKeyVersion* of ``1.12.4``, and + *LocalName* of ``Decide``. There must not be another + state called ``Decide`` in the policy ``SalesPolicy``. + However, there may well be a state called ``Decide`` + in some other policy called ``PurchasingPolicy``. + + .. container:: paragraph + + Each concept in the model is also a JPA (`Java + Persistence + API <https://en.wikipedia.org/wiki/Java_Persistence_API>`__) + Entity. This means that every concept can be + individually persisted or the entire model can be + persisted en-bloc to any persistence mechanism using + an JPA framework such as + `Hibernate <http://hibernate.org/>`__ or + `EclipseLink <http://www.eclipse.org/eclipselink/>`__. + +Concept: PolicyModel +#################### + + .. container:: paragraph + + The *PolicyModel* concept is a container that holds + the definition of a set of policies and their + associated events, context maps, and tasks. A + *PolicyModel* is implemented as four maps for + policies, events, context maps, and tasks. Each map is + indexed by the key of the policy, event, context map, + or task. Any non-empty policy model must have at least + one entry in its policy, event, and task map because + all policies must have at least one input and output + event and must execute at least one task. + + .. container:: paragraph + + A *PolicyModel* concept is keyed with an + ``ArtifactKey key``. Because a *PolicyModel* is an + ``AxConcept``, calling the ``validate()`` method on a + policy model validates the concepts, structure, and + relationships of the entire policy model. + +Concept: DataType +################# + + .. container:: paragraph + + Data types are tightly controlled in APEX in order to + provide a very high degree of consistency in policies + and to facilitate tracking of changes to context as + policies execute. All context is modeled as a + *DataType* concept. Each DataType concept instance is + keyed with an ``ArtifactKey`` key. The DataType field + identifies the Java class of objects that is used to + represent concept instances that use this data type. + All context has a *DataType*; incoming and outgoing + context is represented by *EventField* concepts and + all other context is represented by *ContextItem* + concepts. + +Concept: Event +############## + + .. container:: paragraph + + An *Event* defines the structure of a message that + passes into or out of an APEX engine or that passes + between two states in an APEX engine. APEX supports + message reception and sending in many formats and all + messages are translated into an *Event* prior to + processing by an APEX engine. Event concepts are keyed + with an ``ArtifactKey`` key. The parameters of an + event are held as a map of *EventField* concept + instances with each parameter indexed by the + *LocalName* of its ``ReferenceKey``. An *Event* has + three fields: + + .. container:: ulist + + - The *NameSpace* identifies the domain of + application of the event + + - The *Source* of the event identifies the system + that emitted the event + + - The *Target* of the event identifies the system + that the event was sent to + + .. container:: paragraph + + A *PolicyModel* contains a map of all the events known + to a given policy model. Although an empty model may + have no events in its event map, any sane policy model + must have at least one *Event* defined. + +Concept: EventField +################### + + .. container:: paragraph + + The incoming context and outgoing context of an event + are the fields of the event. Each field representing a + single piece of incoming or outgoing context. Each + field of an *Event* is represented by an instance of + the *EventField* concept. Each *EventField* concept + instance in an event is keyed with a ``ReferenceKey`` + key, which references the event. The *LocalName* field + of the ``ReferenceKey`` holds the name of the field A + reference to a *DataType* concept defines the data + type that values of this parameter have at run time. + +Concept: ContextMap +################### + + .. container:: paragraph + + The set of context that is available for use by the + policies of a *PolicyModel* is defined as *ContextMap* + concept instances. The *PolicyModel* holds a map of + all the *ContextMap* definitions. A *ContextMap* is + itself a container for a group of related context + items, each of which is represented by a *ContextItem* + concept instance. *ContextMap* concepts are keyed with + an ``ArtifactKey`` key. A developer can use the APEX + Policy Editor to create context maps for their + application domain. + + .. container:: paragraph + + A *ContextMap* uses a map to hold the context items. + The ContextItem concept instances in the map are + indexed by the *LocalName* of their ``ReferenceKey``. + + .. container:: paragraph + + The *ContextMapType* field of a *ContextMap* defines + the type of a context map. The type can have either of + two values: + + .. container:: ulist + + - A *BAG* context map is a context map with fixed + content. Each possible context item in the context + map is defined at design time and is held in the + *ContextMap* context instance as *ContextItem* + concept definitions and only the values of the + context items in the context map can be changed at + run time. The context items in a *BAG* context map + have mixed types and distinct *ContextItem* concept + instances of the same type can be defined. A *BAG* + context map is convenient for defining a group of + context items that are diverse but are related by + domain, such as the characteristics of a device. A + fully defined *BAG* context map has a fully + populated *ContextItem* map but its + *ContextItemTemplate* reference is not defined. + + - A *SAMETYPE* context map is used to represent a + group of *ContextItem* instances of the same type. + Unlike a *BAG* context map, the *ContextItem* + concept instances of a *SAMETYPE* context map can + be added, modified, and deleted at runtime. All + *ContextItem* concept instances in a *SAMETYPE* + context map must be of the same type, and that + context item is defined as a single + *ContextItemTemplate* concept instances at design + time. At run time, the *ContextItemTemplate* + definition is used to create new *ContextItem* + concept instances for the context map on demand. A + fully defined *SAMETYPE context map has an empty + ContextItem map and its ContextItemTemplate\_* + reference is defined. + + .. container:: paragraph + + The *Scope* of a *ContextMap* defines the range of + applicability of a context map in APEX. The following + scopes of applicability are defined: + + .. container:: ulist + + - *EPHEMERAL* scope means that the context map is + owned, used, and modified by a single application, + but the context map only exists while that + application is running + + - *APPLICATION* scope specifies that the context map + is owned, used, and modified by a single + application, the context map is persistent + + - *GLOBAL* scope specifies that the context map is + globally owned and is used and modified by any + application, the context map is persistent + + - *EXTERNAL* scope specifies that the context map is + owned by an external system and may be used in a + read-only manner by any application, the context + map is persistent + + .. container:: paragraph + + A much more sophisticated scoping mechanism for + context maps is envisaged for Apex in future work. In + such a mechanism, the scope of a context map would + work somewhat like the way roles work in security + authentication systems. + +Concept: ContextItem +#################### + + .. container:: paragraph + + Each piece of context in a *ContextMap* is represented + by an instance of the *ContextItem* concept. Each + *ContextItem* concept instance in a context map keyed + with a ``ReferenceKey`` key, which references the + context map of the context item. The *LocalName* field + of the ``ReferenceKey`` holds the name of the context + item in the context map A reference to a *DataType* + concept defines the data type that values of this + context item have at run time. The *WritableFlag* + indicates if the context item is read only or + read-write at run time. + +Concept: ContextItemTemplate +############################ + + .. container:: paragraph + + In a *SAMETYPE* *ContextMap*, the + *ContextItemTemplate* definition provides a template + for the *ContextItem* instances that will be created + on the context map at run time. Each *ContextItem* + concept instance in the context map is created using + the *ContextItemTemplate* template. It is keyed with a + ``ReferenceKey`` key, which references the context map + of the context item. The *LocalName* field of the + ``ReferenceKey``, supplied by the creator of the + context item at run time, holds the name of the + context item in the context map. A reference to a + *DataType* concept defines the data type that values + of this context item have at run time. The + *WritableFlag* indicates if the context item is read + only or read-write at run time. + +Concept: Task +############# + + .. container:: paragraph + + The smallest unit of logic in a policy is a *Task*. A + task encapsulates a single atomic unit of logic, and + is designed to be a single indivisible unit of + execution. A task may be invoked by a single policy or + by many policies. A task has a single trigger event, + which is sent to the task when it is invoked. Tasks + emit one or more outgoing events, which carry the + result of the task execution. Tasks may use or modify + context as they execute. + + .. container:: paragraph + + The Task concept definition captures the definition of + an APEX task. Task concepts are keyed with an + ``ArtifactKey`` key. The Trigger of the task is a + reference to the *Event* concept that triggers the + task. The *OutgoingEvents* of a task are a set of + references to *Event* concepts that may be emitted by + the task. + + .. container:: paragraph + + All tasks have logic, some code that is programmed to + execute the work of the task. The *Logic* concept of + the task holds the definition of that logic. + + .. container:: paragraph + + The *Task* definition holds a set of *ContextItem* and + *ContextItemTemplate* context items that the task is + allow to access, as defined by the task developer at + design time. The type of access (read-only or read + write) that a task has is determined by the + *WritableFlag* flag on the individual context item + definitions. At run time, a task may only access the + context items specified in its context item set, the + APEX engine makes only the context items in the task + context item set is available to the task. + + .. container:: paragraph + + A task can be configured with startup parameters. The + set of parameters that can be configured on a task are + defined as a set of *TaskParameter* concept + definitions. + +Concept: TaskParameter +###################### + + .. container:: paragraph + + Each configuration parameter of a task are represented + as a *Taskparameter* concept keyed with a + ``ReferenceKey`` key, which references the task. The + *LocalName* field of the ``ReferenceKey`` holds the + name of the parameter. The *DefaultValue* field + defines the default value that the task parameter is + set to. The value of *TaskParameter* instances can be + overridden at deployment time by specifying their + values in the configuration information passed to APEX + engines. + +Concept: Logic +############## + + .. container:: paragraph + + The *Logic* concept instance holds the actual + programmed task logic for a task defined in a *Task* + concept or the programmed task selection logic for a + state defined in a *State* concept. It is keyed with a + ``ReferenceKey`` key, which references the task or + state that owns the logic. The *LocalName* field of + the Logic concept is the name of the logic. + + .. container:: paragraph + + The *LogicCode* field of a Logic concept definition is + a string that holds the program code that is to be + executed at run time. The *LogicType* field defines + the language of the code. The standard values are the + logic languages supported by APEX: + `JAVASCRIPT <https://en.wikipedia.org/wiki/JavaScript>`__, + `JAVA <https://java.com/en/>`__, + `JYTHON <http://www.jython.org/>`__, + `JRUBY <http://jruby.org/>`__, or + `MVEL <https://en.wikibooks.org/wiki/Transwiki:MVEL_Language_Guide>`__. + + .. container:: paragraph + + The APEX engine uses the *LogicType* field value to + decide which language interpreter to use for a task + and then sends the logic defined in the *LogicCode* + field to that interpreter. + +Concept: Policy +############### + + .. container:: paragraph + + The *Policy* concept defines a policy in APEX. The + definition is rather straightforward. A policy is made + up of a set of states with the flavor of the policy + determining the structure of the policy states and the + first state defining what state in the policy executes + first. *Policy* concepts are keyed with an + ``ArtifactKey`` key. + + .. container:: paragraph + + The *PolicyFlavour* of a *Policy* concept specifies + the structure that will be used for the states in the + policy. A number of commonly used policy patterns are + supported as APEX policy flavors. The standard policy + flavors are: + + .. container:: ulist + + - The *MEDA* flavor supports policies written to the + `MEDA policy + pattern <https://www.researchgate.net/publication/282576518_Dynamically_Adaptive_Policies_for_Dynamically_Adaptive_Telecommunications_Networks>`__ + and require a sequence of four states: namely + *Match*, *Establish*, *Decide* and *Act*. + + - The *OODA* flavor supports policies written to the + `OODA loop + pattern <https://en.wikipedia.org/wiki/OODA_loop>`__ + and require a sequence of four states: namely + *Observe*, *Orient*, *Decide* and *Act*. + + - The *ECA* flavor supports policies written to the + `ECA active rule + pattern <https://en.wikipedia.org/wiki/Event_condition_action>`__ + and require a sequence of three states: namely + *Event*, *Condition* and *Action* + + - The *XACML* flavor supports policies written in + `XACML <https://en.wikipedia.org/wiki/XACML>`__ and + require a single state: namely *XACML* + + - The *FREEFORM* flavor supports policies written in + an arbitrary style. A user can define a *FREEFORM* + policy as an arbitrarily long chain of states. + + .. container:: paragraph + + The *FirstState* field of a *Policy* definition is the + starting point for execution of a policy. Therefore, + the trigger event of the state referenced in the + *FirstState* field is also the trigger event for the + entire policy. + +Concept: State +############## + + .. container:: paragraph + + The *State* concept represents a phase or a stage in a + policy, with a policy being composed of a series of + states. Each state has at least one but may have many + tasks and, on each run of execution, a state executes + one and only one of its tasks. If a state has more + than one task, then its task selection logic is used + to select which task to execute. Task selection logic + is programmable logic provided by the state designer. + That logic can use incoming, policy, global, and + external context to select which task best + accomplishes the purpose of the state in a give + situation if more than one task has been specified on + a state. A state calls one and only one task when it + is executed. + + .. container:: paragraph + + Each state is triggered by an event, which means that + all tasks of a state must also be triggered by that + same event. The set of output events for a state is + the union of all output events from all tasks for that + task. In practice at the moment, because a state can + only have a single input event, a state that is not + the final state of a policy may only output a single + event and all tasks of that state may also only output + that single event. In future work, the concept of + having a less restrictive trigger pattern will be + examined. + + .. container:: paragraph + + A *State* concept is keyed with a ``ReferenceKey`` + key, which references the *Policy* concept that owns + the state. The *LocalName* field of the + ``ReferenceKey`` holds the name of the state. As a + state is part of a chain of states, the *NextState* + field of a state holds the ``ReferenceKey`` key of the + state in the policy to execute after this state. + + .. container:: paragraph + + The *Trigger* field of a state holds the + ``ArtifactKey`` of the event that triggers this state. + The *OutgoingEvents* field holds the ``ArtifactKey`` + references of all possible events that may be output + from the state. This is a set that is the union of all + output events of all tasks of the state. + + .. container:: paragraph + + The *Task* concepts that hold the definitions of the + task for the state are held as a set of + ``ArtifactKey`` references in the state. The + *DefaultTask* field holds a reference to the default + task for the state, a task that is executed if no task + selection logic is specified. If the state has only + one task, that task is the default task. + + .. container:: paragraph + + The *Logic* concept referenced by a state holds the + task selection logic for a state. The task selection + logic uses the incoming context (parameters of the + incoming event) and other context to determine the + best task to use to execute its goals. The state holds + a set of references to *ContextItem* and + *ContextItemTemplate* definitions for the context used + by its task selection logic. + +Writing Logic +^^^^^^^^^^^^^ + +Writing APEX Task Logic +----------------------- + + .. container:: paragraph + + 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: + + .. container:: ulist + + - ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__, + + - ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__, + + - ```JRuby`` <https://en.wikipedia.org/wiki/JRuby>`__ or + + - ```Jython`` <https://en.wikipedia.org/wiki/Jython>`__. + + .. container:: paragraph + + 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. + + .. container:: paragraph + + 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: + + .. container:: listingblock + + .. container:: title + + Javascript code for the ``MorningBoozeCheck`` task + + .. container:: content + + .. code:: javascript + :number-lines: + + /* + * ============LICENSE_START======================================================= + * Copyright (C) 2016-2018 Ericsson. All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * SPDX-License-Identifier: Apache-2.0 + * ============LICENSE_END========================================================= + */ + + var returnValueType = Java.type("java.lang.Boolean"); + var returnValue = new returnValueType(true); + + // Load compatibility script for imports etc + load("nashorn:mozilla_compat.js"); + importPackage(java.text); + importClass(java.text.SimpleDateFormat); + + executor.logger.info("Task Execution: '"+executor.subject.id+"'. Input Fields: '"+executor.inFields+"'"); + + executor.outFields.put("amount" , executor.inFields.get("amount")); + executor.outFields.put("assistant_ID", executor.inFields.get("assistant_ID")); + executor.outFields.put("notes" , executor.inFields.get("notes")); + executor.outFields.put("quantity" , executor.inFields.get("quantity")); + executor.outFields.put("branch_ID" , executor.inFields.get("branch_ID")); + executor.outFields.put("item_ID" , executor.inFields.get("item_ID")); + executor.outFields.put("time" , executor.inFields.get("time")); + executor.outFields.put("sale_ID" , executor.inFields.get("sale_ID")); + + item_id = executor.inFields.get("item_ID"); + + //All times in this script are in GMT/UTC since the policy and events assume time is in GMT. + var timenow_gmt = new Date(Number(executor.inFields.get("time"))); + + var midnight_gmt = new Date(Number(executor.inFields.get("time"))); + midnight_gmt.setUTCHours(0,0,0,0); + + var eleven30_gmt = new Date(Number(executor.inFields.get("time"))); + eleven30_gmt.setUTCHours(11,30,0,0); + + var timeformatter = new java.text.SimpleDateFormat("HH:mm:ss z"); + + var itemisalcohol = false; + if(item_id != null && item_id >=1000 && item_id < 2000) + itemisalcohol = true; + + if( itemisalcohol + && timenow_gmt.getTime() >= midnight_gmt.getTime() + && timenow_gmt.getTime() < eleven30_gmt.getTime()) { + + executor.outFields.put("authorised", false); + executor.outFields.put("message", "Sale not authorised by policy task " + + executor.subject.taskName+ " for time " + timeformatter.format(timenow_gmt.getTime()) + + ". Alcohol can not be sold between " + timeformatter.format(midnight_gmt.getTime()) + + " and " + timeformatter.format(eleven30_gmt.getTime())); + } + else{ + executor.outFields.put("authorised", true); + executor.outFields.put("message", "Sale authorised by policy task " + + executor.subject.taskName + " for time "+timeformatter.format(timenow_gmt.getTime())); + } + + /* + This task checks if a sale request is for an item that is an alcoholic drink. + If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not + authorised. Otherwise the sale is authorised. + In this implementation we assume that items with item_ID value between 1000 and + 2000 are all alcoholic drinks :-) + */ + + .. container:: listingblock + + .. container:: title + + MVEL code for the ``MorningBoozeCheck`` task + + .. container:: content + + .. code:: javascript + :number-lines: + + /* + * ============LICENSE_START======================================================= + * Copyright (C) 2016-2018 Ericsson. All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * SPDX-License-Identifier: Apache-2.0 + * ============LICENSE_END========================================================= + */ + import java.util.Date; + import java.util.Calendar; + import java.util.TimeZone; + import java.text.SimpleDateFormat; + + logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'"); + + outFields.put("amount" , inFields.get("amount")); + outFields.put("assistant_ID", inFields.get("assistant_ID")); + outFields.put("notes" , inFields.get("notes")); + outFields.put("quantity" , inFields.get("quantity")); + outFields.put("branch_ID" , inFields.get("branch_ID")); + outFields.put("item_ID" , inFields.get("item_ID")); + outFields.put("time" , inFields.get("time")); + outFields.put("sale_ID" , inFields.get("sale_ID")); + + item_id = inFields.get("item_ID"); + + //The events used later to test this task use GMT timezone! + gmt = TimeZone.getTimeZone("GMT"); + timenow = Calendar.getInstance(gmt); + df = new SimpleDateFormat("HH:mm:ss z"); + df.setTimeZone(gmt); + timenow.setTimeInMillis(inFields.get("time")); + + midnight = timenow.clone(); + midnight.set( + timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), + timenow.get(Calendar.DATE),0,0,0); + eleven30 = timenow.clone(); + eleven30.set( + timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), + timenow.get(Calendar.DATE),11,30,0); + + itemisalcohol = false; + if(item_id != null && item_id >=1000 && item_id < 2000) + itemisalcohol = true; + + if( itemisalcohol + && timenow.after(midnight) && timenow.before(eleven30)){ + outFields.put("authorised", false); + outFields.put("message", "Sale not authorised by policy task "+subject.taskName+ + " for time "+df.format(timenow.getTime())+ + ". Alcohol can not be sold between "+df.format(midnight.getTime())+ + " and "+df.format(eleven30.getTime())); + return true; + } + else{ + outFields.put("authorised", true); + outFields.put("message", "Sale authorised by policy task "+subject.taskName+ + " for time "+df.format(timenow.getTime())); + return true; + } + + /* + This task checks if a sale request is for an item that is an alcoholic drink. + If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not + authorised. Otherwise the sale is authorised. + In this implementation we assume that items with item_ID value between 1000 and + 2000 are all alcoholic drinks :-) + */ + + .. container:: paragraph + + 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``). + + .. container:: paragraph + + 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). + + .. container:: paragraph + + 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): + + Table 1. The ``executor`` Fields / Methods + ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ +| Name | Type | Java type | Description | ++============+=============+================================+=====================================================================================+ +| inFields | Fields | java.util.Map <String,Object> | .. container:: paragraph | +| | | | | +| | | | The incoming task fields. This is implemented as a standard Java | +| | | | Java (unmodifiable) Map | +| | | | | +| | | | .. container:: | +| | | | | +| | | | .. container:: content | +| | | | | +| | | | .. container:: paragraph | +| | | | | +| | | | **Example:** | +| | | | | +| | | | .. code:: javascript | +| | | | | +| | | | 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> | .. container:: paragraph | +| | | | | +| | | | 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 | +| | | | | +| | | | .. container:: | +| | | | | +| | | | .. container:: content | +| | | | | +| | | | .. container:: paragraph | +| | | | | +| | | | **Example:** | +| | | | | +| | | | .. code:: javascript | +| | | | | +| | | | executor.outFields["authorised"] = false; | ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ +| logger | Logger | org.slf4j.ext.XLogger | .. container:: paragraph | +| | | | | +| | | | A helpful logger | +| | | | | +| | | | .. container:: | +| | | | | +| | | | .. container:: content | +| | | | | +| | | | .. container:: paragraph | +| | | | | +| | | | **Example:** | +| | | | | +| | | | .. code:: javascript | +| | | | | +| | | | executor.logger.info("Executing task: " | +| | | | +executor.subject.id); | ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ +| TRUE/FALSE | boolean | java.lang.Boolean | .. container:: paragraph | +| | | | | +| | | | 2 helpful constants. These are useful to retrieve correct return values for the | +| | | | task logic | +| | | | | +| | | | .. container:: | +| | | | | +| | | | .. container:: content | +| | | | | +| | | | .. container:: paragraph | +| | | | | +| | | | **Example:** | +| | | | | +| | | | .. code:: javascript | +| | | | | +| | | | var returnValue = executor.isTrue; | +| | | | var returnValueType = Java.type("java.lang.Boolean"); | +| | | | var returnValue = new returnValueType(true); | ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ +| subject | Task | TaskFacade | .. container:: paragraph | +| | | | | +| | | | This provides some useful information about the task that contains this task | +| | | | logic. This object has some useful fields and methods : | +| | | | | +| | | | .. container:: ulist | +| | | | | +| | | | - **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 | +| | | | | +| | | | .. container:: | +| | | | | +| | | | .. container:: content | +| | | | | +| | | | .. container:: paragraph | +| | | | | +| | | | **Example:** | +| | | | | +| | | | .. code:: javascript | +| | | | | +| | | | 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"); | ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ +| ContextAlbum getContextAlbum(String ctxtAlbumName ) | .. container:: paragraph | +| | | +| | 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. | +| | | +| | .. container:: | +| | | +| | .. container:: content | +| | | +| | .. container:: paragraph | +| | | +| | **Example:** | +| | | +| | .. code:: javascript | +| | | +| | 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); | ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ + +Writing APEX Task Selection Logic +--------------------------------- + + .. container:: paragraph + + The function of Task Selection Logic is to choose which task + should be executed for an Apex State as one of the steps in an + Apex Policy. Since each state must define a default task there is + no need for Task Selection Logic unless the state uses more than + one 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 Selection Logic can be written in + any of these languages: + + .. container:: ulist + + - ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__, + + - ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__, + + - ```JRuby`` <https://en.wikipedia.org/wiki/JRuby>`__ or + + - ```Jython`` <https://en.wikipedia.org/wiki/Jython>`__. + + .. container:: paragraph + + These languages were chosen because the scripts can be compiled + into Java bytecode at runtime and then efficiently executed + natively in the JVM. Task Selection 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 Selection Logic types but these are not supported as yet. + This guide will focus on the scripted Task Selection 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 does Task Selection Logic do? + When an Apex state references multiple tasks, there must be a way to dynamically decide + which task should be chosen and executed. This can depend on the many factors, e.g. the + *incoming event for the state*, *shared state* or *context*, *external context*, + etc.. This is the function of a state’s Task Selection Logic. Obviously, if there is + only one task then Task only one task then Task Selection Logic is not needed. + Each state must also select one of the tasks a the *default state*. If the Task + Selection Logic is unable to select an appropriate task, then it should select the + *default task*. Once the task has been selected the Apex Engine will then execute that + task. + + .. container:: paragraph + + First lets start with some simple Task Selection Logic, drawn from + the "My First Apex Policy" example: The Task Selection Logic from + the "My First Apex Policy" example is specified in JavaScript + here: + + .. container:: listingblock + + .. container:: title + + Javascript code for the "My First Policy" Task Selection Logic + + .. container:: content + + .. code:: javascript + + /* + * ============LICENSE_START======================================================= + * Copyright (C) 2016-2018 Ericsson. All rights reserved. + * ================================================================================ + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + * + * SPDX-License-Identifier: Apache-2.0 + * ============LICENSE_END========================================================= + */ + + + var returnValueType = Java.type("java.lang.Boolean"); + var returnValue = new returnValueType(true); + + executor.logger.info("Task Selection Execution: '"+executor.subject.id+ + "'. Input Event: '"+executor.inFields+"'"); + + branchid = executor.inFields.get("branch_ID"); + taskorig = executor.subject.getTaskKey("MorningBoozeCheck"); + taskalt = executor.subject.getTaskKey("MorningBoozeCheckAlt1"); + taskdef = executor.subject.getDefaultTaskKey(); + + if(branchid >=0 && branchid <1000){ + taskorig.copyTo(executor.selectedTask); + } + else if (branchid >=1000 && branchid <2000){ + taskalt.copyTo(executor.selectedTask); + } + else{ + taskdef.copyTo(executor.selectedTask); + } + + /* + This task selection logic selects task "MorningBoozeCheck" for branches with + 0<=branch_ID<1000 and selects task "MorningBoozeCheckAlt1" for branches with + 1000<=branch_ID<2000. Otherwise the default task is selected. + In this case the default task is also "MorningBoozeCheck" + */ + + .. container:: paragraph + + The role of the Task Selection Logic in this simple example is to + examine the value in one incoming field (``branchid``), then + depending on that field’s value set the value for the selected + task to the appropriate task (``MorningBoozeCheck``, + ``MorningBoozeCheckAlt1``, or the default task). + + .. container:: paragraph + + Another thing to notice is that Task Selection 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 Selection 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 not 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). + + .. container:: paragraph + + Each of the scripting languages used in Apex can import and use + standard Java libraries to perform complex tasks. Besides 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): + + Table 2. The ``executor`` Fields / Methods + +-------------------------------------------------------+--------------------------------------------------------+ + | Unix, Cygwin | Windows | + +=======================================================+========================================================+ + | .. container:: | .. container:: | + | | | + | .. container:: content | .. container:: content | + | | | + | .. code:: bash | .. code:: bash | + | :number-lines: | :number-lines: | + | | | + | >c: | # cd /usr/local/src/apex-pdp | + | >cd \dev\apex | # mvn clean install -DskipTest | + | >mvn clean install -DskipTests | | + +-------------------------------------------------------+--------------------------------------------------------+ + ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ +| Name | Type | Java type | Description | ++============+=============+================================+=====================================================================================+ +| inFields | Fields | java.util.Map <String,Object> | .. container:: paragraph | +| | | | | +| | | | All fields in the state’s incoming event. This is implemented as a standard Java | +| | | | Java (unmodifiable) Map | +| | | | | +| | | | .. container:: | +| | | | | +| | | | .. container:: content | +| | | | | +| | | | .. container:: paragraph | +| | | | | +| | | | **Example:** | +| | | | | +| | | | .. code:: javascript | +| | | | | +| | | | 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> | .. container:: paragraph | +| | | | | +| | | | 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 | +| | | | | +| | | | .. container:: | +| | | | | +| | | | .. container:: content | +| | | | | +| | | | .. container:: paragraph | +| | | | | +| | | | **Example:** | +| | | | | +| | | | .. code:: javascript | +| | | | | +| | | | executor.outFields["authorised"] = false; | ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ +| logger | Logger | org.slf4j.ext.XLogger | .. container:: paragraph | +| | | | | +| | | | A helpful logger | +| | | | | +| | | | .. container:: | +| | | | | +| | | | .. container:: content | +| | | | | +| | | | .. container:: paragraph | +| | | | | +| | | | **Example:** | +| | | | | +| | | | .. code:: javascript | +| | | | | +| | | | executor.logger.info("Executing task: " | +| | | | +executor.subject.id); | ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ +| TRUE/FALSE | boolean | java.lang.Boolean | .. container:: paragraph | +| | | | | +| | | | 2 helpful constants. These are useful to retrieve correct return values for the | +| | | | task logic | +| | | | | +| | | | .. container:: | +| | | | | +| | | | .. container:: content | +| | | | | +| | | | .. container:: paragraph | +| | | | | +| | | | **Example:** | +| | | | | +| | | | .. code:: javascript | +| | | | | +| | | | var returnValue = executor.isTrue; | +| | | | var returnValueType = Java.type("java.lang.Boolean"); | +| | | | var returnValue = new returnValueType(true); | ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ +| subject | Task | TaskFacade | .. container:: paragraph | +| | | | | +| | | | This provides some useful information about the task that contains this task | +| | | | logic. This object has some useful fields and methods : | +| | | | | +| | | | .. container:: ulist | +| | | | | +| | | | - **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 | +| | | | | +| | | | .. container:: | +| | | | | +| | | | .. container:: content | +| | | | | +| | | | .. container:: paragraph | +| | | | | +| | | | **Example:** | +| | | | | +| | | | .. code:: javascript | +| | | | | +| | | | 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"); | ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ +| ContextAlbum getContextAlbum(String ctxtAlbumName ) | .. container:: paragraph | +| | | +| | 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. | +| | | +| | .. container:: | +| | | +| | .. container:: content | +| | | +| | .. container:: paragraph | +| | | +| | **Example:** | +| | | +| | .. code:: javascript | +| | | +| | 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); | ++------------+-------------+--------------------------------+-------------------------------------------------------------------------------------+ + +Logic Cheatsheet +---------------- + + .. container:: paragraph + + Examples given here use Javascript (if not stated otherwise), + other execution environments will be similar. + +Add Nashorn +########### + + .. container:: paragraph + + First line in the logic use this import. + + .. container:: listingblock + + .. container:: title + + JS Nashorn + + .. container:: content + + .. code:: javascript + + load("nashorn:mozilla_compat.js"); + +Finish Logic with Success or Error +################################## + + .. container:: paragraph + + To finish logic, i.e. return to APEX, with success use the + following lines close to the end of the logic. + + .. container:: listingblock + + .. container:: title + + JS Success + + .. container:: content + + .. code:: javascript + + var returnValueType = Java.type("java.lang.Boolean"); + var returnValue = new returnValueType(true); + + .. container:: paragraph + + To notify a problem, finish with an error. + + .. container:: listingblock + + .. container:: title + + JS Fail + + .. container:: content + + .. code:: javascript + + var returnValueType = Java.type("java.lang.Boolean"); + var returnValue = new returnValueType(false); + +Logic Logging +############# + + .. container:: paragraph + + Logging can be made easy using a local variable for the logger. + Line 1 below does that. Then we start with a trace log with the + task (or task logic) identifier followed by the infields. + + .. container:: listingblock + + .. container:: title + + JS Logging + + .. container:: content + + .. code:: javascript + + var logger = executor.logger; + logger.trace("start: " + executor.subject.id); + logger.trace("-- infields: " + executor.inFields); + + .. container:: paragraph + + For larger logging blocks you can use the standard logging API + to detect log levels, for instance: + + .. container:: listingblock + + .. container:: title + + JS Logging Blocks + + .. container:: content + + .. code:: javascript + + if(logger.isTraceEnabled()){ + // trace logging block here + } + + .. container:: paragraph + + Note: the shown logger here logs to + ``org.onap.policy.apex.executionlogging``. The behavior of the + actual logging can be specified in the + ``$APEX_HOME/etc/logback.xml``. + + .. container:: paragraph + + If you want to log into the APEX root logger (which is + sometimes necessary to report serious logic errors to the top), + then import the required class and use this logger. + + .. container:: listingblock + + .. container:: title + + JS Root Logger + + .. container:: content + + .. code:: javascript + + importClass(org.slf4j.LoggerFactory); + var rootLogger = LoggerFactory.getLogger(logger.ROOT_LOGGER_NAME); + + rootLogger.error("Serious error in logic detected: " + executor.subject.id); + +Local Variable for Infields +########################### + + .. container:: paragraph + + It is a good idea to use local variables for ``infields``. This + avoids long code lines and policy evolution. The following + example assumes infields named ``nodeName`` and ``nodeAlias``. + + .. container:: listingblock + + .. container:: title + + JS Infields Local Var + + .. container:: content + + .. code:: javascript + + var ifNodeName = executor.inFields["nodeName"]; + var ifNodeAlias = executor.inFields["nodeAlias"]; + +Local Variable for Context Albums +################################# + + .. container:: paragraph + + Similar to the ``infields`` it is good practice to use local + variables for context albums as well. The following example + assumes that a task can access a context album + ``albumTopoNodes``. The second line gets a particular node from + this context album. + + .. container:: listingblock + + .. container:: title + + JS Infields Local Var + + .. container:: content + + .. code:: javascript + + var albumTopoNodes = executor.getContextAlbum("albumTopoNodes"); + var ctxtNode = albumTopoNodes.get(ifNodeName); + +Set Outfields in Logic +###################### + + .. container:: paragraph + + The task logic needs to set outfields with content generated. + The exception are outfields that are a direct copy from an + infield of the same name, APEX does that autmatically. + + .. container:: listingblock + + .. container:: title + + JS Set Outfields + + .. container:: content + + .. code:: javascript + + executor.outFields["report"] = "node ctxt :: added node " + ifNodeName; + +Create a instance of an Outfield using Schemas +############################################## + + .. container:: paragraph + + If an outfield is not an atomic type (string, integer, etc.) + but uses a complex schema (with a Java or Avro backend), APEX + can help to create new instances. The ``executor`` provides a + field called ``subject``, which provides a schem helper with an + API for this. The complete API of the schema helper is + documented here: `API Doc: + SchemaHelper <https://ericsson.github.io/apex-docs/javadocs/index.html>`__. + + .. container:: paragraph + + If the backend is Avro, then an import of the Avro schema + library is required: + + .. container:: listingblock + + .. container:: title + + JS Import Avro + + .. container:: content + + .. code:: javascript + + importClass(org.apache.avro.generic.GenericData.Array); + importClass(org.apache.avro.generic.GenericRecord); + importClass(org.apache.avro.Schema); + + .. container:: paragraph + + If the backend is Java, then the Java class implementing the + schema needs to be imported. + + .. container:: paragraph + + The following example assumes an outfield ``situation``. The + ``subject`` method ``getOutFieldSchemaHelper()`` is used to + create a new instance. + + .. container:: listingblock + + .. container:: title + + JS Outfield Instance with Schema + + .. container:: content + + .. code:: javascript + + var situation = executor.subject.getOutFieldSchemaHelper("situation").createNewInstance(); + + .. container:: paragraph + + If the schema backend is Java, the new instance will be as + implemented in the Java class. If the schema backend is Avro, + the new instance will have all fields from the Avro schema + specification, but set to ``null``. So any entry here needs to + be done separately. For instance, the ``situation`` schema has + a field ``problemID`` which we set. + + .. container:: listingblock + + .. container:: title + + JS Outfield Instance with Schema, set + + .. container:: content + + .. code:: javascript + + situation.put("problemID", "my-problem"); + +Create a instance of an Context Album entry using Schemas +######################################################### + + .. container:: paragraph + + Context album instances can be created using very similar to + the outfields. Here, the schema helper comes from the context + album directly. The API of the schema helper is the same as for + outfields, see `API Doc: + SchemaHelper <https://ericsson.github.io/apex-docs/javadocs/index.html>`__. + + .. container:: paragraph + + If the backend is Avro, then an import of the Avro schema + library is required: + + .. container:: listingblock + + .. container:: title + + JS Import Avro + + .. container:: content + + .. code:: javascript + + importClass(org.apache.avro.generic.GenericData.Array); + importClass(org.apache.avro.generic.GenericRecord); + importClass(org.apache.avro.Schema); + + .. container:: paragraph + + If the backend is Java, then the Java class implementing the + schema needs to be imported. + + .. container:: paragraph + + The following example creates a new instance of a context album + instance named ``albumProblemMap``. + + .. container:: listingblock + + .. container:: title + + JS Outfield Instance with Schema + + .. container:: content + + .. code:: javascript + + var albumProblemMap = executor.getContextAlbum("albumProblemMap"); + var linkProblem = albumProblemMap.getSchemaHelper().createNewInstance(); + + .. container:: paragraph + + This can of course be also done in a single call without the + local variable for the context album. + + .. container:: listingblock + + .. container:: title + + JS Outfield Instance with Schema, one line + + .. container:: content + + .. code:: javascript + + var linkProblem = executor.getContextAlbum("albumProblemMap").getSchemaHelper().createNewInstance(); + + .. container:: paragraph + + If the schema backend is Java, the new instance will be as + implemented in the Java class. If the schema backend is Avro, + the new instance will have all fields from the Avro schema + specification, but set to ``null``. So any entry here needs to + be done separately (see above in outfields for an example). + +Enumerates +########## + + .. container:: paragraph + + When dealing with enumerates (Avro or Java defined), it is + sometimes and in some execution environments necessary to + convert them to a string. For example, assume an Avro enumerate + schema as: + + .. container:: listingblock + + .. container:: title + + Avro Enumerate Schema + + .. container:: content + + .. code:: javascript + + { + "type": "enum", + "name": "Status", + "symbols" : [ + "UP", + "DOWN" + ] + } + + .. container:: paragraph + + Using a switch over a field initialized with this enumerate in + Javascript will fail. Instead, use the ``toString`` method, for + example: + + .. container:: listingblock + + .. container:: title + + JS Outfield Instance with Schema, one line + + .. container:: content + + .. code:: javascript + + var switchTest = executor.inFields["status"]; + switch(switchTest.toString()){ + case "UP": ...; break; + case "DOWN": ...; break; + default: ...; + } + +MVEL Initialize Outfields First! +################################ + + .. container:: paragraph + + In MVEL, we observed a problem when accessing (setting) + outfields without a prior access to them. So in any MVEL task + logic, before setting any outfield, simply do a get (with any + string), to load the outfields into the MVEL cache. + + .. container:: listingblock + + .. container:: title + + MVEL Outfield Initialization + + .. container:: content + + .. code:: javascript + + outFields.get("initialize outfields"); + +Using Java in Scripting Logic +############################# + + .. container:: paragraph + + Since APEX executes the logic inside a JVM, most scripting + languages provide access to all standard Java classes. Simply + add an import for the required class and then use it as in + actual Java. + + .. container:: paragraph + + The following example imports ``java.util.arraylist`` into a + Javascript logic, and then creates a new list. + + .. container:: listingblock + + .. container:: title + + JS Import ArrayList + + .. container:: content + + .. code:: javascript + + importClass(java.util.ArrayList); + var myList = new ArrayList(); + +Policy Examples +^^^^^^^^^^^^^^^ + +My First Policy +--------------- + + .. container:: paragraph + + A good starting point is the ``My First Policy`` example. It + describes a sales problem, to which policy can be applied. + The example details the policy background, shows how to use + the REST Editor to create a policy, and provides details for + running the policies. The documentation can be found: + + .. container:: ulist + + - `My-First-Policy on the APEX + site <https://ericsson.github.io/apex-docs/modules/examples/examples-myfirstpolicy/MyFirstPolicyHowto.html>`__ + + - `Stand-alone + HTML <https://ericsson.github.io/apex-docs/docs-apex/html/HowTo-MyFirstPolicy.html>`__ + + - `Stand-alone + PDF <https://ericsson.github.io/apex-docs/docs-apex/pdf/HowTo-MyFirstPolicy.pdf>`__ + +VPN SLA +------- + + .. container:: paragraph + + The domain Policy-controlled Video Streaming (PCVS) contains + a policy for controlling video streams with different + strategies. It also provides details for installing an + actual testbed with off-the-shelve software (Mininet, + Floodlight, Kafka, Zookeeper). The policy model here + demonstrates virtually all APEX features: local context and + policies controlling it, task selection logic and multiple + tasks in a single state, AVRO schemas for context, AVOR + schemas for events (trigger and local), and a CLI editor + specification of the policy. The documentation can be found: + + .. container:: ulist + + - `VPN SLA Policy on the APEX + site <https://ericsson.github.io/apex-docs/modules/examples/examples-pcvs/vpnsla/policy.html>`__ + +Decision Maker +-------------- + + .. container:: paragraph + + The domain Decision Maker shows a very simple policy for + decisions. Interesting here is that the it creates a Docker + image to run the policy and that it uses the APEX REST + applications to update the policy on the-fly. It also has + local context to remember past decisions, and shows how to + use that to no make the same decision twice in a row. The + documentation can be found: + + .. container:: ulist + + - `Decision Maker on APEX + site <https://ericsson.github.io/apex-docs/modules/examples/examples-decisionmaker/index.html>`__ + +.. container:: + :name: footer + + .. container:: + :name: footer-text + + 2.0.0-SNAPSHOT + Last updated 2018-09-04 16:04:24 IST + +.. |APEX Policy Matrix| image:: images/apex-intro/ApexPolicyMatrix.png +.. |APEX Policy Model for Execution| image:: images/apex-policy-model/UmlPolicyModels.png +.. |Concepts and Keys| image:: images/apex-policy-model/ConceptsKeys.png + |