summaryrefslogtreecommitdiffstats
path: root/docs/APEX-User-Manual.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/APEX-User-Manual.rst')
-rw-r--r--docs/APEX-User-Manual.rst8071
1 files changed, 0 insertions, 8071 deletions
diff --git a/docs/APEX-User-Manual.rst b/docs/APEX-User-Manual.rst
deleted file mode 100644
index 01f74fabe..000000000
--- a/docs/APEX-User-Manual.rst
+++ /dev/null
@@ -1,8071 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-
-APEX User Manual
-****************
-
-.. contents::
- :depth: 3
-
-Installation
-^^^^^^^^^^^^
-
-Requirements
-------------
-
- .. container:: paragraph
-
- APEX is 100% written in Java and runs on any platform
- that supports a JVM, e.g. Windows, Unix, Cygwin. Some
- APEX applications (such as the monitoring application)
- come as web archives, they do require a war-capable web
- server installed.
-
-Installation Requirements
-#########################
-
- .. container:: ulist
-
- - Downloaded distribution: JAVA runtime environment
- (JRE, Java 8 or later, APEX is tested with the
- Oracle Java)
-
- - Building from source: JAVA development kit (JDK,
- Java 8 or later, APEX is tested with the Oracle
- Java)
-
- - A web archive capable webserver, for instance for
- the monitoring application
-
- .. container:: ulist
-
- - for instance `Apache
- Tomcat <https://tomcat.apache.org/>`__
-
- - Sufficient rights to install APEX on the system
-
- - Installation tools depending on the installation
- method used:
-
- .. container:: ulist
-
- - ZIP to extract from a ZIP distribution
-
- .. container:: ulist
-
- - Windows for instance
- `7Zip <http://www.7-zip.org/>`__
-
- - TAR and GZ to extract from that TAR.GZ
- distribution
-
- .. container:: ulist
-
- - Windows for instance
- `7Zip <http://www.7-zip.org/>`__
-
- - RPM to install from the RPM distribution
-
- .. container:: ulist
-
- - Install: ``sudo apt-get install rpm``
-
- - DPKG to install from the DEB distribution
-
- .. container:: ulist
-
- - Install: ``sudo apt-get install dpkg``
-
-Feature Requirements
-####################
-
- .. container:: paragraph
-
- APEX supports a number of features that require extra
- software being installed.
-
- .. container:: ulist
-
- - `Apache Kafka <https://kafka.apache.org/>`__ to
- connect APEX to a Kafka message bus
-
- - `Hazelcast <https://hazelcast.com/>`__ to use
- distributed hash maps for context
-
- - `Infinispan <http://infinispan.org/>`__ for
- distributed context and persistence
-
- - `Docker <https://www.docker.com/>`__ to run APEX
- inside a Docker container
-
-Build (Install from Source) Requirements
-########################################
-
- .. container:: paragraph
-
- Installation from source requires a few development
- tools
-
- .. container:: ulist
-
- - GIT to retrieve the source code
-
- - Java SDK, Java version 8 or later
-
- - Apache Maven 3 (the APEX build environment)
-
-Get the APEX Source Code
-------------------------
-
- .. container:: paragraph
-
- The first APEX source code was hosted on Github in
- January 2018. By the end of 2018, APEX was added as a
- project in the ONAP Policy Framework, released later in
- the ONAP Casablanca release.
-
- .. container:: paragraph
-
- The APEX source code is hosted in ONAP as project APEX.
- The current stable version is in the master branch.
- Simply clone the master branch from ONAP using HTTPS.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- git clone https://gerrit.onap.org/r/policy/apex-pdp
-
-Build APEX
-----------
-
- .. container:: paragraph
-
- The examples in this document assume that the APEX source
- repositories are cloned to:
-
- .. container:: ulist
-
- - Unix, Cygwin: ``/usr/local/src/apex-pdp``
-
- - Windows: ``C:\dev\apex-pdp``
-
- - Cygwin: ``/cygdrive/c/dev/apex-pdp``
-
- .. important::
- A Build requires ONAP Nexus
- APEX has a dependency to ONAP parent projects. You might need to adjust your Maven M2 settings. The most current
- settings can be found in the ONAP oparent repo: `Settings <https://git.onap.org/oparent/plain/settings.xml>`__.
-
- .. important::
- A Build needs Space
- Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full
- distribution and 1-2 GB for the downloaded dependencies
-
- .. important::
- A Build requires Internet (for first build)
- During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven
- repository. The first standard build (and any first specific build) requires Internet access to download those
- dependencies.
-
- .. important::
- Building RPM distributions
- RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``,
- then build APEX.
-
- .. container:: paragraph
-
- Use Maven to for a standard build without any tests.
-
- +-------------------------------------------------------+--------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +=======================================================+========================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | :number-lines: | :number-lines: |
- | | |
- | # cd /usr/local/src/apex-pdp | >c: |
- | # mvn clean install -DskipTest | >cd \dev\apex |
- | | >mvn clean install -DskipTests |
- +-------------------------------------------------------+--------------------------------------------------------+
-
-.. container:: paragraph
-
- The build takes 2-3 minutes on a standard development laptop. It
- should run through without errors, but with a lot of messages from
- the build process.
-
-.. container:: paragraph
-
- When Maven is finished with the build, the final screen should look
- similar to this (omitting some ``success`` lines):
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- [INFO] tools .............................................. SUCCESS [ 0.248 s]
- [INFO] tools-common ....................................... SUCCESS [ 0.784 s]
- [INFO] simple-wsclient .................................... SUCCESS [ 3.303 s]
- [INFO] model-generator .................................... SUCCESS [ 0.644 s]
- [INFO] packages ........................................... SUCCESS [ 0.336 s]
- [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
- [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
- [INFO] ------------------------------------------------------------------------
- [INFO] BUILD SUCCESS
- [INFO] ------------------------------------------------------------------------
- [INFO] Total time: 03:43 min
- [INFO] Finished at: 2018-09-03T11:56:01+01:00
- [INFO] ------------------------------------------------------------------------
-
-.. container:: paragraph
-
- The build will have created all artifacts required for an APEX
- installation. The following example show how to change to the target
- directory and how it should look like.
-
-+----------------------------------------------------------------------------------------------------------------------------+
-| Unix, Cygwin |
-+============================================================================================================================+
-| .. container:: |
-| |
-| .. container:: listingblock |
-| |
-| .. container:: content |
-| |
-| .. code:: |
-| :number-lines: |
-| |
-| -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* |
-| -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* |
-| -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* |
-| -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ |
-| -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* |
-| -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* |
-| -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* |
-| -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ |
-+----------------------------------------------------------------------------------------------------------------------------+
-
-+--------------------------------------------------------------------------------------------------------+
-| Windows |
-+========================================================================================================+
-| .. container:: |
-| |
-| .. container:: listingblock |
-| |
-| .. container:: content |
-| |
-| .. code:: |
-| :number-lines: |
-| |
-| 03/09/2018 11:55 <DIR> . |
-| 03/09/2018 11:55 <DIR> .. |
-| 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz |
-| 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb |
-| 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar |
-| 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes |
-| 03/09/2018 11:54 <DIR> archive-tmp |
-| 03/09/2018 11:54 89 checkstyle-cachefile |
-| 03/09/2018 11:54 10,621 checkstyle-checker.xml |
-| 03/09/2018 11:54 584 checkstyle-header.txt |
-| 03/09/2018 11:54 86 checkstyle-result.xml |
-| 03/09/2018 11:54 <DIR> classes |
-| 03/09/2018 11:54 <DIR> dependency-maven-plugin-markers |
-| 03/09/2018 11:54 <DIR> etc |
-| 03/09/2018 11:54 <DIR> examples |
-| 03/09/2018 11:55 <DIR> install_hierarchy |
-| 03/09/2018 11:54 <DIR> maven-archiver |
-| 8 File(s) 292,652,686 bytes |
-| 9 Dir(s) 14,138,720,256 bytes free |
-+--------------------------------------------------------------------------------------------------------+
-
-Install APEX
-------------
-
- .. container:: paragraph
-
- APEX can be installed in different ways:
-
- .. container:: ulist
-
- - Unix: automatically using ``rpm`` or ``dpkg`` from ``.rpm`` or
- ``.deb`` archive
-
- - Windows, Unix, Cygwin: manually from a ``.tar.gz`` archive
-
- - Windows, Unix, Cygwin: build from source using Maven, then
- install manually
-
-Install with RPM and DPKG
-#########################
-
- .. container:: paragraph
-
- The install distributions of APEX automatically install the
- system. The installation directory is
- ``/opt/app/policy/apex-pdp``. Log files are located in
- ``/var/log/onap/policy/apex-pdp``. The latest APEX version will
- be available as ``/opt/app/policy/apex-pdp/apex-pdp``.
-
- .. container:: paragraph
-
- For the installation, a new user ``apexuser`` and a new group
- ``apexuser`` will be created. This user owns the installation
- directories and the log file location. The user is also used by
- the standard APEX start scripts to run APEX with this user’s
- permissions.
-
- +-----------------------------------------------------------------------+
- | RPM Installation |
- +=======================================================================+
- | .. container:: |
- | |
- | .. container:: listingblock |
- | |
- | .. container:: content |
- | |
- | .. code:: |
- | :number-lines: |
- | |
- | # sudo rpm -i apex-pdp-package-full-2.0.0-SNAPSHOT.rpm |
- | ********************preinst******************* |
- | arguments 1 |
- | ********************************************** |
- | creating group apexuser . . . |
- | creating user apexuser . . . |
- | ********************postinst**************** |
- | arguments 1 |
- | *********************************************** |
- +-----------------------------------------------------------------------+
-
-+--------------------------------------------------------------------------------------+
-| DPKG Installation |
-+======================================================================================+
-| .. container:: |
-| |
-| .. container:: listingblock |
-| |
-| .. container:: content |
-| |
-| .. code:: |
-| :number-lines: |
-| |
-| # sudo dpkg -i apex-pdp-package-full-2.0.0-SNAPSHOT.deb |
-| Selecting previously unselected package apex-uservice. |
-| (Reading database ... 288458 files and directories currently installed.) |
-| Preparing to unpack apex-pdp-package-full-2.0.0-SNAPSHOT.deb ... |
-| ********************preinst******************* |
-| arguments install |
-| ********************************************** |
-| creating group apexuser . . . |
-| creating user apexuser . . . |
-| Unpacking apex-uservice (2.0.0-SNAPSHOT) ... |
-| Setting up apex-uservice (2.0.0-SNAPSHOT) ... |
-| ********************postinst**************** |
-| arguments configure |
-| *********************************************** |
-+--------------------------------------------------------------------------------------+
-
-.. container:: paragraph
-
- Once the installation is finished, APEX is fully installed and ready
- to run.
-
-Install Manually from Archive (Unix, Cygwin)
-############################################
-
- .. container:: paragraph
-
- Download a ``tar.gz`` archive. Create a directory where APEX
- should be installed. Extract the ``tar`` archive. The following
- example shows how to install APEX in ``/opt/apex`` and create a
- link to ``/opt/apex/apex`` for the most recent installation.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- # cd /opt
- # mkdir apex
- # cd apex
- # mkdir apex-full-2.0.0-SNAPSHOT
- # tar xvfz ~/Downloads/apex-pdp-package-full-2.0.0-SNAPSHOT.tar.gz -C apex-full-2.0.0-SNAPSHOT
- # ln -s apex apex-pdp-package-full-2.0.0-SNAPSHOT
-
-Install Manually from Archive (Windows, 7Zip, GUI)
-##################################################
-
- .. container:: paragraph
-
- Download a ``tar.gz`` archive and copy the file into the install
- folder (in this example ``C:\apex``). Assuming you are using 7Zip,
- right click on the file and extract the ``tar`` archive. Note: the
- screenshots might show an older version than you have.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Extract the TAR archive|
-
- .. container:: paragraph
-
- The right-click on the new created TAR file and extract the actual
- APEX distribution.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Extract the APEX distribution|
-
- .. container:: paragraph
-
- Inside the new APEX folder you see the main directories: ``bin``,
- ``etc``, ``examples``, ``lib``, and ``war``
-
- .. container:: paragraph
-
- Once extracted, please rename the created folder to
- ``apex-full-2.0.0-SNAPSHOT``. This will keep the directory name in
- line with the rest of this documentation.
-
-Install Manually from Archive (Windows, 7Zip, CMD)
-##################################################
-
- .. container:: paragraph
-
- Download a ``tar.gz`` archive and copy the file into the install
- folder (in this example ``C:\apex``). Start ``cmd``, for instance
- typing ``Windows+R`` and then ``cmd`` in the dialog. Assuming
- ``7Zip`` is installed in the standard folder, simply run the
- following commands (for APEX version 2.0.0-SNAPSHOT full
- distribution)
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- >c:
- >cd \apex
- >"\Program Files\7-Zip\7z.exe" x apex-pdp-package-full-2.0.0-SNAPSHOT.tar.gz -so | "\Program Files\7-Zip\7z.exe" x -aoa -si -ttar -o"apex-full-2.0.0-SNAPSHOT"
-
-.. container:: paragraph
-
- APEX is now installed in the folder
- ``C:\apex\apex-full-2.0.0-SNAPSHOT``.
-
-Build from Source
------------------
-
-Build and Install Manually (Unix, Windows, Cygwin)
-##################################################
-
- .. container:: paragraph
-
- Clone the APEX GIT repositories into a directory. Go to that
- directory. Use Maven to build APEX (all details on building
- APEX from source can be found in *APEX HowTo: Build*). Install
- from the created artifacts (``rpm``, ``deb``, ``tar.gz``, or
- copying manually).
-
- .. important::
- Building RPM distributions
- RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` run
- ``sudo apt-get install rpm``, then build APEX.
-
- .. container:: paragraph
-
- The following example shows how to build the APEX system,
- without tests (``-DskipTests``) to safe some time. It assumes
- that the APX GIT repositories are cloned to:
-
- .. container:: ulist
-
- - Unix, Cygwin: ``/usr/local/src/apex``
-
- - Windows: ``C:\dev\apex``
-
- +-------------------------------------------------------+--------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +=======================================================+========================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | :number-lines: | :number-lines: |
- | | |
- | # cd /usr/local/src/apex | >c: |
- | # mvn clean install -DskipTests | >cd \dev\apex |
- | | >mvn clean install -DskipTests |
- +-------------------------------------------------------+--------------------------------------------------------+
-
-.. container:: paragraph
-
- The build takes about 2 minutes without test and about 4-5 minutes
- with tests on a standard development laptop. It should run through
- without errors, but with a lot of messages from the build process. If
- build with tests (i.e. without ``-DskipTests``), there will be error
- messages and stack trace prints from some tests. This is normal, as
- long as the build finishes successful.
-
-.. container:: paragraph
-
- When Maven is finished with the build, the final screen should look
- similar to this (omitting some ``success`` lines):
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- [INFO] tools .............................................. SUCCESS [ 0.248 s]
- [INFO] tools-common ....................................... SUCCESS [ 0.784 s]
- [INFO] simple-wsclient .................................... SUCCESS [ 3.303 s]
- [INFO] model-generator .................................... SUCCESS [ 0.644 s]
- [INFO] packages ........................................... SUCCESS [ 0.336 s]
- [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
- [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
- [INFO] ------------------------------------------------------------------------
- [INFO] BUILD SUCCESS
- [INFO] ------------------------------------------------------------------------
- [INFO] Total time: 03:43 min
- [INFO] Finished at: 2018-09-03T11:56:01+01:00
- [INFO] ------------------------------------------------------------------------
-
-.. container:: paragraph
-
- The build will have created all artifacts required for an APEX
- installation. The following example show how to change to the target
- directory and how it should look like.
-
-+-----------------------------------------------------------------------------------------------------------------------------+
-| Unix, Cygwin |
-+=============================================================================================================================+
-| .. container:: |
-| |
-| .. container:: listingblock |
-| |
-| .. code:: |
-| :number-lines: |
-| |
-| # cd packages/apex-pdp-package-full/target |
-| # ls -l |
-| -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* |
-| -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* |
-| -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* |
-| -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ |
-| -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* |
-| -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* |
-| -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* |
-| -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ |
-| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ |
-+-----------------------------------------------------------------------------------------------------------------------------+
-
-+-----------------------------------------------------------------------------------------------------------------------------+
-| Windows |
-+=============================================================================================================================+
-| .. container:: |
-| |
-| .. container:: listingblock |
-| |
-| .. code:: |
-| :number-lines: |
-| |
-| >cd packages\apex-pdp-package-full\target |
-| >dir |
-| 03/09/2018 11:55 <DIR> . |
-| 03/09/2018 11:55 <DIR> .. |
-| 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz |
-| 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb |
-| 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar |
-| 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes |
-| 03/09/2018 11:54 <DIR> archive-tmp |
-| 03/09/2018 11:54 89 checkstyle-cachefile |
-| 03/09/2018 11:54 10,621 checkstyle-checker.xml |
-| 03/09/2018 11:54 584 checkstyle-header.txt |
-| 03/09/2018 11:54 86 checkstyle-result.xml |
-| 03/09/2018 11:54 <DIR> classes |
-| 03/09/2018 11:54 <DIR> dependency-maven-plugin-markers |
-| 03/09/2018 11:54 <DIR> etc |
-| 03/09/2018 11:54 <DIR> examples |
-| 03/09/2018 11:55 <DIR> install_hierarchy |
-| 03/09/2018 11:54 <DIR> maven-archiver |
-| 8 File(s) 292,652,686 bytes |
-| 9 Dir(s) 14,138,720,256 bytes free |
-+-----------------------------------------------------------------------------------------------------------------------------+
-
-.. container:: paragraph
-
- Now, take the ``.deb`` or the ``.tar.gz`` file and install APEX.
- Alternatively, copy the content of the folder ``install_hierarchy``
- to your APEX directory.
-
-Installation Layout
--------------------
-
- .. container:: paragraph
-
- A full installation of APEX comes with the following layout.
-
- .. container:: listingblock
-
- .. container:: content
-
- ::
-
- $APEX_HOME
- ├───bin (1)
- ├───etc (2)
- │ ├───editor
- │ ├───hazelcast
- │ ├───infinispan
- │ └───META-INF
- ├───examples (3)
- │ ├───config (4)
- │ ├───docker (5)
- │ ├───events (6)
- │ ├───html (7)
- │ ├───models (8)
- │ └───scripts (9)
- ├───lib (10)
- │ └───applications (11)
- └───war (12)
-
- .. container:: colist arabic
-
- +-----------------------------------+-----------------------------------+
- | **1** | binaries, mainly scripts (bash |
- | | and bat) to start the APEX engine |
- | | and applications |
- +-----------------------------------+-----------------------------------+
- | **2** | configuration files, such as |
- | | logback (logging) and third party |
- | | library configurations |
- +-----------------------------------+-----------------------------------+
- | **3** | example policy models to get |
- | | started |
- +-----------------------------------+-----------------------------------+
- | **4** | configurations for the examples |
- | | (with sub directories for |
- | | individual examples) |
- +-----------------------------------+-----------------------------------+
- | **5** | Docker files and additional |
- | | Docker instructions for the |
- | | exampples |
- +-----------------------------------+-----------------------------------+
- | **6** | example events for the examples |
- | | (with sub directories for |
- | | individual examples) |
- +-----------------------------------+-----------------------------------+
- | **7** | HTML files for some examples, |
- | | e.g. the Decisionmaker example |
- +-----------------------------------+-----------------------------------+
- | **8** | the policy models, generated for |
- | | each example (with sub |
- | | directories for individual |
- | | examples) |
- +-----------------------------------+-----------------------------------+
- | **9** | additional scripts for the |
- | | examples (with sub directories |
- | | for individual examples) |
- +-----------------------------------+-----------------------------------+
- | **10** | the library folder with all Java |
- | | JAR files |
- +-----------------------------------+-----------------------------------+
- | **11** | applications, also known as jar |
- | | with dependencies (or fat jars), |
- | | individually deployable |
- +-----------------------------------+-----------------------------------+
- | **12** | WAR files for web applications |
- +-----------------------------------+-----------------------------------+
-
-System Configuration
---------------------
-
- .. container:: paragraph
-
- Once APEX is installed, a few configurations need to be done:
-
- .. container:: ulist
-
- - Create an APEX user and an APEX group (optional, if not
- installed using RPM and DPKG)
-
- - Create environment settings for ``APEX_HOME`` and
- ``APEX_USER``, required by the start scripts
-
- - Change settings of the logging framework (optional)
-
- - Create directories for logging, required (execution might fail
- if directories do not exist or cannot be created)
-
-APEX User and Group
-###################
-
- .. container:: paragraph
-
- On smaller installations and test systems, APEX can run as any
- user or group.
-
- .. container:: paragraph
-
- However, if APEX is installed in production, we strongly
- recommend you set up a dedicated user for running APEX. This
- will isolate the execution of APEX to that user. We recommend
- you use the userid ``apexuser`` but you may use any user you
- choose.
-
- .. container:: paragraph
-
- The following example, for UNIX, creates a group called
- ``apexuser``, an APEX user called ``apexuser``, adds the group
- to the user, and changes ownership of the APEX installation to
- the user. Substitute ``<apex-dir>`` with the directory where
- APEX is installed.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- # sudo groupadd apexuser
- # sudo useradd -g apexuser apexuser
- # sudo chown -R apexuser:apexuser <apex-dir>
-
-.. container:: paragraph
-
- For other operating systems please consult your manual or system
- administrator.
-
-Environment Settings: APEX_HOME and APEX_USER
-#############################################
-
- .. container:: paragraph
-
- The provided start scripts for APEX require two environment
- variables being set:
-
- .. container:: ulist
-
- - ``APEX_USER`` with the user under whos name and permission APEX
- should be started (Unix only)
-
- - ``APEX_HOME`` with the directory where APEX is installed (Unix,
- Windows, Cygwin)
-
- .. container:: paragraph
-
- The first row in the following table shows how to set these
- environment variables temporary (assuming the user is
- ``apexuser``). The second row shows how to verify the settings.
- The last row explains how to set those variables permanently.
-
- +------------------------------------------------+---------------------------------------------------------+
- | Unix, Cygwin (bash/tcsh) | Windows |
- +================================================+=========================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | :number-lines: | :number-lines: |
- | | |
- | # export APEX_USER=apexuser | >set APEX_HOME=C:\apex\apex-full-2.0.0-SNAPSHOT |
- | # cd /opt/app/policy/apex-pdp | |
- | # export APEX_HOME=`pwd` | |
- | | |
- +------------------------------------------------+ |
- | .. container:: | |
- | | |
- | .. container:: content | |
- | | |
- | .. code:: tcsh | |
- | :number-lines: | |
- | | |
- | # setenv APEX_USER apexuser | |
- | # cd /opt/app/policy/apex-pdp | |
- | # setenv APEX_HOME `pwd` | |
- | | |
- +------------------------------------------------+---------------------------------------------------------+
- | .. container:: | .. container:: |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | :number-lines: | :number-lines: |
- | | |
- | # env | grep APEX | >set APEX_HOME |
- | # APEX_USER=apexuser | APEX_HOME=\apex\apex-full-2.0.0-SNAPSHOT |
- | # APEX_HOME=/opt/app/policy/apex-pdp | |
- | | |
- +------------------------------------------------+---------------------------------------------------------+
-
-Making Environment Settings Permanent (Unix, Cygwin)
-====================================================
-
- .. container:: paragraph
-
- For a per-user setting, edit the a user’s ``bash`` or ``tcsh``
- settings in ``~/.bashrc`` or ``~/.tcshrc``. For system-wide
- settings, edit ``/etc/profiles`` (requires permissions).
-
-Making Environment Settings Permanent (Windows)
-===============================================
-
- .. container:: paragraph
-
- On Windows 7 do
-
- .. container:: ulist
-
- - Click on the **Start** Menu
-
- - Right click on **Computer**
-
- - Select **Properties**
-
- .. container:: paragraph
-
- On Windows 8/10 do
-
- .. container:: ulist
-
- - Click on the **Start** Menu
-
- - Select **System**
-
- .. container:: paragraph
-
- Then do the following
-
- .. container:: ulist
-
- - Select **Advanced System Settings**
-
- - On the **Advanced** tab, click the **Environment Variables**
- button
-
- - Edit an existing variable, or create a new System variable:
- 'Variable name'="APEX_HOME", 'Variable
- value'="C:\apex\apex-full-2.0.0-SNAPSHOT"
-
- .. container:: paragraph
-
- For the settings to take effect, an application needs to be
- restarted (e.g. any open ``cmd`` window).
-
-Edit the APEX Logging Settings
-##############################
-
- .. container:: paragraph
-
- Configure the APEX logging settings to your requirements, for
- instance:
-
- .. container:: ulist
-
- - change the directory where logs are written to, or
-
- - change the log levels
-
- .. container:: paragraph
-
- Edit the file ``$APEX_HOME/etc/logback.xml`` for any required
- changes. To change the log directory change the line
-
- .. container:: paragraph
-
- ``<property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />``
-
- .. container:: paragraph
-
- to
-
- .. container:: paragraph
-
- ``<property name="VAR_LOG" value="/PATH/TO/LOG/DIRECTORY/" />``
-
- .. container:: paragraph
-
- On Windows, it is recommended to change the log directory to:
-
- .. container:: paragraph
-
- ``<property name="VAR_LOG" value="C:/apex/apex-full-2.0.0-SNAPSHOT/logs" />``
-
- .. container:: paragraph
-
- Note: Be careful about when to use ``\`` vs. ``/`` as the path
- separator!
-
-Create Directories for Logging
-##############################
-
- .. container:: paragraph
-
- Make sure that the log directory exists. This is important when
- APEX was installed manually or when the log directory was changed
- in the settings (see above).
-
- +------------------------------------------------------------------+-------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +==================================================================+=======================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | :number-lines: | :number-lines: |
- | | |
- | mkdir -p /var/log/onap/policy/apex-pdp | >mkdir C:\apex\apex-full-2.0.0-SNAPSHOT\logs |
- | chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp | |
- +------------------------------------------------------------------+-------------------------------------------------------+
-
-Verify the APEX Installation
-----------------------------
-
- .. container:: paragraph
-
- When APEX is installed and all settings are realized, the
- installation can be verified.
-
-Verify Installation - run Engine
-################################
-
- .. container:: paragraph
-
- A simple verification of an APEX installation can be done by
- simply starting the APEX engine without any configuration. On
- Unix (or Cygwin) start the engine using
- ``$APEX_HOME/bin/apexEngine.sh``. On Windows start the engine
- using ``%APEX_HOME%\bin\apexEngine.bat``. The engine will fail
- to fully start. However, if the output looks similar to the
- following line, the APEX installation is realized.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- Starting Apex service with parameters [] . . .
- start of Apex service failed: Apex configuration file was not specified as an argument
- 2018-09-03 13:11:33,914 Apex [main] ERROR o.o.p.a.service.engine.main.ApexMain - start of Apex service failed
- org.onap.policy.apex.model.basicmodel.concepts.ApexException: Apex configuration file was not specified as an argument
- at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:267)
- at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:161)
- at org.onap.policy.apex.service.engine.main.ApexMain.<init>(ApexMain.java:68)
- at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:165)
- usage: org.onap.policy.apex.service.engine.main.ApexMain [options...]
- options
- -c,--config-file <CONFIG_FILE>the full path to the configuration file to use, the configuration file must be a Json file
- containing the Apex configuration parameters
- -h,--help outputs the usage of this command
- -m,--model-file <MODEL_FILE> the full path to the model file to use, if set it overrides the model file set in the
- configuration file
- -v,--version outputs the version of Apex
-
-Verify Installation - run an Example
-####################################
-
- .. container:: paragraph
-
- A full APEX installation comes with several examples. Here, we can
- fully verify the installation by running one of the examples.
-
- .. container:: paragraph
-
- We use the example called *SampleDomain* and configure the engine
- to use standard in and standard out for events. Run the engine
- with the provided configuration. Note: Cygwin executes scripts as
- Unix scripts but runs Java as a Windows application, thus the
- configuration file must be given as a Windows path.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (1)
- # $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-2.0.0-SNAPSHOT/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (2)
- >%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json :: (3)
-
-.. container:: colist arabic
-
- +-------+---------+
- | **1** | UNIX |
- +-------+---------+
- | **2** | Cygwin |
- +-------+---------+
- | **3** | Windows |
- +-------+---------+
-
-.. container:: paragraph
-
- The engine should start successfully. Assuming the logging levels are
- not change (default level is ``info``), the output should look
- similar to this (last few lines)
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- Starting Apex service with parameters [-c, v:/dev/ericsson/apex/onap/apex-pdp/packages/apex-pdp-package-full/target/install_hierarchy/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json] . . .
- 2018-09-05 15:16:42,800 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-0:0.0.1 .
- 2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-1:0.0.1 .
- 2018-09-05 15:16:42,804 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-2:0.0.1 .
- 2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Created apex engine MyApexEngine-3:0.0.1 .
- 2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - APEX service created.
- 2018-09-05 15:16:43,962 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging starting . . .
- 2018-09-05 15:16:43,963 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging started
- 2018-09-05 15:16:44,987 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-0:0.0.1
- 2018-09-05 15:16:45,112 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-1:0.0.1
- 2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-2:0.0.1
- 2018-09-05 15:16:45,113 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Registering apex model on engine MyApexEngine-3:0.0.1
- 2018-09-05 15:16:45,120 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine
- Started Apex service
-
-.. container:: paragraph
-
- Important are the last two line, stating that APEX has added the
- final action listener to the engine and that the engine is started.
-
-.. container:: paragraph
-
- The engine is configured to read events from standard input and write
- produced events to standard output. The policy model is a very simple
- policy.
-
-.. container:: paragraph
-
- The following table shows an input event in the left column and an
- output event in the right column. Past the input event into the
- console where APEX is running, and the output event should appear in
- the console. Pasting the input event multiple times will produce
- output events with different values.
-
-+-------------------------------------------------------------+-------------------------------------------------------------+
-| Input Event | Example Output Event |
-+=============================================================+=============================================================+
-| .. container:: | .. container:: |
-| | |
-| .. container:: content | .. container:: content |
-| | |
-| .. code:: | .. code:: |
-| :number-lines: | :number-lines: |
-| | |
-| { | { |
-| "nameSpace": "org.onap.policy.apex.sample.events", | "name": "Event0004", |
-| "name": "Event0000", | "version": "0.0.1", |
-| "version": "0.0.1", | "nameSpace": "org.onap.policy.apex.sample.events", |
-| "source": "test", | "source": "Act", |
-| "target": "apex", | "target": "Outside", |
-| "TestSlogan": "Test slogan for External Event0", | "TestActCaseSelected": 2, |
-| "TestMatchCase": 0, | "TestActStateTime": 1536157104627, |
-| "TestTimestamp": 1469781869269, | "TestDecideCaseSelected": 0, |
-| "TestTemperature": 9080.866 | "TestDecideStateTime": 1536157104625, |
-| } | "TestEstablishCaseSelected": 0, |
-| | "TestEstablishStateTime": 1536157104623, |
-| | "TestMatchCase": 0, |
-| | "TestMatchCaseSelected": 1, |
-| | "TestMatchStateTime": 1536157104620, |
-| | "TestSlogan": "Test slogan for External Event0", |
-| | "TestTemperature": 9080.866, |
-| | "TestTimestamp": 1469781869269 |
-| | } |
-+-------------------------------------------------------------+-------------------------------------------------------------+
-
-.. container:: paragraph
-
- Terminate APEX by simply using ``CTRL+C`` in the console.
-
-Verify a Full Installation - REST Editor
-########################################
-
- .. container:: paragraph
-
- APEX has a REST application for viewing policy models. The
- application can also be used to create new policy models close to
- the engine native policy language. Start the REST editor as
- follows.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- # $APEX_HOME/bin/apexApps.sh rest-editor
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- >%APEX_HOME%\bin\apexApps.bat rest-editor
-
-.. container:: paragraph
-
- The script will start a simple web server
- (`Grizzly <https://javaee.github.io/grizzly/>`__) and deploy a
- ``war`` web archive in it. Once the editor is started, it will be
- available on ``localhost:18989``. The last few line of the messages
- should be:
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
- Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.NetworkListener start
- INFO: Started listener bound to [localhost:18989]
- Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.HttpServer start
- INFO: [HttpServer] Started.
- Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
-
-.. container:: paragraph
-
- Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and
- use the URL ``http://localhost:18989/``. This will connect the
- browser to the started REST editor. The start screen should be as
- follows.
-
-.. container:: imageblock
-
- .. container:: content
-
- |REST Editor Start Screen|
-
- .. container:: title
-
- Figure 1. REST Editor Start Screen
-
-.. container:: paragraph
-
- Now load a policy model by clicking the menu ``File`` and then
- ``Open``. In the opened dialog, go to the directory where APEX is
- installed, then ``examples``, ``models``, ``SampleDomain``, and there
- select the file ``SamplePolicyModelJAVA.json``. This will load the
- policy model used to verify the policy engine (see above). Once
- loaded, the screen should look as follows.
-
-.. container:: imageblock
-
- .. container:: content
-
- |REST Editor with loaded SampleDomain Policy Model|
-
- .. container:: title
-
- Figure 2. REST Editor with loaded SampleDomain Policy Model
-
-.. container:: paragraph
-
- Now you can use the REST editor. To finish this verification, simply
- terminate your browser (or the tab), and then use ``CTRL+C`` in the
- console where you started the REST editor.
-
-Installing WAR Applications
----------------------------
-
- .. container:: paragraph
-
- APEX comes with a set of WAR files. These are complete
- applications that can be installed and run in an application
- server. All of these applications are realized as servlets. You
- can find the WAR applications in ``$APEX_HOME/war`` (UNIX, Cygwin)
- or ``%APEX_HOME%\war`` (Windows).
-
- .. container:: paragraph
-
- Installing and using the WAR applications requires a web server
- that can execute ``war`` web archives. We recommend to use `Apache
- Tomcat <https://tomcat.apache.org/>`__, however other web servers
- can be used as well.
-
- .. container:: paragraph
-
- Install Apache Tomcat including the ``Manager App``, see `V9.0
- Docs <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access>`__
- for details. Start the Tomcat service, or make sure that Tomcat is
- running.
-
- .. container:: paragraph
-
- There are multiple ways to install the APEX WAR applications:
-
- .. container:: ulist
-
- - copy the ``.war`` file into the Tomcat ``webapps`` folder
-
- - use the Tomcat ``Manager App`` to deploy via the web interface
-
- - deploy using a REST call to Tomcat
-
- .. container:: paragraph
-
- For details on how to install ``war`` files please consult the
- `Tomcat
- Documentation <https://tomcat.apache.org/tomcat-9.0-doc/index.html>`__
- or the `Manager App
- HOW-TO <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html>`__.
- Once you installed an APEX WAR application (and wait for
- sufficient time for Tomcat to finalize the installation), open the
- ``Manager App`` in Tomcat. You should see the APEX WAR application
- being installed and running.
-
- .. container:: paragraph
-
- In case of errors, examine the log files in the Tomcat log
- directory. In a conventional install, those log files are in the
- logs directory where Tomcat is installed.
-
- .. container:: paragraph
-
- The current APEX version provides the following WAR applications:
-
- .. container:: ulist
-
- - client-deployment-2.0.0-SNAPSHOT.war - a client to deploy new
- policy models to a running engine
-
- - client-editor-2.0.0-SNAPSHOT.war - the standard policy REST
- editor GUI
-
- - client-monitoring-2.0.0-SNAPSHOT.war - a client for monitoring
- a running APEX engine
-
- - client-full-2.0.0-SNAPSHOT.war - a full client with a
- one-stop-access to deployment, monitoring, and REST editor
-
- - examples-servlet-2.0.0-SNAPSHOT.war - an example APEX servlet
-
-Running APEX in Docker
-----------------------
-
- .. container:: paragraph
-
- Since APEX is in ONAP, we provide a full virtualization
- environment for the engine.
-
-Run in ONAP
-###########
-
- .. container:: paragraph
-
- Running APEX from the ONAP docker repository only requires 2
- commands:
-
- .. container:: olist arabic
-
- #. Log into the ONAP docker repo
-
- .. container:: listingblock
-
- .. container:: content
-
- ::
-
- docker login -u docker -p docker nexus3.onap.org:10003
-
- .. container:: olist arabic
-
- #. Run the APEX docker image
-
- .. container:: listingblock
-
- .. container:: content
-
- ::
-
- docker run -it --rm nexus3.onap.org:10003/onap/policy-apex-pdp:latest
-
-Build a Docker Image
-####################
-
- .. container:: paragraph
-
- Alternatively, one can use the Dockerfile defined in the Docker
- package to build an image.
-
- .. container:: listingblock
-
- .. container:: title
-
- APEX Dockerfile
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- #
- # Docker file to build an image that runs APEX on Java 8 in Ubuntu
- #
- FROM ubuntu:16.04
-
- RUN apt-get update && \
- apt-get upgrade -y && \
- apt-get install -y software-properties-common && \
- add-apt-repository ppa:openjdk-r/ppa -y && \
- apt-get update && \
- apt-get install -y openjdk-8-jdk
-
- # Create apex user and group
- RUN groupadd apexuser
- RUN useradd --create-home -g apexuser apexuser
-
- # Add Apex-specific directories and set ownership as the Apex admin user
- RUN mkdir -p /opt/app/policy/apex-pdp
- RUN mkdir -p /var/log/onap/policy/apex-pdp
- RUN chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp
-
- # Unpack the tarball
- RUN mkdir /packages
- COPY apex-pdp-package-full.tar.gz /packages
- RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory /opt/app/policy/apex-pdp
- RUN rm /packages/apex-pdp-package-full.tar.gz
-
- # Ensure everything has the correct permissions
- RUN find /opt/app -type d -perm 755
- RUN find /opt/app -type f -perm 644
- RUN chmod a+x /opt/app/policy/apex-pdp/bin/*
-
- # Copy examples to Apex user area
- RUN cp -pr /opt/app/policy/apex-pdp/examples /home/apexuser
-
- RUN apt-get clean
-
- RUN chown -R apexuser:apexuser /home/apexuser/*
-
- USER apexuser
- ENV PATH /opt/app/policy/apex-pdp/bin:$PATH
- WORKDIR /home/apexuser
-
-APEX Configurations Explained
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Introduction to APEX Configuration
-----------------------------------
-
- .. container:: paragraph
-
- An APEX engine can be configured to use various combinations
- of event input handlers, event output handlers, event
- protocols, context handlers, and logic executors. The system
- is build using a plugin architecture. Each configuration
- option is realized by a plugin, which can be loaded and
- configured when the engine is started. New plugins can be
- added to the system at any time, though to benefit from a
- new plugin an engine will need to be restarted.
-
- .. container:: imageblock
-
- .. container:: content
-
- |APEX Configuration Matrix|
-
- .. container:: title
-
- Figure 3. APEX Configuration Matrix
-
- .. container:: paragraph
-
- The APEX distribution already comes with a number of
- plugins. The figure above shows the provided plugins. Any
- combination of input, output, event protocol, context
- handlers, and executors is possible.
-
-General Configuration Format
-----------------------------
-
- .. container:: paragraph
-
- The APEX configuration file is a JSON file containing a few
- main blocks for different parts of the configuration. Each
- block then holds the configuration details. The following
- code shows the main blocks:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- {
- "engineServiceParameters":{
- ... (1)
- "engineParameters":{ (2)
- "engineParameters":{...}, (3)
- "contextParameters":{...} (4)
- }
- },
- "eventInputParameters":{ (5)
- "input1":{ (6)
- "carrierTechnologyParameters":{...},
- "eventProtocolParameters":{...}
- },
- "input2":{...}, (7)
- "carrierTechnologyParameters":{...},
- "eventProtocolParameters":{...}
- },
- ... (8)
- },
- "eventOutputParameters":{ (9)
- "output1":{ (10)
- "carrierTechnologyParameters":{...},
- "eventProtocolParameters":{...}
- },
- "output2":{ (11)
- "carrierTechnologyParameters":{...},
- "eventProtocolParameters":{...}
- },
- ... (12)
- }
- }
-
- .. container:: colist arabic
-
- +-----------------------------------+-----------------------------------+
- | **1** | main engine configuration |
- +-----------------------------------+-----------------------------------+
- | **2** | engine parameters for plugin |
- | | configurations (execution |
- | | environments and context |
- | | handling) |
- +-----------------------------------+-----------------------------------+
- | **3** | engine specific parameters, |
- | | mainly for executor plugins |
- +-----------------------------------+-----------------------------------+
- | **4** | context specific parameters, e.g. |
- | | for context schemas, persistence, |
- | | etc. |
- +-----------------------------------+-----------------------------------+
- | **5** | configuration of the input |
- | | interface |
- +-----------------------------------+-----------------------------------+
- | **6** | an example input called |
- | | ``input1`` with carrier |
- | | technology and event protocol |
- +-----------------------------------+-----------------------------------+
- | **7** | an example input called |
- | | ``input2`` with carrier |
- | | technology and event protocol |
- +-----------------------------------+-----------------------------------+
- | **8** | any further input configuration |
- +-----------------------------------+-----------------------------------+
- | **9** | configuration of the output |
- | | interface |
- +-----------------------------------+-----------------------------------+
- | **10** | an example output called |
- | | ``output1`` with carrier |
- | | technology and event protocol |
- +-----------------------------------+-----------------------------------+
- | **11** | an example output called |
- | | ``output2`` with carrier |
- | | technology and event protocol |
- +-----------------------------------+-----------------------------------+
- | **12** | any further output configuration |
- +-----------------------------------+-----------------------------------+
-
-Engine Service Parameters
--------------------------
-
- .. container:: paragraph
-
- The configuration provides a number of parameters to
- configure the engine. An example configuration with
- explanations of all options is shown below.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "engineServiceParameters" : {
- "name" : "AADMApexEngine", (1)
- "version" : "0.0.1", (2)
- "id" : 45, (3)
- "instanceCount" : 4, (4)
- "deploymentPort" : 12345, (5)
- "policyModelFileName" : "examples/models/VPN/VPNPolicyModelJava.json", (6)
- "periodicEventPeriod": 1000, (7)
- "engineParameters":{ (8)
- "engineParameters":{...}, (9)
- "contextParameters":{...} (10)
- }
- }
-
- .. container:: colist arabic
-
- +-----------------------------------+-----------------------------------+
- | **1** | a name for the engine. The engine |
- | | name is used to create a key in a |
- | | runtime engine. An name matching |
- | | the following regular expression |
- | | can be used here: |
- | | ``[A-Za-z0-9\\-_\\.]+`` |
- +-----------------------------------+-----------------------------------+
- | **2** | a version of the engine, use |
- | | semantic versioning as explained |
- | | here: `Semantic |
- | | Versioning <http://semver.org/>`_ |
- | | _. |
- | | This version is used in a runtime |
- | | engine to create a version of the |
- | | engine. For that reason, the |
- | | version must match the following |
- | | regular expression ``[A-Z0-9.]+`` |
- +-----------------------------------+-----------------------------------+
- | **3** | a numeric identifier for the |
- | | engine |
- +-----------------------------------+-----------------------------------+
- | **4** | the number of threads (policy |
- | | instances executed in parallel) |
- | | the engine should use, use ``1`` |
- | | for single threaded engines |
- +-----------------------------------+-----------------------------------+
- | **5** | the port for the deployment |
- | | Websocket connection to the |
- | | engine |
- +-----------------------------------+-----------------------------------+
- | **6** | the model file to load into the |
- | | engine on startup (optional) |
- +-----------------------------------+-----------------------------------+
- | **7** | an optional timer for periodic |
- | | policies, in milliseconds (a |
- | | defined periodic policy will be |
- | | executed every ``X`` |
- | | milliseconds), not used of not |
- | | set or ``0`` |
- +-----------------------------------+-----------------------------------+
- | **8** | engine parameters for plugin |
- | | configurations (execution |
- | | environments and context |
- | | handling) |
- +-----------------------------------+-----------------------------------+
- | **9** | engine specific parameters, |
- | | mainly for executor plugins |
- +-----------------------------------+-----------------------------------+
- | **10** | context specific parameters, e.g. |
- | | for context schemas, persistence, |
- | | etc. |
- +-----------------------------------+-----------------------------------+
-
- .. container:: paragraph
-
- The model file is optional, it can also be specified via
- command line. In any case, make sure all execution and other
- required plug-ins for the loaded model are loaded as
- required.
-
-Input and Output Interfaces
----------------------------
-
- .. container:: paragraph
-
- An APEX engine has two main interfaces:
-
- .. container:: ulist
-
- - An *input* interface to receive events: also known as
- ingress interface or consumer, receiving (consuming)
- events commonly named triggers, and
-
- - An *output* interface to publish produced events: also
- known as egress interface or producer, sending
- (publishing) events commonly named actions or action
- events.
-
- .. container:: paragraph
-
- The input and output interface is configured in terms of
- inputs and outputs, respectively. Each input and output is a
- combination of a carrier technology and an event protocol.
- Carrier technologies and event protocols are provided by
- plugins, each with its own specific configuration. Most
- carrier technologies can be configured for input as well as
- output. Most event protocols can be used for all carrier
- technologies. One exception is the JMS object event
- protocol, which can only be used for the JMS carrier
- technology. Some further restrictions apply (for instance
- for carrier technologies using bi- or uni-directional
- modes).
-
- .. container:: paragraph
-
- Input and output interface can be configured separately, in
- isolation, with any number of carrier technologies. The
- resulting general configuration options are:
-
- .. container:: ulist
-
- - Input interface with one or more inputs
-
- .. container:: ulist
-
- - each input with a carrier technology and an event
- protocol
-
- - some inputs with optional synchronous mode
-
- - some event protocols with additional parameters
-
- - Output interface with one or more outputs
-
- .. container:: ulist
-
- - each output with a carrier technology and an event
- encoding
-
- - some outputs with optional synchronous mode
-
- - some event protocols with additional parameters
-
- .. container:: paragraph
-
- The configuration for input and output is contained in
- ``eventInputParameters`` and ``eventOutputParameters``,
- respectively. Inside here, one can configure any number of
- inputs and outputs. Each of them needs to have a unique
- identifier (name), the content of the name is free form. The
- example below shows a configuration for two inputs and two
- outputs.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventInputParameters": { (1)
- "FirstConsumer": { (2)
- "carrierTechnologyParameters" : {...}, (3)
- "eventProtocolParameters":{...}, (4)
- ... (5)
- },
- "SecondConsumer": { (6)
- "carrierTechnologyParameters" : {...}, (7)
- "eventProtocolParameters":{...}, (8)
- ... (9)
- },
- },
- "eventOutputParameters": { (10)
- "FirstProducer": { (11)
- "carrierTechnologyParameters":{...}, (12)
- "eventProtocolParameters":{...}, (13)
- ... (14)
- },
- "SecondProducer": { (15)
- "carrierTechnologyParameters":{...}, (16)
- "eventProtocolParameters":{...}, (17)
- ... (18)
- }
- }
-
- .. container:: colist arabic
-
- +--------+--------------------------------------------------------------------+
- | **1** | input interface configuration, APEX input plugins |
- +--------+--------------------------------------------------------------------+
- | **2** | first input called ``FirstConsumer`` |
- +--------+--------------------------------------------------------------------+
- | **3** | carrier technology for plugin |
- +--------+--------------------------------------------------------------------+
- | **4** | event protocol for plugin |
- +--------+--------------------------------------------------------------------+
- | **5** | any other input configuration (e.g. event name filter, see below) |
- +--------+--------------------------------------------------------------------+
- | **6** | second input called ``SecondConsumer`` |
- +--------+--------------------------------------------------------------------+
- | **7** | carrier technology for plugin |
- +--------+--------------------------------------------------------------------+
- | **8** | event protocol for plugin |
- +--------+--------------------------------------------------------------------+
- | **9** | any other plugin configuration |
- +--------+--------------------------------------------------------------------+
- | **10** | output interface configuration, APEX output plugins |
- +--------+--------------------------------------------------------------------+
- | **11** | first output called ``FirstProducer`` |
- +--------+--------------------------------------------------------------------+
- | **12** | carrier technology for plugin |
- +--------+--------------------------------------------------------------------+
- | **13** | event protocol for plugin |
- +--------+--------------------------------------------------------------------+
- | **14** | any other plugin configuration |
- +--------+--------------------------------------------------------------------+
- | **15** | second output called ``SecondProducer`` |
- +--------+--------------------------------------------------------------------+
- | **16** | carrier technology for plugin |
- +--------+--------------------------------------------------------------------+
- | **17** | event protocol for plugin |
- +--------+--------------------------------------------------------------------+
- | **18** | any other output configuration (e.g. event name filter, see below) |
- +--------+--------------------------------------------------------------------+
-
-Event Filters
-#############
-
- .. container:: paragraph
-
- APEX will always send an event after a policy execution
- is finished. For a successful execution, the event sent
- is the output event created by the policy. In case the
- policy does not create an output event, APEX will create
- a new event with all input event fields plus an
- additional field ``exceptionMessage`` with an exception
- message.
-
- .. container:: paragraph
-
- There are situations in which this auto-generated error
- event might not be required or wanted:
-
- .. container:: ulist
-
- - when a policy failing should not result in an event
- send out via an output interface
-
- - when the auto-generated event goes back in an APEX
- engine (or the same APEX engine), this can create
- endless loops
-
- - the auto-generated event should go to a special output
- interface or channel
-
- .. container:: paragraph
-
- All of these situations are supported by a filter option
- using a wildecard (regular expression) configuration on
- APEX I/O interfaces. The parameter is called
- ``eventNameFilter`` and the value are `Java regular
- expressions <https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html>`__
- (a
- `tutorial <http://www.vogella.com/tutorials/JavaRegularExpressions/article.html>`__).
- The following code shows some examples:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventInputParameters": {
- "Input1": {
- "carrierTechnologyParameters" : {...},
- "eventProtocolParameters":{...},
- "eventNameFilter" : "^E[Vv][Ee][Nn][Tt][0-9]004$" (1)
- }
- },
- "eventOutputParameters": {
- "Output1": {
- "carrierTechnologyParameters":{...},
- "eventProtocolParameters":{...},
- "eventNameFilter" : "^E[Vv][Ee][Nn][Tt][0-9]104$" (2)
- }
- }
-
-Executors
----------
-
- .. container:: paragraph
-
- Executors are plugins that realize the execution of logic
- contained in a policy model. Logic can be in a task
- selector, a task, and a state finalizer. Using plugins for
- execution environments makes APEX very flexible to support
- virtually any executable logic expressions.
-
- .. container:: paragraph
-
- APEX 2.0.0-SNAPSHOT supports the following executors:
-
- .. container:: ulist
-
- - Java, for Java implemented logic
-
- .. container:: ulist
-
- - This executor requires logic implemented using the
- APEX Java interfaces.
-
- - Generated JAR files must be in the classpath of the
- APEX engine at start time.
-
- - Javascript
-
- - JRuby,
-
- - Jython,
-
- - MVEL
-
- .. container:: ulist
-
- - This executor uses the latest version of the MVEL
- engine, which can be very hard to debug and can
- produce unwanted side effects during execution
-
-Configure the Javascript Executor
-#################################
-
- .. container:: paragraph
-
- The Javascript executor is added to the configuration as
- follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "engineServiceParameters":{
- "engineParameters":{
- "executorParameters":{
- "JAVASCRIPT":{
- "parameterClassName" :
- "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"
- }
- }
- }
- }
-
-Configure the Jython Executor
-#############################
-
- .. container:: paragraph
-
- The Jython executor is added to the configuration as
- follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "engineServiceParameters":{
- "engineParameters":{
- "executorParameters":{
- "JYTHON":{
- "parameterClassName" :
- "org.onap.policy.apex.plugins.executor.jython.JythonExecutorParameters"
- }
- }
- }
- }
-
-Configure the JRuby Executor
-############################
-
- .. container:: paragraph
-
- The JRuby executor is added to the configuration as
- follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "engineServiceParameters":{
- "engineParameters":{
- "executorParameters":{
- "JRUBY":{
- "parameterClassName" :
- "org.onap.policy.apex.plugins.executor.jruby.JrubyExecutorParameters"
- }
- }
- }
- }
-
-Configure the Java Executor
-###########################
-
- .. container:: paragraph
-
- The Java executor is added to the configuration as
- follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "engineServiceParameters":{
- "engineParameters":{
- "executorParameters":{
- "JAVA":{
- "parameterClassName" :
- "org.onap.policy.apex.plugins.executor.java.JavaExecutorParameters"
- }
- }
- }
- }
-
-Configure the MVEL Executor
-###########################
-
- .. container:: paragraph
-
- The MVEL executor is added to the configuration as
- follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "engineServiceParameters":{
- "engineParameters":{
- "executorParameters":{
- "MVEL":{
- "parameterClassName" :
- "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
- }
- }
- }
- }
-
-Context Handlers
-----------------
-
- .. container:: paragraph
-
- Context handlers are responsible for all context processing.
- There are the following main areas:
-
- .. container:: ulist
-
- - Context schema: use schema handlers other than Java class
- (supported by default without configuration)
-
- - Context distribution: distribute context across multiple
- APEX engines
-
- - Context locking: mechanisms to lock context elements for
- read/write
-
- - Context persistence: mechanisms to persist context
-
- .. container:: paragraph
-
- APEX provides plugins for each of the main areas.
-
-Configure AVRO Schema Handler
-#############################
-
- .. container:: paragraph
-
- The AVRO schema handler is added to the configuration as
- follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "engineServiceParameters":{
- "engineParameters":{
- "contextParameters":{
- "parameterClassName" : "org.onap.policy.apex.context.parameters.ContextParameters",
- "schemaParameters":{
- "Avro":{
- "parameterClassName" :
- "org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters"
- }
- }
- }
- }
- }
-
- .. container:: paragraph
-
- Using the AVRO schema handler has one limitation: AVRO
- only supports field names that represent valid Java class
- names. This means only letters and the character ``_``
- are supported. Characters commonly used in field names,
- such as ``.`` and ``-``, are not supported by AVRO. for
- more information see `Avro Spec:
- Names <https://avro.apache.org/docs/1.8.1/spec.html#names>`__.
-
- .. container:: paragraph
-
- To work with this limitation, the APEX Avro plugin will
- parse a given AVRO definition and replace *all*
- occurrences of ``.`` and ``-`` with a ``_``. This means
- that
-
- .. container:: ulist
-
- - In a policy model, if the AVRO schema defined a field
- as ``my-name`` the policy logic should access it as
- ``my_name``
-
- - In a policy model, if the AVRO schema defined a field
- as ``my.name`` the policy logic should access it as
- ``my_name``
-
- - There should be no field names that convert to the
- same internal name
-
- .. container:: ulist
-
- - For instance the simultaneous use of
- ``my_name``, ``my.name``, and ``my-name`` should
- be avoided
-
- - If not avoided, the event processing might
- create unwanted side effects
-
- - If field names use any other not-supported character,
- the AVRO plugin will reject it
-
- .. container:: ulist
-
- - Since AVRO uses lazy initialization, this
- rejection might only become visible at runtime
-
-Carrier Technologies
---------------------
-
- .. container:: paragraph
-
- Carrier technologies define how APEX receives (input) and
- sends (output) events. They can be used in any combination,
- using asynchronous or synchronous mode. There can also be
- any number of carrier technologies for the input (consume)
- and the output (produce) interface.
-
- .. container:: paragraph
-
- Supported *input* technologies are:
-
- .. container:: ulist
-
- - Standard input, read events from the standard input
- (console), not suitable for APEX background servers
-
- - File input, read events from a file
-
- - Kafka, read events from a Kafka system
-
- - Websockets, read events from a Websocket
-
- - JMS,
-
- - REST (synchronous and asynchronous), additionally as
- client or server
-
- - Event Requestor, allows reading of events that have been
- looped back into APEX
-
- .. container:: paragraph
-
- Supported *output* technologies are:
-
- .. container:: ulist
-
- - Standard output, write events to the standard output
- (console), not suitable for APEX background servers
-
- - File output, write events to a file
-
- - Kafka, write events to a Kafka system
-
- - Websockets, write events to a Websocket
-
- - JMS
-
- - REST (synchronous and asynchronous), additionally as
- client or server
-
- - Event Requestor, allows events to be looped back into
- APEX
-
- .. container:: paragraph
-
- New carrier technologies can be added as plugins to APEX or
- developed outside APEX and added to an APEX deployment.
-
-Standard IO
-###########
-
- .. container:: paragraph
-
- Standard IO does not require a specific plugin, it is
- supported be default.
-
-Standard Input
-==============
- .. container:: paragraph
-
- APEX will take events from its standard input. This
- carrier is good for testing, but certainly not for a
- use case where APEX runs as a server. The
- configuration is as follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- ::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "FILE", (1)
- "parameters" : {
- "standardIO" : true (2)
- }
- }
-
- .. container:: colist arabic
-
- +-------+---------------------------------------+
- | **1** | standard input is considered a file |
- +-------+---------------------------------------+
- | **2** | file descriptor set to standard input |
- +-------+---------------------------------------+
-
-Standard Output
-===============
-
- .. container:: paragraph
-
- APEX will send events to its standard output. This
- carrier is good for testing, but certainly not for a
- use case where APEX runs as a server. The
- configuration is as follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "FILE", (1)
- "parameters" : {
- "standardIO" : true (2)
- }
- }
-
- .. container:: colist arabic
-
- +-------+----------------------------------------+
- | **1** | standard output is considered a file |
- +-------+----------------------------------------+
- | **2** | file descriptor set to standard output |
- +-------+----------------------------------------+
-
-2.7.2. File IO
-##############
-
- .. container:: paragraph
-
- File IO does not require a specific plugin, it is
- supported be default.
-
-File Input
-==========
-
- .. container:: paragraph
-
- APEX will take events from a file. The same file
- should not be used as an output. The configuration is
- as follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "FILE", (1)
- "parameters" : {
- "fileName" : "examples/events/SampleDomain/EventsIn.xmlfile" (2)
- }
- }
-
- .. container:: colist arabic
-
- +-------+------------------------------------------+
- | **1** | set file input |
- +-------+------------------------------------------+
- | **2** | the name of the file to read events from |
- +-------+------------------------------------------+
-
-File Output
-===========
- .. container:: paragraph
-
- APEX will write events to a file. The same file should
- not be used as an input. The configuration is as
- follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "FILE", (1)
- "parameters" : {
- "fileName" : "examples/events/SampleDomain/EventsOut.xmlfile" (2)
- }
- }
-
- .. container:: colist arabic
-
- +-------+-----------------------------------------+
- | **1** | set file output |
- +-------+-----------------------------------------+
- | **2** | the name of the file to write events to |
- +-------+-----------------------------------------+
-
-Event Requestor IO
-##################
-
- .. container:: paragraph
-
- Event Requestor IO does not require a specific plugin, it
- is supported be default. It should only be used with the
- APEX event protocol.
-
-Event Requestor Input
-=====================
-
- .. container:: paragraph
-
- APEX will take events from APEX.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology": "EVENT_REQUESTOR" (1)
- }
-
- .. container:: colist arabic
-
- +-------+---------------------------+
- | **1** | set event requestor input |
- +-------+---------------------------+
-
-Event Requestor Output
-======================
-
- .. container:: paragraph
-
- APEX will write events to APEX.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology": "EVENT_REQUESTOR" (1)
- }
-
-Peering Event Requestors
-========================
-
- .. container:: paragraph
-
- When using event requestors, they need to be peered.
- This means an event requestor output needs to be
- peered (associated) with an event requestor input. The
- following example shows the use of an event requestor
- with the APEX event protocol and the peering of output
- and input.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventInputParameters": {
- "EventRequestorConsumer": {
- "carrierTechnologyParameters": {
- "carrierTechnology": "EVENT_REQUESTOR" (1)
- },
- "eventProtocolParameters": {
- "eventProtocol": "APEX" (2)
- },
- "eventNameFilter": "InputEvent", (3)
- "requestorMode": true, (4)
- "requestorPeer": "EventRequestorProducer", (5)
- "requestorTimeout": 500 (6)
- }
- },
- "eventOutputParameters": {
- "EventRequestorProducer": {
- "carrierTechnologyParameters": {
- "carrierTechnology": "EVENT_REQUESTOR" (7)
- },
- "eventProtocolParameters": {
- "eventProtocol": "APEX" (8)
- },
- "eventNameFilter": "EventListEvent", (9)
- "requestorMode": true, (10)
- "requestorPeer": "EventRequestorConsumer", (11)
- "requestorTimeout": 500 (12)
- }
- }
-
- .. container:: colist arabic
-
- +-----------------------------------+-----------------------------------+
- | **1** | event requestor on a consumer |
- +-----------------------------------+-----------------------------------+
- | **2** | with APEX event protocol |
- +-----------------------------------+-----------------------------------+
- | **3** | optional filter (best to use a |
- | | filter to prevent unwanted events |
- | | on the consumer side) |
- +-----------------------------------+-----------------------------------+
- | **4** | activate requestor mode |
- +-----------------------------------+-----------------------------------+
- | **5** | the peer to the output (must |
- | | match the output carrier) |
- +-----------------------------------+-----------------------------------+
- | **6** | an optional timeout in |
- | | milliseconds |
- +-----------------------------------+-----------------------------------+
- | **7** | event requestor on a producer |
- +-----------------------------------+-----------------------------------+
- | **8** | with APEX event protocol |
- +-----------------------------------+-----------------------------------+
- | **9** | optional filter (best to use a |
- | | filter to prevent unwanted events |
- | | on the consumer side) |
- +-----------------------------------+-----------------------------------+
- | **10** | activate requestor mode |
- +-----------------------------------+-----------------------------------+
- | **11** | the peer to the output (must |
- | | match the input carrier) |
- +-----------------------------------+-----------------------------------+
- | **12** | an optional timeout in |
- | | milliseconds |
- +-----------------------------------+-----------------------------------+
-
-Kafka IO
-########
-
- .. container:: paragraph
-
- Kafka IO is supported by the APEX Kafka plugin. The
- configurations below are examples. APEX will take any
- configuration inside the parameter object and forward it
- to Kafka. More information on Kafka specific
- configuration parameters can be found in the Kafka
- documentation:
-
- .. container:: ulist
-
- - `Kafka Consumer
- Class <https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/consumer/KafkaConsumer.html>`__
-
- - `Kafka Producer
- Class <https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/producer/KafkaProducer.html>`__
-
-Kafka Input
-===========
- .. container:: paragraph
-
- APEX will receive events from the Apache Kafka
- messaging system. The input is uni-directional, an
- engine will only receive events from the input but not
- send any event to the input.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "KAFKA", (1)
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters",
- "parameters" : {
- "bootstrapServers" : "localhost:49092", (2)
- "groupId" : "apex-group-id", (3)
- "enableAutoCommit" : true, (4)
- "autoCommitTime" : 1000, (5)
- "sessionTimeout" : 30000, (6)
- "consumerPollTime" : 100, (7)
- "consumerTopicList" : ["apex-in-0", "apex-in-1"], (8)
- "keyDeserializer" :
- "org.apache.kafka.common.serialization.StringDeserializer", (9)
- "valueDeserializer" :
- "org.apache.kafka.common.serialization.StringDeserializer" (10)
- }
- }
-
- .. container:: colist arabic
-
- +--------+-------------------------------------+
- | **1** | set Kafka as carrier technology |
- +--------+-------------------------------------+
- | **2** | bootstrap server and port |
- +--------+-------------------------------------+
- | **3** | a group identifier |
- +--------+-------------------------------------+
- | **4** | flag for auto-commit |
- +--------+-------------------------------------+
- | **5** | auto-commit timeout in milliseconds |
- +--------+-------------------------------------+
- | **6** | session timeout in milliseconds |
- +--------+-------------------------------------+
- | **7** | consumer poll time in milliseconds |
- +--------+-------------------------------------+
- | **8** | consumer topic list |
- +--------+-------------------------------------+
- | **9** | key for the Kafka de-serializer |
- +--------+-------------------------------------+
- | **10** | value for the Kafka de-serializer |
- +--------+-------------------------------------+
-
-Kafka Output
-============
- .. container:: paragraph
-
- APEX will send events to the Apache Kafka messaging
- system. The output is uni-directional, an engine will
- send events to the output but not receive any event
- from the output.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "KAFKA", (1)
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters",
- "parameters" : {
- "bootstrapServers" : "localhost:49092", (2)
- "acks" : "all", (3)
- "retries" : 0, (4)
- "batchSize" : 16384, (5)
- "lingerTime" : 1, (6)
- "bufferMemory" : 33554432, (7)
- "producerTopic" : "apex-out", (8)
- "keySerializer" :
- "org.apache.kafka.common.serialization.StringSerializer", (9)
- "valueSerializer" :
- "org.apache.kafka.common.serialization.StringSerializer" (10)
- }
- }
-
- .. container:: colist arabic
-
- +--------+---------------------------------+
- | **1** | set Kafka as carrier technology |
- +--------+---------------------------------+
- | **2** | bootstrap server and port |
- +--------+---------------------------------+
- | **3** | acknowledgement strategy |
- +--------+---------------------------------+
- | **4** | number of retries |
- +--------+---------------------------------+
- | **5** | batch size |
- +--------+---------------------------------+
- | **6** | time to linger in milliseconds |
- +--------+---------------------------------+
- | **7** | buffer memory in byte |
- +--------+---------------------------------+
- | **8** | producer topic |
- +--------+---------------------------------+
- | **9** | key for the Kafka serializer |
- +--------+---------------------------------+
- | **10** | value for the Kafka serializer |
- +--------+---------------------------------+
-
-JMS IO
-#######
-
- .. container:: paragraph
-
- APEX supports the Java Messaging Service (JMS) as input
- as well as output. JMS IO is supported by the APEX JMS
- plugin. Input and output support an event encoding as
- text (JSON string) or object (serialized object). The
- input configuration is the same for both encodings, the
- output configuration differs.
-
-JMS Input
-=========
- .. container:: paragraph
-
- APEX will receive events from a JMS messaging system.
- The input is uni-directional, an engine will only
- receive events from the input but not send any event
- to the input.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "JMS", (1)
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.jms.JMSCarrierTechnologyParameters",
- "parameters" : { (2)
- "initialContextFactory" :
- "org.jboss.naming.remote.client.InitialContextFactory", (3)
- "connectionFactory" : "ConnectionFactory", (4)
- "providerURL" : "remote://localhost:5445", (5)
- "securityPrincipal" : "guest", (6)
- "securityCredentials" : "IAmAGuest", (7)
- "consumerTopic" : "jms/topic/apexIn" (8)
- }
- }
-
- .. container:: colist arabic
-
- +-----------------------------------+-----------------------------------+
- | **1** | set JMS as carrier technology |
- +-----------------------------------+-----------------------------------+
- | **2** | set all JMS specific parameters |
- +-----------------------------------+-----------------------------------+
- | **3** | the context factory, in this case |
- | | from JBOSS (it requires the |
- | | dependency |
- | | org.jboss:jboss-remote-naming:2.0 |
- | | .4.Final |
- | | or a different version to be in |
- | | the directory ``$APEX_HOME/lib`` |
- | | or ``%APEX_HOME%\lib`` |
- +-----------------------------------+-----------------------------------+
- | **4** | a connection factory for the JMS |
- | | connection |
- +-----------------------------------+-----------------------------------+
- | **5** | URL with host and port of the JMS |
- | | provider |
- +-----------------------------------+-----------------------------------+
- | **6** | access credentials, user name |
- +-----------------------------------+-----------------------------------+
- | **7** | access credentials, user password |
- +-----------------------------------+-----------------------------------+
- | **8** | the JMS topic to listen to |
- +-----------------------------------+-----------------------------------+
-
-JMS Output with Text
-====================
-
- .. container:: paragraph
-
- APEX engine send events to a JMS messaging system. The
- output is uni-directional, an engine will send events
- to the output but not receive any event from output.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "JMS", (1)
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.jms.JMSCarrierTechnologyParameters",
- "parameters" : { (2)
- "initialContextFactory" :
- "org.jboss.naming.remote.client.InitialContextFactory", (3)
- "connectionFactory" : "ConnectionFactory", (4)
- "providerURL" : "remote://localhost:5445", (5)
- "securityPrincipal" : "guest", (6)
- "securityCredentials" : "IAmAGuest", (7)
- "producerTopic" : "jms/topic/apexOut", (8)
- "objectMessageSending": "false" (9)
- }
- }
-
- .. container:: colist arabic
-
- +-----------------------------------+-----------------------------------+
- | **1** | set JMS as carrier technology |
- +-----------------------------------+-----------------------------------+
- | **2** | set all JMS specific parameters |
- +-----------------------------------+-----------------------------------+
- | **3** | the context factory, in this case |
- | | from JBOSS (it requires the |
- | | dependency |
- | | org.jboss:jboss-remote-naming:2.0 |
- | | .4.Final |
- | | or a different version to be in |
- | | the directory ``$APEX_HOME/lib`` |
- | | or ``%APEX_HOME%\lib`` |
- +-----------------------------------+-----------------------------------+
- | **4** | a connection factory for the JMS |
- | | connection |
- +-----------------------------------+-----------------------------------+
- | **5** | URL with host and port of the JMS |
- | | provider |
- +-----------------------------------+-----------------------------------+
- | **6** | access credentials, user name |
- +-----------------------------------+-----------------------------------+
- | **7** | access credentials, user password |
- +-----------------------------------+-----------------------------------+
- | **8** | the JMS topic to write to |
- +-----------------------------------+-----------------------------------+
- | **9** | set object messaging to ``false`` |
- | | means it sends JSON text |
- +-----------------------------------+-----------------------------------+
-
-JMS Output with Object
-======================
-
- .. container:: paragraph
-
- To configure APEX for JMS objects on the output
- interface use the same configuration as above (for
- output). Simply change the ``objectMessageSending``
- parameter to ``true``.
-
-Websocket (WS) IO
-########################
-
- .. container:: paragraph
-
- APEX supports the Websockets as input as well as output.
- WS IO is supported by the APEX Websocket plugin. This
- carrier technology does only support uni-directional
- communication. APEX will not send events to a Websocket
- input and any event sent to a Websocket output will
- result in an error log.
-
- .. container:: paragraph
-
- The input can be configured as client (APEX connects to
- an existing Websocket server) or server (APEX starts a
- Websocket server). The same applies to the output. Input
- and output can both use a client or a server
- configuration, or separate configurations (input as
- client and output as server, input as server and output
- as client). Each configuration should use its own
- dedicated port to avoid any communication loops. The
- configuration of a Websocket client is the same for input
- and output. The configuration of a Websocket server is
- the same for input and output.
-
-Websocket Client
-================
-
- .. container:: paragraph
-
- APEX will connect to a given Websocket server. As
- input, it will receive events from the server but not
- send any events. As output, it will send events to the
- server and any event received from the server will
- result in an error log.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "WEBSOCKET", (1)
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",
- "parameters" : {
- "host" : "localhost", (2)
- "port" : 42451 (3)
- }
- }
-
- .. container:: colist arabic
-
- +-------+------------------------------------------------------+
- | **1** | set Websocket as carrier technology |
- +-------+------------------------------------------------------+
- | **2** | the host name on which a Websocket server is running |
- +-------+------------------------------------------------------+
- | **3** | the port of that Websocket server |
- +-------+------------------------------------------------------+
-
-Websocket Server
-================
-
- .. container:: paragraph
-
- APEX will start a Websocket server, which will accept
- any Websocket clients to connect. As input, it will
- receive events from the server but not send any
- events. As output, it will send events to the server
- and any event received from the server will result in
- an error log.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "WEBSOCKET", (1)
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",
- "parameters" : {
- "wsClient" : false, (2)
- "port" : 42450 (3)
- }
- }
-
- .. container:: colist arabic
-
- +-------+------------------------------------------------------------+
- | **1** | set Websocket as carrier technology |
- +-------+------------------------------------------------------------+
- | **2** | disable client, so that APEX will start a Websocket server |
- +-------+------------------------------------------------------------+
- | **3** | the port for the Websocket server APEX will start |
- +-------+------------------------------------------------------------+
-
-REST Client IO
-##############
-
- .. container:: paragraph
-
- APEX can act as REST client on the input as well as on
- the output interface. The media type is
- ``application/json``, so this plugin does only work with
- the JSON Event protocol.
-
-REST Client Input
-=================
-
- .. container:: paragraph
-
- APEX will connect to a given URL to receive events,
- but not send any events. The server is polled, i.e.
- APEX will do an HTTP GET, take the result, and then do
- the next GET. Any required timing needs to be handled
- by the server configured via the URL. For instance,
- the server could support a wait timeout via the URL as
- ``?timeout=100ms``.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "RESTCLIENT", (1)
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.restclient.RESTClientCarrierTechnologyParameters",
- "parameters" : {
- "url" : "http://example.org:8080/triggers/events", (2)
- }
- }
-
- .. container:: colist arabic
-
- +-------+---------------------------------------+
- | **1** | set REST client as carrier technology |
- +-------+---------------------------------------+
- | **2** | the URL of the HTTP server for events |
- +-------+---------------------------------------+
-
-REST Client Output
-==================
-
- .. container:: paragraph
-
- APEX will connect to a given URL to send events, but
- not receive any events. The default HTTP operation is
- POST (no configuration required). To change it to PUT
- simply add the configuration parameter (as shown in
- the example below).
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "RESTCLIENT", (1)
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.restclient.RESTClientCarrierTechnologyParameters",
- "parameters" : {
- "url" : "http://example.com:8888/actions/events", (2)
- "httpMethod" : "PUT" (3)
- }
- }
-
- .. container:: colist arabic
-
- +-------+--------------------------------------------------+
- | **1** | set REST client as carrier technology |
- +-------+--------------------------------------------------+
- | **2** | the URL of the HTTP server for events |
- +-------+--------------------------------------------------+
- | **3** | use HTTP PUT (remove this line to use HTTP POST) |
- +-------+--------------------------------------------------+
-
-REST Server IO
-##############
-
- .. container:: paragraph
-
- APEX supports a REST server for input and output.
-
- .. container:: paragraph
-
- The REST server plugin always uses a synchronous mode. A
- client does a HTTP GET on the APEX REST server with the
- input event and receives the generated output event in
- the server reply. This means that for the REST server
- there has to always to be an input with an associated
- output. Input or output only are not permitted.
-
- .. container:: paragraph
-
- The plugin will start a Grizzly server as REST server for
- a normal APEX engine. If the APEX engine is executed as a
- servlet, for instance inside Tomcat, then Tomcat will be
- used as REST server (this case requires configuration on
- Tomcat as well).
-
- .. container:: paragraph
-
- Some configuration restrictions apply for all scenarios:
-
- .. container:: ulist
-
- - Minimum port: 1024
-
- - Maximum port: 65535
-
- - The media type is ``application/json``, so this plugin
- does only work with the JSON Event protocol.
-
- .. container:: paragraph
-
- The URL the client calls is created using
-
- .. container:: ulist
-
- - the configured host and port, e.g.
- ``http://localhost:12345``
-
- - the standard path, e.g. ``/apex/``
-
- - the name of the input/output, e.g. ``FirstConsumer/``
-
- - the input or output name, e.g. ``EventIn``.
-
- .. container:: paragraph
-
- The examples above lead to the URL
- ``http://localhost:12345/apex/FirstConsumer/EventIn``.
-
- .. container:: paragraph
-
- A client can also get status information of the REST
- server using ``/Status``, e.g.
- ``http://localhost:12345/apex/FirstConsumer/Status``.
-
-REST Server Stand-alone
-=======================
-
- .. container:: paragraph
-
- We need to configure a REST server input and a REST
- server output. Input and output are associated with
- each other via there name.
-
- .. container:: paragraph
-
- Timeouts for REST calls need to be set carefully. If
- they are too short, the call might timeout before a
- policy finished creating an event.
-
- .. container:: paragraph
-
- The following example configures the input named as
- ``MyConsumer`` and associates an output named
- ``MyProducer`` with it.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventInputParameters": {
- "MyConsumer": {
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "RESTSERVER", (1)
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.restserver.RESTServerCarrierTechnologyParameters",
- "parameters" : {
- "standalone" : true, (2)
- "host" : "localhost", (3)
- "port" : 12345 (4)
- }
- },
- "eventProtocolParameters":{
- "eventProtocol" : "JSON" (5)
- },
- "synchronousMode" : true, (6)
- "synchronousPeer" : "MyProducer", (7)
- "synchronousTimeout" : 500 (8)
- }
- }
-
- .. container:: colist arabic
-
- +-------+---------------------------------------+
- | **1** | set REST server as carrier technology |
- +-------+---------------------------------------+
- | **2** | set the server as stand-alone |
- +-------+---------------------------------------+
- | **3** | set the server host |
- +-------+---------------------------------------+
- | **4** | set the server listen port |
- +-------+---------------------------------------+
- | **5** | use JSON event protocol |
- +-------+---------------------------------------+
- | **6** | activate synchronous mode |
- +-------+---------------------------------------+
- | **7** | associate an output ``MyProducer`` |
- +-------+---------------------------------------+
- | **8** | set a timeout of 500 milliseconds |
- +-------+---------------------------------------+
-
- .. container:: paragraph
-
- The following example configures the output named as
- ``MyProducer`` and associates the input ``MyConsumer``
- with it. Note that for the output there are no more
- paramters (such as host or port), since they are
- already configured in the associated input
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventOutputParameters": {
- "MyProducer": {
- "carrierTechnologyParameters":{
- "carrierTechnology" : "RESTSERVER",
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.restserver.RESTServerCarrierTechnologyParameters"
- },
- "eventProtocolParameters":{
- "eventProtocol" : "JSON"
- },
- "synchronousMode" : true,
- "synchronousPeer" : "MyConsumer",
- "synchronousTimeout" : 500
- }
- }
-
-REST Server Stand-alone, multi input
-====================================
-
- .. container:: paragraph
-
- Any number of input/output pairs for REST servers can
- be configured. For instance, we can configure an input
- ``FirstConsumer`` with output ``FirstProducer`` and an
- input ``SecondConsumer`` with output
- ``SecondProducer``. Important is that there is always
- one pair of input/output.
-
-REST Server Stand-alone in Servlet
-==================================
-
- .. container:: paragraph
-
- If APEX is executed as a servlet, e.g. inside Tomcat,
- the configuration becomes easier since the plugin can
- now use Tomcat as the REST server. In this scenario,
- there are not parameters (port, host, etc.) and the
- key ``standalone`` must not be used (or set to false).
-
- .. container:: paragraph
-
- For the Tomcat configuration, we need to add the REST
- server plugin, e.g.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <servlet>
- ...
- <init-param>
- ...
- <param-value>org.onap.policy.apex.plugins.event.carrier.restserver</param-value>
- </init-param>
- ...
- </servlet>
-
-REST Requestor IO
-##################
-
- .. container:: paragraph
-
- APEX can act as REST requestor on the input as well as on
- the output interface. The media type is
- ``application/json``, so this plugin does only work with
- the JSON Event protocol.
-
-REST Requestor Input
-====================
-
- .. container:: paragraph
-
- APEX will connect to a given URL to request an input.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters": {
- "carrierTechnology": "RESTREQUESTOR", (1)
- "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters",
- "parameters": {
- "url": "http://localhost:54321/some/path/to/rest/resource", (2)
- "httpMethod": "POST", (3)
- "restRequestTimeout": 2000 (4)
- }
- },
-
- .. container:: colist arabic
-
- +-------+--------------------------------------------------+
- | **1** | set REST requestor as carrier technology |
- +-------+--------------------------------------------------+
- | **2** | the URL of the HTTP server for events |
- +-------+--------------------------------------------------+
- | **3** | use HTTP PUT (remove this line to use HTTP POST) |
- +-------+--------------------------------------------------+
- | **4** | request timeout in milliseconds |
- +-------+--------------------------------------------------+
-
- .. container:: paragraph
-
- Further settings are required on the consumer to
- define the event that is requested, for example:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventName": "GuardResponseEvent", (1)
- "eventNameFilter": "GuardResponseEvent", (2)
- "requestorMode": true, (3)
- "requestorPeer": "GuardRequestorProducer", (4)
- "requestorTimeout": 500 (5)
-
- .. container:: colist arabic
-
- +-------+---------------------------+
- | **1** | the event name |
- +-------+---------------------------+
- | **2** | a filter on the event |
- +-------+---------------------------+
- | **3** | the mode of the requestor |
- +-------+---------------------------+
- | **4** | a peer for the requestor |
- +-------+---------------------------+
- | **5** | a general request timeout |
- +-------+---------------------------+
-
-REST Requestor Output
-=====================
-
- .. container:: paragraph
-
- APEX will connect to a given URL to send events, but
- not receive any events.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "carrierTechnologyParameters": {
- "carrierTechnology": "RESTREQUESTOR", (1)
- "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters"
- },
-
- .. container:: colist arabic
-
- +-------+------------------------------------------+
- | **1** | set REST requestor as carrier technology |
- +-------+------------------------------------------+
-
- .. container:: paragraph
-
- Further settings are required on the consumer to
- define the event that is requested, for example:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventNameFilter": "GuardRequestEvent", (1)
- "requestorMode": true, (2)
- "requestorPeer": "GuardRequestorConsumer", (3)
- "requestorTimeout": 500 (4)
-
- .. container:: colist arabic
-
- +-------+---------------------------+
- | **1** | a filter on the event |
- +-------+---------------------------+
- | **2** | the mode of the requestor |
- +-------+---------------------------+
- | **3** | a peer for the requestor |
- +-------+---------------------------+
- | **4** | a general request timeout |
- +-------+---------------------------+
-
-Event Protocols, Format and Encoding
-------------------------------------
-
- .. container:: paragraph
-
- Event protocols define what event formats APEX can receive
- (input) and should send (output). They can be used in any
- combination for input and output, unless further restricted
- by a carrier technology plugin (for instance for JMS
- output). There can only be 1 event protocol per event
- plugin.
-
- .. container:: paragraph
-
- Supported *input* event protocols are:
-
- .. container:: ulist
-
- - JSON, the event as a JSON string
-
- - APEX, an APEX event
-
- - JMS object, the event as a JMS object,
-
- - JMS text, the event as a JMS text,
-
- - XML, the event as an XML string,
-
- - YAML, the event as YAML text
-
- .. container:: paragraph
-
- Supported *output* event protocols are:
-
- .. container:: ulist
-
- - JSON, the event as a JSON string
-
- - APEX, an APEX event
-
- - JMS object, the event as a JMS object,
-
- - JMS text, the event as a JMS text,
-
- - XML, the event as an XML string,
-
- - YAML, the event as YAML text
-
- .. container:: paragraph
-
- New event protocols can be added as plugins to APEX or
- developed outside APEX and added to an APEX deployment.
-
-JSON Event
-##########
-
- .. container:: paragraph
-
- The event protocol for JSON encoding does not require a
- specific plugin, it is supported by default. Furthermore,
- there is no difference in the configuration for the input
- and output interface.
-
- .. container:: paragraph
-
- For an input, APEX requires a well-formed JSON string.
- Well-formed here means according to the definitions of a
- policy. Any JSON string that is not defined as a trigger
- event (consume) will not be consumed (errors will be
- thrown). For output JSON events, APEX will always produce
- valid JSON strings according to the definition in the
- policy model.
-
- .. container:: paragraph
-
- The following JSON shows the configuration.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventProtocolParameters":{
- "eventProtocol" : "JSON"
- }
-
- .. container:: paragraph
-
- For JSON events, there are a few more optional
- parameters, which allow to define a mapping for standard
- event fields. An APEX event must have the fields
- ``name``, ``version``, ``source``, and ``target``
- defined. Sometimes it is not possible to configure a
- trigger or actioning system to use those fields. However,
- they might be in an event generated outside APEX (or used
- outside APEX) just with different names. To configure
- APEX to map between the different event names, simply add
- the following parameters to a JSON event:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventProtocolParameters":{
- "eventProtocol" : "JSON",
- "nameAlias" : "policyName", (1)
- "versionAlias" : "policyVersion", (2)
- "sourceAlias" : "from", (3)
- "targetAlias" : "to", (4)
- "nameSpaceAlias": "my.name.space" (5)
- }
-
- .. container:: colist arabic
-
- +-----------------------------------+-----------------------------------+
- | **1** | mapping for the ``name`` field, |
- | | here from a field called |
- | | ``policyName`` |
- +-----------------------------------+-----------------------------------+
- | **2** | mapping for the ``version`` |
- | | field, here from a field called |
- | | ``policyVersion`` |
- +-----------------------------------+-----------------------------------+
- | **3** | mapping for the ``source`` field, |
- | | here from a field called ``from`` |
- | | (only for an input event) |
- +-----------------------------------+-----------------------------------+
- | **4** | mapping for the ``target`` field, |
- | | here from a field called ``to`` |
- | | (only for an output event) |
- +-----------------------------------+-----------------------------------+
- | **5** | mapping for the ``nameSpace`` |
- | | field, here from a field called |
- | | ``my.name.space`` |
- +-----------------------------------+-----------------------------------+
-
-APEX Event
-##########
- .. container:: paragraph
-
- The event protocol for APEX events does not require a
- specific plugin, it is supported by default. Furthermore,
- there is no difference in the configuration for the input
- and output interface.
-
- .. container:: paragraph
-
- For input and output APEX uses APEX events.
-
- .. container:: paragraph
-
- The following JSON shows the configuration.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventProtocolParameters":{
- "eventProtocol" : "APEX"
- }
-
-JMS Event
-#########
-
- .. container:: paragraph
-
- The event protocol for JMS is provided by the APEX JMS
- plugin. The plugin supports encoding as JSON text or as
- object. There is no difference in the configuration for
- the input and output interface.
-
-JMS Text
-========
- .. container:: paragraph
-
- If used as input, APEX will take a JMS message and
- extract a JSON string, then proceed as if a JSON event
- was received. If used as output, APEX will take the
- event produced by a policy, create a JSON string, and
- then wrap it into a JMS message.
-
- .. container:: paragraph
-
- The configuration for JMS text is as follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventProtocolParameters":{
- "eventProtocol" : "JMSTEXT",
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.protocol.jms.JMSTextEventProtocolParameters"
- }
-
-JMS Object
-==========
- .. container:: paragraph
-
- If used as input, APEX will will take a JMS message,
- extract a Java Bean from the ``ObjectMessage``
- message, construct an APEX event and put the bean on
- the APEX event as a parameter. If used as output, APEX
- will take the event produced by a policy, create a
- Java Bean and send it as a JMS message.
-
- .. container:: paragraph
-
- The configuration for JMS object is as follows:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventProtocolParameters":{
- "eventProtocol" : "JMSOBJECT",
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.protocol.jms.JMSObjectEventProtocolParameters"
- }
-
-YAML Event
-##########
-
- .. container:: paragraph
-
- The event protocol for YAML is provided by the APEX YAML
- plugin. There is no difference in the configuration for
- the input and output interface.
-
- .. container:: paragraph
-
- If used as input, APEX will consume events as YAML and
- map them to policy trigger events. Not well-formed YAML
- and not understood trigger events will be rejected. If
- used as output, APEX produce YAML encoded events from the
- event a policy produces. Those events will always be
- well-formed according to the definition in the policy
- model.
-
- .. container:: paragraph
-
- The following code shows the configuration.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventProtocolParameters":{
- "eventProtocol" : "XML",
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.protocol.yaml.YamlEventProtocolParameters"
- }
-
-XML Event
-#########
- .. container:: paragraph
-
- The event protocol for XML is provided by the APEX XML
- plugin. There is no difference in the configuration for
- the input and output interface.
-
- .. container:: paragraph
-
- If used as input, APEX will consume events as XML and map
- them to policy trigger events. Not well-formed XML and
- not understood trigger events will be rejected. If used
- as output, APEX produce XML encoded events from the event
- a policy produces. Those events will always be
- well-formed according to the definition in the policy
- model.
-
- .. container:: paragraph
-
- The following code shows the configuration.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- "eventProtocolParameters":{
- "eventProtocol" : "XML",
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.protocol.xml.XMLEventProtocolParameters"
- }
-
-A configuration example
------------------------
-
- .. container:: paragraph
-
- The following example loads all available plug-ins.
-
- .. container:: paragraph
-
- Events are consumed from a Websocket, APEX as client.
- Consumed event format is JSON.
-
- .. container:: paragraph
-
- Events are produced to Kafka. Produced event format is XML.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- {
- "engineServiceParameters" : {
- "name" : "MyApexEngine",
- "version" : "0.0.1",
- "id" : 45,
- "instanceCount" : 4,
- "deploymentPort" : 12345,
- "policyModelFileName" : "examples/models/some-model.json",
- "engineParameters" : {
- "executorParameters" : {
- "JAVASCRIPT" : {
- "parameterClassName" :
- "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"
- },
- "JYTHON" : {
- "parameterClassName" :
- "org.onap.policy.apex.plugins.executor.jython.JythonExecutorParameters"
- },
- "JRUBY" : {
- "parameterClassName" :
- "org.onap.policy.apex.plugins.executor.jruby.JrubyExecutorParameters"
- },
- "JAVA" : {
- "parameterClassName" :
- "org.onap.policy.apex.plugins.executor.java.JavaExecutorParameters"
- },
- "MVEL" : {
- "parameterClassName" :
- "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
- }
- },
- "contextParameters" : {
- "parameterClassName" :
- "org.onap.policy.apex.context.parameters.ContextParameters",
- "schemaParameters" : {
- "Avro":{
- "parameterClassName" :
- "org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters"
- }
- }
- }
- }
- },
- "producerCarrierTechnologyParameters" : {
- "carrierTechnology" : "KAFKA",
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters",
- "parameters" : {
- "bootstrapServers" : "localhost:49092",
- "acks" : "all",
- "retries" : 0,
- "batchSize" : 16384,
- "lingerTime" : 1,
- "bufferMemory" : 33554432,
- "producerTopic" : "apex-out",
- "keySerializer" : "org.apache.kafka.common.serialization.StringSerializer",
- "valueSerializer" : "org.apache.kafka.common.serialization.StringSerializer"
- }
- },
- "producerEventProtocolParameters" : {
- "eventProtocol" : "XML",
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.protocol.xml.XMLEventProtocolParameters"
- },
- "consumerCarrierTechnologyParameters" : {
- "carrierTechnology" : "WEBSOCKET",
- "parameterClassName" :
- "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",
- "parameters" : {
- "host" : "localhost",
- "port" : 88888
- }
- },
- "consumerEventProtocolParameters" : {
- "eventProtocol" : "JSON"
- }
- }
-
-Engine and Applications of the APEX System
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Introduction to APEX Engine and Applications
---------------------------------------------
-
- .. container:: paragraph
-
- The core of APEX is the APEX Engine, also known as the APEX
- Policy Engine or the APEX PDP (since it is in fact a Policy
- Decision Point). Beside this engine, an APEX system comes
- with a few applications intended to help with policy
- authoring, deployment, and execution.
-
- .. container:: paragraph
-
- The engine itself and most applications are started from the
- command line with command line arguments. This is called a
- Command Line Interface (CLI). Some applications require an
- installation on a webserver, as for instance the REST
- Editor. Those applications can be accessed via a web
- browser.
-
- .. container:: paragraph
-
- You can also use the available APEX APIs and applications to
- develop other applications as required. This includes policy
- languages (and associated parsers and compilers /
- interpreters), GUIs to access APEX or to define policies,
- clients to connect to APEX, etc.
-
- .. container:: paragraph
-
- For this documentation, we assume an installation of APEX as
- a full system based on a current ONAP release.
-
-CLI on Unix, Windows, and Cygwin
---------------------------------
-
- .. container:: paragraph
-
- A note on APEX CLI applications: all applications and the
- engine itself have been deployed and tested on different
- operating systems: Red Hat, Ubuntu, Debian, Mac OSX,
- Windows, Cygwin. Each operating system comes with its own
- way of configuring and executing Java. The main items here
- are:
-
- .. container:: ulist
-
- - For UNIX systems (RHL, Ubuntu, Debian, Mac OSX), the
- provided bash scripts work as expected with absolute
- paths (e.g.
- ``/opt/app/policy/apex-pdp/apex-pdp-2.0.0-SNAPSHOT/examples``),
- indirect and linked paths (e.g. ``../apex/apex``), and
- path substitutions using environment settings (e.g.
- ``$APEX_HOME/bin/``)
-
- - For Windows systems, the provided batch files (``.bat``)
- work as expected with with absolute paths (e.g.
- ``C:\apex\apex-2.0.0-SNAPSHOT\examples``), and path
- substitutions using environment settings (e.g.
- ``%APEX_HOME%\bin\``)
-
- - For Cygwin system we assume a standard Cygwin
- installation with standard tools (mainly bash) using a
- Windows Java installation. This means that the bash
- scripts can be used as in UNIX, however any argument
- pointing to files and directories need to use either a
- DOS path (e.g.
- ``C:\apex\apex-2.0.0-SNAPSHOT\examples\config...``) or
- the command ``cygpath`` with a mixed option. The reason
- for that is: Cygwin executes Java using UNIX paths but
- then runs Java as a DOS/WINDOWS process, which requires
- DOS paths for file access.
-
-The APEX Engine
----------------
-
- .. container:: paragraph
-
- The APEX engine can be started in different ways, depending
- your requirements. All scripts are located in the APEX *bin*
- directory
-
- .. container:: paragraph
-
- On UNIX and Cygwin systems use:
-
- .. container:: ulist
-
- - ``apexEngine.sh`` - this script will
-
- .. container:: ulist
-
- - Test if ``$APEX_USER`` is set and if the user
- exists, terminate with an error otherwise
-
- - Test if ``$APEX_HOME`` is set. If not set, it will
- use the default setting as
- ``/opt/app/policy/apex-pdp/apex-pdp``. Then the set
- directory is tested to exist, the script will
- terminate if not.
-
- - When all tests are passed successfully, the script
- will call ``apexApps.sh`` with arguments to start
- the APEX engine.
-
- - ``apexApps.sh engine`` - this is the general APEX
- application launcher, which will
-
- .. container:: ulist
-
- - Start the engine with the argument ``engine``
-
- - Test if ``$APEX_HOME`` is set and points to an
- existing directory. If not set or directory does
- not exist, script terminates.
-
- - Not test for any settings of ``$APEX_USER``.
-
- .. container:: paragraph
-
- On Windows systems use ``apexEngine.bat`` and
- ``apexApps.bat engine`` respectively. Note: none of the
- windows batch files will test for ``%APEX_USER%``.
-
- .. container:: paragraph
-
- Summary of alternatives to start the APEX Engine:
-
- +--------------------------------------------------------+----------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +========================================================+==========================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexEngine.sh [args] | > %APEX_HOME%\bin\apexEngine.bat [args] |
- | # $APEX_HOME/bin/apexApps.sh engine [args] | > %APEX_HOME%\bin\apexApps.bat engine [args] |
- +--------------------------------------------------------+----------------------------------------------------------+
-
- .. container:: paragraph
-
- The APEX engine comes with a few CLI arguments for setting
- configuration and policy model. The configuration file is
- always required. The policy model file is only required if
- no model file is specified in the configuration, or if the
- specified model file should be over written. The option
- ``-h`` prints a help screen.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: org.onap.policy.apex.service.engine.main.ApexMain [options...]
- options
- -c,--config-file <CONFIG_FILE> the full path to the configuration file to use, the configuration file must be a Json file
- containing the Apex configuration parameters
- -h,--help outputs the usage of this command
- -m,--model-file <MODEL_FILE> the full path to the model file to use, if set it overrides the model file set in the
- configuration file
- -v,--version outputs the version of Apex
-
-The APEX CLI Editor
--------------------
-
- .. container:: paragraph
-
- The CLI Editor allows to define policies from the command
- line. The application uses a simple language and supports
- all elements of an APEX policy. It can be used in to
- different ways:
-
- .. container:: ulist
-
- - non-interactive, specifying a file with the commands to
- create a policy
-
- - interactive, using the editors CLI to create a policy
-
- .. container:: paragraph
-
- When a policy is fully specified, the editor will generate
- the APEX core policy specification in JSON. This core
- specification is called the policy model in the APEX engine
- and can be used directly with the APEX engine.
-
- .. container:: paragraph
-
- On UNIX and Cygwin systems use:
-
- .. container:: ulist
-
- - ``apexCLIEditor.sh`` - simply starts the CLI editor,
- arguments to the script determine the mode of the editor
-
- - ``apexApps.sh cli-editor`` - simply starts the CLI
- editor, arguments to the script determine the mode of the
- editor
-
- .. container:: paragraph
-
- On Windows systems use:
-
- .. container:: ulist
-
- - ``apexCLIEditor.bat`` - simply starts the CLI editor,
- arguments to the script determine the mode of the editor
-
- - ``apexApps.bat cli-editor`` - simply starts the CLI
- editor, arguments to the script determine the mode of the
- editor
-
- .. container:: paragraph
-
- Summary of alternatives to start the APEX CLI Editor:
-
- +------------------------------------------------------------+--------------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +============================================================+==============================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexCLIEditor.sh.sh [args] | > %APEX_HOME%\bin\apexCLIEditor.bat [args] |
- | # $APEX_HOME/bin/apexApps.sh cli-editor [args] | > %APEX_HOME%\bin\apexApps.bat cli-editor [args] |
- +------------------------------------------------------------+--------------------------------------------------------------+
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen with all command
- line arguments.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: org.onap.policy.apex.auth.clieditor.ApexCLIEditorMain [options...]
- options
- -a,--model-props-file <MODEL_PROPS_FILE> name of the apex model properties file to use
- -c,--command-file <COMMAND_FILE> name of a file containing editor commands to run into the editor
- -h,--help outputs the usage of this command
- -i,--input-model-file <INPUT_MODEL_FILE> name of a file that contains an input model for the editor
- -if,--ignore-failures <IGNORE_FAILURES_FLAG> true or false, ignore failures of commands in command files and continue
- executing the command file
- -l,--log-file <LOG_FILE> name of a file that will contain command logs from the editor, will log
- to standard output if not specified or suppressed with "-nl" flag
- -m,--metadata-file <CMD_METADATA_FILE> name of the command metadata file to use
- -nl,--no-log if specified, no logging or output of commands to standard output or log
- file is carried out
- -nm,--no-model-output if specified, no output of a model to standard output or model output
- file is carried out, the user can use the "save" command in a script to
- save a model
- -o,--output-model-file <OUTPUT_MODEL_FILE> name of a file that will contain the output model for the editor, will
- output model to standard output if not specified or suppressed with
- "-nm" flag
- -wd,--working-directory <WORKING_DIRECTORY> the working directory that is the root for the CLI editor and is the
- root from which to look for included macro files
-
-The APEX REST Editor
---------------------
-
- .. container:: paragraph
-
- The standard way to use the APEX REST Editor is via an
- installation of the *war* file on a webserver. However, the
- REST editor can also be started via command line. This will
- start a Grizzly webserver with the *war* deployed. Access to
- the REST Editor is then via the provided URL
-
- .. container:: paragraph
-
- On UNIX and Cygwin systems use:
-
- .. container:: ulist
-
- - ``apexRESTEditor.sh`` - simply starts the webserver with
- the REST editor
-
- - ``apexApps.sh rest-editor`` - simply starts the webserver
- with the REST editor
-
- .. container:: paragraph
-
- On Windows systems use:
-
- .. container:: ulist
-
- - ``apexRESTEditor.bat`` - simply starts the webserver with
- the REST editor
-
- - ``apexApps.bat rest-editor`` - simply starts the
- webserver with the REST editor
-
- .. container:: paragraph
-
- Summary of alternatives to start the APEX REST Editor:
-
- +-------------------------------------------------------------+---------------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +=============================================================+===============================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexRESTEditor.sh.sh [args] | > %APEX_HOME%\bin\apexRESTEditor.bat [args] |
- | # $APEX_HOME/bin/apexApps.sh rest-editor [args] | > %APEX_HOME%\bin\apexApps.bat rest-editor [args] |
- +-------------------------------------------------------------+---------------------------------------------------------------+
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen with all command
- line arguments.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: org.onap.policy.apex.client.editor.rest.ApexEditorMain [options...]
- -h,--help outputs the usage of this command
- -l,--listen <ADDRESS> the IP address to listen on. Default value is localhost to restrict access to the
- local machine only.
- -p,--port <PORT> port to use for the Apex RESTful editor REST calls.
- -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating. Default
- value is -1 to run indefinitely.
-
- .. container:: paragraph
-
- If the REST Editor is started without any arguments the
- final messages will look similar to this:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
- Sep 05, 2018 11:24:30 PM org.glassfish.grizzly.http.server.NetworkListener start
- INFO: Started listener bound to [localhost:18989]
- Sep 05, 2018 11:24:30 PM org.glassfish.grizzly.http.server.HttpServer start
- INFO: [HttpServer] Started.
- Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
-
- .. container:: paragraph
-
- The last line states the URL on which the REST Editor can be
- accessed. The example above stated
- ``http://0.0.0.0:18989/apex/``. In a web browser use the URL
- ``http://localhost:18989`` and the REST Editor will start.
-
-The APEX Monitoring Client
---------------------------
-
- .. container:: paragraph
-
- The standard way to use the APEX Monitoring Client is via an
- installation of the *war* file on a webserver. However, the
- Monitoring Client can also be started via command line. This
- will start a Grizzly webserver with the *war* deployed.
- Access to the Monitoring Client is then via the provided URL
-
- .. container:: paragraph
-
- On UNIX and Cygwin systems use:
-
- .. container:: ulist
-
- - ``apexApps.sh eng-monitoring`` - simply starts the
- webserver with the Monitoring Client
-
- .. container:: paragraph
-
- On Windows systems use:
-
- .. container:: ulist
-
- - ``apexApps.bat eng-monitoring`` - simply starts the
- webserver with the Monitoring Client
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen with all command
- line arguments.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: org.onap.policy.apex.client.monitoring.rest.ApexMonitoringRestMain [options...]
- -h,--help outputs the usage of this command
- -p,--port <PORT> port to use for the Apex Services REST calls
- -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating
-
- .. container:: paragraph
-
- If the Monitoring Client is started without any arguments
- the final messages will look similar to this:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
- Sep 05, 2018 11:26:20 PM org.glassfish.grizzly.http.server.NetworkListener start
- INFO: Started listener bound to [localhost:18989]
- Sep 05, 2018 11:26:20 PM org.glassfish.grizzly.http.server.HttpServer start
- INFO: [HttpServer] Started.
- Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
-
- .. container:: paragraph
-
- The last line states the URL on which the Monitoring Client
- can be accessed. The example above stated
- ``http://localhost:18989/apexservices``. In a web browser
- use the URL ``http://localhost:18989``.
-
-The APEX Deployment Client
---------------------------
-
- .. container:: paragraph
-
- The standard way to use the APEX Deployment Client is via an
- installation of the *war* file on a webserver. However, the
- Deployment Client can also be started via command line. This
- will start a Grizzly webserver with the *war* deployed.
- Access to the Deployment Client is then via the provided URL
-
- .. container:: paragraph
-
- On UNIX and Cygwin systems use:
-
- .. container:: ulist
-
- - ``apexApps.sh eng-deployment`` - simply starts the
- webserver with the Deployment Client
-
- .. container:: paragraph
-
- On Windows systems use:
-
- .. container:: ulist
-
- - ``apexApps.bat eng-deployment`` - simply starts the
- webserver with the Deployment Client
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen with all command
- line arguments.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: org.onap.policy.apex.client.deployment.rest.ApexDeploymentRestMain [options...]
- -h,--help outputs the usage of this command
- -p,--port <PORT> port to use for the Apex Services REST calls
- -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating
-
- .. container:: paragraph
-
- If the Deployment Client is started without any arguments
- the final messages will look similar to this:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
- Sep 05, 2018 11:27:09 PM org.glassfish.grizzly.http.server.NetworkListener start
- INFO: Started listener bound to [localhost:18989]
- Sep 05, 2018 11:27:09 PM org.glassfish.grizzly.http.server.HttpServer start
- INFO: [HttpServer] Started.
- Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
-
- .. container:: paragraph
-
- The last line states the URL on which the Deployment Client
- can be accessed. The example above stated
- ``http://localhost:18989/apexservices``. In a web browser
- use the URL ``http://localhost:18989``.
-
-The APEX Full Client
---------------------
-
- .. container:: paragraph
-
- The APEX Full Client combines the REST Editor, the
- Monitoring Client, and the Deployment Client into a single
- application. The standard way to use the APEX Full Client is
- via an installation of the *war* file on a webserver.
- However, the Full Client can also be started via command
- line. This will start a Grizzly webserver with the *war*
- deployed. Access to the Full Client is then via the provided
- URL
-
- .. container:: paragraph
-
- On UNIX and Cygwin systems use:
-
- .. container:: ulist
-
- - ``apexApps.sh full-client`` - simply starts the webserver
- with the Full Client
-
- .. container:: paragraph
-
- On Windows systems use:
-
- .. container:: ulist
-
- - ``apexApps.bat full-client`` - simply starts the
- webserver with the Full Client
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen with all command
- line arguments.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: org.onap.policy.apex.client.full.rest.ApexServicesRestMain [options...]
- -h,--help outputs the usage of this command
- -p,--port <PORT> port to use for the Apex Services REST calls
- -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating
-
- .. container:: paragraph
-
- If the Full Client is started without any arguments the
- final messages will look similar to this:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
- Sep 05, 2018 11:28:28 PM org.glassfish.grizzly.http.server.NetworkListener start
- INFO: Started listener bound to [localhost:18989]
- Sep 05, 2018 11:28:28 PM org.glassfish.grizzly.http.server.HttpServer start
- INFO: [HttpServer] Started.
- Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
-
- .. container:: paragraph
-
- The last line states the URL on which the Monitoring Client
- can be accessed. The example above stated
- ``http://localhost:18989/apexservices``. In a web browser
- use the URL ``http://localhost:18989``.
-
- The APEX Application Launcher
-------------------------------
-
- .. container:: paragraph
-
- The standard applications (Engine, CLI Editor, REST Editor)
- come with dedicated start scripts. For all other APEX
- applications, we provide an application launcher.
-
- .. container:: paragraph
-
- On UNIX and Cygwin systems use:
-
- .. container:: ulist
-
- - apexApps.sh\` - simply starts the application launcher
-
- .. container:: paragraph
-
- On Windows systems use:
-
- .. container:: ulist
-
- - ``apexApps.bat`` - simply starts the application launcher
-
- .. container:: paragraph
-
- Summary of alternatives to start the APEX application
- launcher:
-
- +-------------------------------------------------+---------------------------------------------------+
- | Unix, Cygwin | Windows |
- +=================================================+===================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexApps.sh [args] | > %APEX_HOME%\bin\apexApps.bat [args] |
- +-------------------------------------------------+---------------------------------------------------+
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen with all launcher
- command line arguments.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- apexApps.sh - runs APEX applications
-
- Usage: apexApps.sh [options] | [<application> [<application options>]]
-
- Options
- -d <app> - describes an application
- -l - lists all applications supported by this script
- -h - this help screen
-
- .. container:: paragraph
-
- Using ``-l`` lists all known application the launcher can
- start.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- apexApps.sh: supported applications:
- --> ws-echo engine eng-monitoring full-client eng-deployment tpl-event-json model-2-cli rest-editor cli-editor ws-console
-
- .. container:: paragraph
-
- Using the ``-d <name>`` option describes the named
- application, for instance for the ``ws-console``:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- apexApps.sh: application 'ws-console'
- --> a simple console sending events to APEX, connect to APEX consumer port
-
- .. container:: paragraph
-
- Launching an application is done by calling the script with
- only the application name and any CLI arguments for the
- application. For instance, starting the ``ws-echo``
- application with port ``8888``:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- apexApps.sh ws-echo -p 8888
-
-Application: Create Event Templates
------------------------------------
-
- .. container:: paragraph
-
- **Status: Experimental**
-
- .. container:: paragraph
-
- This application takes a policy model (JSON or XML encoded)
- and generates templates for events in JSON format. This can
- help when a policy defines rather complex trigger or action
- events or complex events between states. The application can
- produce events for the types: stimuli (policy trigger
- events), internal (events between policy states), and
- response (action events).
-
- +----------------------------------------------------------------+------------------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +================================================================+==================================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexApps.sh tpl-event-json [args] | > %APEX_HOME%\bin\apexApps.bat tpl-event-json [args] |
- +----------------------------------------------------------------+------------------------------------------------------------------+
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- gen-model2event v{release-version} - generates JSON templates for events generated from a policy model
- usage: gen-model2event
- -h,--help prints this help and usage screen
- -m,--model <MODEL-FILE> set the input policy model file
- -t,--type <TYPE> set the event type for generation, one of:
- stimuli (trigger events), response (action
- events), internal (events between states)
- -v,--version prints the application version
-
- .. container:: paragraph
-
- The created templates are not valid events, instead they use
- some markup for values one will need to change to actual
- values. For instance, running the tool with the *Sample
- Domain* policy model as:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli
-
- .. container:: paragraph
-
- will produce the following status messages:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- gen-model2event: starting Event generator
- --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json
- --> type: stimuli
-
- .. container:: paragraph
-
- and then run the generator application producing two event
- templates. The first template is called ``Event0000``.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- {
- "name" : "Event0000",
- "nameSpace" : "org.onap.policy.apex.sample.events",
- "version" : "0.0.1",
- "source" : "Outside",
- "target" : "Match",
- "TestTemperature" : ###double: 0.0###,
- "TestTimestamp" : ###long: 0###,
- "TestMatchCase" : ###integer: 0###,
- "TestSlogan" : "###string###"
- }
-
- .. container:: paragraph
-
- The values for the keys are marked with ``#`` and the
- expected type of the value. To create an actual stimuli
- event, all these markers need to be change to actual values,
- for instance:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- {
- "name" : "Event0000",
- "nameSpace" : "org.onap.policy.apex.sample.events",
- "version" : "0.0.1",
- "source" : "Outside",
- "target" : "Match",
- "TestTemperature" : 25,
- "TestTimestamp" : 123456789123456789,
- "TestMatchCase" : 1,
- "TestSlogan" : "Testing the Match Case with Temperature 25"
- }
-
-Application: Convert a Policy Model to CLI Editor Commands
-----------------------------------------------------------
-
- .. container:: paragraph
-
- **Status: Experimental**
-
- .. container:: paragraph
-
- This application takes a policy model (JSON or XML encoded)
- and generates commands for the APEX CLI Editor. This
- effectively reverses a policy specification realized with
- the CLI Editor.
-
- +-------------------------------------------------------------+---------------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +=============================================================+===============================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexApps.sh model-2-cli [args] | > %APEX_HOME%\bin\apexApps.bat model-2-cli [args] |
- +-------------------------------------------------------------+---------------------------------------------------------------+
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: gen-model2cli
- -h,--help prints this help and usage screen
- -m,--model <MODEL-FILE> set the input policy model file
- -sv,--skip-validation switch of validation of the input file
- -v,--version prints the application version
-
- .. container:: paragraph
-
- For instance, running the tool with the *Sample Domain*
- policy model as:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- apexApps.sh model-2-cli -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json
-
- .. container:: paragraph
-
- will produce the following status messages:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- gen-model2cli: starting CLI generator
- --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json
-
- .. container:: paragraph
-
- and then run the generator application producing all CLI
- Editor commands and printing them to standard out.
-
-Application: Websocket Clients (Echo and Console)
--------------------------------------------------
-
- .. container:: paragraph
-
- **Status: Production**
-
- .. container:: paragraph
-
- The application launcher also provides a Websocket echo
- client and a Websocket console client. The echo client
- connects to APEX and prints all events it receives from
- APEX. The console client connects to APEX, reads input from
- the command line, and sends this input as events to APEX.
-
- +------------------------------------------------------------+--------------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +============================================================+==============================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexApps.sh ws-echo [args] | > %APEX_HOME%\bin\apexApps.bat ws-echo [args] |
- | # $APEX_HOME/bin/apexApps.sh ws-console [args] | > %APEX_HOME%\bin\apexApps.bat ws-console [args] |
- +------------------------------------------------------------+--------------------------------------------------------------+
-
- .. container:: paragraph
-
- The arguments are the same for both applications:
-
- .. container:: ulist
-
- - ``-p`` defines the Websocket port to connect to (defaults
- to ``8887``)
-
- - ``-s`` defines the host on which a Websocket server is
- running (defaults to ``localhost``)
-
- .. container:: paragraph
-
- A discussion on how to use these two applications to build
- an APEX system is detailed HowTo-Websockets.
-
-My First Policy
-^^^^^^^^^^^^^^^
-
-Introduction
-------------
- .. container:: paragraph
-
- Consider a scenario where a supermarket chain called
- *HyperM* controls how it sells items in a policy-based
- manner. Each time an item is processed by *HyperM*'s
- point-of-sale (PoS) system an event is generated and
- published about that item of stock being sold. This event
- can then be used to update stock levels, etc..
-
- .. container:: paragraph
-
- *HyperM* want to extend this approach to allow some checks
- to be performed before the sale can be completed. This can
- be achieved by requesting a policy-controlled decision as
- each item is processed by for sale by each PoS system. The
- decision process is integrated with *HyperM*'s other IT
- systems that manage stock control, sourcing and purchasing,
- personnel systems, etc.
-
- .. container:: paragraph
-
- In this document we will show how APEX and APEX Policies can
- be used to achieve this, starting with a simple policy,
- building up to more complicated policy that demonstrates the
- features of APEX.
-
-Data Models
------------
-
-Sales Input Event
-#################
-
- .. container:: paragraph
-
- Each time a PoS system processes a sales item an event
- with the following format is emitted:
-
- .. table:: Table 1. Sale Input Event
-
- +----------------------+----------------------+-----------------------+
- | Event | Fields | Description |
- +======================+======================+=======================+
- | SALE_INPUT | time, sale_ID, | Event indicating a |
- | | amount, item_ID, | sale of an item is |
- | | quantity, | occurring |
- | | assistant_ID, | |
- | | branch_ID, notes, …​ | |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- In each ``SALE_INPUT`` event the ``sale_ID`` field is a
- unique ID generated by the PoS system. A timestamp for
- the event is stored in the ``time`` field. The ``amount``
- field refers to the value of the item(s) to be sold (in
- cents). The ``item_ID`` field is a unique identifier for
- each item type, and can be used to retrieve more
- information about the item from *HyperM*'s stock control
- system. The ``quantity`` field refers to the quantity of
- the item to be sold. The ``assistant_ID`` field is a
- unique identifier for the PoS operator, and can be used
- to retrieve more information about the operator from the
- *HyperM*'s personnel system. Since *HyperM* has many
- branches the ``branch_ID`` identifies the shop. The
- ``notes`` field contains arbitrary notes about the sale.
-
-Sales Decision Event
-####################
-
- .. container:: paragraph
-
- After a ``SALE_INPUT`` event is emitted by the PoS system
- *HyperM*'s policy-based controlled sales checking system
- emits a Sale Authorization Event indicating whether the
- sale is authorized or denied. The PoS system can then
- listen for this event before continuing with the sale.
-
- .. table:: Table 2. Sale Authorisation Event
-
- +----------------------+----------------------+-----------------------+
- | Event | Fields | Description |
- +======================+======================+=======================+
- | SALE_AUTH | sale_ID, time, | Event indicating a |
- | | authorized, amount, | sale of an item is |
- | | item_ID, quantity, | authorized or denied |
- | | assistant_ID, | |
- | | branch_ID, notes, | |
- | | message…​ | |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- In each ``SALE_AUTH`` event the ``sale_ID`` field is
- copied from the ``SALE_INPUT`` event that trigger the
- decision request. The ``SALE_AUTH`` event is also
- timestamped using the ``time`` field, and a field called
- ``authorised`` is set to ``true`` or ``false`` depending
- on whether the sale is authorized or denied. The
- ``message`` field carries an optional message about why a
- sale was not authorized. The other fields from the
- ``SALE_INPUT`` event are also included for completeness.
-
-Stock Control: Items
-####################
-
- .. container:: paragraph
-
- *HyperM* maintains information about each item for sale
- in a database table called ``ITEMS``.
-
- .. table:: Table 3. Items Database
-
- +----------------------+----------------------+-----------------------+
- | Table | Fields | Description |
- +======================+======================+=======================+
- | ITEMS | item_ID, | Database table |
- | | description, | describing each item |
- | | cost_price, barcode, | for sale |
- | | supplier_ID, | |
- | | category, …​ | |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- The database table ``ITEMS`` has a row for each items
- that *HyperM* sells. Each item is identified by an
- ``item_ID`` value. The ``description`` field stores a
- description of the item. The cost price of the item is
- given in ``cost_price``. The barcode of the item is
- encoded in ``barcode``, while the item supplier is
- identified by ``supplier_ID``. Items may also be
- classified into categories using the ``category`` field.
- Useful categories might include: ``soft drinks``,
- ``alcoholic drinks``, ``cigarettes``, ``knives``,
- ``confectionery``, ``bakery``, ``fruit&vegetables``,
- ``meat``, etc..
-
-Personnel System: Assistants
-############################
-
- .. table:: Table 4. Assistants Database
-
- +----------------------+----------------------+-----------------------+
- | Table | Fields | Description |
- +======================+======================+=======================+
- | ASSISTANTS | assistant_ID, | Database table |
- | | surname, firstname, | describing each |
- | | middlename, age, | *HyperM* sales |
- | | grade, phone_number, | assistant |
- | | …​ | |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- The database table ``ASSISTANTS`` has a row for each
- sales assistant employed by *HyperM*. Each assistant is
- identified by an ``assistant_ID`` value, with their name
- given in the ``firstname``, ``middlename`` and
- ``surname`` fields. The assistant’s age in years is given
- in ``age``, while their phone number is contained in the
- ``phone_number`` field. The assistant’s grade is encoded
- in ``grade``. Useful values for ``grade`` might include:
- ``trainee``, ``operator``, ``supervisor``, etc..
-
-Locations: Branches
-####################
-
- .. table:: Table 5. Branches Database
-
- +----------------------+----------------------+-----------------------+
- | Table | Fields | Description |
- +======================+======================+=======================+
- | BRANCHES | branch_ID, | Database table |
- | | branch_Name, | describing each |
- | | category, street, | *HyperM* branch |
- | | city, country, | |
- | | postcode, …​ | |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- *HyperM* operates a number of branches. Each branch is
- described in the ``BRANCHES`` database table. Each branch
- is identified by a ``branch_ID``, with a branch name
- given in ``branch_Name``. The address for the branch is
- encoded in ``street``, ``city``, ``country`` and
- ``postcode``. The branch category is given in the
- ``category`` field. Useful values for ``category`` might
- include: ``Small``, ``Large``, ``Super``, ``Hyper``,
- etc..
-
-Policy Step 1
--------------
-
-Scenario
-#########
- .. container:: paragraph
-
- For the first version of our policy, let’s start with
- something simple. Let us assume that there exists some
- restriction that alcohol products cannot be sold before
- 11:30am. In this section we will go through the necessary
- steps to define a policy that can enforce this for
- *HyperM*.
-
- .. container:: ulist
-
- - Alcohol cannot be sold before 11:30am.
-
-Create the an new empty Policy Model ``MyFirstPolicyModel``
-###########################################################
-
- .. container:: paragraph
-
- Since an organisation like *HyperM* may have many
- policies covering many different domains, policies should
- be grouped into policy sets. In order to edit or deploy a
- policy, or policy set, the definition of the policy(ies)
- and all required events, tasks, states, etc., are grouped
- together into a 'Policy Model'. An organization might
- define many Policy Models, each containing a different
- set of policies.
-
- .. container:: paragraph
-
- So the first step is to create a new empty Policy Model
- called ``MyFirstPolicyModel``. Using the APEX Policy
- Editor, click on the 'File' menus and select 'New'. Then
- define our new policy model called
- ``MyFirstPolicyModel``. Use the 'Generate UUID' button to
- create a new unique ID for the policy model, and fill in
- a description for the policy model. Press the ``Submit``
- button to save your changes.
-
- .. container:: imageblock
-
- .. container:: content
-
- |File > New to create a new Policy Model|
-
- .. container:: title
-
- Figure 4. Create a new Policy Model 1/2
-
- .. container:: imageblock
-
- .. container:: content
-
- |Create a new Policy Model|
-
- .. container:: title
-
- Figure 5. Create a new Policy Model 2/2
-
-Create the input event ``SALE_INPUT`` and the output event ``SALE_AUTH``
-########################################################################
-
- .. container:: paragraph
-
- Using the APEX Policy Editor, click on the 'Events' tab.
- In the 'Events' pane, right click and select 'New':
-
- .. container:: imageblock
-
- .. container:: content
-
- |Right click to create a new event|
-
- .. container:: title
-
- Figure 6. Create a new Event type
-
- .. container:: paragraph
-
- Create a new event type called ``SALE_INPUT``. Use the
- 'Generate UUID' button to create a new unique ID for the
- event type, and fill in a description for the event. Add
- a namespace, e.g. ``com.hyperm``. We can add hard-coded
- strings for the ``Source`` and ``Target``, e.g. ``POS``
- and ``APEX``. At this stage we will not add any parameter
- fields, we will leave this until later. Use the
- ``Submit`` button to create the event.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Fill in the necessary information for the
- 'SALE_INPUT' event and click 'Submit'|
-
- .. container:: title
-
- Figure 7. Populate the ``SALE_INPUT`` event
-
- .. container:: paragraph
-
- Repeat the same steps for a new event type called
- ``SALE_AUTH``. Just use ``APEX`` as source and ``POS`` as
- target, since this is the output event coming from APEX
- going to the sales point.
-
- .. container:: paragraph
-
- Before we can add parameter fields to an event we must
- first define APEX Context Item Schemas that can be used
- by those fields.
-
- .. container:: paragraph
-
- To create new item schemas, click on the 'Context Item
- Schemas' tab. In that 'Context Item Schemas' pane, right
- click and select 'Create new ContextSchema'.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Right click to create a new Item Schema|
-
- .. container:: title
-
- Figure 8. Create new Data Types
-
- .. container:: paragraph
-
- Create item schemas with the following characteristics,
- each with its own unique UUID:
-
- .. table:: Table 6. Item Schemas
-
- +-------------------+-----------------+-----------------+----------------------+
- | Name | Schema Flavour | Schema | Description |
- | | | Definition | |
- +===================+=================+=================+======================+
- | timestamp_type | Java | java.lang.Long | A type for |
- | | | | ``time`` values |
- +-------------------+-----------------+-----------------+----------------------+
- | sale_ID_type | Java | java.lang.Long | A type for |
- | | | | ``sale_ID`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | price_type | Java | java.lang.Long | A type for |
- | | | | ``amount``/``price`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | item_ID_type | Java | java.lang.Long | A type for |
- | | | | ``item_ID`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | assistant_ID_type | Java | java.lang.Long | A type for |
- | | | | ``assistant_ID`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | quantity_type | Java | java.lang.Integ | A type for |
- | | | er | ``quantity`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | branch_ID_type | Java | java.lang.Long | A type for |
- | | | | ``branch_ID`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | notes_type | Java | java.lang.Strin | A type for |
- | | | g | ``notes`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | authorised_type | Java | java.lang.Boole | A type for |
- | | | an | ``authorised`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | message_type | Java | java.lang.Strin | A type for |
- | | | g | ``message`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
-
- .. container:: imageblock
-
- .. container:: content
-
- |Create a new Item Schema|
-
- .. container:: title
-
- Figure 9. Create new Item Schemas
-
- .. container:: paragraph
-
- The item schemas can now be seen on the 'Context Item
- Schemas' tab, and can be updated at any time by
- right-clicking on the item schemas on the 'Context Item
- Schemas' tab. Now we can go back to the event definitions
- for ``SALE_INPUT`` and ``SALE_AUTH`` and add some
- parameter fields.
-
- .. tip
-
- .. container:: title
-
- Field Schema types
-
- .. container:: paragraph
-
- APEX natively supports schema definitions in ``Java`` and ``Avro``.
-
- .. container:: paragraph
-
- ``Java`` schema definitions are simply the name of a Java Class. There are some restrictions:
-
- .. container:: ulist
-
- - the class must be instantiatable, i.e. not an Java interface or abstract class
-
- - primitive types are not supported, i.e. use ``java.lang.Integer`` instead of ``int``, etc.
-
- - it must be possible to find the class, i.e. the class must be contained in the Java classpath.
-
- .. container:: paragraph
-
- ``Avro`` schema definitions can be any valid `Avro <https://avro.apache.org/docs/current/spec.html>`__
- schema. For events using fields defined with ``Avro`` schemas, any incoming event containing that field must
- contain a value that conforms to the Avro schema.
-
- .. container:: paragraph
-
- Click on the 'Events' tab, then right click the
- ``SALE_INPUT`` row and select 'Edit Event
- :literal:`SALE_INPUT’. To add a new event parameter use the 'Add Event Parameter' button at the bottom of the screen. For the `SALE_INPUT`
- event add the following event parameters:
-
- .. table:: Table 7. Event Parameter Fields for the ``SALE_INPUT`` Event
-
- +----------------------+----------------------+-----------------------+
- | Parameter Name | Parameter Type | Optional |
- +======================+======================+=======================+
- | time | timestamp_type | no |
- +----------------------+----------------------+-----------------------+
- | sale_ID | sale_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | amount | price_type | no |
- +----------------------+----------------------+-----------------------+
- | item_ID | item_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | quantity | quantity_type | no |
- +----------------------+----------------------+-----------------------+
- | assistant_ID | assistant_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | branch_ID | branch_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | notes | notes_type | *yes* |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- Remember to click the 'Submit' button at the bottom of
- the event definition pane.
-
- .. tip::
- Optional Fields in APEX Events
- Parameter fields can be *optional* in events. If a parameter is not marked as *optional* then by default it
- is *mandatory*, so it must appear in any input event passed to APEX. If an *optional* field is not set
- for an output event then value will be set to ``null``.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Add new event parameters to an event|
-
- .. container:: title
-
- Figure 10. Add typed parameter fields to an event
-
- .. container:: paragraph
-
- Select the ``SALE_AUTH`` event and add the following
- event parameters:
-
- .. table:: Table 8. Event Parameter Fields for the ``SALE_AUTH`` Event
-
- +----------------------+----------------------+-----------------------+
- | Parameter Name | Parameter Type | no |
- +======================+======================+=======================+
- | sale_ID | sale_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | time | timestamp_type | no |
- +----------------------+----------------------+-----------------------+
- | authorised | authorised_type | no |
- +----------------------+----------------------+-----------------------+
- | message | message_type | *yes* |
- +----------------------+----------------------+-----------------------+
- | amount | price_type | no |
- +----------------------+----------------------+-----------------------+
- | item_ID | item_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | assistant_ID | assistant_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | quantity | quantity_type | no |
- +----------------------+----------------------+-----------------------+
- | branch_ID | branch_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | notes | notes_type | *yes* |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- Remember to click the 'Submit' button at the bottom of
- the event definition pane.
-
- .. container:: paragraph
-
- The events for our policy are now defined.
-
-Create a new Policy and add the *"No Booze before 11:30"* check
-###############################################################
-
- .. container:: paragraph
-
- APEX policies are defined using a state-machine model.
- Each policy comprises one or more *states* that can be
- individually executed. Where there is more than one
- *state* the states are chained together to form a
- `Directed Acyclic Graph
- (DAG) <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__
- of states. A *state* is triggered by passing it a single
- input (or 'trigger') event and once executed each state
- then emits an output event. For each *state* the logic
- for the *state* is embedded in one or more *tasks*. Each
- *task* contains specific *task logic* that is executed by
- the APEX execution environment each time the *task* is
- invoked. Where there is more than one *task* in a *state*
- then the *state* also defines some *task selection logic*
- to select an appropriate task each time the *state* is
- executed.
-
- .. container:: paragraph
-
- Therefore, to create a new policy we must first define
- one or more tasks.
-
- .. container:: paragraph
-
- To create a new Task click on the 'Tasks' tab. In the
- 'Tasks' pane, right click and select 'Create new Task'.
- Create a new Task called ``MorningBoozeCheck``. Use the
- 'Generate UUID' button to create a new unique ID for the
- task, and fill in a description for the task.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Right click to create a new task|
-
- .. container:: title
-
- Figure 11. Create a new Task
-
- .. container:: paragraph
-
- Tasks are configured with a set of *input fields* and a
- set of *output fields*. To add new input/output fields
- for a task use the 'Add Task Input Field' and 'Add Task
- Output Field' button. The list of input and out fields to
- add for the ``MorningBoozeCheck`` task are given below.
- The input fields are drawn from the parameters in the
- state’s input event, and the task’s output fields are
- used to populate the state’s output event. The task’s
- input and output fields must be a subset of the event
- parameters defined for the input and output events for
- any state that uses that task. (You may have noticed that
- the input and output fields for the ``MorningBoozeCheck``
- task have the exact same names and reuse the item schemas
- that we used for the parameters in the ``SALE_INPUT`` and
- ``SALE_AUTH`` events respectively).
-
- .. table:: Table 9. Input fields for ``MorningBoozeCheck`` task
-
- +-----------------------------------+-----------------------------------+
- | Parameter Name | Parameter Type |
- +===================================+===================================+
- | time | timestamp_type |
- +-----------------------------------+-----------------------------------+
- | sale_ID | sale_ID_type |
- +-----------------------------------+-----------------------------------+
- | amount | price_type |
- +-----------------------------------+-----------------------------------+
- | item_ID | item_ID_type |
- +-----------------------------------+-----------------------------------+
- | quantity | quantity_type |
- +-----------------------------------+-----------------------------------+
- | assistant_ID | assistant_ID_type |
- +-----------------------------------+-----------------------------------+
- | branch_ID | branch_ID_type |
- +-----------------------------------+-----------------------------------+
- | notes | notes_type |
- +-----------------------------------+-----------------------------------+
-
- .. table:: Table 10. Output fields for ``MorningBoozeCheck`` task
-
- +-----------------------------------+-----------------------------------+
- | Parameter Name | Parameter Type |
- +===================================+===================================+
- | sale_ID | sale_ID_type |
- +-----------------------------------+-----------------------------------+
- | time | timestamp_type |
- +-----------------------------------+-----------------------------------+
- | authorised | authorised_type |
- +-----------------------------------+-----------------------------------+
- | message | message_type |
- +-----------------------------------+-----------------------------------+
- | amount | price_type |
- +-----------------------------------+-----------------------------------+
- | item_ID | item_ID_type |
- +-----------------------------------+-----------------------------------+
- | assistant_ID | assistant_ID_type |
- +-----------------------------------+-----------------------------------+
- | quantity | quantity_type |
- +-----------------------------------+-----------------------------------+
- | branch_ID | branch_ID_type |
- +-----------------------------------+-----------------------------------+
- | notes | notes_type |
- +-----------------------------------+-----------------------------------+
-
- .. container:: imageblock
-
- .. container:: content
-
- |Add input and out fields for the task|
-
- .. container:: title
-
- Figure 12. Add input and out fields for the Task
-
- .. container:: paragraph
-
- Each task must include some 'Task Logic' that implements
- the behaviour for the task. Task logic can be defined in
- a number of different ways using a choice of languages.
- For this task we will author the logic using the
- Java-like scripting language called
- ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__.
-
- .. container:: paragraph
-
- For simplicity use the following code for the task logic.
- Paste the script text into the 'Task Logic' box, and use
- "MVEL" as the 'Task Logic Type / Flavour'.
-
- .. container:: paragraph
-
- This logic assumes that all items with ``item_ID``
- between 1000 and 2000 contain alcohol, which is not very
- realistic, but we will see a better approach for this
- later. It also uses the standard ``Java`` time utilities
- to check if the current time is between ``00:00:00 GMT``
- and ``11:30:00 GMT``. For a detailed guide to how to
- write your own logic in
- ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__,
- ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__ or one
- of the other supported languages please refer to APEX
- Programmers Guide.
-
- .. container:: listingblock
-
- .. container:: title
-
- MVEL code for the ``MorningBoozeCheck`` task
-
- .. container:: content
-
- .. code::
-
- /*
- * ============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:: imageblock
-
- .. container:: content
-
- |Add task logic the task|
-
- .. container:: title
-
- Figure 13. Add Task Logic the Task
-
- .. container:: paragraph
-
- An alternative version of the same logic is available in
- JavaScript. Just use "JAVASCRIPT" as the 'Task Logic Type
- / Flavour' instead.
-
- .. container:: listingblock
-
- .. container:: title
-
- Javascript alternative for the ``MorningBoozeCheck``
- task
-
- .. container:: content
-
- .. code::
-
- /*
- * ============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:: paragraph
-
- The task definition is now complete so click the 'Submit'
- button to save the task. The task can now be seen on the
- 'Tasks' tab, and can be updated at any time by
- right-clicking on the task on the 'Task' tab. Now that we
- have created our task, we can can create a policy that
- uses that task.
-
- .. container:: paragraph
-
- To create a new Policy click on the 'Policies' tab. In
- the 'Policies' pane, right click and select 'Create new
- Policy':
-
- .. container:: paragraph
-
- Create a new Policy called ``MyFirstPolicy``. Use the
- 'Generate UUID' button to create a new unique ID for the
- policy, and fill in a description for the policy. Use
- 'FREEFORM' as the 'Policy Flavour'.
-
- .. container:: paragraph
-
- Each policy must have at least one state. Since this is
- 'freeform' policy we can add as many states as we wish.
- Let’s start with one state. Add a new state called
- ``BoozeAuthDecide`` to this ``MyFirstPolicy`` policy
- using the 'Add new State' button after filling in the
- name of our new state.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Create a new policy|
-
- .. container:: title
-
- Figure 14. Create a new Policy
-
- .. container:: paragraph
-
- Each state must uses one input event type. For this new
- state select the ``SALE_INPUT`` event as the input event.
-
- .. container:: paragraph
-
- Each policy must define a 'First State' and a 'Policy
- Trigger Event'. The 'Policy Trigger Event' is the input
- event for the policy as a whole. This event is then
- passed to the first state in the chain of states in the
- policy, therefore the 'Policy Trigger Event' will be the
- input event for the first state. Each policy can only
- have one 'First State'. For our ``MyFirstPolicy`` policy,
- select ``BoozeAuthDecide`` as the 'First State'. This
- will automatically select ``SALE_INPUT`` as the 'Policy
- Trigger Event' for our policy.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Create a state|
-
- .. container:: title
-
- Figure 15. Create a new State
-
- .. container:: paragraph
-
- In this case we will create a reference the pre-existing
- ``MorningBoozeCheck`` task that we defined above using
- the 'Add New Task' button. Select the
- ``MorningBoozeCheck`` task, and use the name of the task
- as the 'Local Name' for the task.
-
- .. container:: paragraph
-
- in the case where a state references more than one task,
- a 'Default Task' must be selected for the state and some
- logic ('Task Selection Logic') must be specified to
- select the appropriate task at execution time. Since our
- new state ``BoozeAuthDecide`` only has one task the
- default task is automatically selected and no 'Task
- Selection Logic' is required.
-
- .. note::
- .. container:: title
-
- State Output Mappings
-
- .. container:: paragraph
-
- In a 'Policy' 'State' a 'State Output Mapping' has 3 roles:
- 1) Select which 'State' should be executed next, 2) Select
- the type of the state’s 'Outgoing Event', and 3)
- Populate the state’s 'Outgoing Event'. This is how states are
- chained together to form a (`Directed Acyclic Graph
- (DAG) <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__ )
- of states. The final state(s) of a policy are those that do
- not select any 'next' state. Since a 'State' can only
- accept a single type of event, the type of the event emitted
- by a previous 'State' must be match the incoming event type
- of the next 'State'. This is also how the last state(s) in
- a policy can emit events of different types. The 'State
- Output Mapping' is also responsible for taking the
- fields that are output by the task executed in the state and
- populating the state’s output event before it is emitted.
-
- .. container:: paragraph
-
- Each 'Task' referenced in 'State' must have a defined
- 'Output Mapping' to take the output of the task, select an
- 'Outgoing Event' type for the state, populate the state’s
- outgoing event, and then select the next state to be
- executed (if any).
-
- .. container:: paragraph
-
- There are 2 basic types of output mappings:
-
- .. container:: olist arabic
-
- #. **Direct Output Mappings** have a single value for
- 'Next State' and a single value for 'State Output
- Event'. The outgoing event for the state is
- automatically created, any outgoing event parameters
- that were present in the incoming event are copied
- into the outgoing event, then any task output fields
- that have the same name and type as parameters in the
- outgoing event are automatically copied into
- the outgoing event.
-
- #. **Logic-based State Output Mappings / Finalizers**
- have some logic defined that dynamically selects
- and creates the 'State Outgoing Event', manages
- the population of the outgoing event parameters
- (perhaps changing or adding to the outputs from the
- task), and then dynamically selects the next state to
- be executed (if any).
-
- .. container:: paragraph
-
- Each task reference must also have an associated 'Output
- State Mapping' so we need an 'Output State Mapping' for
- the ``BoozeAuthDecide`` state to use when the
- ``MorningBoozeCheck`` task is executed. The simplest type
- of output mapping is a 'Direct Output Mapping'.
-
- .. container:: paragraph
-
- Create a new 'Direct Output Mapping' for the state called
- ``MorningBoozeCheck_Output_Direct`` using the 'Add New
- Direct State Output Mapping' button. Select ``SALE_AUTH``
- as the output event and select ``None`` for the next
- state value. We can then select this output mapping for
- use when the the ``MorningBoozeCheck`` task is executed.
- Since there is only state, and only one task for that
- state, this output mapping ensures that the
- ``BoozeAuthDecide`` state is the only state executed and
- the state (and the policy) can only emit events of type
- ``SALE_AUTH``. (You may remember that the output fields
- for the ``MorningBoozeCheck`` task have the exact same
- names and reuse the item schemas that we used for the
- parameters in ``SALE_AUTH`` event. The
- ``MorningBoozeCheck_Output_Direct`` direct output mapping
- can now automatically copy the values from the
- ``MorningBoozeCheck`` task directly into outgoing
- ``SALE_AUTH`` events.)
-
- .. container:: imageblock
-
- .. container:: content
-
- |Add a Task and Output Mapping|
-
- .. container:: title
-
- Figure 16. Add a Task and Output Mapping
-
- .. container:: paragraph
-
- Click the 'Submit' button to complete the definition of
- our ``MyFirstPolicy`` policy. The policy
- ``MyFirstPolicy`` can now be seen in the list of policies
- on the 'Policies' tab, and can be updated at any time by
- right-clicking on the policy on the 'Policies' tab.
-
- .. container:: paragraph
-
- The ``MyFirstPolicyModel``, including our
- ``MyFirstPolicy`` policy can now be checked for errors.
- Click on the 'Model' menu and select 'Validate'. The
- model should validate without any 'Warning' or 'Error'
- messages. If you see any 'Error' or 'Warning' messages,
- carefully read the message as a hint to find where you
- might have made a mistake when defining some aspect of
- your policy model.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Validate the policy model for error using the 'Model'
- > 'Validate' menu item|
-
- .. container:: title
-
- Figure 17. Validate a Policy Model
-
- .. container:: paragraph
-
- Congratulations, you have now completed your first APEX
- policy. The policy model containing our new policy can
- now be exported from the editor and saved. Click on the
- 'File' menu and select 'Download' to save the policy
- model in JSON format. The exported policy model is then
- available in the directory you selected, for instance
- ``$APEX_HOME/examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json``.
- The exported policy can now be loaded into the APEX
- Policy Engine, or can be re-loaded and edited by the APEX
- Policy Editor.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Download the completed policy model using the 'File'
- > 'Download' menu item|
-
- .. container:: title
-
- Figure 18. Export a Policy Model
-
-Test Policy Step 1
-##################
-
- .. container:: paragraph
-
- To start a new APEX Engine you can use the following
- configuration. In a full APEX installation you can find
- this configuration in
- ``$APEX_HOME/examples/config/MyFirstPolicy/1/MyFirstPolicyConfigStdin2StdoutJsonEvent.json``.
- This configuration expects incoming events to be in
- ``JSON`` format and to be passed into the APEX Engine
- from ``stdin``, and result events will be printed in
- ``JSON`` format to ``stdout``. This configuration loads
- the policy model stored in the file
- 'MyFirstPolicyModel_0.0.1.json' as exported from the APEX
- Editor. Note, you may need to edit this file to provide
- the full path to wherever you stored the exported policy
- model file.
-
- .. container:: listingblock
-
- .. container:: title
-
- JSON to load and execute *My First Policy*, read input
- JSON events from ``stdin``, and emit output events to
- ``stdout``
-
- .. container:: content
-
- .. code::
-
- {
- "engineServiceParameters" : {
- "name" : "MyFirstPolicyApexEngine",
- "version" : "0.0.1",
- "id" : 101,
- "instanceCount" : 4,
- "deploymentPort" : 12345,
- "policyModelFileName" : "examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json",
- "engineParameters" : {
- "executorParameters" : {
- "MVEL" : {
- "parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
- },
- "JAVASCRIPT" : {
- "parameterClassName" : "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"
- }
- }
- }
- },
- "eventOutputParameters": {
- "FirstProducer": {
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "FILE",
- "parameters" : {
- "standardIO" : true
- }
- },
- "eventProtocolParameters" : {
- "eventProtocol" : "JSON"
- }
- }
- },
- "eventInputParameters": {
- "FirstConsumer": {
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "FILE",
- "parameters" : {
- "standardIO" : true
- }
- },
- "eventProtocolParameters" : {
- "eventProtocol" : "JSON"
- }
- }
- }
- }
-
- .. container:: paragraph
-
- To test the policy try paste the following events into
- the console as the APEX engine executes:
-
- .. table:: Table 11. Inputs and Outputs when testing *My First Policy*
-
- +------------------------------------------+-------------------------------------------+-----------+
- | Input Event (JSON) | Output Event (JSON) | comment |
- +==========================================+===========================================+===========+
- | .. container:: | .. container:: | Request |
- | | | to buy a |
- | .. container:: listingblock | .. container:: listingblock | non-alcoh |
- | | | olic |
- | | .. container:: content | item |
- | .. container:: content | | (``item_I |
- | | .. code:: | D=5123``) |
- | | | at |
- | .. code:: | { | *10:13:09 |
- | | "name": "SALE_AUTH", | * |
- | | | on |
- | { | "version": "0.0.1", | *Tuesday, |
- | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | 10 |
- | "name" : "SALE_INPUT", | "source": "", | January |
- | "version": "0.0.1", | "target": "", | 2017*. |
- | "time" : 1483351989000, | "amount": 299, | Sale is |
- | "sale_ID": 99999991, | "assistant_ID": 23, | authorize |
- | "amount": 299, | "authorised": true, | d. |
- | "item_ID": 5123, | "branch_ID": 1, | |
- | "quantity": 1, | "item_ID": 5123, | |
- | "assistant_ID": 23, | "message": "Sale authorised | |
- | "branch_ID": 1, | by policy task MorningBo | |
- | "notes": "Special Offer!!" | ozeCheck for time 10:13:09 | |
- | } | GMT", | |
- | | "notes": "Special Offer!!", | |
- | | "quantity": 1, | |
- | | "sale_ID": 99999991, | |
- | | "time": 1483351989000 | |
- | | } | |
- | | | |
- | | | |
- | | | |
- +------------------------------------------+-------------------------------------------+-----------+
- | .. container:: | .. container:: | Request |
- | | | to buy |
- | .. container:: listingblock | .. container:: listingblock | alcohol |
- | | | item |
- | .. container:: content | .. container:: content | (``item_I |
- | | | D=1249``) |
- | .. code:: | .. code:: | at |
- | | | *08:41:06 |
- | { | { | * |
- | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | on |
- | "name": "SALE_INPUT", | "name": "SALE_AUTH", | *Monday, |
- | "version": "0.0.1", | "source": "", | 02 |
- | "time": 1483346466000, | "target": "", | January |
- | "sale_ID": 99999992, | "amount": 1249, | 2017*. |
- | "version": "0.0.1", | "assistant_ID": 12, | |
- | "amount": 1249, | "authorised": false, | Sale is |
- | "item_ID": 1012, | "branch_ID": 2, | not |
- | "quantity": 1, | "item_ID": 1012, | authorize |
- | "assistant_ID": 12, | "message": "Sale not | d. |
- | "branch_ID": 2 | authorised by policy task | |
- | } | MorningBoozeCheck for time | |
- | | 08:41:06 GMT. Alcohol can | |
- | | not be sold between | |
- | | 00:00:00 GMT and 11:30:00 | |
- | | GMT", | |
- | | "notes": null, | |
- | | "quantity": 1, | |
- | | "sale_ID": 99999992, | |
- | | "time": 1483346466000 | |
- | | } | |
- +------------------------------------------+-------------------------------------------+-----------+
- | .. container:: | .. container:: | Request |
- | | | to buy |
- | .. container:: listingblock | .. container:: listingblock | alcohol |
- | | | (``item_I |
- | | .. container:: content | D=1943``) |
- | .. container:: content | | at |
- | | .. code:: | *20:17:13 |
- | | | * |
- | .. code:: | { | on |
- | | "name": "SALE_AUTH", | *Tuesday, |
- | { | "version": "0.0.1", | 20 |
- | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | December |
- | "name" : "SALE_INPUT", | "source": "", | 2016*. |
- | "version": "0.0.1", | "target": "", | |
- | "time" : 1482265033000, | "amount": 4799, | Sale is |
- | "sale_ID": 99999993, | "assistant_ID": 9, | authorize |
- | "amount": 4799, | "authorised": true, | d. |
- | "item_ID": 1943, | "branch_ID": 3, | |
- | "quantity": 2, | "item_ID": 1943, | |
- | "assistant_ID": 9, | "message": "Sale authorised | |
- | "branch_ID": 3 | by policy task MorningBo | |
- | } | ozeCheck for time 20:17:13 | |
- | | GMT", | |
- | | "notes": null, | |
- | | "quantity": 2, | |
- | | "sale_ID": 99999993, | |
- | | "time": 1482265033000 | |
- | | } | |
- +------------------------------------------+-------------------------------------------+-----------+
-
-4.3.6. Policy 1 in CLI Editor
-#############################
-
- .. container:: paragraph
-
- An equivalent version of the ``MyFirstPolicyModel``
- policy model can again be generated using the APEX CLI
- editor. A sample APEX CLI script is shown below:
-
- .. container:: listingblock
-
- .. container:: title
-
- APEX CLI Editor code for Policy 1
-
- .. container:: content
-
- .. code::
-
- #-------------------------------------------------------------------------------
- # ============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=========================================================
- #-------------------------------------------------------------------------------
-
- model create name=MyFirstPolicyModel version=0.0.1 uuid=540226fb-55ee-4f0e-a444-983a0494818e description="This is my first Apex Policy Model."
-
- schema create name=assistant_ID_type version=0.0.1 uuid=36df4c71-9616-4206-8b53-976a5cd4bd87 description="A type for 'assistant_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=authorised_type version=0.0.1 uuid=d48b619e-d00d-4008-b884-02d76ea4350b description="A type for 'authorised' values" flavour=Java schema=java.lang.Boolean
-
- schema create name=branch_ID_type version=0.0.1 uuid=6468845f-4122-4128-8e49-0f52c26078b5 description="A type for 'branch_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=item_ID_type version=0.0.1 uuid=4f227ff1-aee0-453a-b6b6-9a4b2e0da932 description="A type for 'item_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=message_type version=0.0.1 uuid=ad1431bb-3155-4e73-b5a3-b89bee498749 description="A type for 'message' values" flavour=Java schema=java.lang.String
-
- schema create name=notes_type version=0.0.1 uuid=eecfde90-896c-4343-8f9c-2603ced94e2d description="A type for 'notes' values" flavour=Java schema=java.lang.String
-
- schema create name=price_type version=0.0.1 uuid=52c2fc45-fd8c-463c-bd6f-d91b0554aea7 description="A type for 'amount'/'price' values" flavour=Java schema=java.lang.Long
-
- schema create name=quantity_type version=0.0.1 uuid=ac3d9842-80af-4a98-951c-bd79a431c613 description="A type for 'quantity' values" flavour=Java schema=java.lang.Integer
-
- schema create name=sale_ID_type version=0.0.1 uuid=cca47d74-7754-4a61-b163-ca31f66b157b description="A type for 'sale_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=timestamp_type version=0.0.1 uuid=fd594e88-411d-4a94-b2be-697b3a0d7adf description="A type for 'time' values" flavour=Java schema=java.lang.Long
-
- task create name=MorningBoozeCheck version=0.0.1 uuid=3351b0f4-cf06-4fa2-8823-edf67bd30223 description=LS
- This task checks if the sales request is for an item that contains alcohol.
- If the local time is between 00:00:00 and 11:30:00 then the sale is not authorised. Otherwise the sale is authorised.
- In this implementation we assume that all items with item_ID values between 1000 and 2000 contain alcohol :-)
- LE
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true
- task logic create name=MorningBoozeCheck version=0.0.1 logicFlavour=MVEL logic=LS
- /*
- * ============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 :-)
- */
- LE
-
- event create name=SALE_AUTH version=0.0.1 uuid=c4500941-3f98-4080-a9cc-5b9753ed050b description="An event emitted by the Policy to indicate whether the sale of an item has been authorised" nameSpace=com.hyperm source="APEX" target="POS"
- event parameter create name=SALE_AUTH version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=authorised schemaName=authorised_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=message schemaName=message_type schemaVersion=0.0.1 optional=true
- event parameter create name=SALE_AUTH version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- event parameter create name=SALE_AUTH version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1
-
- event create name=SALE_INPUT version=0.0.1 uuid=4f04aa98-e917-4f4a-882a-c75ba5a99374 description="An event raised by the PoS system each time an item is scanned for purchase" nameSpace=com.hyperm source="POS" target="APEX"
- event parameter create name=SALE_INPUT version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- event parameter create name=SALE_INPUT version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1
-
-
- policy create name=MyFirstPolicy version=0.0.1 uuid=6c5e410f-489a-46ff-964e-982ce6e8b6d0 description="This is my first Apex policy. It checks if a sale should be authorised or not." template=FREEFORM firstState=BoozeAuthDecide
- policy state create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide triggerName=SALE_INPUT triggerVersion=0.0.1 defaultTaskName=MorningBoozeCheck defaultTaskVersion=0.0.1
- policy state output create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide outputName=MorningBoozeCheck_Output_Direct eventName=SALE_AUTH eventVersion=0.0.1 nextState=NULL
- policy state taskref create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide taskLocalName=MorningBoozeCheck taskName=MorningBoozeCheck taskVersion=0.0.1 outputType=DIRECT outputName=MorningBoozeCheck_Output_Direct
-
-Policy Step 2
--------------
-
-Scenario
-#########
- .. container:: paragraph
-
- *HyperM* have just opened a new branch in a different
- country, but that country has different rules about when
- alcohol can be sold! In this section we will go through
- the necessary steps to extend our policy to enforce this
- for *HyperM*.
-
- .. container:: ulist
-
- - In some branches alcohol cannot be sold before 1pm,
- and not at all on Sundays.
-
- .. container:: paragraph
-
- Although there are a number of ways to accomplish this
- the easiest approach for us is to define another task and
- then select which task is appropriate at runtime
- depending on the branch identifier in the incoming event.
-
-Extend the Policy with the new Scenario
-#######################################
-
- .. container:: paragraph
-
- To create a new Task click on the 'Tasks' tab. In the
- 'Tasks' pane, right click and select 'Create new Task':
-
- .. container:: paragraph
-
- Create a new Task called ``MorningBoozeCheckAlt1``. Use
- the 'Generate UUID' button to create a new unique ID for
- the task, and fill in a description for the task. Select
- the same input and output fields that we used earlier
- when we defined the ``MorningBoozeCheck`` task earlier.
-
- .. table:: Table 12. Input fields for ``MorningBoozeCheckAlt1`` task
-
- +-----------------------------------+-----------------------------------+
- | Parameter Name | Parameter Type |
- +===================================+===================================+
- | time | timestamp_type |
- +-----------------------------------+-----------------------------------+
- | sale_ID | sale_ID_type |
- +-----------------------------------+-----------------------------------+
- | amount | price_type |
- +-----------------------------------+-----------------------------------+
- | item_ID | item_ID_type |
- +-----------------------------------+-----------------------------------+
- | quantity | quantity_type |
- +-----------------------------------+-----------------------------------+
- | assistant_ID | assistant_ID_type |
- +-----------------------------------+-----------------------------------+
- | branch_ID | branch_ID_type |
- +-----------------------------------+-----------------------------------+
- | notes | notes_type |
- +-----------------------------------+-----------------------------------+
-
- .. table:: Table 13. Output fields for ``MorningBoozeCheckAlt1`` task
-
- +-----------------------------------+-----------------------------------+
- | Parameter Name | Parameter Type |
- +===================================+===================================+
- | sale_ID | sale_ID_type |
- +-----------------------------------+-----------------------------------+
- | time | timestamp_type |
- +-----------------------------------+-----------------------------------+
- | authorised | authorised_type |
- +-----------------------------------+-----------------------------------+
- | message | message_type |
- +-----------------------------------+-----------------------------------+
- | amount | price_type |
- +-----------------------------------+-----------------------------------+
- | item_ID | item_ID_type |
- +-----------------------------------+-----------------------------------+
- | assistant_ID | assistant_ID_type |
- +-----------------------------------+-----------------------------------+
- | quantity | quantity_type |
- +-----------------------------------+-----------------------------------+
- | branch_ID | branch_ID_type |
- +-----------------------------------+-----------------------------------+
- | notes | notes_type |
- +-----------------------------------+-----------------------------------+
-
- .. container:: paragraph
-
- This task also requires some 'Task Logic' to implement
- the new behaviour for this task.
-
- .. container:: paragraph
-
- For simplicity use the following code for the task logic.
- It again assumes that all items with ``item_ID`` between
- 1000 and 2000 contain alcohol. We again use the standard
- ``Java`` time utilities to check if the current time is
- between ``00:00:00 CET`` and ``13:00:00 CET`` or if it is
- ``Sunday``.
-
- .. container:: paragraph
-
- For this task we will again author the logic using the
- ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__
- scripting language. Sample task logic code (specified in
- ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__) is
- given below. For a detailed guide to how to write your
- own logic in
- ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__,
- ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__ or one
- of the other supported languages please refer to APEX
- Programmers Guide.
-
- .. container:: listingblock
-
- .. container:: title
-
- MVEL code for the ``MorningBoozeCheckAlt1`` task
-
- .. container:: content
-
- .. code::
-
- /*
- * ============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 Event: '"+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 CET timezone!
- cet = TimeZone.getTimeZone("CET");
- timenow = Calendar.getInstance(cet);
- df = new SimpleDateFormat("HH:mm:ss z");
- df.setTimeZone(cet);
- 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);
- onepm = timenow.clone();
- onepm.set(
- timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
- timenow.get(Calendar.DATE),13,0,0);
-
- itemisalcohol = false;
- if(item_id != null && item_id >=1000 && item_id < 2000)
- itemisalcohol = true;
-
- if( itemisalcohol &&
- ( (timenow.after(midnight) && timenow.before(onepm))
- ||
- (timenow.get(Calendar.DAY_OF_WEEK) == Calendar.SUNDAY)
- )){
- 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(onepm.getTime()) +" or on Sunday");
- 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 CET and 13:00:00 CET then the sale is not authorised.
- Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised.
- In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks :-)
- */
-
- .. container:: imageblock
-
- .. container:: content
-
- |Create a new alternative task MorningBoozeCheckAlt1|
-
- .. container:: title
-
- Figure 19. Create a new Task
-
- .. container:: paragraph
-
- The task definition is now complete so click the 'Submit'
- button to save the task. Now that we have created our
- task, we can can add this task to the single pre-existing
- state (``BoozeAuthDecide``) in our policy.
-
- .. container:: paragraph
-
- To edit the ``BoozeAuthDecide`` state in our policy click
- on the 'Policies' tab. In the 'Policies' pane, right
- click on our ``MyFirstPolicy`` policy and select 'Edit'.
- Navigate to the ``BoozeAuthDecide`` state in the 'states'
- section at the bottom of the policy definition pane.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Right click to edit a policy|
-
- .. container:: title
-
- Figure 20. Edit a Policy
-
- .. container:: paragraph
-
- To add our new task ``MorningBoozeCheckAlt1``, scroll
- down to the ``BoozeAuthDecide`` state in the 'States'
- section. In the 'State Tasks' section for
- ``BoozeAuthDecide`` use the 'Add new task' button. Select
- our new ``MorningBoozeCheckAlt1`` task, and use the name
- of the task as the 'Local Name' for the task. The
- ``MorningBoozeCheckAlt1`` task can reuse the same
- ``MorningBoozeCheck_Output_Direct`` 'Direct State Output
- Mapping' that we used for the ``MorningBoozeCheck`` task.
- (Recall that the role of the 'State Output Mapping' is to
- select the output event for the state, and select the
- next state to be executed. These both remain the same as
- before.)
-
- .. container:: paragraph
-
- Since our state has more than one task we must define
- some logic to determine which task should be used each
- time the state is executed. This *task selection logic*
- is defined in the state definition. For our
- ``BoozeAuthDecide`` state we want the choice of which
- task to use to be based on the ``branch_ID`` from which
- the ``SALE_INPUT`` event originated. For simplicity sake
- let us assume that branches with ``branch_ID`` between
- ``0`` and ``999`` should use the ``MorningBoozeCheck``
- task, and the branches with with ``branch_ID`` between
- ``1000`` and ``1999`` should use the
- ``MorningBoozeCheckAlt1`` task.
-
- .. container:: paragraph
-
- This time, for variety, we will author the task selection
- logic using the
- ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__
- scripting language. Sample task selection logic code
- (specified in
- ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__)
- is given below. Paste the script text into the 'Task
- Selection Logic' box, and use "JAVASCRIPT" as the 'Task
- Selection Logic Type / Flavour'. It is necessary to mark
- one of the tasks as the 'Default Task' so that the task
- selection logic always has a fallback default option in
- cases where a particular task cannot be selected. In this
- case the ``MorningBoozeCheck`` task can be the default
- task.
-
- .. container:: listingblock
-
- .. container:: title
-
- JavaScript code for the ``BoozeAuthDecide`` task
- selection logic
-
- .. container:: content
-
- .. code::
-
- /*
- * ============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:: imageblock
-
- .. container:: content
-
- |State definition with 2 Tasks and Task Selection
- Logic|
-
- .. container:: title
-
- Figure 21. State definition with 2 Tasks and Task
- Selection Logic
-
- .. container:: paragraph
-
- When complete don’t forget to click the 'Submit' button
- at the bottom of 'Policies' pane for our
- ``MyFirstPolicy`` policy after updating the
- ``BoozeAuthDecide`` state.
-
- .. container:: paragraph
-
- Congratulations, you have now completed the second step
- towards your first APEX policy. The policy model
- containing our new policy can again be validated and
- exported from the editor and saved as shown in Step 1.
-
- .. container:: paragraph
-
- The exported policy model is then available in the
- directory you selected, as
- `MyFirstPolicyModel_0.0.1.json <files/mfp-files/2/MyFirstPolicyModel_0.0.1.json>`__.
- The exported policy can now be loaded into the APEX
- Policy Engine, or can be re-loaded and edited by the APEX
- Policy Editor.
-
-Test Policy Step 2
-##################
-
- .. container:: paragraph
-
- To start a new APEX Engine you can use the following
- configuration. In a full APEX installation you can find
- this configuration in
- ``$APEX_HOME/examples/config/MyFirstPolicy/2/MyFirstPolicyConfigStdin2StdoutJsonEvent.json``.
- Note, this has changed from the configuration file in
- Step 1 to enable the ``JAVASCRIPT`` executor for our new
- 'Task Selection Logic'.
-
- .. container:: listingblock
-
- .. container:: title
-
- JSON to load and execute *My First Policy*, read input
- JSON events from ``stdin``, and emit output events to
- ``stdout``
-
- .. container:: content
-
- .. code::
-
- {
- "engineServiceParameters" : {
- "name" : "MyFirstPolicyApexEngine",
- "version" : "0.0.1",
- "id" : 102,
- "instanceCount" : 4,
- "deploymentPort" : 12345,
- "policyModelFileName" : "examples/models/MyFirstPolicy/2/MyFirstPolicyModel_0.0.1.json",
- "engineParameters" : {
- "executorParameters" : {
- "MVEL" : {
- "parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
- },
- "JAVASCRIPT" : {
- "parameterClassName" : "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"
- }
- }
- }
- },
- "eventOutputParameters": {
- "FirstProducer": {
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "FILE",
- "parameters" : {
- "standardIO" : true
- }
- },
- "eventProtocolParameters" : {
- "eventProtocol" : "JSON"
- }
- }
- },
- "eventInputParameters": {
- "FirstConsumer": {
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "FILE",
- "parameters" : {
- "standardIO" : true
- }
- },
- "eventProtocolParameters" : {
- "eventProtocol" : "JSON"
- }
- }
- }
- }
-
- .. container:: paragraph
-
- To test the policy try paste the following events into
- the console as the APEX engine executes. Note, all tests
- from Step 1 will still work perfectly since none of those
- events originate from a branch with ``branch_ID`` between
- ``1000`` and ``2000``. The 'Task Selection Logic' will
- therefore pick the ``MorningBoozeCheck`` task as
- expected, and will therefore give the same results.
-
- .. table:: Table 14. Inputs and Outputs when testing *My First Policy*
-
- +----------------------------------------------+------------------------------------------------------------+---------------------------+
- | Input Event (JSON) | Output Event (JSON) | comment |
- +==============================================+============================================================+===========================+
- | .. container:: | .. container:: | Request to buy |
- | | | alcohol item |
- | .. container:: listingblock | .. container:: listingblock | (``item_ID=1249``) |
- | | | |
- | | | at *08:41:06 |
- | | .. container:: content | GMT* on *Monday, |
- | .. container:: content | | 02 January |
- | | .. code:: | 2017*. |
- | | | |
- | | { | Sale is not |
- | .. code:: | "nameSpace": "com.hyperm", | authorized. Uses |
- | | "name": "SALE_AUTH", | the |
- | | "version": "0.0.1", | ``MorningBoozeCheck`` |
- | { | "source": "", | |
- | "nameSpace": "com.hyperm", | "target": "", | task. |
- | "name": "SALE_INPUT", | "amount": 1249, | |
- | "version": "0.0.1", | "assistant_ID":12, | Note this test |
- | "time": 1483346466000, | "authorised": false, | is copied from |
- | "sale_ID": 99999992, | "branch_ID": 2, | Step 1 above, |
- | "amount": 1249, | "item_ID": 1012, | and demonstrates |
- | "item_ID": 1012, | "message": "Sale not authorised by policy ta | that the |
- | "quantity": 1, | sk MorningBoozeCheck for time 08:41:06 GMT.| original |
- | "assistant_ID": 12, | Alcohol can not be sold between 00:00:00 | ``MorningBoozeCheck`` |
- | "branch_ID": 2 | GMT and 11:30:00 GMT", | |
- | } | "notes": null, | task is |
- | | "quantity": 1, | executed. |
- | | "sale_ID": 99999992, | |
- | | "time": 1483346466000 | |
- | | } | |
- +----------------------------------------------+------------------------------------------------------------+---------------------------+
- | .. container:: | .. container:: | Request to buy |
- | | | alcohol |
- | .. container:: listingblock | .. container:: listingblock | (``item_ID=1047``) |
- | | | |
- | | | at *10:14:33* on |
- | | .. container:: content | *Thursday, 22 |
- | .. container:: content | | December 2016*. |
- | | .. code:: | |
- | | | Sale is not |
- | | { | authorized. Uses |
- | .. code:: | "nameSpace" : "com.hyperm", | the |
- | | "name" : "SALE_AUTH", | ``MorningBoozeCheckAlt1`` |
- | | "version" : "0.0.1", | task. |
- | { | "source" : "", | |
- | | "target" : "", | |
- | "nameSpace": "com.hyperm", | "sale_ID" : 99999981, | |
- | "name": "SALE_INPUT", | "amount" : 299, | |
- | "version": "0.0.1", | "assistant_ID": 1212, | |
- | "time": 1482398073000, | "notes" : null, | |
- | "sale_ID": 99999981, | "quantity" : 1, | |
- | "amount": 299, | "branch_ID" : 1002, | |
- | "item_ID": 1047, | "item_ID" : 1047, | |
- | "quantity": 1, | "authorised" : false, | |
- | "assistant_ID": 1212, | "time" : 1482398073000, | |
- | "branch_ID": 1002 | "message" : "Sale not authorised by policy t | |
- | } | ask MorningBoozeCheckAlt1 fortime | |
- | | 10:14:33 CET. Alcohol can not be sold | |
- | | between 00:00:00 CET and 13:00:00 CET or on | |
- | | Sunday" | |
- | | } | |
- +----------------------------------------------+------------------------------------------------------------+---------------------------+
- | .. container:: | .. container:: | Request to buy |
- | | | alcohol |
- | .. container:: listingblock | .. container:: listingblock | (``item_ID=1443``) |
- | | | |
- | | | at *17:19:37* on |
- | | .. container:: content | *Sunday, 18 |
- | .. container:: content | | December 2016*. |
- | | .. code:: | |
- | | | Sale is not |
- | | { | authorized. Uses |
- | .. code:: | "nameSpace" : "com.hyperm", | the |
- | | | ``MorningBoozeCheckAlt1`` |
- | | "name" : "SALE_AUTH", | task. |
- | { | | |
- | "nameSpace": "com.hyperm", | "version" : "0.0.1", | |
- | "name": "SALE_INPUT", | "source" : "", | |
- | "version": "0.0.1", | "target" : "", | |
- | "time": 1482077977000, | "sale_ID" : 99999982, | |
- | "sale_ID": 99999982, | "amount" : 2199, | |
- | "amount": 2199, | "assistant_ID" : 94, | |
- | "item_ID": 1443, | "notes" : "Buy 3, get 1 free!!", | |
- | "quantity": 12, | "quantity" : 12, | |
- | "assistant_ID": 94, | "branch_ID" : 1003, | |
- | "branch_ID": 1003, | "item_ID" : 1443, | |
- | "notes": "Buy 3, get 1 free!!" | "authorised" : false, | |
- | } | "time" : 1482077977000, | |
- | | "message" : "Sale not authorised by policy t | |
- | | ask MorningBoozeCheckAlt1 for | |
- | | time 17:19:37 CET. Alcohol c | |
- | | an not be sold between 00:00: | |
- | | 00 CET and 13:00:00 CET or on | |
- | | Sunday" | |
- +----------------------------------------------+------------------------------------------------------------+---------------------------+
- | .. container:: | .. container:: | Request to buy |
- | | | non-alcoholic |
- | .. container:: listingblock | .. container:: listingblock | item |
- | | | (``item_ID=5321``) |
- | | | |
- | | .. container:: content | at *11:13:09* on |
- | .. container:: content | | *Monday, 2 |
- | | .. code:: | January 2017*. |
- | | | |
- | | { | Sale is |
- | .. code:: | "nameSpace" : "com.hyperm", | authorized. Uses |
- | | "name" : "SALE_AUTH", | the |
- | { | "version" : "0.0.1", | ``MorningBoozeCheckAlt1`` |
- | "nameSpace": "com.hyperm", | "source" : "", | task. |
- | "name": "SALE_INPUT", | "target" : "", | |
- | "version": "0.0.1", | "sale_ID" : 99999983, | |
- | "time": 1483351989000, | "amount" : 699, | |
- | "sale_ID": 99999983, | "assistant_ID" : 2323, | |
- | "amount": 699, | "notes" : "", | |
- | "item_ID": 5321, | "quantity" : 1, | |
- | "quantity": 1, | "branch_ID" : 1001, | |
- | "assistant_ID": 2323, | "item_ID" : 5321, | |
- | "branch_ID": 1001, | "authorised" : true, | |
- | "notes": "" | "time" : 1483351989000, | |
- | } | "message" : "Sale authorised by policy task | |
- | | MorningBoozeCheckAlt1 for time 11:13:09 CET"| |
- | | } | |
- +----------------------------------------------+------------------------------------------------------------+---------------------------+
-
-Policy 2 in CLI Editor
-######################
-
- .. container:: paragraph
-
- An equivalent version of the ``MyFirstPolicyModel``
- policy model can again be generated using the APEX CLI
- editor. A sample APEX CLI script is shown below:
-
- .. container:: listingblock
-
- .. container:: title
-
- APEX CLI Editor code for Policy 2
-
- .. container:: content
-
- .. code::
-
- #-------------------------------------------------------------------------------
- # ============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=========================================================
- #-------------------------------------------------------------------------------
-
- model create name=MyFirstPolicyModel version=0.0.1 uuid=540226fb-55ee-4f0e-a444-983a0494818e description="This is my first Apex Policy Model."
-
- schema create name=assistant_ID_type version=0.0.1 uuid=36df4c71-9616-4206-8b53-976a5cd4bd87 description="A type for 'assistant_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=authorised_type version=0.0.1 uuid=d48b619e-d00d-4008-b884-02d76ea4350b description="A type for 'authorised' values" flavour=Java schema=java.lang.Boolean
-
- schema create name=branch_ID_type version=0.0.1 uuid=6468845f-4122-4128-8e49-0f52c26078b5 description="A type for 'branch_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=item_ID_type version=0.0.1 uuid=4f227ff1-aee0-453a-b6b6-9a4b2e0da932 description="A type for 'item_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=message_type version=0.0.1 uuid=ad1431bb-3155-4e73-b5a3-b89bee498749 description="A type for 'message' values" flavour=Java schema=java.lang.String
-
- schema create name=notes_type version=0.0.1 uuid=eecfde90-896c-4343-8f9c-2603ced94e2d description="A type for 'notes' values" flavour=Java schema=java.lang.String
-
- schema create name=price_type version=0.0.1 uuid=52c2fc45-fd8c-463c-bd6f-d91b0554aea7 description="A type for 'amount'/'price' values" flavour=Java schema=java.lang.Long
-
- schema create name=quantity_type version=0.0.1 uuid=ac3d9842-80af-4a98-951c-bd79a431c613 description="A type for 'quantity' values" flavour=Java schema=java.lang.Integer
-
- schema create name=sale_ID_type version=0.0.1 uuid=cca47d74-7754-4a61-b163-ca31f66b157b description="A type for 'sale_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=timestamp_type version=0.0.1 uuid=fd594e88-411d-4a94-b2be-697b3a0d7adf description="A type for 'time' values" flavour=Java schema=java.lang.Long
-
- task create name=MorningBoozeCheck version=0.0.1 uuid=3351b0f4-cf06-4fa2-8823-edf67bd30223 description=LS
- This task checks if the sales request is for an item that contains alcohol.
- If the local time is between 00:00:00 and 11:30:00 then the sale is not authorised. Otherwise the sale is authorised.
- In this implementation we assume that all items with item_ID values between 1000 and 2000 contain alcohol :-)
- LE
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true
- task logic create name=MorningBoozeCheck version=0.0.1 logicFlavour=MVEL logic=LS
- /*
- * ============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 :-)
- */
- LE
-
- task create name=MorningBoozeCheckAlt1 version=0.0.1 uuid=bc6d90c9-c902-4686-afd3-925b30e39990 description=LS
- 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 CET and 13:00:00 CET then the sale is not authorised.
- Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised.
- In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks
- LE
- task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true
- task logic create name=MorningBoozeCheckAlt1 version=0.0.1 logicFlavour=MVEL logic=LS
- /*
- * ============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 Event: '"+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 CET timezone!
- cet = TimeZone.getTimeZone("CET");
- timenow = Calendar.getInstance(cet);
- df = new SimpleDateFormat("HH:mm:ss z");
- df.setTimeZone(cet);
- 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);
- onepm = timenow.clone();
- onepm.set(
- timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
- timenow.get(Calendar.DATE),13,0,0);
-
- itemisalcohol = false;
- if(item_id != null && item_id >=1000 && item_id < 2000)
- itemisalcohol = true;
-
- if( itemisalcohol &&
- ( (timenow.after(midnight) && timenow.before(onepm))
- ||
- (timenow.get(Calendar.DAY_OF_WEEK) == Calendar.SUNDAY)
- )){
- 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(onepm.getTime()) +" or on Sunday");
- 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 CET and 13:00:00 CET then the sale is not authorised.
- Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised.
- In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks :-)
- */
- LE
-
- event create name=SALE_AUTH version=0.0.1 uuid=c4500941-3f98-4080-a9cc-5b9753ed050b description="An event emitted by the Policy to indicate whether the sale of an item has been authorised" nameSpace=com.hyperm source="APEX" target="POS"
- event parameter create name=SALE_AUTH version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=authorised schemaName=authorised_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=message schemaName=message_type schemaVersion=0.0.1 optional=true
- event parameter create name=SALE_AUTH version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- event parameter create name=SALE_AUTH version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1
-
- event create name=SALE_INPUT version=0.0.1 uuid=4f04aa98-e917-4f4a-882a-c75ba5a99374 description="An event raised by the PoS system each time an item is scanned for purchase" nameSpace=com.hyperm source="POS" target="APEX"
- event parameter create name=SALE_INPUT version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- event parameter create name=SALE_INPUT version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1
-
-
- policy create name=MyFirstPolicy version=0.0.1 uuid=6c5e410f-489a-46ff-964e-982ce6e8b6d0 description="This is my first Apex policy. It checks if a sale should be authorised or not." template=FREEFORM firstState=BoozeAuthDecide
- policy state create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide triggerName=SALE_INPUT triggerVersion=0.0.1 defaultTaskName=MorningBoozeCheck defaultTaskVersion=0.0.1
- policy state output create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide outputName=MorningBoozeCheck_Output_Direct eventName=SALE_AUTH eventVersion=0.0.1 nextState=NULL
- policy state taskref create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide taskLocalName=MorningBoozeCheckAlt1 taskName=MorningBoozeCheckAlt1 taskVersion=0.0.1 outputType=DIRECT outputName=MorningBoozeCheck_Output_Direct
- policy state taskref create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide taskLocalName=MorningBoozeCheck taskName=MorningBoozeCheck taskVersion=0.0.1 outputType=DIRECT outputName=MorningBoozeCheck_Output_Direct
- policy state selecttasklogic create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide logicFlavour=JAVASCRIPT logic=LS
- /*
- * ============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"
- */
- LE
-
-APEX Logging
-^^^^^^^^^^^^
-
-Introduction to APEX Logging
-----------------------------
-
- .. container:: paragraph
-
- All APEX components make extensive use of logging using the
- logging façade `SLF4J <https://www.slf4j.org/>`__ with the
- backend `Logback <https://logback.qos.ch/>`__. Both are used
- off-the-shelve, so the standard documentation and
- configuration apply to APEX logging. For details on how to
- work with logback please see the `logback
- manual <https://logback.qos.ch/manual/index.html>`__.
-
- .. container:: paragraph
-
- The APEX applications is the logback configuration file
- ``$APEX_HOME/etc/logback.xml`` (Windows:
- ``%APEX_HOME%\etc\logback.xml``). The logging backend is set
- to no debug, i.e. logs from the logging framework should be
- hidden at runtime.
-
- .. container:: paragraph
-
- The configurable log levels work as expected:
-
- .. container:: ulist
-
- - *error* (or *ERROR*) is used for serious errors in the
- APEX runtime engine
-
- - *warn* (or *WARN*) is used for warnings, which in general
- can be ignored but might indicate some deeper problems
-
- - *info* (or *INFO*) is used to provide generally
- interesting messages for startup and policy execution
-
- - *debug* (or *DEBUG*) provides more details on startup and
- policy execution
-
- - *trace* (or *TRACE*) gives full details on every aspect
- of the APEX engine from start to end
-
- .. container:: paragraph
-
- The loggers can also be configured as expected. The standard
- configuration (after installing APEX) uses log level *info*
- on all APEX classes (components).
-
- .. container:: paragraph
-
- The applications and scripts in ``$APEX_HOME/bin`` (Windows:
- ``%APEX_HOME\bin``) are configured to use the logback
- configuration ``$APEX_HOME/etc/logback.xml`` (Windows:
- ``%APEX_HOME\etc\logback.xml``). There are multiple ways to
- use different logback configurations, for instance:
-
- .. container:: ulist
-
- - Maintain multiple configurations in ``etc``, for instance
- a ``logback-debug.xml`` for deep debugging and a
- ``logback-production.xml`` for APEX in production mode,
- then copy the required configuration file to the used
- ``logback.xml`` prior starting APEX
-
- - Edit the scripts in ``bin`` to use a different logback
- configuration file (only recommended if you are familiar
- with editing bash scripts or windows batch files)
-
-Standard Logging Configuration
-------------------------------
-
- .. container:: paragraph
-
- The standard logging configuration defines a context *APEX*,
- which is used in the standard output pattern. The location
- for log files is defined in the property ``VAR_LOG`` and set
- to ``/var/log/onap/policy/apex-pdp``. The standard status
- listener is set to *NOP* and the overall logback
- configuration is set to no debug.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- <configuration debug="false">
- <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
-
- <contextName>Apex</contextName>
- <property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />
-
- ...appenders
- ...loggers
- </configuration>
-
-.. container:: paragraph
-
- The first appender defined is called ``STDOUT`` for logs to standard
- out.
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
- <encoder>
- <Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern>
- </encoder>
- </appender>
-
-.. container:: paragraph
-
- The root level logger then is set to the level *info* using the
- standard out appender.
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- <root level="info">
- <appender-ref ref="STDOUT" />
- </root>
-
-.. container:: paragraph
-
- The second appender is called ``FILE``. It writes logs to a file
- ``apex.log``.
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- <appender name="FILE" class="ch.qos.logback.core.FileAppender">
- <file>${VAR_LOG}/apex.log</file>
- <encoder>
- <pattern>%d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full}</pattern>
- </encoder>
- </appender>
-
-.. container:: paragraph
-
- The third appender is called ``CTXT_FILE``. It writes logs to a file
- ``apex_ctxt.log``.
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- <appender name="CTXT_FILE" class="ch.qos.logback.core.FileAppender">
- <file>${VAR_LOG}/apex_ctxt.log</file>
- <encoder>
- <pattern>%d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full}</pattern>
- </encoder>
- </appender>
-
-.. container:: paragraph
-
- The last definitions are for specific loggers. The first logger
- captures all standard APEX classes. It is configured for log level
- *info* and uses the standard output and file appenders. The second
- logger captures APEX context classes responsible for context
- monitoring. It is configured for log level *trace* and uses the
- context file appender.
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
-
- <logger name="org.onap.policy.apex" level="info" additivity="false">
- <appender-ref ref="STDOUT" />
- <appender-ref ref="FILE" />
- </logger>
-
- <logger name="org.onap.policy.apex.core.context.monitoring" level="TRACE" additivity="false">
- <appender-ref ref="CTXT_FILE" />
- </logger>
-
-Adding Logback Status and Debug
--------------------------------
-
- .. container:: paragraph
-
- To activate logback status messages change the status listener
- from 'NOP' to for instance console.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" />
-
- .. container:: paragraph
-
- To activate all logback debugging, for instance to debug a new
- logback configuration, activate the debug attribute in the
- configuration.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <configuration debug="true">
- ...
- </configuration>
-
-Logging External Components
----------------------------
-
- .. container:: paragraph
-
- Logback can also be configured to log any other, external
- components APEX is using, if they are using the common logging
- framework.
-
- .. container:: paragraph
-
- For instance, the context component of APEX is using *Infinispan*
- and one can add a logger for this external component. The
- following example adds a logger for *Infinispan* using the
- standard output appender.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <logger name="org.infinispan" level="INFO" additivity="false">
- <appender-ref ref="STDOUT" />
- </logger>
-
- .. container:: paragraph
-
- Another example is Apache Zookeeper. The following example adds a
- logger for Zookeeper using the standard outout appender.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <logger name="org.apache.zookeeper.ClientCnxn" level="INFO" additivity="false">
- <appender-ref ref="STDOUT" />
- </logger>
-
-Configuring loggers for Policy Logic
-------------------------------------
-
- .. container:: paragraph
-
- The logging for the logic inside a policy (task logic, task
- selection logic, state finalizer logic) can be configured separate
- from standard logging. The logger for policy logic is
- ``org.onap.policy.apex.executionlogging``. The following example
- defines
-
- .. container:: ulist
-
- - a new appender for standard out using a very simple pattern
- (simply the actual message)
-
- - a logger for policy logic to standard out using the new
- appender and the already described file appender.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender">
- <encoder>
- <pattern>policy: %msg\n</pattern>
- </encoder>
- </appender>
-
- <logger name="org.onap.policy.apex.executionlogging" level="info" additivity="false">
- <appender-ref ref="POLICY_APPENDER_STDOUT" />
- <appender-ref ref="FILE" />
- </logger>
-
- .. container:: paragraph
-
- It is also possible to use specific logging for parts of policy
- logic. The following example defines a logger for task logic.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <logger name="org.onap.policy.apex.executionlogging.TaskExecutionLogging" level="TRACE" additivity="false">
- <appender-ref ref="POLICY_APPENDER_STDOUT" />
- </logger>
-
-Rolling File Appenders
-----------------------
-
- .. container:: paragraph
-
- Rolling file appenders are a good option for more complex logging
- of a production or complex testing APEX installation. The standard
- logback configuration can be used for these use cases. This
- section gives two examples for the standard logging and for
- context logging.
-
- .. container:: paragraph
-
- First the standard logging. The following example defines a
- rolling file appender. The appender rolls over on a daily basis.
- It allows for a file size of 100 MB.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
- <file>${VAR_LOG}/apex.log</file>
- <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
- <!-- rollover daily -->
- <!-- <fileNamePattern>xstream-%d{yyyy-MM-dd}.%i.txt</fileNamePattern> -->
- <fileNamePattern>${VAR_LOG}/apex_%d{yyyy-MM-dd}.%i.log.gz
- </fileNamePattern>
- <maxHistory>4</maxHistory>
- <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
- <!-- or whenever the file size reaches 100MB -->
- <maxFileSize>100MB</maxFileSize>
- </timeBasedFileNamingAndTriggeringPolicy>
- </rollingPolicy>
- <encoder>
- <pattern>
- %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %ex{full} %n
- </pattern>
- </encoder>
- </appender>
-
- .. container:: paragraph
-
- A very similar configuration can be used for a rolling file
- appender logging APEX context.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <appender name="CTXT-FILE"
- class="ch.qos.logback.core.rolling.RollingFileAppender">
- <file>${VAR_LOG}/apex_ctxt.log</file>
- <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
- <fileNamePattern>${VAR_LOG}/apex_ctxt_%d{yyyy-MM-dd}.%i.log.gz
- </fileNamePattern>
- <maxHistory>4</maxHistory>
- <timeBasedFileNamingAndTriggeringPolicy
- class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
- <maxFileSize>100MB</maxFileSize>
- </timeBasedFileNamingAndTriggeringPolicy>
- </rollingPolicy>
- <encoder>
- <pattern>
- %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %ex{full} %n
- </pattern>
- </encoder>
- </appender>
-
-Example Configuration for Logging Logic
----------------------------------------
-
- .. container:: paragraph
-
- The following example shows a configuration that logs policy logic
- to standard out and a file (*info*). All other APEX components are
- logging to a file (*debug*).. This configuration an be used in a
- pre-production phase with the APEX engine still running in a
- separate terminal to monitor policy execution. This logback
- configuration is in the APEX installation as
- ``etc/logback-logic.xml``.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <configuration debug="false">
- <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
-
- <contextName>Apex</contextName>
- <property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />
-
- <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
- <encoder>
- <Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern>
- </encoder>
- </appender>
-
- <appender name="FILE" class="ch.qos.logback.core.FileAppender">
- <file>${VAR_LOG}/apex.log</file>
- <encoder>
- <pattern>
- %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}
- </pattern>
- </encoder>
- </appender>
-
- <appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender">
- <encoder>
- <pattern>policy: %msg\n</pattern>
- </encoder>
- </appender>
-
- <root level="error">
- <appender-ref ref="STDOUT" />
- </root>
-
- <logger name="org.onap.policy.apex" level="debug" additivity="false">
- <appender-ref ref="FILE" />
- </logger>
-
- <logger name="org.onap.policy.apex.executionlogging" level="info" additivity="false">
- <appender-ref ref="POLICY_APPENDER_STDOUT" />
- <appender-ref ref="FILE" />
- </logger>
- </configuration>
-
-Example Configuration for a Production Server
----------------------------------------------
-
- .. container:: paragraph
-
- The following example shows a configuration that logs all APEX
- components, including policy logic, to a file (*debug*). This
- configuration an be used in a production phase with the APEX
- engine being executed as a service on a system without console
- output. This logback configuration is in the APEX installation as
- ``logback-server.xml``
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- <configuration debug="false">
- <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
-
- <contextName>Apex</contextName>
- <property name="VAR_LOG" value="/var/log/onap/policy/apex-pdp/" />
-
- <appender name="FILE" class="ch.qos.logback.core.FileAppender">
- <file>${VAR_LOG}/apex.log</file>
- <encoder>
- <pattern>
- %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}
- </pattern>
- </encoder>
- </appender>
-
- <root level="debug">
- <appender-ref ref="FILE" />
- </root>
-
- <logger name="org.onap.policy.apex.executionlogging" level="debug" additivity="false">
- <appender-ref ref="FILE" />
- </logger>
- </configuration>
-
-Building a System with Websocket Backend
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Websockets
-----------
-
- .. container:: paragraph
-
- Websocket is a protocol to run sockets of HTTP. Since it in
- essence a socket, the connection is realized between a
- server (waiting for connections) and a client (connecting to
- a server). Server/client separation is only important for
- connection establishment, once connected, everyone can
- send/receive on the same socket (as any standard socket
- would allow).
-
- .. container:: paragraph
-
- Standard Websocket implementations are simple, no
- publish/subscribe and no special event handling. Most
- servers simply send all incoming messages to all
- connections. There is a PubSub definition on top of
- Websocket called `WAMP <http://wamp-proto.org/>`__. APEX
- does not support WAMP at the moment.
-
-Websocket in Java
------------------
-
- .. container:: paragraph
-
- In Java, `JSR
- 356 <http://www.oracle.com/technetwork/articles/java/jsr356-1937161.html>`__
- defines the standard Websocket API. This JSR is part of Jave
- EE 7 standard. For Java SE, several implementations exist in
- open source. Since Websockets are a stable standard and
- simple, most implementations are stable and ready to use. A
- lot of products support Websockets, like Spring, JBoss,
- Netty, … there are also Kafka extensions for Websockets.
-
-Websocket Example Code for Websocket clients (FOSS)
----------------------------------------------------
-
- .. container:: paragraph
-
- There are a lot of implementations and examples available on
- Github for Websocket clients. If one is using Java EE 7,
- then one can also use the native Websocket implementation.
- Good examples for clients using simply Java SE are here:
-
- .. container:: ulist
-
- - `Websocket
- implementation <https://github.com/TooTallNate/Java-WebSocket>`__
-
- - `Websocket sending client example, using
- AWT <https://github.com/TooTallNate/Java-WebSocket/blob/master/src/main/example/ChatClient.java>`__
-
- - `Websocket receiving client example (simple echo
- client) <https://github.com/TooTallNate/Java-WebSocket/blob/master/src/main/example/ExampleClient.java>`__
-
- .. container:: paragraph
-
- For Java EE, the native Websocket API is explained here:
-
- .. container:: ulist
-
- - `Oracle
- docs <http://www.oracle.com/technetwork/articles/java/jsr356-1937161.html>`__
-
- - link: `An
- example <http://www.programmingforliving.com/2013/08/jsr-356-java-api-for-websocket-client-api.html>`__
-
-BCP: Websocket Configuration
-----------------------------
-
- .. container:: paragraph
-
- The probably best is to configure APEX for Websocket servers
- for input (ingress, consume) and output (egress, produce)
- interfaces. This means that APEX will start Websocket
- servers on named ports and wait for clients to connect.
- Advantage: once APEX is running all connectivity
- infrastructure is running as well. Consequence: if APEX is
- not running, everyone else is in the dark, too.
-
- .. container:: paragraph
-
- The best protocol to be used is JSON string. Each event on
- any interface is then a string with a JSON encoding. JSON
- string is a little bit slower than byte code, but we doubt
- that this will be noticeable. A further advantage of JSON
- strings over Websockets with APEX starting the servers: it
- is very easy to connect web browsers to such a system.
- Simple connect the web browser to the APEX sockets and
- send/read JSON strings.
-
- .. container:: paragraph
-
- Once APEX is started you simply connect Websocket clients to
- it, and send/receive event. When APEX is terminated, the
- Websocket servers go down, and the clients will be
- disconnected. APEX does not (yet) support auto-client
- reconnect nor WAMP, so clients might need to be restarted or
- reconnected manually after an APEX boot.
-
-Demo with VPN Policy Model
---------------------------
-
- .. container:: paragraph
-
- We assume that you have an APEX installation using the full
- package, i.e. APEX with all examples, of version ``0.5.6``
- or higher. We will use the VPN policy from the APEX examples
- here.
-
- .. container:: paragraph
-
- Now, have the following ready to start the demo:
-
- .. container:: ulist
-
- - 3 terminals on the host where APEX is running (we need 1
- for APEX and 1 for each client)
-
- - the events in the file
- ``$APEX_HOME/examples/events/VPN/SetupEvents.json`` open
- in an editor (we need to send those events to APEX)
-
- - the events in the file
- ``$APEX_HOME/examples/events/VPN/Link09Events.json`` open
- in an editor (we need to send those events to APEX)
-
-A Websocket Configuration for the VPN Domain
-############################################
-
- .. container:: paragraph
-
- Create a new APEX configuration using the VPN policy
- model and configuring APEX as discussed above for
- Websockets. Copy the following configuration into
- ``$APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json``
- (for Windows use
- ``%APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json``):
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- {
- "engineServiceParameters" : {
- "name" : "VPNApexEngine",
- "version" : "0.0.1",
- "id" : 45,
- "instanceCount" : 1,
- "deploymentPort" : 12345,
- "policyModelFileName" : "examples/models/VPN/VPNPolicyModelAvro.json",
- "engineParameters" : {
- "executorParameters" : {
- "MVEL" : {
- "parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
- }
- },
- "contextParameters" : {
- "parameterClassName" : "org.onap.policy.apex.context.parameters.ContextParameters",
- "schemaParameters":{
- "Avro":{
- "parameterClassName" : "org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters"
- }
- }
- }
- }
- },
- "producerCarrierTechnologyParameters" : {
- "carrierTechnology" : "WEBSOCKET",
- "parameterClassName" : "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",
- "parameters" : {
- "wsClient" : false,
- "port" : 42452
- }
- },
- "producerEventProtocolParameters" : {
- "eventProtocol" : "JSON"
- },
- "consumerCarrierTechnologyParameters" : {
- "carrierTechnology" : "WEBSOCKET",
- "parameterClassName" : "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",
- "parameters" : {
- "wsClient" : false,
- "port" : 42450
- }
- },
- "consumerEventProtocolParameters" : {
- "eventProtocol" : "JSON"
- }
- }
-
-Start APEX Engine
-#################
-
- .. container:: paragraph
-
- In a new terminal, start APEX with the new configuration for
- Websocket-Server ingress/egress:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- #: $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- #: %APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json
-
-.. container:: paragraph
-
- Wait for APEX to start, it takes a while to create all Websocket
- servers (about 8 seconds on a standard laptop without cached
- binaries). depending on your log messages, you will see no (some, a
- lot) log messages. If APEX starts correctly, the last few messages
- you should see are:
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- 2017-07-28 13:17:20,834 Apex [main] INFO c.e.a.s.engine.runtime.EngineService - engine model VPNPolicyModelAvro:0.0.1 added to the engine-AxArtifactKey:(name=VPNApexEngine-0,version=0.0.1)
- 2017-07-28 13:17:21,057 Apex [Apex-apex-engine-service-0:0] INFO c.e.a.s.engine.runtime.EngineService - Engine AxArtifactKey:(name=VPNApexEngine-0,version=0.0.1) processing ...
- 2017-07-28 13:17:21,296 Apex [main] INFO c.e.a.s.e.r.impl.EngineServiceImpl - Added the action listener to the engine
- Started Apex service
-
-.. container:: paragraph
-
- APEX is running in the new terminal and will produce output when the
- policy is triggered/executed.
-
-Run the Websocket Echo Client
-#############################
-
- .. container:: paragraph
-
- The echo client is included in an APEX full installation. To run
- the client, open a new shell (Unix, Cygwin) or command prompt
- (``cmd`` on Windows). Then use the APEX application launcher to
- start the client.
-
- .. important::
- APEX engine needs to run first
- The example assumes that an APEX engine configured for *produce* carrier technology Websocket and *JSON* event protocol is executed first.
-
- +---------------------------------------------------------+-----------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +=========================================================+===========================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexApps.sh ws-echo [args] | > %APEX_HOME%\bin\apexApps.bat ws-echo [args] |
- +---------------------------------------------------------+-----------------------------------------------------------+
-
- .. container:: paragraph
-
- Use the following command line arguments for server and port of
- the Websocket server. The port should be the same as configured in
- the APEX engine. The server host should be the host on which the
- APEX engine is running
-
- .. container:: ulist
-
- - ``-p`` defines the Websocket port to connect to (defaults to
- ``8887``)
-
- - ``-s`` defines the host on which a Websocket server is running
- (defaults to ``localhost``)
-
- .. container:: paragraph
-
- Let’s assume that there is an APEX engine running, configured for
- produce Websocket carrier technology, as server, for port 42452,
- with produce event protocol JSON,. If we start the console client
- on the same host, we can omit the ``-s`` options. We start the
- console client as:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- # $APEX_HOME/bin/apexApps.sh ws-echo -p 42452 (1)
- > %APEX_HOME%\bin\apexApps.bat ws-echo -p 42452 (2)
-
- .. container:: colist arabic
-
- +-------+--------------------------------+
- | **1** | Start client on Unix or Cygwin |
- +-------+--------------------------------+
- | **2** | Start client on Windows |
- +-------+--------------------------------+
-
- .. container:: paragraph
-
- Once started successfully, the client will produce the following
- messages (assuming we used ``-p 42452`` and an APEX engine is
- running on ``localhost`` with the same port:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- ws-simple-echo: starting simple event echo
- --> server: localhost
- --> port: 42452
-
- Once started, the application will simply print out all received events to standard out.
- Each received event will be prefixed by '---' and suffixed by '===='
-
-
- ws-simple-echo: opened connection to APEX (Web Socket Protocol Handshake)
-
-Run the Websocket Console Client
-################################
-
- .. container:: paragraph
-
- The console client is included in an APEX full installation. To
- run the client, open a new shell (Unix, Cygwin) or command prompt
- (``cmd`` on Windows). Then use the APEX application launcher to
- start the client.
-
- .. important::
- APEX engine needs to run first
- The example assumes that an APEX engine configured for *consume* carrier technology Websocket and *JSON* event
- protocol is executed first.
-
- +------------------------------------------------------------+--------------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +============================================================+==============================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexApps.sh ws-console [args] | > %APEX_HOME%\bin\apexApps.bat ws-console [args] |
- +------------------------------------------------------------+--------------------------------------------------------------+
-
- .. container:: paragraph
-
- Use the following command line arguments for server and port of
- the Websocket server. The port should be the same as configured in
- the APEX engine. The server host should be the host on which the
- APEX engine is running
-
- .. container:: ulist
-
- - ``-p`` defines the Websocket port to connect to (defaults to
- ``8887``)
-
- - ``-s`` defines the host on which a Websocket server is running
- (defaults to ``localhost``)
-
- .. container:: paragraph
-
- Let’s assume that there is an APEX engine running, configured for
- consume Websocket carrier technology, as server, for port 42450,
- with consume event protocol JSON,. If we start the console client
- on the same host, we can omit the ``-s`` options. We start the
- console client as:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- # $APEX_HOME/bin/apexApps.sh ws-console -p 42450 (1)
- > %APEX_HOME%\bin\apexApps.sh ws-console -p 42450 (2)
-
- .. container:: colist arabic
-
- +-------+--------------------------------+
- | **1** | Start client on Unix or Cygwin |
- +-------+--------------------------------+
- | **2** | Start client on Windows |
- +-------+--------------------------------+
-
- .. container:: paragraph
-
- Once started successfully, the client will produce the following
- messages (assuming we used ``-p 42450`` and an APEX engine is
- running on ``localhost`` with the same port:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- ws-simple-console: starting simple event console
- --> server: localhost
- --> port: 42450
-
- - terminate the application typing 'exit<enter>' or using 'CTRL+C'
- - events are created by a non-blank starting line and terminated by a blank line
-
-
- ws-simple-console: opened connection to APEX (Web Socket Protocol Handshake)
-
-Send Events
-###########
-
- .. container:: paragraph
-
- Now you have the full system up and running:
-
- .. container:: ulist
-
- - Terminal 1: APEX ready and loaded
-
- - Terminal 2: an echo client, printing received messages produced
- by the VPN policy
-
- - Terminal 2: a console client, waiting for input on the console
- (standard in) and sending text to APEX
-
- .. container:: paragraph
-
- We started the engine with the VPN policy example. So all the
- events we are using now are located in files in the following
- example directory:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- #: $APEX_HOME/examples/events/VPN
- > %APEX_HOME%\examples\events\VPN
-
-.. container:: paragraph
-
- To sends events, simply copy the content of the event files into
- Terminal 3 (the console client). It will read multi-line JSON text
- and send the events. So copy the content of ``SetupEvents.json`` into
- the client. APEX will trigger a policy and produce some output, the
- echo client will also print some events created in the policy. In
- Terminal 1 (APEX) you’ll see some status messages from the policy as:
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- {Link=L09, LinkUp=true}
- L09 true
- outFields: {Link=L09, LinkUp=true}
- {Link=L10, LinkUp=true}
- L09 true
- L10 true
- outFields: {Link=L10, LinkUp=true}
- {CustomerName=C, LinkList=L09 L10, SlaDT=300, YtdDT=300}
- *** Customers ***
- C 300 300 [L09, L10]
- outFields: {CustomerName=C, LinkList=L09 L10, SlaDT=300, YtdDT=300}
- {CustomerName=A, LinkList=L09 L10, SlaDT=300, YtdDT=50}
- *** Customers ***
- A 300 50 [L09, L10]
- C 300 300 [L09, L10]
- outFields: {CustomerName=A, LinkList=L09 L10, SlaDT=300, YtdDT=50}
- {CustomerName=D, LinkList=L09 L10, SlaDT=300, YtdDT=400}
- *** Customers ***
- A 300 50 [L09, L10]
- C 300 300 [L09, L10]
- D 300 400 [L09, L10]
- outFields: {CustomerName=D, LinkList=L09 L10, SlaDT=300, YtdDT=400}
- {CustomerName=B, LinkList=L09 L10, SlaDT=300, YtdDT=299}
- *** Customers ***
- A 300 50 [L09, L10]
- B 300 299 [L09, L10]
- C 300 300 [L09, L10]
- D 300 400 [L09, L10]
- outFields: {CustomerName=B, LinkList=L09 L10, SlaDT=300, YtdDT=299}
-
-.. container:: paragraph
-
- In Terminal 2 (echo-client) you see the received events, the last two
- should look like:
-
-.. container:: listingblock
-
- .. container:: content
-
- .. code::
- :number-lines:
-
- ws-simple-echo: received
- ---------------------------------
- {
- "name": "VPNCustomerCtxtActEvent",
- "version": "0.0.1",
- "nameSpace": "org.onap.policy.apex.domains.vpn.events",
- "source": "Source",
- "target": "Target",
- "CustomerName": "C",
- "LinkList": "L09 L10",
- "SlaDT": 300,
- "YtdDT": 300
- }
- =================================
-
- ws-simple-echo: received
- ---------------------------------
- {
- "name": "VPNCustomerCtxtActEvent",
- "version": "0.0.1",
- "nameSpace": "org.onap.policy.apex.domains.vpn.events",
- "source": "Source",
- "target": "Target",
- "CustomerName": "D",
- "LinkList": "L09 L10",
- "SlaDT": 300,
- "YtdDT": 400
- }
- =================================
-
-.. container:: paragraph
-
- Congratulations, you have triggered a policy in APEX using
- Websockets, the policy did run through, created events, picked up by
- the echo-client.
-
-.. container:: paragraph
-
- Now you can send the Link 09 and Link 10 events, they will trigger
- the actual VPN policy and some calculations are made. Let’s take the
- Link 09 events from ``Link09Events.json``, copy them all into
- Terminal 3 (the console). APEX will run the policy (with some status
- output), and the echo client will receive and print events.
-
-.. container:: paragraph
-
- To terminate the applications, simply press ``CTRL+C`` in Terminal 1
- (APEX). This will also terminate the echo-client in Terminal 2. Then
- type ``exit<enter>`` in Terminal 3 (or ``CTRL+C``) to terminate the
- console-client.
-
-.. container::
- :name: footer
-
- .. container::
- :name: footer-text
-
- 2.0.0-SNAPSHOT
- Last updated 2018-09-10 15:38:16 IST
-
-.. |Extract the TAR archive| image:: images/install-guide/win-extract-tar-gz.png
-.. |Extract the APEX distribution| image:: images/install-guide/win-extract-tar.png
-.. |REST Editor Start Screen| image:: images/install-guide/rest-start.png
-.. |REST Editor with loaded SampleDomain Policy Model| image:: images/install-guide/rest-loaded.png
-.. |APEX Configuration Matrix| image:: images/apex-intro/ApexEngineConfig.png
-.. |File > New to create a new Policy Model| image:: images/mfp/MyFirstPolicy_P1_newPolicyModel1.png
-.. |Create a new Policy Model| image:: images/mfp/MyFirstPolicy_P1_newPolicyModel2.png
-.. |Right click to create a new event| image:: images/mfp/MyFirstPolicy_P1_newEvent1.png
-.. |Fill in the necessary information for the 'SALE_INPUT' event and click 'Submit'| image:: images/mfp/MyFirstPolicy_P1_newEvent2.png
-.. |Right click to create a new Item Schema| image:: images/mfp/MyFirstPolicy_P1_newItemSchema1.png
-.. |Create a new Item Schema| image:: images/mfp/MyFirstPolicy_P1_newItemSchema2.png
-.. |Add new event parameters to an event| image:: images/mfp/MyFirstPolicy_P1_newEvent3.png
-.. |Right click to create a new task| image:: images/mfp/MyFirstPolicy_P1_newTask1.png
-.. |Add input and out fields for the task| image:: images/mfp/MyFirstPolicy_P1_newTask2.png
-.. |Add task logic the task| image:: images/mfp/MyFirstPolicy_P1_newTask3.png
-.. |Create a new policy| image:: images/mfp/MyFirstPolicy_P1_newPolicy1.png
-.. |Create a state| image:: images/mfp/MyFirstPolicy_P1_newState1.png
-.. |Add a Task and Output Mapping| image:: images/mfp/MyFirstPolicy_P1_newState2.png
-.. |Validate the policy model for error using the 'Model' > 'Validate' menu item| image:: images/mfp/MyFirstPolicy_P1_validatePolicyModel.png
-.. |Download the completed policy model using the 'File' > 'Download' menu item| image:: images/mfp/MyFirstPolicy_P1_exportPolicyModel1.png
-.. |Create a new alternative task MorningBoozeCheckAlt1| image:: images/mfp/MyFirstPolicy_P2_newTask1.png
-.. |Right click to edit a policy| image:: images/mfp/MyFirstPolicy_P2_editPolicy1.png
-.. |State definition with 2 Tasks and Task Selection Logic| image:: images/mfp/MyFirstPolicy_P2_editState1.png
-