APEX Policy Guide

Contents

• APEX Policy Guide

  • APEX Policy Matrix

  • APEX Policy Model

    • Concepts and Keys

    • Concept: PolicyModel

    • Concept: DataType

    • Concept: Event

    • Concept: EventField

    • Concept: ContextMap

    • Concept: ContextItem

    • Concept: ContextItemTemplate

    • Concept: Task

    • Concept: TaskParameter

    • Concept: Logic

    • Concept: Policy

    • Concept: State

  • Writing Logic

    • Writing APEX Task Logic

    • Writing APEX Task Selection Logic

    • Logic Cheat Sheet

      • Finish Logic with Success or Error

      • Logic Logging

      • Accessing TaskParameters

      • Local Variable for Infields

      • Local Variable for Context Albums

      • Set Outfields in Logic

      • Create a instance of an Outfield using Schemas

      • Create a instance of an Context Album entry using Schemas

      • Enumerates

      • MVEL Initialize Outfields First!

      • Using Java in Scripting Logic

      • Converting Javascript scripts from Nashorn to Rhino dialects

        • Return Values

        • return statement

        • Compatibility Script

        • Import of Java classes

        • Using Java Classes and Objects as Variables

        • Equal Value and Equal Type operator ===

APEX Policy Matrix

APEX offers a lot of flexibility for defining, deploying, and executing policies. Based on a theoretic model, it supports virtually any policy model and supports translation of 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.

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.

Figure 1. APEX Policy Matrix

The policy can support one of a number of stimuli with an associated purpose/model of the policy, for instance:

• 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.

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:

• 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)

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:

• 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.

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:

• 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

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.

The figure shows four different views of the policy model:

• 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.

Figure 2. APEX Policy Model for Execution

Concepts and Keys

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:

Figure 3. Concepts and Keys

• 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.

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.

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.

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.

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.

Each concept in the model is also a JPA (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 or EclipseLink.

Concept: PolicyModel

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.

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

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

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:

• 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

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

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

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.

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.

The ContextMapType field of a ContextMap defines the type of a context map. The type can have either of two values:

• 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.

The Scope of a ContextMap defines the range of applicability of a context map in APEX. The following scopes of applicability are defined:

• 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

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

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

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

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.

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.

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.

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.

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

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.

The taskParameters field is specified under engineParameters in the ApexConfig. It can contain one or more task parameters, where each item can contain the parameter key, value as well as the taskId to which it is associated. If the taskId is not specified, then the parameters are added to all tasks.

Concept: Logic

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.

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, JAVA, JYTHON, JRUBY, or MVEL.

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

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.

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:

• The MEDA flavor supports policies written to the MEDA policy pattern and require a sequence of four states: namely Match, Establish, Decide and Act.

• The OODA flavor supports policies written to the OODA loop pattern 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 and require a sequence of three states: namely Event, Condition and Action

• The XACML flavor supports policies written in 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.

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

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.

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.

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.

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.

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.

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

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:

• `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>`__.

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

/*
 * ============LICENSE_START=======================================================
 *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
 *  Modifications Copyright (C) 2020 Nordix Foundation.
 * ================================================================================
 * 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=========================================================
 */

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 :-)
*/

true;

MVEL code for the MorningBoozeCheck task

/*
 * ============LICENSE_START=======================================================
 *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
 *  Modifications Copyright (C) 2020 Nordix Foundation.
 * ================================================================================
 * 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 :-)
*/

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. 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).

For Javascript, the last statement of a script must be a statement that evaluates to true or false, indicating whether the script executed correctly or not. In the case where the script always executes to compeletion sucessfully, simply add a last line with the statement true’. In cases where success or failure is assessed in the script, create a boolean local variable with a name such as returnvalue. In the execution of the script, set returnValue to be true or false as appropriate. The last line of the scritp tehn should simply be returnValue;, which returns the value of returnValue.

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>	The incoming task fields, implemented as a standard Java (unmodifiable) Map Example: 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 Example: executor.outFields["authorised"] = false;
logger	Logger	org.slf4j.ext.XLogger	A helpful logger Example: executor.logger.info("Executing task: " +executor.subject.id);
TRUE/FALSE	boolean	java.lang.Boolean	2 helpful constants. These are useful to retrieve correct return values for the task logic Example: var returnValue = executor.isTrue; 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 : 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 Example: 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 )	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. Example: 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

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:

• `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>`__.

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.

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:

Javascript code for the “My First Policy” Task Selection Logic

/*
 * ============LICENSE_START=======================================================
 *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
 *  Modifications Copyright (C) 2020 Nordix Foundation.
 * ================================================================================
 * 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=========================================================
 */

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"
*/

true;

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).

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).

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
>c: >cd \dev\apex >mvn clean install -DskipTests	# cd /usr/local/src/apex-pdp # mvn clean install -DskipTests

Name	Type	Java type	Description
inFields	Fields	java.util.Map <String,Object>	All fields in the state’s incoming event. This is implemented as a standard Java Java (unmodifiable) Map Example: 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 Example: executor.outFields["authorised"] = false;
logger	Logger	org.slf4j.ext.XLogger	A helpful logger Example: executor.logger.info("Executing task: " +executor.subject.id);
TRUE/FALSE	boolean	java.lang.Boolean	2 helpful constants. These are useful to retrieve correct return values for the task logic Example: var returnValue = executor.isTrue; 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 : 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 Example: 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");
parameters	Fields	java.util.Map <String,String>	All parameters in the current task. This is implemented as a standard Java Map. Example: executor.parameters.get("ParameterKey1"))
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. Example: 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 Cheat Sheet

Examples given here use Javascript (if not stated otherwise), other execution environments will be similar.

Finish Logic with Success or Error

To finish logic, i.e. return to APEX, with success use the following line close to the end of the logic.

JS Success

true;

To notify a problem, finish with an error.

JS Fail

false;

Logic Logging

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.

JS Logging

var logger = executor.logger;
logger.trace("start: " + executor.subject.id);
logger.trace("-- infields: " + executor.inFields);

For larger logging blocks you can use the standard logging API to detect log levels, for instance:

JS Logging Blocks

if(logger.isTraceEnabled()){
  // trace logging block here
}

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.

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.

JS Root Logger

var rootLogger = LoggerFactory.getLogger(logger.ROOT_LOGGER_NAME);
rootLogger.error("Serious error in logic detected: " + executor.subject.id);

Accessing TaskParameters

TaskParameters available in a Task can be accessed in the logic. The parameters in each task are made available at the executor level. This example assumes a parameter with key ParameterKey1.

JS TaskParameter value

executor.parameters.get("ParameterKey1"))

Alternatively, the task parameters can also be accessed from the task object.

JS TaskParameter value using task object

executor.subject.task.getTaskParameters.get("ParameterKey1").getTaskParameterValue()

Local Variable for Infields

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.

JS Infields Local Var

var ifNodeName = executor.inFields["nodeName"];
var ifNodeAlias = executor.inFields["nodeAlias"];

Local Variable for Context Albums

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.

JS Infields Local Var

var albumTopoNodes = executor.getContextAlbum("albumTopoNodes");
var ctxtNode = albumTopoNodes.get(ifNodeName);

Set Outfields in Logic

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.

JS Set Outfields

executor.outFields["report"] = "node ctxt :: added node " + ifNodeName;

Create a instance of an Outfield using Schemas

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.

If the backend is Java, then the Java class implementing the schema needs to be imported.

The following example assumes an outfield situation. The subject method getOutFieldSchemaHelper() is used to create a new instance.

JS Outfield Instance with Schema

var situation = executor.subject.getOutFieldSchemaHelper("situation").createNewInstance();

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.

JS Outfield Instance with Schema, set

situation.put("problemID", "my-problem");

Create a instance of an Context Album entry using Schemas

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.

If the backend is Java, then the Java class implementing the schema needs to be imported.

The following example creates a new instance of a context album instance named albumProblemMap.

JS Outfield Instance with Schema

var albumProblemMap = executor.getContextAlbum("albumProblemMap");
var linkProblem = albumProblemMap.getSchemaHelper().createNewInstance();

This can of course be also done in a single call without the local variable for the context album.

JS Outfield Instance with Schema, one line

var linkProblem = executor.getContextAlbum("albumProblemMap").getSchemaHelper().createNewInstance();

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

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:

Avro Enumerate Schema

{
  "type": "enum", "name": "Status", "symbols" : [
    "UP", "DOWN"
  ]
}

Using a switch over a field initialized with this enumerate in Javascript will fail. Instead, use the toString method, for example:

JS Outfield Instance with Schema, one line

var switchTest = executor.inFields["status"]; switch(switchTest.toString()){
  case "UP": ...; break; case "DOWN": ...; break; default: ...;
}

MVEL Initialize Outfields First!

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.

MVEL Outfield Initialization

outFields.get("initialize outfields");

Using Java in Scripting Logic

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.

The following example imports java.util.arraylist into a Javascript logic, and then creates a new list.

JS Import ArrayList

var myList = new ArrayList();

Converting Javascript scripts from Nashorn to Rhino dialects

The Nashorn Javascript engine was removed from Java in the Java 11 release. Java 11 was introduced into the Policy Framework in the Frankfurt release, so from Frankfurt on, APEX Javascript scripts use the Rhino Javascript engine and scripts must be in the Rhino dialect.

There are some minor but important differences between the dialects that users should be aware of so that they can convert their scripts into the Rhino dialect.

Return Values

APEX scripts must always return a value of true indicating that the script executed correctly or false indicating that there was an error in script execution.

Pre Frankfurt

In Nashorn dialect scripts, the user had to create a special variable called returnValue and set the value of that variable to be the return value for the script.

Frankfurt and Later

In Rhino dialect scripts, the return value of the script is the logical result of the last statement. Therefore the last line of the script must evaluate to either true or false.

JS Rhino script last executed line examples

true;

returnValue; // Where returnValue is assigned earlier in the script

someValue == 1; // Where the value of someValue is assigned earlier in the script

return statement

The return statement is not supported from the main script called in the Rhino interpreter.

Pre Frankfurt

In Nashorn dialect scripts, the user could return a value of true or false at any point in their script.

JS Nashorn main script returning true and false

var n;

// some code assigns n a value

if (n < 2) {
  return false;
} else {
  return true;
}

Frankfurt and Later

In Rhino dialect scripts, the return statement cannot be used in the main method, but it can still be used in functions. If you want to have a return statement in your code prior to the last statement, encapsulate your code in a function.

JS Rhino script with return statements in a function

someFunction();

function someFunction() {
  var n;

  // some code assigns n a value

  if (n < 2) {
      return false;
  } else {
      return true;
  }
}

Compatibility Script

For Nashorn, the user had to call a compatibility script at the beginning of their Javascript script. This is not required in Rhino.

Pre Frankfurt

In Nashorn dialect scripts, the compatibility script must be loaded.

Nashorn compatability script loading

load("nashorn:mozilla_compat.js");

Frankfurt and Later

Not required.

Import of Java classes

For Nashorn, the user had explicitly import all the Java packages and classes they wished to use in their Javascript script. In Rhino, all Java classes on the classpath are available for use.

Pre Frankfurt

In Nashorn dialect scripts, Java classes must be imported.

Importation of Java packages and classes

importPackage(java.text);
importClass(java.text.SimpleDateFormat);

Frankfurt and Later

Not required.

Using Java Classes and Objects as Variables

Setting a Javascript variable to hold a Java class or a Java object is more straightforward in Rhino than it is in Nashorn. The examples below show how to instantiate a Javascript variable as a Java class and how to use that variable to create an instance of the Java class in another Javascript variable in both dialects.

Pre Frankfurt

Create Javascript variables to hold a Java class and instance

var webClientClass = Java.type("org.onap.policy.apex.examples.bbs.WebClient");
var webClientObject = new webClientClass();

Frankfurt and Later

Create Javascript variables to hold a Java class and instance

var webClientClass = org.onap.policy.apex.examples.bbs.WebClient;
var webClientObject = new webClientClass();

Equal Value and Equal Type operator ===

The Equal Value and Equal Type operator === is not supported in Rhino. Developers must use the Equal To operator == instead. To check types, they may need to explicitly find and check the type of the variables they are using.