1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
17 .. container:: paragraph
19 APEX is 100% written in Java and runs on any platform
20 that supports a JVM, e.g. Windows, Unix, Cygwin. Some
21 APEX applications (such as the monitoring application)
22 come as web archives, they do require a war-capable web
25 Installation Requirements
26 #########################
30 - Downloaded distribution: JAVA runtime environment
31 (JRE, Java 8 or later, APEX is tested with the
34 - Building from source: JAVA development kit (JDK,
35 Java 8 or later, APEX is tested with the Oracle
38 - A web archive capable webserver, for instance for
39 the monitoring application
43 - for instance `Apache
44 Tomcat <https://tomcat.apache.org/>`__
46 - Sufficient rights to install APEX on the system
48 - Installation tools depending on the installation
53 - ZIP to extract from a ZIP distribution
57 - Windows for instance
58 `7Zip <http://www.7-zip.org/>`__
60 - TAR and GZ to extract from that TAR.GZ
65 - Windows for instance
66 `7Zip <http://www.7-zip.org/>`__
68 - RPM to install from the RPM distribution
72 - Install: ``sudo apt-get install rpm``
74 - DPKG to install from the DEB distribution
78 - Install: ``sudo apt-get install dpkg``
83 .. container:: paragraph
85 APEX supports a number of features that require extra
86 software being installed.
90 - `Apache Kafka <https://kafka.apache.org/>`__ to
91 connect APEX to a Kafka message bus
93 - `Hazelcast <https://hazelcast.com/>`__ to use
94 distributed hash maps for context
96 - `Infinispan <http://infinispan.org/>`__ for
97 distributed context and persistence
99 - `Docker <https://www.docker.com/>`__ to run APEX
100 inside a Docker container
102 Build (Install from Source) Requirements
103 ########################################
105 .. container:: paragraph
107 Installation from source requires a few development
112 - GIT to retrieve the source code
114 - Java SDK, Java version 8 or later
116 - Apache Maven 3 (the APEX build environment)
118 Get the APEX Source Code
119 ------------------------
121 .. container:: paragraph
123 The first APEX source code was hosted on Github in
124 January 2018. By the end of 2018, APEX was added as a
125 project in the ONAP Policy Framework, released later in
126 the ONAP Casablanca release.
128 .. container:: paragraph
130 The APEX source code is hosted in ONAP as project APEX.
131 The current stable version is in the master branch.
132 Simply clone the master branch from ONAP using HTTPS.
134 .. container:: listingblock
136 .. container:: content
141 git clone https://gerrit.onap.org/r/policy/apex-pdp
146 .. container:: paragraph
148 The examples in this document assume that the APEX source
149 repositories are cloned to:
153 - Unix, Cygwin: ``/usr/local/src/apex-pdp``
155 - Windows: ``C:\dev\apex-pdp``
157 - Cygwin: ``/cygdrive/c/dev/apex-pdp``
160 A Build requires ONAP Nexus
161 APEX has a dependency to ONAP parent projects. You might need to adjust your Maven M2 settings. The most current
162 settings can be found in the ONAP oparent repo: `Settings <https://git.onap.org/oparent/plain/settings.xml>`__.
166 Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full
167 distribution and 1-2 GB for the downloaded dependencies
170 A Build requires Internet (for first build)
171 During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven
172 repository. The first standard build (and any first specific build) requires Internet access to download those
176 Building RPM distributions
177 RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` run ``sudo apt-get install rpm``,
180 .. container:: paragraph
182 Use Maven to for a standard build without any tests.
184 +-------------------------------------------------------+--------------------------------------------------------+
185 | Unix, Cygwin | Windows |
186 +=======================================================+========================================================+
187 | .. container:: | .. container:: |
189 | .. container:: content | .. container:: content |
191 | .. code:: | .. code:: |
192 | :number-lines: | :number-lines: |
194 | # cd /usr/local/src/apex-pdp | >c: |
195 | # mvn clean install -Pdocker -DskipTests | >cd \dev\apex |
196 | | >mvn clean install -Pdocker -DskipTests |
197 +-------------------------------------------------------+--------------------------------------------------------+
199 .. container:: paragraph
201 The build takes 2-3 minutes on a standard development laptop. It
202 should run through without errors, but with a lot of messages from
205 .. container:: paragraph
207 When Maven is finished with the build, the final screen should look
208 similar to this (omitting some ``success`` lines):
210 .. container:: listingblock
212 .. container:: content
217 [INFO] tools .............................................. SUCCESS [ 0.248 s]
218 [INFO] tools-common ....................................... SUCCESS [ 0.784 s]
219 [INFO] simple-wsclient .................................... SUCCESS [ 3.303 s]
220 [INFO] model-generator .................................... SUCCESS [ 0.644 s]
221 [INFO] packages ........................................... SUCCESS [ 0.336 s]
222 [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
223 [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
224 [INFO] ------------------------------------------------------------------------
226 [INFO] ------------------------------------------------------------------------
227 [INFO] Total time: 03:43 min
228 [INFO] Finished at: 2018-09-03T11:56:01+01:00
229 [INFO] ------------------------------------------------------------------------
231 .. container:: paragraph
233 The build will have created all artifacts required for an APEX
234 installation. The following example show how to change to the target
235 directory and how it should look like.
237 +----------------------------------------------------------------------------------------------------------------------------+
239 +============================================================================================================================+
242 | .. container:: listingblock |
244 | .. container:: content |
249 | -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* |
250 | -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* |
251 | -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* |
252 | -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* |
253 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ |
254 | -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* |
255 | -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* |
256 | -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* |
257 | -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* |
258 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ |
259 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ |
260 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ |
261 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ |
262 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ |
263 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ |
264 +----------------------------------------------------------------------------------------------------------------------------+
266 +--------------------------------------------------------------------------------------------------------+
268 +========================================================================================================+
271 | .. container:: listingblock |
273 | .. container:: content |
278 | 03/09/2018 11:55 <DIR> . |
279 | 03/09/2018 11:55 <DIR> .. |
280 | 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz |
281 | 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb |
282 | 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar |
283 | 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes |
284 | 03/09/2018 11:54 <DIR> archive-tmp |
285 | 03/09/2018 11:54 89 checkstyle-cachefile |
286 | 03/09/2018 11:54 10,621 checkstyle-checker.xml |
287 | 03/09/2018 11:54 584 checkstyle-header.txt |
288 | 03/09/2018 11:54 86 checkstyle-result.xml |
289 | 03/09/2018 11:54 <DIR> classes |
290 | 03/09/2018 11:54 <DIR> dependency-maven-plugin-markers |
291 | 03/09/2018 11:54 <DIR> etc |
292 | 03/09/2018 11:54 <DIR> examples |
293 | 03/09/2018 11:55 <DIR> install_hierarchy |
294 | 03/09/2018 11:54 <DIR> maven-archiver |
295 | 8 File(s) 292,652,686 bytes |
296 | 9 Dir(s) 14,138,720,256 bytes free |
297 +--------------------------------------------------------------------------------------------------------+
302 .. container:: paragraph
304 APEX can be installed in different ways:
308 - Unix: automatically using ``rpm`` or ``dpkg`` from ``.rpm`` or
311 - Windows, Unix, Cygwin: manually from a ``.tar.gz`` archive
313 - Windows, Unix, Cygwin: build from source using Maven, then
316 Install with RPM and DPKG
317 #########################
319 .. container:: paragraph
321 The install distributions of APEX automatically install the
322 system. The installation directory is
323 ``/opt/app/policy/apex-pdp``. Log files are located in
324 ``/var/log/onap/policy/apex-pdp``. The latest APEX version will
325 be available as ``/opt/app/policy/apex-pdp/apex-pdp``.
327 .. container:: paragraph
329 For the installation, a new user ``apexuser`` and a new group
330 ``apexuser`` will be created. This user owns the installation
331 directories and the log file location. The user is also used by
332 the standard APEX start scripts to run APEX with this user’s
335 +-----------------------------------------------------------------------+
337 +=======================================================================+
340 | .. container:: listingblock |
342 | .. container:: content |
347 | # sudo rpm -i apex-pdp-package-full-2.0.0-SNAPSHOT.rpm |
348 | ********************preinst******************* |
350 | ********************************************** |
351 | creating group apexuser . . . |
352 | creating user apexuser . . . |
353 | ********************postinst**************** |
355 | *********************************************** |
356 +-----------------------------------------------------------------------+
358 +--------------------------------------------------------------------------------------+
359 | DPKG Installation |
360 +======================================================================================+
363 | .. container:: listingblock |
365 | .. container:: content |
370 | # sudo dpkg -i apex-pdp-package-full-2.0.0-SNAPSHOT.deb |
371 | Selecting previously unselected package apex-uservice. |
372 | (Reading database ... 288458 files and directories currently installed.) |
373 | Preparing to unpack apex-pdp-package-full-2.0.0-SNAPSHOT.deb ... |
374 | ********************preinst******************* |
375 | arguments install |
376 | ********************************************** |
377 | creating group apexuser . . . |
378 | creating user apexuser . . . |
379 | Unpacking apex-uservice (2.0.0-SNAPSHOT) ... |
380 | Setting up apex-uservice (2.0.0-SNAPSHOT) ... |
381 | ********************postinst**************** |
382 | arguments configure |
383 | *********************************************** |
384 +--------------------------------------------------------------------------------------+
386 .. container:: paragraph
388 Once the installation is finished, APEX is fully installed and ready
391 Install Manually from Archive (Unix, Cygwin)
392 ############################################
394 .. container:: paragraph
396 Download a ``tar.gz`` archive. Create a directory where APEX
397 should be installed. Extract the ``tar`` archive. The following
398 example shows how to install APEX in ``/opt/apex`` and create a
399 link to ``/opt/apex/apex`` for the most recent installation.
401 .. container:: listingblock
403 .. container:: content
411 # mkdir apex-full-2.0.0-SNAPSHOT
412 # tar xvfz ~/Downloads/apex-pdp-package-full-2.0.0-SNAPSHOT.tar.gz -C apex-full-2.0.0-SNAPSHOT
413 # ln -s apex apex-pdp-package-full-2.0.0-SNAPSHOT
415 Install Manually from Archive (Windows, 7Zip, GUI)
416 ##################################################
418 .. container:: paragraph
420 Download a ``tar.gz`` archive and copy the file into the install
421 folder (in this example ``C:\apex``). Assuming you are using 7Zip,
422 right click on the file and extract the ``tar`` archive. Note: the
423 screenshots might show an older version than you have.
425 .. container:: imageblock
427 .. container:: content
429 |Extract the TAR archive|
431 .. container:: paragraph
433 The right-click on the new created TAR file and extract the actual
436 .. container:: imageblock
438 .. container:: content
440 |Extract the APEX distribution|
442 .. container:: paragraph
444 Inside the new APEX folder you see the main directories: ``bin``,
445 ``etc``, ``examples``, ``lib``, and ``war``
447 .. container:: paragraph
449 Once extracted, please rename the created folder to
450 ``apex-full-2.0.0-SNAPSHOT``. This will keep the directory name in
451 line with the rest of this documentation.
453 Install Manually from Archive (Windows, 7Zip, CMD)
454 ##################################################
456 .. container:: paragraph
458 Download a ``tar.gz`` archive and copy the file into the install
459 folder (in this example ``C:\apex``). Start ``cmd``, for instance
460 typing ``Windows+R`` and then ``cmd`` in the dialog. Assuming
461 ``7Zip`` is installed in the standard folder, simply run the
462 following commands (for APEX version 2.0.0-SNAPSHOT full
465 .. container:: listingblock
467 .. container:: content
474 >"\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"
476 .. container:: paragraph
478 APEX is now installed in the folder
479 ``C:\apex\apex-full-2.0.0-SNAPSHOT``.
484 Build and Install Manually (Unix, Windows, Cygwin)
485 ##################################################
487 .. container:: paragraph
489 Clone the APEX GIT repositories into a directory. Go to that
490 directory. Use Maven to build APEX (all details on building
491 APEX from source can be found in *APEX HowTo: Build*). Install
492 from the created artifacts (``rpm``, ``deb``, ``tar.gz``, or
496 Building RPM distributions
497 RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm`` run
498 ``sudo apt-get install rpm``, then build APEX.
500 .. container:: paragraph
502 The following example shows how to build the APEX system,
503 without tests (``-DskipTests``) to safe some time. It assumes
504 that the APX GIT repositories are cloned to:
508 - Unix, Cygwin: ``/usr/local/src/apex``
510 - Windows: ``C:\dev\apex``
512 +-------------------------------------------------------+--------------------------------------------------------+
513 | Unix, Cygwin | Windows |
514 +=======================================================+========================================================+
515 | .. container:: | .. container:: |
517 | .. container:: content | .. container:: content |
519 | .. code:: | .. code:: |
520 | :number-lines: | :number-lines: |
522 | # cd /usr/local/src/apex | >c: |
523 | # mvn clean install -Pdocker -DskipTests | >cd \dev\apex |
524 | | >mvn clean install -Pdocker -DskipTests |
525 +-------------------------------------------------------+--------------------------------------------------------+
527 .. container:: paragraph
529 The build takes about 2 minutes without test and about 4-5 minutes
530 with tests on a standard development laptop. It should run through
531 without errors, but with a lot of messages from the build process. If
532 build with tests (i.e. without ``-DskipTests``), there will be error
533 messages and stack trace prints from some tests. This is normal, as
534 long as the build finishes successful.
536 .. container:: paragraph
538 When Maven is finished with the build, the final screen should look
539 similar to this (omitting some ``success`` lines):
541 .. container:: listingblock
543 .. container:: content
548 [INFO] tools .............................................. SUCCESS [ 0.248 s]
549 [INFO] tools-common ....................................... SUCCESS [ 0.784 s]
550 [INFO] simple-wsclient .................................... SUCCESS [ 3.303 s]
551 [INFO] model-generator .................................... SUCCESS [ 0.644 s]
552 [INFO] packages ........................................... SUCCESS [ 0.336 s]
553 [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
554 [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
555 [INFO] ------------------------------------------------------------------------
557 [INFO] ------------------------------------------------------------------------
558 [INFO] Total time: 03:43 min
559 [INFO] Finished at: 2018-09-03T11:56:01+01:00
560 [INFO] ------------------------------------------------------------------------
562 .. container:: paragraph
564 The build will have created all artifacts required for an APEX
565 installation. The following example show how to change to the target
566 directory and how it should look like.
568 +-----------------------------------------------------------------------------------------------------------------------------+
570 +=============================================================================================================================+
573 | .. container:: listingblock |
578 | # cd packages/apex-pdp-package-full/target |
580 | -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* |
581 | -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* |
582 | -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* |
583 | -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* |
584 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ |
585 | -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* |
586 | -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* |
587 | -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* |
588 | -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* |
589 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ |
590 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ |
591 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ |
592 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ |
593 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ |
594 | drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ |
595 +-----------------------------------------------------------------------------------------------------------------------------+
597 +-----------------------------------------------------------------------------------------------------------------------------+
599 +=============================================================================================================================+
602 | .. container:: listingblock |
607 | >cd packages\apex-pdp-package-full\target |
609 | 03/09/2018 11:55 <DIR> . |
610 | 03/09/2018 11:55 <DIR> .. |
611 | 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz |
612 | 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb |
613 | 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar |
614 | 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes |
615 | 03/09/2018 11:54 <DIR> archive-tmp |
616 | 03/09/2018 11:54 89 checkstyle-cachefile |
617 | 03/09/2018 11:54 10,621 checkstyle-checker.xml |
618 | 03/09/2018 11:54 584 checkstyle-header.txt |
619 | 03/09/2018 11:54 86 checkstyle-result.xml |
620 | 03/09/2018 11:54 <DIR> classes |
621 | 03/09/2018 11:54 <DIR> dependency-maven-plugin-markers |
622 | 03/09/2018 11:54 <DIR> etc |
623 | 03/09/2018 11:54 <DIR> examples |
624 | 03/09/2018 11:55 <DIR> install_hierarchy |
625 | 03/09/2018 11:54 <DIR> maven-archiver |
626 | 8 File(s) 292,652,686 bytes |
627 | 9 Dir(s) 14,138,720,256 bytes free |
628 +-----------------------------------------------------------------------------------------------------------------------------+
630 .. container:: paragraph
632 Now, take the ``.deb`` or the ``.tar.gz`` file and install APEX.
633 Alternatively, copy the content of the folder ``install_hierarchy``
634 to your APEX directory.
639 .. container:: paragraph
641 A full installation of APEX comes with the following layout.
643 .. container:: listingblock
645 .. container:: content
664 │ └───applications (11)
667 .. container:: colist arabic
669 +-----------------------------------+-----------------------------------+
670 | **1** | binaries, mainly scripts (bash |
671 | | and bat) to start the APEX engine |
672 | | and applications |
673 +-----------------------------------+-----------------------------------+
674 | **2** | configuration files, such as |
675 | | logback (logging) and third party |
676 | | library configurations |
677 +-----------------------------------+-----------------------------------+
678 | **3** | example policy models to get |
680 +-----------------------------------+-----------------------------------+
681 | **4** | configurations for the examples |
682 | | (with sub directories for |
683 | | individual examples) |
684 +-----------------------------------+-----------------------------------+
685 | **5** | Docker files and additional |
686 | | Docker instructions for the |
688 +-----------------------------------+-----------------------------------+
689 | **6** | example events for the examples |
690 | | (with sub directories for |
691 | | individual examples) |
692 +-----------------------------------+-----------------------------------+
693 | **7** | HTML files for some examples, |
694 | | e.g. the Decisionmaker example |
695 +-----------------------------------+-----------------------------------+
696 | **8** | the policy models, generated for |
697 | | each example (with sub |
698 | | directories for individual |
700 +-----------------------------------+-----------------------------------+
701 | **9** | additional scripts for the |
702 | | examples (with sub directories |
703 | | for individual examples) |
704 +-----------------------------------+-----------------------------------+
705 | **10** | the library folder with all Java |
707 +-----------------------------------+-----------------------------------+
708 | **11** | applications, also known as jar |
709 | | with dependencies (or fat jars), |
710 | | individually deployable |
711 +-----------------------------------+-----------------------------------+
712 | **12** | WAR files for web applications |
713 +-----------------------------------+-----------------------------------+
718 .. container:: paragraph
720 Once APEX is installed, a few configurations need to be done:
724 - Create an APEX user and an APEX group (optional, if not
725 installed using RPM and DPKG)
727 - Create environment settings for ``APEX_HOME`` and
728 ``APEX_USER``, required by the start scripts
730 - Change settings of the logging framework (optional)
732 - Create directories for logging, required (execution might fail
733 if directories do not exist or cannot be created)
738 .. container:: paragraph
740 On smaller installations and test systems, APEX can run as any
743 .. container:: paragraph
745 However, if APEX is installed in production, we strongly
746 recommend you set up a dedicated user for running APEX. This
747 will isolate the execution of APEX to that user. We recommend
748 you use the userid ``apexuser`` but you may use any user you
751 .. container:: paragraph
753 The following example, for UNIX, creates a group called
754 ``apexuser``, an APEX user called ``apexuser``, adds the group
755 to the user, and changes ownership of the APEX installation to
756 the user. Substitute ``<apex-dir>`` with the directory where
759 .. container:: listingblock
761 .. container:: content
766 # sudo groupadd apexuser
767 # sudo useradd -g apexuser apexuser
768 # sudo chown -R apexuser:apexuser <apex-dir>
770 .. container:: paragraph
772 For other operating systems please consult your manual or system
775 Environment Settings: APEX_HOME and APEX_USER
776 #############################################
778 .. container:: paragraph
780 The provided start scripts for APEX require two environment
785 - ``APEX_USER`` with the user under whos name and permission APEX
786 should be started (Unix only)
788 - ``APEX_HOME`` with the directory where APEX is installed (Unix,
791 .. container:: paragraph
793 The first row in the following table shows how to set these
794 environment variables temporary (assuming the user is
795 ``apexuser``). The second row shows how to verify the settings.
796 The last row explains how to set those variables permanently.
798 +------------------------------------------------+---------------------------------------------------------+
799 | Unix, Cygwin (bash/tcsh) | Windows |
800 +================================================+=========================================================+
801 | .. container:: | .. container:: |
803 | .. container:: content | .. container:: content |
805 | .. code:: | .. code:: |
806 | :number-lines: | :number-lines: |
808 | # export APEX_USER=apexuser | >set APEX_HOME=C:\apex\apex-full-2.0.0-SNAPSHOT |
809 | # cd /opt/app/policy/apex-pdp | |
810 | # export APEX_HOME=`pwd` | |
812 +------------------------------------------------+ |
815 | .. container:: content | |
820 | # setenv APEX_USER apexuser | |
821 | # cd /opt/app/policy/apex-pdp | |
822 | # setenv APEX_HOME `pwd` | |
824 +------------------------------------------------+---------------------------------------------------------+
825 | .. container:: | .. container:: |
827 | .. container:: content | .. container:: content |
829 | .. code:: | .. code:: |
830 | :number-lines: | :number-lines: |
832 | # env | grep APEX | >set APEX_HOME |
833 | # APEX_USER=apexuser | APEX_HOME=\apex\apex-full-2.0.0-SNAPSHOT |
834 | # APEX_HOME=/opt/app/policy/apex-pdp | |
836 +------------------------------------------------+---------------------------------------------------------+
838 Making Environment Settings Permanent (Unix, Cygwin)
839 ====================================================
841 .. container:: paragraph
843 For a per-user setting, edit the a user’s ``bash`` or ``tcsh``
844 settings in ``~/.bashrc`` or ``~/.tcshrc``. For system-wide
845 settings, edit ``/etc/profiles`` (requires permissions).
847 Making Environment Settings Permanent (Windows)
848 ===============================================
850 .. container:: paragraph
856 - Click on the **Start** Menu
858 - Right click on **Computer**
860 - Select **Properties**
862 .. container:: paragraph
868 - Click on the **Start** Menu
872 .. container:: paragraph
874 Then do the following
878 - Select **Advanced System Settings**
880 - On the **Advanced** tab, click the **Environment Variables**
883 - Edit an existing variable, or create a new System variable:
884 'Variable name'="APEX_HOME", 'Variable
885 value'="C:\apex\apex-full-2.0.0-SNAPSHOT"
887 .. container:: paragraph
889 For the settings to take effect, an application needs to be
890 restarted (e.g. any open ``cmd`` window).
892 Edit the APEX Logging Settings
893 ##############################
895 .. container:: paragraph
897 Configure the APEX logging settings to your requirements, for
902 - change the directory where logs are written to, or
904 - change the log levels
906 .. container:: paragraph
908 Edit the file ``$APEX_HOME/etc/logback.xml`` for any required
909 changes. To change the log directory change the line
911 .. container:: paragraph
913 ``<property name="logDir" value="/var/log/onap/policy/apex-pdp/" />``
915 .. container:: paragraph
919 .. container:: paragraph
921 ``<property name="logDir" value="/PATH/TO/LOG/DIRECTORY/" />``
923 .. container:: paragraph
925 On Windows, it is recommended to change the log directory to:
927 .. container:: paragraph
929 ``<property name="logDir" value="C:/apex/apex-full-2.0.0-SNAPSHOT/logs" />``
931 .. container:: paragraph
933 Note: Be careful about when to use ``\`` vs. ``/`` as the path
936 Create Directories for Logging
937 ##############################
939 .. container:: paragraph
941 Make sure that the log directory exists. This is important when
942 APEX was installed manually or when the log directory was changed
943 in the settings (see above).
945 +-----------------------------------------------------------------------+-------------------------------------------------------+
946 | Unix, Cygwin | Windows |
947 +=======================================================================+=======================================================+
948 | .. container:: | .. container:: |
950 | .. container:: content | .. container:: content |
952 | .. code:: | .. code:: |
953 | :number-lines: | :number-lines: |
955 | sudo mkdir -p /var/log/onap/policy/apex-pdp | >mkdir C:\apex\apex-full-2.0.0-SNAPSHOT\logs |
956 | sudo chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp | |
957 +-----------------------------------------------------------------------+-------------------------------------------------------+
959 Verify the APEX Installation
960 ----------------------------
962 .. container:: paragraph
964 When APEX is installed and all settings are realized, the
965 installation can be verified.
967 Verify Installation - run Engine
968 ################################
970 .. container:: paragraph
972 A simple verification of an APEX installation can be done by
973 simply starting the APEX engine without any configuration. On
974 Unix (or Cygwin) start the engine using
975 ``$APEX_HOME/bin/apexEngine.sh``. On Windows start the engine
976 using ``%APEX_HOME%\bin\apexEngine.bat``. The engine will fail
977 to fully start. However, if the output looks similar to the
978 following line, the APEX installation is realized.
980 .. container:: listingblock
982 .. container:: content
987 Starting Apex service with parameters [] . . .
988 start of Apex service failed: Apex configuration file was not specified as an argument
989 2018-09-03 13:11:33,914 Apex [main] ERROR o.o.p.a.service.engine.main.ApexMain - start of Apex service failed
990 org.onap.policy.apex.model.basicmodel.concepts.ApexException: Apex configuration file was not specified as an argument
991 at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validateReadableFile(ApexCommandLineArguments.java:267)
992 at org.onap.policy.apex.service.engine.main.ApexCommandLineArguments.validate(ApexCommandLineArguments.java:161)
993 at org.onap.policy.apex.service.engine.main.ApexMain.<init>(ApexMain.java:68)
994 at org.onap.policy.apex.service.engine.main.ApexMain.main(ApexMain.java:165)
995 usage: org.onap.policy.apex.service.engine.main.ApexMain [options...]
997 -c,--config-file <CONFIG_FILE>the full path to the configuration file to use, the configuration file must be a Json file
998 containing the Apex configuration parameters
999 -h,--help outputs the usage of this command
1000 -m,--model-file <MODEL_FILE> the full path to the model file to use, if set it overrides the model file set in the
1002 -v,--version outputs the version of Apex
1004 Verify Installation - run an Example
1005 ####################################
1007 .. container:: paragraph
1009 A full APEX installation comes with several examples. Here, we can
1010 fully verify the installation by running one of the examples.
1012 .. container:: paragraph
1014 We use the example called *SampleDomain* and configure the engine
1015 to use standard in and standard out for events. Run the engine
1016 with the provided configuration. Note: Cygwin executes scripts as
1017 Unix scripts but runs Java as a Windows application, thus the
1018 configuration file must be given as a Windows path.
1020 .. container:: paragraph
1022 On Unix/Linux flavoured platforms, give the commands below:
1024 .. container:: listingblock
1026 .. container:: content
1032 export APEX_HOME <path to apex installation>
1033 export APEX_USER apexuser
1035 .. container:: paragraph
1037 You can now try to run apex.
1039 .. container:: listingblock
1041 .. container:: content
1046 # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (1)
1047 # $APEX_HOME/bin/apexEngine.sh -c C:/apex/apex-full-2.0.0-SNAPSHOT/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (2)
1048 >%APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\SampleDomain\Stdin2StdoutJsonEventJava.json :: (3)
1050 .. container:: colist arabic
1060 .. container:: paragraph
1062 The engine should start successfully. Assuming the logging levels are set to ``info`` in the built system, the output
1063 should look similar to this (last few lines)
1065 .. container:: listingblock
1067 .. container:: content
1072 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] . . .
1073 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 .
1074 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 .
1075 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 .
1076 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 .
1077 2018-09-05 15:16:42,805 Apex [main] INFO o.o.p.a.s.e.r.impl.EngineServiceImpl - APEX service created.
1078 2018-09-05 15:16:43,962 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging starting . . .
1079 2018-09-05 15:16:43,963 Apex [main] INFO o.o.p.a.s.e.e.EngDepMessagingService - engine<-->deployment messaging started
1080 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
1081 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
1082 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
1083 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
1084 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
1085 Started Apex service
1087 .. container:: paragraph
1089 Important are the last two line, stating that APEX has added the
1090 final action listener to the engine and that the engine is started.
1092 .. container:: paragraph
1094 The engine is configured to read events from standard input and write
1095 produced events to standard output. The policy model is a very simple
1098 .. container:: paragraph
1100 The following table shows an input event in the left column and an
1101 output event in the right column. Past the input event into the
1102 console where APEX is running, and the output event should appear in
1103 the console. Pasting the input event multiple times will produce
1104 output events with different values.
1106 +-------------------------------------------------------------+-------------------------------------------------------------+
1107 | Input Event | Example Output Event |
1108 +=============================================================+=============================================================+
1109 | .. container:: | .. container:: |
1111 | .. container:: content | .. container:: content |
1113 | .. code:: | .. code:: |
1114 | :number-lines: | :number-lines: |
1117 | "nameSpace": "org.onap.policy.apex.sample.events", | "name": "Event0004", |
1118 | "name": "Event0000", | "version": "0.0.1", |
1119 | "version": "0.0.1", | "nameSpace": "org.onap.policy.apex.sample.events", |
1120 | "source": "test", | "source": "Act", |
1121 | "target": "apex", | "target": "Outside", |
1122 | "TestSlogan": "Test slogan for External Event0", | "TestActCaseSelected": 2, |
1123 | "TestMatchCase": 0, | "TestActStateTime": 1536157104627, |
1124 | "TestTimestamp": 1469781869269, | "TestDecideCaseSelected": 0, |
1125 | "TestTemperature": 9080.866 | "TestDecideStateTime": 1536157104625, |
1126 | } | "TestEstablishCaseSelected": 0, |
1127 | | "TestEstablishStateTime": 1536157104623, |
1128 | | "TestMatchCase": 0, |
1129 | | "TestMatchCaseSelected": 1, |
1130 | | "TestMatchStateTime": 1536157104620, |
1131 | | "TestSlogan": "Test slogan for External Event0", |
1132 | | "TestTemperature": 9080.866, |
1133 | | "TestTimestamp": 1469781869269 |
1135 +-------------------------------------------------------------+-------------------------------------------------------------+
1137 .. container:: paragraph
1139 Terminate APEX by simply using ``CTRL+C`` in the console.
1141 Verify a Full Installation - REST Editor
1142 ########################################
1144 .. container:: paragraph
1146 APEX has a REST application for viewing policy models. The
1147 application can also be used to create new policy models close to
1148 the engine native policy language. Start the REST editor as
1151 .. container:: listingblock
1153 .. container:: content
1158 # $APEX_HOME/bin/apexApps.sh rest-editor
1160 .. container:: listingblock
1162 .. container:: content
1167 >%APEX_HOME%\bin\apexApps.bat rest-editor
1169 .. container:: paragraph
1171 The script will start a simple web server
1172 (`Grizzly <https://javaee.github.io/grizzly/>`__) and deploy a
1173 ``war`` web archive in it. Once the editor is started, it will be
1174 available on ``localhost:18989``. The last few line of the messages
1177 .. container:: listingblock
1179 .. container:: content
1184 Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
1185 Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.NetworkListener start
1186 INFO: Started listener bound to [localhost:18989]
1187 Sep 05, 2018 10:35:57 PM org.glassfish.grizzly.http.server.HttpServer start
1188 INFO: [HttpServer] Started.
1189 Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
1191 .. container:: paragraph
1193 Now open a browser (Firefox, Chrome, Opera, Internet Explorer) and
1194 use the URL ``http://localhost:18989/``. This will connect the
1195 browser to the started REST editor. The start screen should be as
1198 .. container:: imageblock
1200 .. container:: content
1202 |REST Editor Start Screen|
1204 .. container:: title
1206 Figure 1. REST Editor Start Screen
1208 .. container:: paragraph
1210 Now load a policy model by clicking the menu ``File`` and then
1211 ``Open``. In the opened dialog, go to the directory where APEX is
1212 installed, then ``examples``, ``models``, ``SampleDomain``, and there
1213 select the file ``SamplePolicyModelJAVA.json``. This will load the
1214 policy model used to verify the policy engine (see above). Once
1215 loaded, the screen should look as follows.
1217 .. container:: imageblock
1219 .. container:: content
1221 |REST Editor with loaded SampleDomain Policy Model|
1223 .. container:: title
1225 Figure 2. REST Editor with loaded SampleDomain Policy Model
1227 .. container:: paragraph
1229 Now you can use the REST editor. To finish this verification, simply
1230 terminate your browser (or the tab), and then use ``CTRL+C`` in the
1231 console where you started the REST editor.
1233 Installing WAR Applications
1234 ---------------------------
1236 .. container:: paragraph
1238 APEX comes with a set of WAR files. These are complete
1239 applications that can be installed and run in an application
1240 server. All of these applications are realized as servlets. You
1241 can find the WAR applications in ``$APEX_HOME/war`` (UNIX, Cygwin)
1242 or ``%APEX_HOME%\war`` (Windows).
1244 .. container:: paragraph
1246 Installing and using the WAR applications requires a web server
1247 that can execute ``war`` web archives. We recommend to use `Apache
1248 Tomcat <https://tomcat.apache.org/>`__, however other web servers
1249 can be used as well.
1251 .. container:: paragraph
1253 Install Apache Tomcat including the ``Manager App``, see `V9.0
1254 Docs <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html#Configuring_Manager_Application_Access>`__
1255 for details. Start the Tomcat service, or make sure that Tomcat is
1258 .. container:: paragraph
1260 There are multiple ways to install the APEX WAR applications:
1262 .. container:: ulist
1264 - copy the ``.war`` file into the Tomcat ``webapps`` folder
1266 - use the Tomcat ``Manager App`` to deploy via the web interface
1268 - deploy using a REST call to Tomcat
1270 .. container:: paragraph
1272 For details on how to install ``war`` files please consult the
1274 Documentation <https://tomcat.apache.org/tomcat-9.0-doc/index.html>`__
1276 HOW-TO <https://tomcat.apache.org/tomcat-9.0-doc/manager-howto.html>`__.
1277 Once you installed an APEX WAR application (and wait for
1278 sufficient time for Tomcat to finalize the installation), open the
1279 ``Manager App`` in Tomcat. You should see the APEX WAR application
1280 being installed and running.
1282 .. container:: paragraph
1284 In case of errors, examine the log files in the Tomcat log
1285 directory. In a conventional install, those log files are in the
1286 logs directory where Tomcat is installed.
1288 .. container:: paragraph
1290 The current APEX version provides the following WAR applications:
1292 .. container:: ulist
1294 - client-deployment-2.0.0-SNAPSHOT.war - a client to deploy new
1295 policy models to a running engine
1297 - client-editor-2.0.0-SNAPSHOT.war - the standard policy REST
1300 - client-monitoring-2.0.0-SNAPSHOT.war - a client for monitoring
1301 a running APEX engine
1303 - client-full-2.0.0-SNAPSHOT.war - a full client with a
1304 one-stop-access to deployment, monitoring, and REST editor
1306 - examples-servlet-2.0.0-SNAPSHOT.war - an example APEX servlet
1308 Running APEX in Docker
1309 ----------------------
1311 .. container:: paragraph
1313 Since APEX is in ONAP, we provide a full virtualization
1314 environment for the engine.
1319 .. container:: paragraph
1321 Running APEX from the ONAP docker repository only requires 2
1324 .. container:: olist arabic
1326 #. Log into the ONAP docker repo
1328 .. container:: listingblock
1330 .. container:: content
1334 docker login -u docker -p docker nexus3.onap.org:10003
1336 .. container:: olist arabic
1338 #. Run the APEX docker image
1340 .. container:: listingblock
1342 .. container:: content
1346 docker run -it --rm nexus3.onap.org:10003/onap/policy-apex-pdp:latest
1348 Build a Docker Image
1349 ####################
1351 .. container:: paragraph
1353 Alternatively, one can use the Dockerfile defined in the Docker
1354 package to build an image.
1356 .. container:: listingblock
1358 .. container:: title
1362 .. container:: content
1368 # Docker file to build an image that runs APEX on Java 8 in Ubuntu
1372 RUN apt-get update && \
1373 apt-get upgrade -y && \
1374 apt-get install -y software-properties-common && \
1375 add-apt-repository ppa:openjdk-r/ppa -y && \
1377 apt-get install -y openjdk-8-jdk
1379 # Create apex user and group
1380 RUN groupadd apexuser
1381 RUN useradd --create-home -g apexuser apexuser
1383 # Add Apex-specific directories and set ownership as the Apex admin user
1384 RUN mkdir -p /opt/app/policy/apex-pdp
1385 RUN mkdir -p /var/log/onap/policy/apex-pdp
1386 RUN chown -R apexuser:apexuser /var/log/onap/policy/apex-pdp
1388 # Unpack the tarball
1390 COPY apex-pdp-package-full.tar.gz /packages
1391 RUN tar xvfz /packages/apex-pdp-package-full.tar.gz --directory /opt/app/policy/apex-pdp
1392 RUN rm /packages/apex-pdp-package-full.tar.gz
1394 # Ensure everything has the correct permissions
1395 RUN find /opt/app -type d -perm 755
1396 RUN find /opt/app -type f -perm 644
1397 RUN chmod a+x /opt/app/policy/apex-pdp/bin/*
1399 # Copy examples to Apex user area
1400 RUN cp -pr /opt/app/policy/apex-pdp/examples /home/apexuser
1404 RUN chown -R apexuser:apexuser /home/apexuser/*
1407 ENV PATH /opt/app/policy/apex-pdp/bin:$PATH
1408 WORKDIR /home/apexuser
1410 APEX Configurations Explained
1411 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1413 Introduction to APEX Configuration
1414 ----------------------------------
1416 .. container:: paragraph
1418 An APEX engine can be configured to use various combinations
1419 of event input handlers, event output handlers, event
1420 protocols, context handlers, and logic executors. The system
1421 is build using a plugin architecture. Each configuration
1422 option is realized by a plugin, which can be loaded and
1423 configured when the engine is started. New plugins can be
1424 added to the system at any time, though to benefit from a
1425 new plugin an engine will need to be restarted.
1427 .. container:: imageblock
1429 .. container:: content
1431 |APEX Configuration Matrix|
1433 .. container:: title
1435 Figure 3. APEX Configuration Matrix
1437 .. container:: paragraph
1439 The APEX distribution already comes with a number of
1440 plugins. The figure above shows the provided plugins. Any
1441 combination of input, output, event protocol, context
1442 handlers, and executors is possible.
1444 General Configuration Format
1445 ----------------------------
1447 .. container:: paragraph
1449 The APEX configuration file is a JSON file containing a few
1450 main blocks for different parts of the configuration. Each
1451 block then holds the configuration details. The following
1452 code shows the main blocks:
1454 .. container:: listingblock
1456 .. container:: content
1461 "engineServiceParameters":{
1463 "engineParameters":{ (2)
1464 "engineParameters":{...}, (3)
1465 "contextParameters":{...} (4)
1468 "eventInputParameters":{ (5)
1470 "carrierTechnologyParameters":{...},
1471 "eventProtocolParameters":{...}
1474 "carrierTechnologyParameters":{...},
1475 "eventProtocolParameters":{...}
1479 "eventOutputParameters":{ (9)
1481 "carrierTechnologyParameters":{...},
1482 "eventProtocolParameters":{...}
1485 "carrierTechnologyParameters":{...},
1486 "eventProtocolParameters":{...}
1492 .. container:: colist arabic
1494 +-----------------------------------+-----------------------------------+
1495 | **1** | main engine configuration |
1496 +-----------------------------------+-----------------------------------+
1497 | **2** | engine parameters for plugin |
1498 | | configurations (execution |
1499 | | environments and context |
1501 +-----------------------------------+-----------------------------------+
1502 | **3** | engine specific parameters, |
1503 | | mainly for executor plugins |
1504 +-----------------------------------+-----------------------------------+
1505 | **4** | context specific parameters, e.g. |
1506 | | for context schemas, persistence, |
1508 +-----------------------------------+-----------------------------------+
1509 | **5** | configuration of the input |
1511 +-----------------------------------+-----------------------------------+
1512 | **6** | an example input called |
1513 | | ``input1`` with carrier |
1514 | | technology and event protocol |
1515 +-----------------------------------+-----------------------------------+
1516 | **7** | an example input called |
1517 | | ``input2`` with carrier |
1518 | | technology and event protocol |
1519 +-----------------------------------+-----------------------------------+
1520 | **8** | any further input configuration |
1521 +-----------------------------------+-----------------------------------+
1522 | **9** | configuration of the output |
1524 +-----------------------------------+-----------------------------------+
1525 | **10** | an example output called |
1526 | | ``output1`` with carrier |
1527 | | technology and event protocol |
1528 +-----------------------------------+-----------------------------------+
1529 | **11** | an example output called |
1530 | | ``output2`` with carrier |
1531 | | technology and event protocol |
1532 +-----------------------------------+-----------------------------------+
1533 | **12** | any further output configuration |
1534 +-----------------------------------+-----------------------------------+
1536 Engine Service Parameters
1537 -------------------------
1539 .. container:: paragraph
1541 The configuration provides a number of parameters to
1542 configure the engine. An example configuration with
1543 explanations of all options is shown below.
1545 .. container:: listingblock
1547 .. container:: content
1551 "engineServiceParameters" : {
1552 "name" : "AADMApexEngine", (1)
1553 "version" : "0.0.1", (2)
1555 "instanceCount" : 4, (4)
1556 "deploymentPort" : 12345, (5)
1557 "policyModelFileName" : "examples/models/VPN/VPNPolicyModelJava.json", (6)
1558 "periodicEventPeriod": 1000, (7)
1559 "engineParameters":{ (8)
1560 "engineParameters":{...}, (9)
1561 "contextParameters":{...} (10)
1565 .. container:: colist arabic
1567 +-----------------------------------+-----------------------------------+
1568 | **1** | a name for the engine. The engine |
1569 | | name is used to create a key in a |
1570 | | runtime engine. An name matching |
1571 | | the following regular expression |
1572 | | can be used here: |
1573 | | ``[A-Za-z0-9\\-_\\.]+`` |
1574 +-----------------------------------+-----------------------------------+
1575 | **2** | a version of the engine, use |
1576 | | semantic versioning as explained |
1577 | | here: `Semantic |
1578 | | Versioning <http://semver.org/>`_ |
1580 | | This version is used in a runtime |
1581 | | engine to create a version of the |
1582 | | engine. For that reason, the |
1583 | | version must match the following |
1584 | | regular expression ``[A-Z0-9.]+`` |
1585 +-----------------------------------+-----------------------------------+
1586 | **3** | a numeric identifier for the |
1588 +-----------------------------------+-----------------------------------+
1589 | **4** | the number of threads (policy |
1590 | | instances executed in parallel) |
1591 | | the engine should use, use ``1`` |
1592 | | for single threaded engines |
1593 +-----------------------------------+-----------------------------------+
1594 | **5** | the port for the deployment |
1595 | | Websocket connection to the |
1597 +-----------------------------------+-----------------------------------+
1598 | **6** | the model file to load into the |
1599 | | engine on startup (optional) |
1600 +-----------------------------------+-----------------------------------+
1601 | **7** | an optional timer for periodic |
1602 | | policies, in milliseconds (a |
1603 | | defined periodic policy will be |
1604 | | executed every ``X`` |
1605 | | milliseconds), not used of not |
1607 +-----------------------------------+-----------------------------------+
1608 | **8** | engine parameters for plugin |
1609 | | configurations (execution |
1610 | | environments and context |
1612 +-----------------------------------+-----------------------------------+
1613 | **9** | engine specific parameters, |
1614 | | mainly for executor plugins |
1615 +-----------------------------------+-----------------------------------+
1616 | **10** | context specific parameters, e.g. |
1617 | | for context schemas, persistence, |
1619 +-----------------------------------+-----------------------------------+
1621 .. container:: paragraph
1623 The model file is optional, it can also be specified via
1624 command line. In any case, make sure all execution and other
1625 required plug-ins for the loaded model are loaded as
1628 Input and Output Interfaces
1629 ---------------------------
1631 .. container:: paragraph
1633 An APEX engine has two main interfaces:
1635 .. container:: ulist
1637 - An *input* interface to receive events: also known as
1638 ingress interface or consumer, receiving (consuming)
1639 events commonly named triggers, and
1641 - An *output* interface to publish produced events: also
1642 known as egress interface or producer, sending
1643 (publishing) events commonly named actions or action
1646 .. container:: paragraph
1648 The input and output interface is configured in terms of
1649 inputs and outputs, respectively. Each input and output is a
1650 combination of a carrier technology and an event protocol.
1651 Carrier technologies and event protocols are provided by
1652 plugins, each with its own specific configuration. Most
1653 carrier technologies can be configured for input as well as
1654 output. Most event protocols can be used for all carrier
1655 technologies. One exception is the JMS object event
1656 protocol, which can only be used for the JMS carrier
1657 technology. Some further restrictions apply (for instance
1658 for carrier technologies using bi- or uni-directional
1661 .. container:: paragraph
1663 Input and output interface can be configured separately, in
1664 isolation, with any number of carrier technologies. The
1665 resulting general configuration options are:
1667 .. container:: ulist
1669 - Input interface with one or more inputs
1671 .. container:: ulist
1673 - each input with a carrier technology and an event
1676 - some inputs with optional synchronous mode
1678 - some event protocols with additional parameters
1680 - Output interface with one or more outputs
1682 .. container:: ulist
1684 - each output with a carrier technology and an event
1687 - some outputs with optional synchronous mode
1689 - some event protocols with additional parameters
1691 .. container:: paragraph
1693 The configuration for input and output is contained in
1694 ``eventInputParameters`` and ``eventOutputParameters``,
1695 respectively. Inside here, one can configure any number of
1696 inputs and outputs. Each of them needs to have a unique
1697 identifier (name), the content of the name is free form. The
1698 example below shows a configuration for two inputs and two
1701 .. container:: listingblock
1703 .. container:: content
1707 "eventInputParameters": { (1)
1708 "FirstConsumer": { (2)
1709 "carrierTechnologyParameters" : {...}, (3)
1710 "eventProtocolParameters":{...}, (4)
1713 "SecondConsumer": { (6)
1714 "carrierTechnologyParameters" : {...}, (7)
1715 "eventProtocolParameters":{...}, (8)
1719 "eventOutputParameters": { (10)
1720 "FirstProducer": { (11)
1721 "carrierTechnologyParameters":{...}, (12)
1722 "eventProtocolParameters":{...}, (13)
1725 "SecondProducer": { (15)
1726 "carrierTechnologyParameters":{...}, (16)
1727 "eventProtocolParameters":{...}, (17)
1732 .. container:: colist arabic
1734 +--------+--------------------------------------------------------------------+
1735 | **1** | input interface configuration, APEX input plugins |
1736 +--------+--------------------------------------------------------------------+
1737 | **2** | first input called ``FirstConsumer`` |
1738 +--------+--------------------------------------------------------------------+
1739 | **3** | carrier technology for plugin |
1740 +--------+--------------------------------------------------------------------+
1741 | **4** | event protocol for plugin |
1742 +--------+--------------------------------------------------------------------+
1743 | **5** | any other input configuration (e.g. event name filter, see below) |
1744 +--------+--------------------------------------------------------------------+
1745 | **6** | second input called ``SecondConsumer`` |
1746 +--------+--------------------------------------------------------------------+
1747 | **7** | carrier technology for plugin |
1748 +--------+--------------------------------------------------------------------+
1749 | **8** | event protocol for plugin |
1750 +--------+--------------------------------------------------------------------+
1751 | **9** | any other plugin configuration |
1752 +--------+--------------------------------------------------------------------+
1753 | **10** | output interface configuration, APEX output plugins |
1754 +--------+--------------------------------------------------------------------+
1755 | **11** | first output called ``FirstProducer`` |
1756 +--------+--------------------------------------------------------------------+
1757 | **12** | carrier technology for plugin |
1758 +--------+--------------------------------------------------------------------+
1759 | **13** | event protocol for plugin |
1760 +--------+--------------------------------------------------------------------+
1761 | **14** | any other plugin configuration |
1762 +--------+--------------------------------------------------------------------+
1763 | **15** | second output called ``SecondProducer`` |
1764 +--------+--------------------------------------------------------------------+
1765 | **16** | carrier technology for plugin |
1766 +--------+--------------------------------------------------------------------+
1767 | **17** | event protocol for plugin |
1768 +--------+--------------------------------------------------------------------+
1769 | **18** | any other output configuration (e.g. event name filter, see below) |
1770 +--------+--------------------------------------------------------------------+
1775 .. container:: paragraph
1777 APEX will always send an event after a policy execution
1778 is finished. For a successful execution, the event sent
1779 is the output event created by the policy. In case the
1780 policy does not create an output event, APEX will create
1781 a new event with all input event fields plus an
1782 additional field ``exceptionMessage`` with an exception
1785 .. container:: paragraph
1787 There are situations in which this auto-generated error
1788 event might not be required or wanted:
1790 .. container:: ulist
1792 - when a policy failing should not result in an event
1793 send out via an output interface
1795 - when the auto-generated event goes back in an APEX
1796 engine (or the same APEX engine), this can create
1799 - the auto-generated event should go to a special output
1800 interface or channel
1802 .. container:: paragraph
1804 All of these situations are supported by a filter option
1805 using a wildecard (regular expression) configuration on
1806 APEX I/O interfaces. The parameter is called
1807 ``eventNameFilter`` and the value are `Java regular
1808 expressions <https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html>`__
1810 `tutorial <http://www.vogella.com/tutorials/JavaRegularExpressions/article.html>`__).
1811 The following code shows some examples:
1813 .. container:: listingblock
1815 .. container:: content
1819 "eventInputParameters": {
1821 "carrierTechnologyParameters" : {...},
1822 "eventProtocolParameters":{...},
1823 "eventNameFilter" : "^E[Vv][Ee][Nn][Tt][0-9]004$" (1)
1826 "eventOutputParameters": {
1828 "carrierTechnologyParameters":{...},
1829 "eventProtocolParameters":{...},
1830 "eventNameFilter" : "^E[Vv][Ee][Nn][Tt][0-9]104$" (2)
1837 .. container:: paragraph
1839 Executors are plugins that realize the execution of logic
1840 contained in a policy model. Logic can be in a task
1841 selector, a task, and a state finalizer. Using plugins for
1842 execution environments makes APEX very flexible to support
1843 virtually any executable logic expressions.
1845 .. container:: paragraph
1847 APEX 2.0.0-SNAPSHOT supports the following executors:
1849 .. container:: ulist
1851 - Java, for Java implemented logic
1853 .. container:: ulist
1855 - This executor requires logic implemented using the
1856 APEX Java interfaces.
1858 - Generated JAR files must be in the classpath of the
1859 APEX engine at start time.
1869 .. container:: ulist
1871 - This executor uses the latest version of the MVEL
1872 engine, which can be very hard to debug and can
1873 produce unwanted side effects during execution
1875 Configure the Javascript Executor
1876 #################################
1878 .. container:: paragraph
1880 The Javascript executor is added to the configuration as
1883 .. container:: listingblock
1885 .. container:: content
1889 "engineServiceParameters":{
1890 "engineParameters":{
1891 "executorParameters":{
1893 "parameterClassName" :
1894 "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"
1900 Configure the Jython Executor
1901 #############################
1903 .. container:: paragraph
1905 The Jython executor is added to the configuration as
1908 .. container:: listingblock
1910 .. container:: content
1914 "engineServiceParameters":{
1915 "engineParameters":{
1916 "executorParameters":{
1918 "parameterClassName" :
1919 "org.onap.policy.apex.plugins.executor.jython.JythonExecutorParameters"
1925 Configure the JRuby Executor
1926 ############################
1928 .. container:: paragraph
1930 The JRuby executor is added to the configuration as
1933 .. container:: listingblock
1935 .. container:: content
1939 "engineServiceParameters":{
1940 "engineParameters":{
1941 "executorParameters":{
1943 "parameterClassName" :
1944 "org.onap.policy.apex.plugins.executor.jruby.JrubyExecutorParameters"
1950 Configure the Java Executor
1951 ###########################
1953 .. container:: paragraph
1955 The Java executor is added to the configuration as
1958 .. container:: listingblock
1960 .. container:: content
1964 "engineServiceParameters":{
1965 "engineParameters":{
1966 "executorParameters":{
1968 "parameterClassName" :
1969 "org.onap.policy.apex.plugins.executor.java.JavaExecutorParameters"
1975 Configure the MVEL Executor
1976 ###########################
1978 .. container:: paragraph
1980 The MVEL executor is added to the configuration as
1983 .. container:: listingblock
1985 .. container:: content
1989 "engineServiceParameters":{
1990 "engineParameters":{
1991 "executorParameters":{
1993 "parameterClassName" :
1994 "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
2003 .. container:: paragraph
2005 Context handlers are responsible for all context processing.
2006 There are the following main areas:
2008 .. container:: ulist
2010 - Context schema: use schema handlers other than Java class
2011 (supported by default without configuration)
2013 - Context distribution: distribute context across multiple
2016 - Context locking: mechanisms to lock context elements for
2019 - Context persistence: mechanisms to persist context
2021 .. container:: paragraph
2023 APEX provides plugins for each of the main areas.
2025 Configure AVRO Schema Handler
2026 #############################
2028 .. container:: paragraph
2030 The AVRO schema handler is added to the configuration as
2033 .. container:: listingblock
2035 .. container:: content
2039 "engineServiceParameters":{
2040 "engineParameters":{
2041 "contextParameters":{
2042 "parameterClassName" : "org.onap.policy.apex.context.parameters.ContextParameters",
2043 "schemaParameters":{
2045 "parameterClassName" :
2046 "org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters"
2053 .. container:: paragraph
2055 Using the AVRO schema handler has one limitation: AVRO
2056 only supports field names that represent valid Java class
2057 names. This means only letters and the character ``_``
2058 are supported. Characters commonly used in field names,
2059 such as ``.`` and ``-``, are not supported by AVRO. for
2060 more information see `Avro Spec:
2061 Names <https://avro.apache.org/docs/1.8.1/spec.html#names>`__.
2063 .. container:: paragraph
2065 To work with this limitation, the APEX Avro plugin will
2066 parse a given AVRO definition and replace *all*
2067 occurrences of ``.`` and ``-`` with a ``_``. This means
2070 .. container:: ulist
2072 - In a policy model, if the AVRO schema defined a field
2073 as ``my-name`` the policy logic should access it as
2076 - In a policy model, if the AVRO schema defined a field
2077 as ``my.name`` the policy logic should access it as
2080 - There should be no field names that convert to the
2083 .. container:: ulist
2085 - For instance the simultaneous use of
2086 ``my_name``, ``my.name``, and ``my-name`` should
2089 - If not avoided, the event processing might
2090 create unwanted side effects
2092 - If field names use any other not-supported character,
2093 the AVRO plugin will reject it
2095 .. container:: ulist
2097 - Since AVRO uses lazy initialization, this
2098 rejection might only become visible at runtime
2100 Carrier Technologies
2101 --------------------
2103 .. container:: paragraph
2105 Carrier technologies define how APEX receives (input) and
2106 sends (output) events. They can be used in any combination,
2107 using asynchronous or synchronous mode. There can also be
2108 any number of carrier technologies for the input (consume)
2109 and the output (produce) interface.
2111 .. container:: paragraph
2113 Supported *input* technologies are:
2115 .. container:: ulist
2117 - Standard input, read events from the standard input
2118 (console), not suitable for APEX background servers
2120 - File input, read events from a file
2122 - Kafka, read events from a Kafka system
2124 - Websockets, read events from a Websocket
2128 - REST (synchronous and asynchronous), additionally as
2131 - Event Requestor, allows reading of events that have been
2132 looped back into APEX
2134 .. container:: paragraph
2136 Supported *output* technologies are:
2138 .. container:: ulist
2140 - Standard output, write events to the standard output
2141 (console), not suitable for APEX background servers
2143 - File output, write events to a file
2145 - Kafka, write events to a Kafka system
2147 - Websockets, write events to a Websocket
2151 - REST (synchronous and asynchronous), additionally as
2154 - Event Requestor, allows events to be looped back into
2157 .. container:: paragraph
2159 New carrier technologies can be added as plugins to APEX or
2160 developed outside APEX and added to an APEX deployment.
2165 .. container:: paragraph
2167 Standard IO does not require a specific plugin, it is
2168 supported be default.
2172 .. container:: paragraph
2174 APEX will take events from its standard input. This
2175 carrier is good for testing, but certainly not for a
2176 use case where APEX runs as a server. The
2177 configuration is as follows:
2179 .. container:: listingblock
2181 .. container:: content
2185 "carrierTechnologyParameters" : {
2186 "carrierTechnology" : "FILE", (1)
2188 "standardIO" : true (2)
2192 .. container:: colist arabic
2194 +-------+---------------------------------------+
2195 | **1** | standard input is considered a file |
2196 +-------+---------------------------------------+
2197 | **2** | file descriptor set to standard input |
2198 +-------+---------------------------------------+
2203 .. container:: paragraph
2205 APEX will send events to its standard output. This
2206 carrier is good for testing, but certainly not for a
2207 use case where APEX runs as a server. The
2208 configuration is as follows:
2210 .. container:: listingblock
2212 .. container:: content
2216 "carrierTechnologyParameters" : {
2217 "carrierTechnology" : "FILE", (1)
2219 "standardIO" : true (2)
2223 .. container:: colist arabic
2225 +-------+----------------------------------------+
2226 | **1** | standard output is considered a file |
2227 +-------+----------------------------------------+
2228 | **2** | file descriptor set to standard output |
2229 +-------+----------------------------------------+
2234 .. container:: paragraph
2236 File IO does not require a specific plugin, it is
2237 supported be default.
2242 .. container:: paragraph
2244 APEX will take events from a file. The same file
2245 should not be used as an output. The configuration is
2248 .. container:: listingblock
2250 .. container:: content
2254 "carrierTechnologyParameters" : {
2255 "carrierTechnology" : "FILE", (1)
2257 "fileName" : "examples/events/SampleDomain/EventsIn.xmlfile" (2)
2261 .. container:: colist arabic
2263 +-------+------------------------------------------+
2264 | **1** | set file input |
2265 +-------+------------------------------------------+
2266 | **2** | the name of the file to read events from |
2267 +-------+------------------------------------------+
2271 .. container:: paragraph
2273 APEX will write events to a file. The same file should
2274 not be used as an input. The configuration is as
2277 .. container:: listingblock
2279 .. container:: content
2283 "carrierTechnologyParameters" : {
2284 "carrierTechnology" : "FILE", (1)
2286 "fileName" : "examples/events/SampleDomain/EventsOut.xmlfile" (2)
2290 .. container:: colist arabic
2292 +-------+-----------------------------------------+
2293 | **1** | set file output |
2294 +-------+-----------------------------------------+
2295 | **2** | the name of the file to write events to |
2296 +-------+-----------------------------------------+
2301 .. container:: paragraph
2303 Event Requestor IO does not require a specific plugin, it
2304 is supported be default. It should only be used with the
2305 APEX event protocol.
2307 Event Requestor Input
2308 =====================
2310 .. container:: paragraph
2312 APEX will take events from APEX.
2314 .. container:: listingblock
2316 .. container:: content
2320 "carrierTechnologyParameters" : {
2321 "carrierTechnology": "EVENT_REQUESTOR" (1)
2324 .. container:: colist arabic
2326 +-------+---------------------------+
2327 | **1** | set event requestor input |
2328 +-------+---------------------------+
2330 Event Requestor Output
2331 ======================
2333 .. container:: paragraph
2335 APEX will write events to APEX.
2337 .. container:: listingblock
2339 .. container:: content
2343 "carrierTechnologyParameters" : {
2344 "carrierTechnology": "EVENT_REQUESTOR" (1)
2347 Peering Event Requestors
2348 ========================
2350 .. container:: paragraph
2352 When using event requestors, they need to be peered.
2353 This means an event requestor output needs to be
2354 peered (associated) with an event requestor input. The
2355 following example shows the use of an event requestor
2356 with the APEX event protocol and the peering of output
2359 .. container:: listingblock
2361 .. container:: content
2365 "eventInputParameters": {
2366 "EventRequestorConsumer": {
2367 "carrierTechnologyParameters": {
2368 "carrierTechnology": "EVENT_REQUESTOR" (1)
2370 "eventProtocolParameters": {
2371 "eventProtocol": "APEX" (2)
2373 "eventNameFilter": "InputEvent", (3)
2374 "requestorMode": true, (4)
2375 "requestorPeer": "EventRequestorProducer", (5)
2376 "requestorTimeout": 500 (6)
2379 "eventOutputParameters": {
2380 "EventRequestorProducer": {
2381 "carrierTechnologyParameters": {
2382 "carrierTechnology": "EVENT_REQUESTOR" (7)
2384 "eventProtocolParameters": {
2385 "eventProtocol": "APEX" (8)
2387 "eventNameFilter": "EventListEvent", (9)
2388 "requestorMode": true, (10)
2389 "requestorPeer": "EventRequestorConsumer", (11)
2390 "requestorTimeout": 500 (12)
2394 .. container:: colist arabic
2396 +-----------------------------------+-----------------------------------+
2397 | **1** | event requestor on a consumer |
2398 +-----------------------------------+-----------------------------------+
2399 | **2** | with APEX event protocol |
2400 +-----------------------------------+-----------------------------------+
2401 | **3** | optional filter (best to use a |
2402 | | filter to prevent unwanted events |
2403 | | on the consumer side) |
2404 +-----------------------------------+-----------------------------------+
2405 | **4** | activate requestor mode |
2406 +-----------------------------------+-----------------------------------+
2407 | **5** | the peer to the output (must |
2408 | | match the output carrier) |
2409 +-----------------------------------+-----------------------------------+
2410 | **6** | an optional timeout in |
2412 +-----------------------------------+-----------------------------------+
2413 | **7** | event requestor on a producer |
2414 +-----------------------------------+-----------------------------------+
2415 | **8** | with APEX event protocol |
2416 +-----------------------------------+-----------------------------------+
2417 | **9** | optional filter (best to use a |
2418 | | filter to prevent unwanted events |
2419 | | on the consumer side) |
2420 +-----------------------------------+-----------------------------------+
2421 | **10** | activate requestor mode |
2422 +-----------------------------------+-----------------------------------+
2423 | **11** | the peer to the output (must |
2424 | | match the input carrier) |
2425 +-----------------------------------+-----------------------------------+
2426 | **12** | an optional timeout in |
2428 +-----------------------------------+-----------------------------------+
2433 .. container:: paragraph
2435 Kafka IO is supported by the APEX Kafka plugin. The
2436 configurations below are examples. APEX will take any
2437 configuration inside the parameter object and forward it
2438 to Kafka. More information on Kafka specific
2439 configuration parameters can be found in the Kafka
2442 .. container:: ulist
2445 Class <https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/consumer/KafkaConsumer.html>`__
2448 Class <https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/producer/KafkaProducer.html>`__
2452 .. container:: paragraph
2454 APEX will receive events from the Apache Kafka
2455 messaging system. The input is uni-directional, an
2456 engine will only receive events from the input but not
2457 send any event to the input.
2459 .. container:: listingblock
2461 .. container:: content
2465 "carrierTechnologyParameters" : {
2466 "carrierTechnology" : "KAFKA", (1)
2467 "parameterClassName" :
2468 "org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters",
2470 "bootstrapServers" : "localhost:49092", (2)
2471 "groupId" : "apex-group-id", (3)
2472 "enableAutoCommit" : true, (4)
2473 "autoCommitTime" : 1000, (5)
2474 "sessionTimeout" : 30000, (6)
2475 "consumerPollTime" : 100, (7)
2476 "consumerTopicList" : ["apex-in-0", "apex-in-1"], (8)
2478 "org.apache.kafka.common.serialization.StringDeserializer", (9)
2479 "valueDeserializer" :
2480 "org.apache.kafka.common.serialization.StringDeserializer" (10)
2484 .. container:: colist arabic
2486 +--------+-------------------------------------+
2487 | **1** | set Kafka as carrier technology |
2488 +--------+-------------------------------------+
2489 | **2** | bootstrap server and port |
2490 +--------+-------------------------------------+
2491 | **3** | a group identifier |
2492 +--------+-------------------------------------+
2493 | **4** | flag for auto-commit |
2494 +--------+-------------------------------------+
2495 | **5** | auto-commit timeout in milliseconds |
2496 +--------+-------------------------------------+
2497 | **6** | session timeout in milliseconds |
2498 +--------+-------------------------------------+
2499 | **7** | consumer poll time in milliseconds |
2500 +--------+-------------------------------------+
2501 | **8** | consumer topic list |
2502 +--------+-------------------------------------+
2503 | **9** | key for the Kafka de-serializer |
2504 +--------+-------------------------------------+
2505 | **10** | value for the Kafka de-serializer |
2506 +--------+-------------------------------------+
2510 .. container:: paragraph
2512 APEX will send events to the Apache Kafka messaging
2513 system. The output is uni-directional, an engine will
2514 send events to the output but not receive any event
2517 .. container:: listingblock
2519 .. container:: content
2523 "carrierTechnologyParameters" : {
2524 "carrierTechnology" : "KAFKA", (1)
2525 "parameterClassName" :
2526 "org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters",
2528 "bootstrapServers" : "localhost:49092", (2)
2531 "batchSize" : 16384, (5)
2532 "lingerTime" : 1, (6)
2533 "bufferMemory" : 33554432, (7)
2534 "producerTopic" : "apex-out", (8)
2536 "org.apache.kafka.common.serialization.StringSerializer", (9)
2538 "org.apache.kafka.common.serialization.StringSerializer" (10)
2542 .. container:: colist arabic
2544 +--------+---------------------------------+
2545 | **1** | set Kafka as carrier technology |
2546 +--------+---------------------------------+
2547 | **2** | bootstrap server and port |
2548 +--------+---------------------------------+
2549 | **3** | acknowledgement strategy |
2550 +--------+---------------------------------+
2551 | **4** | number of retries |
2552 +--------+---------------------------------+
2553 | **5** | batch size |
2554 +--------+---------------------------------+
2555 | **6** | time to linger in milliseconds |
2556 +--------+---------------------------------+
2557 | **7** | buffer memory in byte |
2558 +--------+---------------------------------+
2559 | **8** | producer topic |
2560 +--------+---------------------------------+
2561 | **9** | key for the Kafka serializer |
2562 +--------+---------------------------------+
2563 | **10** | value for the Kafka serializer |
2564 +--------+---------------------------------+
2569 .. container:: paragraph
2571 APEX supports the Java Messaging Service (JMS) as input
2572 as well as output. JMS IO is supported by the APEX JMS
2573 plugin. Input and output support an event encoding as
2574 text (JSON string) or object (serialized object). The
2575 input configuration is the same for both encodings, the
2576 output configuration differs.
2580 .. container:: paragraph
2582 APEX will receive events from a JMS messaging system.
2583 The input is uni-directional, an engine will only
2584 receive events from the input but not send any event
2587 .. container:: listingblock
2589 .. container:: content
2593 "carrierTechnologyParameters" : {
2594 "carrierTechnology" : "JMS", (1)
2595 "parameterClassName" :
2596 "org.onap.policy.apex.plugins.event.carrier.jms.JMSCarrierTechnologyParameters",
2597 "parameters" : { (2)
2598 "initialContextFactory" :
2599 "org.jboss.naming.remote.client.InitialContextFactory", (3)
2600 "connectionFactory" : "ConnectionFactory", (4)
2601 "providerURL" : "remote://localhost:5445", (5)
2602 "securityPrincipal" : "guest", (6)
2603 "securityCredentials" : "IAmAGuest", (7)
2604 "consumerTopic" : "jms/topic/apexIn" (8)
2608 .. container:: colist arabic
2610 +-----------------------------------+-----------------------------------+
2611 | **1** | set JMS as carrier technology |
2612 +-----------------------------------+-----------------------------------+
2613 | **2** | set all JMS specific parameters |
2614 +-----------------------------------+-----------------------------------+
2615 | **3** | the context factory, in this case |
2616 | | from JBOSS (it requires the |
2618 | | org.jboss:jboss-remote-naming:2.0 |
2620 | | or a different version to be in |
2621 | | the directory ``$APEX_HOME/lib`` |
2622 | | or ``%APEX_HOME%\lib`` |
2623 +-----------------------------------+-----------------------------------+
2624 | **4** | a connection factory for the JMS |
2626 +-----------------------------------+-----------------------------------+
2627 | **5** | URL with host and port of the JMS |
2629 +-----------------------------------+-----------------------------------+
2630 | **6** | access credentials, user name |
2631 +-----------------------------------+-----------------------------------+
2632 | **7** | access credentials, user password |
2633 +-----------------------------------+-----------------------------------+
2634 | **8** | the JMS topic to listen to |
2635 +-----------------------------------+-----------------------------------+
2637 JMS Output with Text
2638 ====================
2640 .. container:: paragraph
2642 APEX engine send events to a JMS messaging system. The
2643 output is uni-directional, an engine will send events
2644 to the output but not receive any event from output.
2646 .. container:: listingblock
2648 .. container:: content
2652 "carrierTechnologyParameters" : {
2653 "carrierTechnology" : "JMS", (1)
2654 "parameterClassName" :
2655 "org.onap.policy.apex.plugins.event.carrier.jms.JMSCarrierTechnologyParameters",
2656 "parameters" : { (2)
2657 "initialContextFactory" :
2658 "org.jboss.naming.remote.client.InitialContextFactory", (3)
2659 "connectionFactory" : "ConnectionFactory", (4)
2660 "providerURL" : "remote://localhost:5445", (5)
2661 "securityPrincipal" : "guest", (6)
2662 "securityCredentials" : "IAmAGuest", (7)
2663 "producerTopic" : "jms/topic/apexOut", (8)
2664 "objectMessageSending": "false" (9)
2668 .. container:: colist arabic
2670 +-----------------------------------+-----------------------------------+
2671 | **1** | set JMS as carrier technology |
2672 +-----------------------------------+-----------------------------------+
2673 | **2** | set all JMS specific parameters |
2674 +-----------------------------------+-----------------------------------+
2675 | **3** | the context factory, in this case |
2676 | | from JBOSS (it requires the |
2678 | | org.jboss:jboss-remote-naming:2.0 |
2680 | | or a different version to be in |
2681 | | the directory ``$APEX_HOME/lib`` |
2682 | | or ``%APEX_HOME%\lib`` |
2683 +-----------------------------------+-----------------------------------+
2684 | **4** | a connection factory for the JMS |
2686 +-----------------------------------+-----------------------------------+
2687 | **5** | URL with host and port of the JMS |
2689 +-----------------------------------+-----------------------------------+
2690 | **6** | access credentials, user name |
2691 +-----------------------------------+-----------------------------------+
2692 | **7** | access credentials, user password |
2693 +-----------------------------------+-----------------------------------+
2694 | **8** | the JMS topic to write to |
2695 +-----------------------------------+-----------------------------------+
2696 | **9** | set object messaging to ``false`` |
2697 | | means it sends JSON text |
2698 +-----------------------------------+-----------------------------------+
2700 JMS Output with Object
2701 ======================
2703 .. container:: paragraph
2705 To configure APEX for JMS objects on the output
2706 interface use the same configuration as above (for
2707 output). Simply change the ``objectMessageSending``
2708 parameter to ``true``.
2711 ########################
2713 .. container:: paragraph
2715 APEX supports the Websockets as input as well as output.
2716 WS IO is supported by the APEX Websocket plugin. This
2717 carrier technology does only support uni-directional
2718 communication. APEX will not send events to a Websocket
2719 input and any event sent to a Websocket output will
2720 result in an error log.
2722 .. container:: paragraph
2724 The input can be configured as client (APEX connects to
2725 an existing Websocket server) or server (APEX starts a
2726 Websocket server). The same applies to the output. Input
2727 and output can both use a client or a server
2728 configuration, or separate configurations (input as
2729 client and output as server, input as server and output
2730 as client). Each configuration should use its own
2731 dedicated port to avoid any communication loops. The
2732 configuration of a Websocket client is the same for input
2733 and output. The configuration of a Websocket server is
2734 the same for input and output.
2739 .. container:: paragraph
2741 APEX will connect to a given Websocket server. As
2742 input, it will receive events from the server but not
2743 send any events. As output, it will send events to the
2744 server and any event received from the server will
2745 result in an error log.
2747 .. container:: listingblock
2749 .. container:: content
2753 "carrierTechnologyParameters" : {
2754 "carrierTechnology" : "WEBSOCKET", (1)
2755 "parameterClassName" :
2756 "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",
2758 "host" : "localhost", (2)
2763 .. container:: colist arabic
2765 +-------+------------------------------------------------------+
2766 | **1** | set Websocket as carrier technology |
2767 +-------+------------------------------------------------------+
2768 | **2** | the host name on which a Websocket server is running |
2769 +-------+------------------------------------------------------+
2770 | **3** | the port of that Websocket server |
2771 +-------+------------------------------------------------------+
2776 .. container:: paragraph
2778 APEX will start a Websocket server, which will accept
2779 any Websocket clients to connect. As input, it will
2780 receive events from the server but not send any
2781 events. As output, it will send events to the server
2782 and any event received from the server will result in
2785 .. container:: listingblock
2787 .. container:: content
2791 "carrierTechnologyParameters" : {
2792 "carrierTechnology" : "WEBSOCKET", (1)
2793 "parameterClassName" :
2794 "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",
2796 "wsClient" : false, (2)
2801 .. container:: colist arabic
2803 +-------+------------------------------------------------------------+
2804 | **1** | set Websocket as carrier technology |
2805 +-------+------------------------------------------------------------+
2806 | **2** | disable client, so that APEX will start a Websocket server |
2807 +-------+------------------------------------------------------------+
2808 | **3** | the port for the Websocket server APEX will start |
2809 +-------+------------------------------------------------------------+
2814 .. container:: paragraph
2816 APEX can act as REST client on the input as well as on
2817 the output interface. The media type is
2818 ``application/json``, so this plugin does only work with
2819 the JSON Event protocol.
2824 .. container:: paragraph
2826 APEX will connect to a given URL to receive events,
2827 but not send any events. The server is polled, i.e.
2828 APEX will do an HTTP GET, take the result, and then do
2829 the next GET. Any required timing needs to be handled
2830 by the server configured via the URL. For instance,
2831 the server could support a wait timeout via the URL as
2833 The httpCodeFilter is used for filtering the status
2834 code, and it can be configured as a regular expression
2835 string. The default httpCodeFilter is "[2][0-9][0-9]"
2836 - for successful response codes.
2837 The response with HTTP status code that matches the
2838 given regular expression is forwarded to the task,
2839 otherwise it is logged as a failure.
2841 .. container:: listingblock
2843 .. container:: content
2847 "carrierTechnologyParameters" : {
2848 "carrierTechnology" : "RESTCLIENT", (1)
2849 "parameterClassName" :
2850 "org.onap.policy.apex.plugins.event.carrier.restclient.RESTClientCarrierTechnologyParameters",
2852 "url" : "http://example.org:8080/triggers/events", (2)
2853 "httpCodeFilter" : "[2][0-9][0-9]" (3)
2857 .. container:: colist arabic
2859 +-------+--------------------------------------------------+
2860 | **1** | set REST client as carrier technology |
2861 +-------+--------------------------------------------------+
2862 | **2** | the URL of the HTTP server for events |
2863 +-------+--------------------------------------------------+
2864 | **3** | use HTTP CODE FILTER for filtering status code |
2865 +-------+--------------------------------------------------+
2870 .. container:: paragraph
2872 APEX will connect to a given URL to send events, but
2873 not receive any events. The default HTTP operation is
2874 POST (no configuration required). To change it to PUT
2875 simply add the configuration parameter (as shown in
2877 The URL can be configured statically or tagged
2878 as ``?example.{site}.org:8080/{trig}/events``,
2879 all tags such as ``site`` and ``trig`` in the URL
2880 need to be set in the properties object available to
2881 the tasks. In addition, the keys should exactly match
2882 with the tags defined in url. The scope of the properties
2883 object is per HTTP call. Hence, key/value pairs set
2884 in the properties object by task are only available
2885 for that specific HTTP call.
2887 .. container:: listingblock
2889 .. container:: content
2893 "carrierTechnologyParameters" : {
2894 "carrierTechnology" : "RESTCLIENT", (1)
2895 "parameterClassName" :
2896 "org.onap.policy.apex.plugins.event.carrier.restclient.RESTClientCarrierTechnologyParameters",
2898 "url" : "http://example.com:8888/actions/events", (2)
2899 "url" : "http://example.{site}.com:8888/{trig}/events", (2')
2900 "httpMethod" : "PUT" (3)
2904 .. container:: colist arabic
2906 +-------+--------------------------------------------------+
2907 | **1** | set REST client as carrier technology |
2908 +-------+--------------------------------------------------+
2909 | **2** | the static URL of the HTTP server for events |
2910 +-------+--------------------------------------------------+
2911 | **2'**| the tagged URL of the HTTP server for events |
2912 +-------+--------------------------------------------------+
2913 | **3** | use HTTP PUT (remove this line to use HTTP POST) |
2914 +-------+--------------------------------------------------+
2919 .. container:: paragraph
2921 APEX supports a REST server for input and output.
2923 .. container:: paragraph
2925 The REST server plugin always uses a synchronous mode. A
2926 client does a HTTP GET on the APEX REST server with the
2927 input event and receives the generated output event in
2928 the server reply. This means that for the REST server
2929 there has to always to be an input with an associated
2930 output. Input or output only are not permitted.
2932 .. container:: paragraph
2934 The plugin will start a Grizzly server as REST server for
2935 a normal APEX engine. If the APEX engine is executed as a
2936 servlet, for instance inside Tomcat, then Tomcat will be
2937 used as REST server (this case requires configuration on
2940 .. container:: paragraph
2942 Some configuration restrictions apply for all scenarios:
2944 .. container:: ulist
2946 - Minimum port: 1024
2948 - Maximum port: 65535
2950 - The media type is ``application/json``, so this plugin
2951 does only work with the JSON Event protocol.
2953 .. container:: paragraph
2955 The URL the client calls is created using
2957 .. container:: ulist
2959 - the configured host and port, e.g.
2960 ``http://localhost:12345``
2962 - the standard path, e.g. ``/apex/``
2964 - the name of the input/output, e.g. ``FirstConsumer/``
2966 - the input or output name, e.g. ``EventIn``.
2968 .. container:: paragraph
2970 The examples above lead to the URL
2971 ``http://localhost:12345/apex/FirstConsumer/EventIn``.
2973 .. container:: paragraph
2975 A client can also get status information of the REST
2976 server using ``/Status``, e.g.
2977 ``http://localhost:12345/apex/FirstConsumer/Status``.
2979 REST Server Stand-alone
2980 =======================
2982 .. container:: paragraph
2984 We need to configure a REST server input and a REST
2985 server output. Input and output are associated with
2986 each other via there name.
2988 .. container:: paragraph
2990 Timeouts for REST calls need to be set carefully. If
2991 they are too short, the call might timeout before a
2992 policy finished creating an event.
2994 .. container:: paragraph
2996 The following example configures the input named as
2997 ``MyConsumer`` and associates an output named
2998 ``MyProducer`` with it.
3000 .. container:: listingblock
3002 .. container:: content
3006 "eventInputParameters": {
3008 "carrierTechnologyParameters" : {
3009 "carrierTechnology" : "RESTSERVER", (1)
3010 "parameterClassName" :
3011 "org.onap.policy.apex.plugins.event.carrier.restserver.RESTServerCarrierTechnologyParameters",
3013 "standalone" : true, (2)
3014 "host" : "localhost", (3)
3018 "eventProtocolParameters":{
3019 "eventProtocol" : "JSON" (5)
3021 "synchronousMode" : true, (6)
3022 "synchronousPeer" : "MyProducer", (7)
3023 "synchronousTimeout" : 500 (8)
3027 .. container:: colist arabic
3029 +-------+---------------------------------------+
3030 | **1** | set REST server as carrier technology |
3031 +-------+---------------------------------------+
3032 | **2** | set the server as stand-alone |
3033 +-------+---------------------------------------+
3034 | **3** | set the server host |
3035 +-------+---------------------------------------+
3036 | **4** | set the server listen port |
3037 +-------+---------------------------------------+
3038 | **5** | use JSON event protocol |
3039 +-------+---------------------------------------+
3040 | **6** | activate synchronous mode |
3041 +-------+---------------------------------------+
3042 | **7** | associate an output ``MyProducer`` |
3043 +-------+---------------------------------------+
3044 | **8** | set a timeout of 500 milliseconds |
3045 +-------+---------------------------------------+
3047 .. container:: paragraph
3049 The following example configures the output named as
3050 ``MyProducer`` and associates the input ``MyConsumer``
3051 with it. Note that for the output there are no more
3052 paramters (such as host or port), since they are
3053 already configured in the associated input
3055 .. container:: listingblock
3057 .. container:: content
3061 "eventOutputParameters": {
3063 "carrierTechnologyParameters":{
3064 "carrierTechnology" : "RESTSERVER",
3065 "parameterClassName" :
3066 "org.onap.policy.apex.plugins.event.carrier.restserver.RESTServerCarrierTechnologyParameters"
3068 "eventProtocolParameters":{
3069 "eventProtocol" : "JSON"
3071 "synchronousMode" : true,
3072 "synchronousPeer" : "MyConsumer",
3073 "synchronousTimeout" : 500
3077 REST Server Stand-alone, multi input
3078 ====================================
3080 .. container:: paragraph
3082 Any number of input/output pairs for REST servers can
3083 be configured. For instance, we can configure an input
3084 ``FirstConsumer`` with output ``FirstProducer`` and an
3085 input ``SecondConsumer`` with output
3086 ``SecondProducer``. Important is that there is always
3087 one pair of input/output.
3089 REST Server Stand-alone in Servlet
3090 ==================================
3092 .. container:: paragraph
3094 If APEX is executed as a servlet, e.g. inside Tomcat,
3095 the configuration becomes easier since the plugin can
3096 now use Tomcat as the REST server. In this scenario,
3097 there are not parameters (port, host, etc.) and the
3098 key ``standalone`` must not be used (or set to false).
3100 .. container:: paragraph
3102 For the Tomcat configuration, we need to add the REST
3105 .. container:: listingblock
3107 .. container:: content
3115 <param-value>org.onap.policy.apex.plugins.event.carrier.restserver</param-value>
3123 .. container:: paragraph
3125 APEX can act as REST requestor on the input as well as on
3126 the output interface. The media type is
3127 ``application/json``, so this plugin does only work with
3128 the JSON Event protocol.
3130 REST Requestor Input
3131 ====================
3133 .. container:: paragraph
3135 APEX will connect to a given URL to request an input.
3136 The URL can be configured statically or tagged
3137 as ``?example.{site}.org:8080/{trig}/events``,
3138 all tags such as ``site`` and ``trig`` in the URL
3139 need to be set in the properties object available to
3140 the tasks. In addition, the keys should exactly match
3141 with the tags defined in url. The scope of the properties
3142 object is per HTTP call. Hence, key/value pairs set
3143 in the properties object by task are only available
3144 for that specific HTTP call.
3145 The httpCodeFilter is used for filtering the status
3146 code, and it can be configured as a regular expression
3147 string. The default httpCodeFilter is "[2][0-9][0-9]"
3148 - for successful response codes.
3149 The response with HTTP status code that matches the
3150 given regular expression is forwarded to the task,
3151 otherwise it is logged as a failure.
3153 .. container:: listingblock
3155 .. container:: content
3159 "carrierTechnologyParameters": {
3160 "carrierTechnology": "RESTREQUESTOR", (1)
3161 "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters",
3163 "url": "http://localhost:54321/some/path/to/rest/resource", (2)
3164 "url": "http://localhost:54321/{site}/path/to/rest/{resValue}", (2')
3165 "httpMethod": "POST", (3)
3166 "restRequestTimeout": 2000, (4)
3167 "httpCodeFilter" : "[2][0-9][0-9]" (5)
3171 .. container:: colist arabic
3173 +-------+--------------------------------------------------+
3174 | **1** | set REST requestor as carrier technology |
3175 +-------+--------------------------------------------------+
3176 | **2** | the static URL of the HTTP server for events |
3177 +-------+--------------------------------------------------+
3178 | **2'**| the tagged URL of the HTTP server for events |
3179 +-------+--------------------------------------------------+
3180 | **3** | use HTTP PUT (remove this line to use HTTP POST) |
3181 +-------+--------------------------------------------------+
3182 | **4** | request timeout in milliseconds |
3183 +-------+--------------------------------------------------+
3184 | **5** | use HTTP CODE FILTER for filtering status code |
3185 +-------+--------------------------------------------------+
3187 .. container:: paragraph
3189 Further settings are required on the consumer to
3190 define the event that is requested, for example:
3192 .. container:: listingblock
3194 .. container:: content
3198 "eventName": "GuardResponseEvent", (1)
3199 "eventNameFilter": "GuardResponseEvent", (2)
3200 "requestorMode": true, (3)
3201 "requestorPeer": "GuardRequestorProducer", (4)
3202 "requestorTimeout": 500 (5)
3204 .. container:: colist arabic
3206 +-------+---------------------------+
3207 | **1** | the event name |
3208 +-------+---------------------------+
3209 | **2** | a filter on the event |
3210 +-------+---------------------------+
3211 | **3** | the mode of the requestor |
3212 +-------+---------------------------+
3213 | **4** | a peer for the requestor |
3214 +-------+---------------------------+
3215 | **5** | a general request timeout |
3216 +-------+---------------------------+
3218 REST Requestor Output
3219 =====================
3221 .. container:: paragraph
3223 APEX will connect to a given URL to send events, but
3224 not receive any events.
3226 .. container:: listingblock
3228 .. container:: content
3232 "carrierTechnologyParameters": {
3233 "carrierTechnology": "RESTREQUESTOR", (1)
3234 "parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters"
3237 .. container:: colist arabic
3239 +-------+------------------------------------------+
3240 | **1** | set REST requestor as carrier technology |
3241 +-------+------------------------------------------+
3243 .. container:: paragraph
3245 Further settings are required on the consumer to
3246 define the event that is requested, for example:
3248 .. container:: listingblock
3250 .. container:: content
3254 "eventNameFilter": "GuardRequestEvent", (1)
3255 "requestorMode": true, (2)
3256 "requestorPeer": "GuardRequestorConsumer", (3)
3257 "requestorTimeout": 500 (4)
3259 .. container:: colist arabic
3261 +-------+---------------------------+
3262 | **1** | a filter on the event |
3263 +-------+---------------------------+
3264 | **2** | the mode of the requestor |
3265 +-------+---------------------------+
3266 | **3** | a peer for the requestor |
3267 +-------+---------------------------+
3268 | **4** | a general request timeout |
3269 +-------+---------------------------+
3271 Event Protocols, Format and Encoding
3272 ------------------------------------
3274 .. container:: paragraph
3276 Event protocols define what event formats APEX can receive
3277 (input) and should send (output). They can be used in any
3278 combination for input and output, unless further restricted
3279 by a carrier technology plugin (for instance for JMS
3280 output). There can only be 1 event protocol per event
3283 .. container:: paragraph
3285 Supported *input* event protocols are:
3287 .. container:: ulist
3289 - JSON, the event as a JSON string
3291 - APEX, an APEX event
3293 - JMS object, the event as a JMS object,
3295 - JMS text, the event as a JMS text,
3297 - XML, the event as an XML string,
3299 - YAML, the event as YAML text
3301 .. container:: paragraph
3303 Supported *output* event protocols are:
3305 .. container:: ulist
3307 - JSON, the event as a JSON string
3309 - APEX, an APEX event
3311 - JMS object, the event as a JMS object,
3313 - JMS text, the event as a JMS text,
3315 - XML, the event as an XML string,
3317 - YAML, the event as YAML text
3319 .. container:: paragraph
3321 New event protocols can be added as plugins to APEX or
3322 developed outside APEX and added to an APEX deployment.
3327 .. container:: paragraph
3329 The event protocol for JSON encoding does not require a
3330 specific plugin, it is supported by default. Furthermore,
3331 there is no difference in the configuration for the input
3332 and output interface.
3334 .. container:: paragraph
3336 For an input, APEX requires a well-formed JSON string.
3337 Well-formed here means according to the definitions of a
3338 policy. Any JSON string that is not defined as a trigger
3339 event (consume) will not be consumed (errors will be
3340 thrown). For output JSON events, APEX will always produce
3341 valid JSON strings according to the definition in the
3344 .. container:: paragraph
3346 The following JSON shows the configuration.
3348 .. container:: listingblock
3350 .. container:: content
3354 "eventProtocolParameters":{
3355 "eventProtocol" : "JSON"
3358 .. container:: paragraph
3360 For JSON events, there are a few more optional
3361 parameters, which allow to define a mapping for standard
3362 event fields. An APEX event must have the fields
3363 ``name``, ``version``, ``source``, and ``target``
3364 defined. Sometimes it is not possible to configure a
3365 trigger or actioning system to use those fields. However,
3366 they might be in an event generated outside APEX (or used
3367 outside APEX) just with different names. To configure
3368 APEX to map between the different event names, simply add
3369 the following parameters to a JSON event:
3371 .. container:: listingblock
3373 .. container:: content
3377 "eventProtocolParameters":{
3378 "eventProtocol" : "JSON",
3379 "nameAlias" : "policyName", (1)
3380 "versionAlias" : "policyVersion", (2)
3381 "sourceAlias" : "from", (3)
3382 "targetAlias" : "to", (4)
3383 "nameSpaceAlias": "my.name.space" (5)
3386 .. container:: colist arabic
3388 +-----------------------------------+-----------------------------------+
3389 | **1** | mapping for the ``name`` field, |
3390 | | here from a field called |
3391 | | ``policyName`` |
3392 +-----------------------------------+-----------------------------------+
3393 | **2** | mapping for the ``version`` |
3394 | | field, here from a field called |
3395 | | ``policyVersion`` |
3396 +-----------------------------------+-----------------------------------+
3397 | **3** | mapping for the ``source`` field, |
3398 | | here from a field called ``from`` |
3399 | | (only for an input event) |
3400 +-----------------------------------+-----------------------------------+
3401 | **4** | mapping for the ``target`` field, |
3402 | | here from a field called ``to`` |
3403 | | (only for an output event) |
3404 +-----------------------------------+-----------------------------------+
3405 | **5** | mapping for the ``nameSpace`` |
3406 | | field, here from a field called |
3407 | | ``my.name.space`` |
3408 +-----------------------------------+-----------------------------------+
3412 .. container:: paragraph
3414 The event protocol for APEX events does not require a
3415 specific plugin, it is supported by default. Furthermore,
3416 there is no difference in the configuration for the input
3417 and output interface.
3419 .. container:: paragraph
3421 For input and output APEX uses APEX events.
3423 .. container:: paragraph
3425 The following JSON shows the configuration.
3427 .. container:: listingblock
3429 .. container:: content
3433 "eventProtocolParameters":{
3434 "eventProtocol" : "APEX"
3440 .. container:: paragraph
3442 The event protocol for JMS is provided by the APEX JMS
3443 plugin. The plugin supports encoding as JSON text or as
3444 object. There is no difference in the configuration for
3445 the input and output interface.
3449 .. container:: paragraph
3451 If used as input, APEX will take a JMS message and
3452 extract a JSON string, then proceed as if a JSON event
3453 was received. If used as output, APEX will take the
3454 event produced by a policy, create a JSON string, and
3455 then wrap it into a JMS message.
3457 .. container:: paragraph
3459 The configuration for JMS text is as follows:
3461 .. container:: listingblock
3463 .. container:: content
3467 "eventProtocolParameters":{
3468 "eventProtocol" : "JMSTEXT",
3469 "parameterClassName" :
3470 "org.onap.policy.apex.plugins.event.protocol.jms.JMSTextEventProtocolParameters"
3475 .. container:: paragraph
3477 If used as input, APEX will will take a JMS message,
3478 extract a Java Bean from the ``ObjectMessage``
3479 message, construct an APEX event and put the bean on
3480 the APEX event as a parameter. If used as output, APEX
3481 will take the event produced by a policy, create a
3482 Java Bean and send it as a JMS message.
3484 .. container:: paragraph
3486 The configuration for JMS object is as follows:
3488 .. container:: listingblock
3490 .. container:: content
3494 "eventProtocolParameters":{
3495 "eventProtocol" : "JMSOBJECT",
3496 "parameterClassName" :
3497 "org.onap.policy.apex.plugins.event.protocol.jms.JMSObjectEventProtocolParameters"
3503 .. container:: paragraph
3505 The event protocol for YAML is provided by the APEX YAML
3506 plugin. There is no difference in the configuration for
3507 the input and output interface.
3509 .. container:: paragraph
3511 If used as input, APEX will consume events as YAML and
3512 map them to policy trigger events. Not well-formed YAML
3513 and not understood trigger events will be rejected. If
3514 used as output, APEX produce YAML encoded events from the
3515 event a policy produces. Those events will always be
3516 well-formed according to the definition in the policy
3519 .. container:: paragraph
3521 The following code shows the configuration.
3523 .. container:: listingblock
3525 .. container:: content
3529 "eventProtocolParameters":{
3530 "eventProtocol" : "XML",
3531 "parameterClassName" :
3532 "org.onap.policy.apex.plugins.event.protocol.yaml.YamlEventProtocolParameters"
3537 .. container:: paragraph
3539 The event protocol for XML is provided by the APEX XML
3540 plugin. There is no difference in the configuration for
3541 the input and output interface.
3543 .. container:: paragraph
3545 If used as input, APEX will consume events as XML and map
3546 them to policy trigger events. Not well-formed XML and
3547 not understood trigger events will be rejected. If used
3548 as output, APEX produce XML encoded events from the event
3549 a policy produces. Those events will always be
3550 well-formed according to the definition in the policy
3553 .. container:: paragraph
3555 The following code shows the configuration.
3557 .. container:: listingblock
3559 .. container:: content
3563 "eventProtocolParameters":{
3564 "eventProtocol" : "XML",
3565 "parameterClassName" :
3566 "org.onap.policy.apex.plugins.event.protocol.xml.XMLEventProtocolParameters"
3569 A configuration example
3570 -----------------------
3572 .. container:: paragraph
3574 The following example loads all available plug-ins.
3576 .. container:: paragraph
3578 Events are consumed from a Websocket, APEX as client.
3579 Consumed event format is JSON.
3581 .. container:: paragraph
3583 Events are produced to Kafka. Produced event format is XML.
3585 .. container:: listingblock
3587 .. container:: content
3592 "engineServiceParameters" : {
3593 "name" : "MyApexEngine",
3594 "version" : "0.0.1",
3596 "instanceCount" : 4,
3597 "deploymentPort" : 12345,
3598 "policyModelFileName" : "examples/models/some-model.json",
3599 "engineParameters" : {
3600 "executorParameters" : {
3602 "parameterClassName" :
3603 "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"
3606 "parameterClassName" :
3607 "org.onap.policy.apex.plugins.executor.jython.JythonExecutorParameters"
3610 "parameterClassName" :
3611 "org.onap.policy.apex.plugins.executor.jruby.JrubyExecutorParameters"
3614 "parameterClassName" :
3615 "org.onap.policy.apex.plugins.executor.java.JavaExecutorParameters"
3618 "parameterClassName" :
3619 "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
3622 "contextParameters" : {
3623 "parameterClassName" :
3624 "org.onap.policy.apex.context.parameters.ContextParameters",
3625 "schemaParameters" : {
3627 "parameterClassName" :
3628 "org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters"
3634 "producerCarrierTechnologyParameters" : {
3635 "carrierTechnology" : "KAFKA",
3636 "parameterClassName" :
3637 "org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters",
3639 "bootstrapServers" : "localhost:49092",
3642 "batchSize" : 16384,
3644 "bufferMemory" : 33554432,
3645 "producerTopic" : "apex-out",
3646 "keySerializer" : "org.apache.kafka.common.serialization.StringSerializer",
3647 "valueSerializer" : "org.apache.kafka.common.serialization.StringSerializer"
3650 "producerEventProtocolParameters" : {
3651 "eventProtocol" : "XML",
3652 "parameterClassName" :
3653 "org.onap.policy.apex.plugins.event.protocol.xml.XMLEventProtocolParameters"
3655 "consumerCarrierTechnologyParameters" : {
3656 "carrierTechnology" : "WEBSOCKET",
3657 "parameterClassName" :
3658 "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",
3660 "host" : "localhost",
3664 "consumerEventProtocolParameters" : {
3665 "eventProtocol" : "JSON"
3669 Engine and Applications of the APEX System
3670 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3672 Introduction to APEX Engine and Applications
3673 --------------------------------------------
3675 .. container:: paragraph
3677 The core of APEX is the APEX Engine, also known as the APEX
3678 Policy Engine or the APEX PDP (since it is in fact a Policy
3679 Decision Point). Beside this engine, an APEX system comes
3680 with a few applications intended to help with policy
3681 authoring, deployment, and execution.
3683 .. container:: paragraph
3685 The engine itself and most applications are started from the
3686 command line with command line arguments. This is called a
3687 Command Line Interface (CLI). Some applications require an
3688 installation on a webserver, as for instance the REST
3689 Editor. Those applications can be accessed via a web
3692 .. container:: paragraph
3694 You can also use the available APEX APIs and applications to
3695 develop other applications as required. This includes policy
3696 languages (and associated parsers and compilers /
3697 interpreters), GUIs to access APEX or to define policies,
3698 clients to connect to APEX, etc.
3700 .. container:: paragraph
3702 For this documentation, we assume an installation of APEX as
3703 a full system based on a current ONAP release.
3705 CLI on Unix, Windows, and Cygwin
3706 --------------------------------
3708 .. container:: paragraph
3710 A note on APEX CLI applications: all applications and the
3711 engine itself have been deployed and tested on different
3712 operating systems: Red Hat, Ubuntu, Debian, Mac OSX,
3713 Windows, Cygwin. Each operating system comes with its own
3714 way of configuring and executing Java. The main items here
3717 .. container:: ulist
3719 - For UNIX systems (RHL, Ubuntu, Debian, Mac OSX), the
3720 provided bash scripts work as expected with absolute
3722 ``/opt/app/policy/apex-pdp/apex-pdp-2.0.0-SNAPSHOT/examples``),
3723 indirect and linked paths (e.g. ``../apex/apex``), and
3724 path substitutions using environment settings (e.g.
3725 ``$APEX_HOME/bin/``)
3727 - For Windows systems, the provided batch files (``.bat``)
3728 work as expected with with absolute paths (e.g.
3729 ``C:\apex\apex-2.0.0-SNAPSHOT\examples``), and path
3730 substitutions using environment settings (e.g.
3731 ``%APEX_HOME%\bin\``)
3733 - For Cygwin system we assume a standard Cygwin
3734 installation with standard tools (mainly bash) using a
3735 Windows Java installation. This means that the bash
3736 scripts can be used as in UNIX, however any argument
3737 pointing to files and directories need to use either a
3739 ``C:\apex\apex-2.0.0-SNAPSHOT\examples\config...``) or
3740 the command ``cygpath`` with a mixed option. The reason
3741 for that is: Cygwin executes Java using UNIX paths but
3742 then runs Java as a DOS/WINDOWS process, which requires
3743 DOS paths for file access.
3748 .. container:: paragraph
3750 The APEX engine can be started in different ways, depending
3751 your requirements. All scripts are located in the APEX *bin*
3754 .. container:: paragraph
3756 On UNIX and Cygwin systems use:
3758 .. container:: ulist
3760 - ``apexEngine.sh`` - this script will
3762 .. container:: ulist
3764 - Test if ``$APEX_USER`` is set and if the user
3765 exists, terminate with an error otherwise
3767 - Test if ``$APEX_HOME`` is set. If not set, it will
3768 use the default setting as
3769 ``/opt/app/policy/apex-pdp/apex-pdp``. Then the set
3770 directory is tested to exist, the script will
3773 - When all tests are passed successfully, the script
3774 will call ``apexApps.sh`` with arguments to start
3777 - ``apexApps.sh engine`` - this is the general APEX
3778 application launcher, which will
3780 .. container:: ulist
3782 - Start the engine with the argument ``engine``
3784 - Test if ``$APEX_HOME`` is set and points to an
3785 existing directory. If not set or directory does
3786 not exist, script terminates.
3788 - Not test for any settings of ``$APEX_USER``.
3790 .. container:: paragraph
3792 On Windows systems use ``apexEngine.bat`` and
3793 ``apexApps.bat engine`` respectively. Note: none of the
3794 windows batch files will test for ``%APEX_USER%``.
3796 .. container:: paragraph
3798 Summary of alternatives to start the APEX Engine:
3800 +--------------------------------------------------------+----------------------------------------------------------+
3801 | Unix, Cygwin | Windows |
3802 +========================================================+==========================================================+
3803 | .. container:: | .. container:: |
3805 | .. container:: listingblock | .. container:: listingblock |
3807 | .. container:: content | .. container:: content |
3809 | .. code:: | .. code:: |
3811 | # $APEX_HOME/bin/apexEngine.sh [args] | > %APEX_HOME%\bin\apexEngine.bat [args] |
3812 | # $APEX_HOME/bin/apexApps.sh engine [args] | > %APEX_HOME%\bin\apexApps.bat engine [args] |
3813 +--------------------------------------------------------+----------------------------------------------------------+
3815 .. container:: paragraph
3817 The APEX engine comes with a few CLI arguments for setting
3818 configuration and policy model. The configuration file is
3819 always required. The policy model file is only required if
3820 no model file is specified in the configuration, or if the
3821 specified model file should be over written. The option
3822 ``-h`` prints a help screen.
3824 .. container:: listingblock
3826 .. container:: content
3830 usage: org.onap.policy.apex.service.engine.main.ApexMain [options...]
3832 -c,--config-file <CONFIG_FILE> the full path to the configuration file to use, the configuration file must be a Json file
3833 containing the Apex configuration parameters
3834 -h,--help outputs the usage of this command
3835 -m,--model-file <MODEL_FILE> the full path to the model file to use, if set it overrides the model file set in the
3837 -v,--version outputs the version of Apex
3842 .. container:: paragraph
3844 The CLI Editor allows to define policies from the command
3845 line. The application uses a simple language and supports
3846 all elements of an APEX policy. It can be used in to
3849 .. container:: ulist
3851 - non-interactive, specifying a file with the commands to
3854 - interactive, using the editors CLI to create a policy
3856 .. container:: paragraph
3858 When a policy is fully specified, the editor will generate
3859 the APEX core policy specification in JSON. This core
3860 specification is called the policy model in the APEX engine
3861 and can be used directly with the APEX engine.
3863 .. container:: paragraph
3865 On UNIX and Cygwin systems use:
3867 .. container:: ulist
3869 - ``apexCLIEditor.sh`` - simply starts the CLI editor,
3870 arguments to the script determine the mode of the editor
3872 - ``apexApps.sh cli-editor`` - simply starts the CLI
3873 editor, arguments to the script determine the mode of the
3876 .. container:: paragraph
3878 On Windows systems use:
3880 .. container:: ulist
3882 - ``apexCLIEditor.bat`` - simply starts the CLI editor,
3883 arguments to the script determine the mode of the editor
3885 - ``apexApps.bat cli-editor`` - simply starts the CLI
3886 editor, arguments to the script determine the mode of the
3889 .. container:: paragraph
3891 Summary of alternatives to start the APEX CLI Editor:
3893 +------------------------------------------------------------+--------------------------------------------------------------+
3894 | Unix, Cygwin | Windows |
3895 +============================================================+==============================================================+
3896 | .. container:: | .. container:: |
3898 | .. container:: listingblock | .. container:: listingblock |
3900 | .. container:: content | .. container:: content |
3902 | .. code:: | .. code:: |
3904 | # $APEX_HOME/bin/apexCLIEditor.sh.sh [args] | > %APEX_HOME%\bin\apexCLIEditor.bat [args] |
3905 | # $APEX_HOME/bin/apexApps.sh cli-editor [args] | > %APEX_HOME%\bin\apexApps.bat cli-editor [args] |
3906 +------------------------------------------------------------+--------------------------------------------------------------+
3908 .. container:: paragraph
3910 The option ``-h`` provides a help screen with all command
3913 .. container:: listingblock
3915 .. container:: content
3919 usage: org.onap.policy.apex.auth.clieditor.ApexCLIEditorMain [options...]
3921 -a,--model-props-file <MODEL_PROPS_FILE> name of the apex model properties file to use
3922 -c,--command-file <COMMAND_FILE> name of a file containing editor commands to run into the editor
3923 -h,--help outputs the usage of this command
3924 -i,--input-model-file <INPUT_MODEL_FILE> name of a file that contains an input model for the editor
3925 -if,--ignore-failures <IGNORE_FAILURES_FLAG> true or false, ignore failures of commands in command files and continue
3926 executing the command file
3927 -l,--log-file <LOG_FILE> name of a file that will contain command logs from the editor, will log
3928 to standard output if not specified or suppressed with "-nl" flag
3929 -m,--metadata-file <CMD_METADATA_FILE> name of the command metadata file to use
3930 -nl,--no-log if specified, no logging or output of commands to standard output or log
3932 -nm,--no-model-output if specified, no output of a model to standard output or model output
3933 file is carried out, the user can use the "save" command in a script to
3935 -o,--output-model-file <OUTPUT_MODEL_FILE> name of a file that will contain the output model for the editor, will
3936 output model to standard output if not specified or suppressed with
3938 -wd,--working-directory <WORKING_DIRECTORY> the working directory that is the root for the CLI editor and is the
3939 root from which to look for included macro files
3941 The APEX CLI Tosca Editor
3942 -------------------------
3944 .. container:: paragraph
3946 As per the new Policy LifeCycle API, the policies are expected to be defined as ToscaServiceTemplate. The CLI Tosca Editor is an extended version of the APEX CLI Editor which can generate the policies in ToscaServiceTemplate way.
3948 .. container:: paragraph
3950 The APEX config file(.json), command file(.apex) and the tosca template skeleton(.json) file paths need to be passed as input arguments to the CLI Tosca Editor. Policy in ToscaServiceTemplate format is generated as the output. This can be used as the input to Policy API for creating policies.
3952 .. container:: paragraph
3954 On UNIX and Cygwin systems use:
3956 .. container:: ulist
3958 - ``apexCLIToscaEditor.sh`` - starts the CLI Tosca editor,
3959 all the arguments supported by the basic CLI Editor are supported in addition to the mandatory arguments needed to generate ToscaServiceTemplate.
3961 - ``apexApps.sh cli-tosca-editor`` - starts the CLI Tosca editor,
3962 all the arguments supported by the basic CLI Editor are supported in addition to the mandatory arguments needed to generate ToscaServiceTemplate.
3964 .. container:: paragraph
3966 On Windows systems use:
3968 .. container:: ulist
3970 - ``apexCLIToscaEditor.bat`` - starts the CLI Tosca editor,
3971 all the arguments supported by the basic CLI Editor are supported in addition to the mandatory arguments needed to generate ToscaServiceTemplate.
3973 - ``apexApps.bat cli-tosca-editor`` - starts the CLI Tosca
3974 editor, all the arguments supported by the basic CLI Editor are supported in addition to the mandatory arguments needed to generate ToscaServiceTemplate.
3976 .. container:: paragraph
3978 Summary of alternatives to start the APEX CLI Tosca Editor:
3980 +-----------------------------------------------------------------+--------------------------------------------------------------------+
3981 | Unix, Cygwin | Windows |
3982 +=================================================================+====================================================================+
3983 | .. container:: | .. container:: |
3985 | .. container:: listingblock | .. container:: listingblock |
3987 | .. container:: content | .. container:: content |
3989 | .. code:: | .. code:: |
3991 | # $APEX_HOME/bin/apexCLIToscaEditor.sh.sh [args] | > %APEX_HOME%\bin\apexCLIToscaEditor.bat [args] |
3992 | # $APEX_HOME/bin/apexApps.sh cli-tosca-editor [args]| > %APEX_HOME%\bin\apexApps.bat cli-tosca-editor [args] |
3993 +-----------------------------------------------------------------+--------------------------------------------------------------------+
3995 .. container:: paragraph
3997 The option ``-h`` provides a help screen with all command
4000 .. container:: listingblock
4002 .. container:: content
4006 usage: org.onap.policy.apex.auth.clieditor.tosca.ApexCliToscaEditorMain [options...]
4008 -a,--model-props-file <MODEL_PROPS_FILE> name of the apex model properties file to use
4009 -ac,--apex-config-file <APEX_CONFIG_FILE> name of the file containing apex configuration details
4010 -c,--command-file <COMMAND_FILE> name of a file containing editor commands to run into the editor
4011 -h,--help outputs the usage of this command
4012 -i,--input-model-file <INPUT_MODEL_FILE> name of a file that contains an input model for the editor
4013 -if,--ignore-failures <IGNORE_FAILURES_FLAG> true or false, ignore failures of commands in command files and
4014 continue executing the command file
4015 -l,--log-file <LOG_FILE> name of a file that will contain command logs from the editor, will
4016 log to standard output if not specified or suppressed with "-nl" flag
4017 -m,--metadata-file <CMD_METADATA_FILE> name of the command metadata file to use
4018 -nl,--no-log if specified, no logging or output of commands to standard output or
4019 log file is carried out
4020 -ot,--output-tosca-file <OUTPUT_TOSCA_FILE> name of a file that will contain the output ToscaServiceTemplate
4021 -t,--tosca-template-file <TOSCA_TEMPLATE_FILE> name of the input file containing tosca template which needs to be
4023 -wd,--working-directory <WORKING_DIRECTORY> the working directory that is the root for the CLI editor and is the
4024 root from which to look for included macro files
4026 .. container:: paragraph
4028 An example command to run the APEX CLI Tosca editor on windows machine is given below.
4030 .. container:: listingblock
4032 .. container:: content
4036 %APEX_HOME%/\bin/\apexCLIToscaEditor.bat -c %APEX_HOME%\examples\PolicyModel.apex -ot %APEX_HOME%\examples\test.json -l %APEX_HOME%\examples\test.log -ac %APEX_HOME%\examples\RESTServerStandaloneJsonEvent.json -t %APEX_HOME%\examples\ToscaTemplate.json
4038 The APEX REST Editor
4039 --------------------
4041 .. container:: paragraph
4043 The standard way to use the APEX REST Editor is via an
4044 installation of the *war* file on a webserver. However, the
4045 REST editor can also be started via command line. This will
4046 start a Grizzly webserver with the *war* deployed. Access to
4047 the REST Editor is then via the provided URL
4049 .. container:: paragraph
4051 On UNIX and Cygwin systems use:
4053 .. container:: ulist
4055 - ``apexRESTEditor.sh`` - simply starts the webserver with
4058 - ``apexApps.sh rest-editor`` - simply starts the webserver
4059 with the REST editor
4061 .. container:: paragraph
4063 On Windows systems use:
4065 .. container:: ulist
4067 - ``apexRESTEditor.bat`` - simply starts the webserver with
4070 - ``apexApps.bat rest-editor`` - simply starts the
4071 webserver with the REST editor
4073 .. container:: paragraph
4075 Summary of alternatives to start the APEX REST Editor:
4077 +-------------------------------------------------------------+---------------------------------------------------------------+
4078 | Unix, Cygwin | Windows |
4079 +=============================================================+===============================================================+
4080 | .. container:: | .. container:: |
4082 | .. container:: listingblock | .. container:: listingblock |
4084 | .. container:: content | .. container:: content |
4086 | .. code:: | .. code:: |
4088 | # $APEX_HOME/bin/apexRESTEditor.sh.sh [args] | > %APEX_HOME%\bin\apexRESTEditor.bat [args] |
4089 | # $APEX_HOME/bin/apexApps.sh rest-editor [args] | > %APEX_HOME%\bin\apexApps.bat rest-editor [args] |
4090 +-------------------------------------------------------------+---------------------------------------------------------------+
4092 .. container:: paragraph
4094 The option ``-h`` provides a help screen with all command
4097 .. container:: listingblock
4099 .. container:: content
4103 usage: org.onap.policy.apex.client.editor.rest.ApexEditorMain [options...]
4104 -h,--help outputs the usage of this command
4105 -l,--listen <ADDRESS> the IP address to listen on. Default value is localhost to restrict access to the
4107 -p,--port <PORT> port to use for the Apex RESTful editor REST calls.
4108 -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating. Default
4109 value is -1 to run indefinitely.
4111 .. container:: paragraph
4113 If the REST Editor is started without any arguments the
4114 final messages will look similar to this:
4116 .. container:: listingblock
4118 .. container:: content
4122 Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
4123 Sep 05, 2018 11:24:30 PM org.glassfish.grizzly.http.server.NetworkListener start
4124 INFO: Started listener bound to [localhost:18989]
4125 Sep 05, 2018 11:24:30 PM org.glassfish.grizzly.http.server.HttpServer start
4126 INFO: [HttpServer] Started.
4127 Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
4129 .. container:: paragraph
4131 The last line states the URL on which the REST Editor can be
4132 accessed. The example above stated
4133 ``http://0.0.0.0:18989/apex/``. In a web browser use the URL
4134 ``http://localhost:18989`` and the REST Editor will start.
4136 The APEX Monitoring Client
4137 --------------------------
4139 .. container:: paragraph
4141 The standard way to use the APEX Monitoring Client is via an
4142 installation of the *war* file on a webserver. However, the
4143 Monitoring Client can also be started via command line. This
4144 will start a Grizzly webserver with the *war* deployed.
4145 Access to the Monitoring Client is then via the provided URL
4147 .. container:: paragraph
4149 On UNIX and Cygwin systems use:
4151 .. container:: ulist
4153 - ``apexApps.sh eng-monitoring`` - simply starts the
4154 webserver with the Monitoring Client
4156 .. container:: paragraph
4158 On Windows systems use:
4160 .. container:: ulist
4162 - ``apexApps.bat eng-monitoring`` - simply starts the
4163 webserver with the Monitoring Client
4165 .. container:: paragraph
4167 The option ``-h`` provides a help screen with all command
4170 .. container:: listingblock
4172 .. container:: content
4176 usage: org.onap.policy.apex.client.monitoring.rest.ApexMonitoringRestMain [options...]
4177 -h,--help outputs the usage of this command
4178 -p,--port <PORT> port to use for the Apex Services REST calls
4179 -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating
4181 .. container:: paragraph
4183 If the Monitoring Client is started without any arguments
4184 the final messages will look similar to this:
4186 .. container:: listingblock
4188 .. container:: content
4192 Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
4193 Sep 05, 2018 11:26:20 PM org.glassfish.grizzly.http.server.NetworkListener start
4194 INFO: Started listener bound to [localhost:18989]
4195 Sep 05, 2018 11:26:20 PM org.glassfish.grizzly.http.server.HttpServer start
4196 INFO: [HttpServer] Started.
4197 Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
4199 .. container:: paragraph
4201 The last line states the URL on which the Monitoring Client
4202 can be accessed. The example above stated
4203 ``http://localhost:18989/apexservices``. In a web browser
4204 use the URL ``http://localhost:18989``.
4206 The APEX Deployment Client
4207 --------------------------
4209 .. container:: paragraph
4211 The standard way to use the APEX Deployment Client is via an
4212 installation of the *war* file on a webserver. However, the
4213 Deployment Client can also be started via command line. This
4214 will start a Grizzly webserver with the *war* deployed.
4215 Access to the Deployment Client is then via the provided URL
4217 .. container:: paragraph
4219 On UNIX and Cygwin systems use:
4221 .. container:: ulist
4223 - ``apexApps.sh eng-deployment`` - simply starts the
4224 webserver with the Deployment Client
4226 .. container:: paragraph
4228 On Windows systems use:
4230 .. container:: ulist
4232 - ``apexApps.bat eng-deployment`` - simply starts the
4233 webserver with the Deployment Client
4235 .. container:: paragraph
4237 The option ``-h`` provides a help screen with all command
4240 .. container:: listingblock
4242 .. container:: content
4246 usage: org.onap.policy.apex.client.deployment.rest.ApexDeploymentRestMain [options...]
4247 -h,--help outputs the usage of this command
4248 -p,--port <PORT> port to use for the Apex Services REST calls
4249 -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating
4251 .. container:: paragraph
4253 If the Deployment Client is started without any arguments
4254 the final messages will look similar to this:
4256 .. container:: listingblock
4258 .. container:: content
4262 Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
4263 Sep 05, 2018 11:27:09 PM org.glassfish.grizzly.http.server.NetworkListener start
4264 INFO: Started listener bound to [localhost:18989]
4265 Sep 05, 2018 11:27:09 PM org.glassfish.grizzly.http.server.HttpServer start
4266 INFO: [HttpServer] Started.
4267 Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
4269 .. container:: paragraph
4271 The last line states the URL on which the Deployment Client
4272 can be accessed. The example above stated
4273 ``http://localhost:18989/apexservices``. In a web browser
4274 use the URL ``http://localhost:18989``.
4276 The APEX Full Client
4277 --------------------
4279 .. container:: paragraph
4281 The APEX Full Client combines the REST Editor, the
4282 Monitoring Client, and the Deployment Client into a single
4283 application. The standard way to use the APEX Full Client is
4284 via an installation of the *war* file on a webserver.
4285 However, the Full Client can also be started via command
4286 line. This will start a Grizzly webserver with the *war*
4287 deployed. Access to the Full Client is then via the provided
4290 .. container:: paragraph
4292 On UNIX and Cygwin systems use:
4294 .. container:: ulist
4296 - ``apexApps.sh full-client`` - simply starts the webserver
4297 with the Full Client
4299 .. container:: paragraph
4301 On Windows systems use:
4303 .. container:: ulist
4305 - ``apexApps.bat full-client`` - simply starts the
4306 webserver with the Full Client
4308 .. container:: paragraph
4310 The option ``-h`` provides a help screen with all command
4313 .. container:: listingblock
4315 .. container:: content
4319 usage: org.onap.policy.apex.client.full.rest.ApexServicesRestMain [options...]
4320 -h,--help outputs the usage of this command
4321 -p,--port <PORT> port to use for the Apex Services REST calls
4322 -t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating
4324 .. container:: paragraph
4326 If the Full Client is started without any arguments the
4327 final messages will look similar to this:
4329 .. container:: listingblock
4331 .. container:: content
4335 Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .
4336 Sep 05, 2018 11:28:28 PM org.glassfish.grizzly.http.server.NetworkListener start
4337 INFO: Started listener bound to [localhost:18989]
4338 Sep 05, 2018 11:28:28 PM org.glassfish.grizzly.http.server.HttpServer start
4339 INFO: [HttpServer] Started.
4340 Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/
4342 .. container:: paragraph
4344 The last line states the URL on which the Monitoring Client
4345 can be accessed. The example above stated
4346 ``http://localhost:18989/apexservices``. In a web browser
4347 use the URL ``http://localhost:18989``.
4349 The APEX Application Launcher
4350 ------------------------------
4352 .. container:: paragraph
4354 The standard applications (Engine, CLI Editor, REST Editor)
4355 come with dedicated start scripts. For all other APEX
4356 applications, we provide an application launcher.
4358 .. container:: paragraph
4360 On UNIX and Cygwin systems use:
4362 .. container:: ulist
4364 - apexApps.sh\` - simply starts the application launcher
4366 .. container:: paragraph
4368 On Windows systems use:
4370 .. container:: ulist
4372 - ``apexApps.bat`` - simply starts the application launcher
4374 .. container:: paragraph
4376 Summary of alternatives to start the APEX application
4379 +-------------------------------------------------+---------------------------------------------------+
4380 | Unix, Cygwin | Windows |
4381 +=================================================+===================================================+
4382 | .. container:: | .. container:: |
4384 | .. container:: listingblock | .. container:: listingblock |
4386 | .. container:: content | .. container:: content |
4388 | .. code:: | .. code:: |
4390 | # $APEX_HOME/bin/apexApps.sh [args] | > %APEX_HOME%\bin\apexApps.bat [args] |
4391 +-------------------------------------------------+---------------------------------------------------+
4393 .. container:: paragraph
4395 The option ``-h`` provides a help screen with all launcher
4396 command line arguments.
4398 .. container:: listingblock
4400 .. container:: content
4404 apexApps.sh - runs APEX applications
4406 Usage: apexApps.sh [options] | [<application> [<application options>]]
4409 -d <app> - describes an application
4410 -l - lists all applications supported by this script
4411 -h - this help screen
4413 .. container:: paragraph
4415 Using ``-l`` lists all known application the launcher can
4418 .. container:: listingblock
4420 .. container:: content
4424 apexApps.sh: supported applications:
4425 --> ws-echo engine eng-monitoring full-client eng-deployment tpl-event-json model-2-cli rest-editor cli-editor ws-console
4427 .. container:: paragraph
4429 Using the ``-d <name>`` option describes the named
4430 application, for instance for the ``ws-console``:
4432 .. container:: listingblock
4434 .. container:: content
4438 apexApps.sh: application 'ws-console'
4439 --> a simple console sending events to APEX, connect to APEX consumer port
4441 .. container:: paragraph
4443 Launching an application is done by calling the script with
4444 only the application name and any CLI arguments for the
4445 application. For instance, starting the ``ws-echo``
4446 application with port ``8888``:
4448 .. container:: listingblock
4450 .. container:: content
4454 apexApps.sh ws-echo -p 8888
4456 Application: Create Event Templates
4457 -----------------------------------
4459 .. container:: paragraph
4461 **Status: Experimental**
4463 .. container:: paragraph
4465 This application takes a policy model (JSON or XML encoded)
4466 and generates templates for events in JSON format. This can
4467 help when a policy defines rather complex trigger or action
4468 events or complex events between states. The application can
4469 produce events for the types: stimuli (policy trigger
4470 events), internal (events between policy states), and
4471 response (action events).
4473 +----------------------------------------------------------------+------------------------------------------------------------------+
4474 | Unix, Cygwin | Windows |
4475 +================================================================+==================================================================+
4476 | .. container:: | .. container:: |
4478 | .. container:: listingblock | .. container:: listingblock |
4480 | .. container:: content | .. container:: content |
4482 | .. code:: | .. code:: |
4484 | # $APEX_HOME/bin/apexApps.sh tpl-event-json [args] | > %APEX_HOME%\bin\apexApps.bat tpl-event-json [args] |
4485 +----------------------------------------------------------------+------------------------------------------------------------------+
4487 .. container:: paragraph
4489 The option ``-h`` provides a help screen.
4491 .. container:: listingblock
4493 .. container:: content
4497 gen-model2event v{release-version} - generates JSON templates for events generated from a policy model
4498 usage: gen-model2event
4499 -h,--help prints this help and usage screen
4500 -m,--model <MODEL-FILE> set the input policy model file
4501 -t,--type <TYPE> set the event type for generation, one of:
4502 stimuli (trigger events), response (action
4503 events), internal (events between states)
4504 -v,--version prints the application version
4506 .. container:: paragraph
4508 The created templates are not valid events, instead they use
4509 some markup for values one will need to change to actual
4510 values. For instance, running the tool with the *Sample
4511 Domain* policy model as:
4513 .. container:: listingblock
4515 .. container:: content
4519 apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli
4521 .. container:: paragraph
4523 will produce the following status messages:
4525 .. container:: listingblock
4527 .. container:: content
4531 gen-model2event: starting Event generator
4532 --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json
4535 .. container:: paragraph
4537 and then run the generator application producing two event
4538 templates. The first template is called ``Event0000``.
4540 .. container:: listingblock
4542 .. container:: content
4547 "name" : "Event0000",
4548 "nameSpace" : "org.onap.policy.apex.sample.events",
4549 "version" : "0.0.1",
4550 "source" : "Outside",
4552 "TestTemperature" : ###double: 0.0###,
4553 "TestTimestamp" : ###long: 0###,
4554 "TestMatchCase" : ###integer: 0###,
4555 "TestSlogan" : "###string###"
4558 .. container:: paragraph
4560 The values for the keys are marked with ``#`` and the
4561 expected type of the value. To create an actual stimuli
4562 event, all these markers need to be change to actual values,
4565 .. container:: listingblock
4567 .. container:: content
4572 "name" : "Event0000",
4573 "nameSpace" : "org.onap.policy.apex.sample.events",
4574 "version" : "0.0.1",
4575 "source" : "Outside",
4577 "TestTemperature" : 25,
4578 "TestTimestamp" : 123456789123456789,
4579 "TestMatchCase" : 1,
4580 "TestSlogan" : "Testing the Match Case with Temperature 25"
4583 Application: Convert a Policy Model to CLI Editor Commands
4584 ----------------------------------------------------------
4586 .. container:: paragraph
4588 **Status: Experimental**
4590 .. container:: paragraph
4592 This application takes a policy model (JSON or XML encoded)
4593 and generates commands for the APEX CLI Editor. This
4594 effectively reverses a policy specification realized with
4597 +-------------------------------------------------------------+---------------------------------------------------------------+
4598 | Unix, Cygwin | Windows |
4599 +=============================================================+===============================================================+
4600 | .. container:: | .. container:: |
4602 | .. container:: listingblock | .. container:: listingblock |
4604 | .. container:: content | .. container:: content |
4606 | .. code:: | .. code:: |
4608 | # $APEX_HOME/bin/apexApps.sh model-2-cli [args] | > %APEX_HOME%\bin\apexApps.bat model-2-cli [args] |
4609 +-------------------------------------------------------------+---------------------------------------------------------------+
4611 .. container:: paragraph
4613 The option ``-h`` provides a help screen.
4615 .. container:: listingblock
4617 .. container:: content
4621 usage: gen-model2cli
4622 -h,--help prints this help and usage screen
4623 -m,--model <MODEL-FILE> set the input policy model file
4624 -sv,--skip-validation switch of validation of the input file
4625 -v,--version prints the application version
4627 .. container:: paragraph
4629 For instance, running the tool with the *Sample Domain*
4632 .. container:: listingblock
4634 .. container:: content
4638 apexApps.sh model-2-cli -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json
4640 .. container:: paragraph
4642 will produce the following status messages:
4644 .. container:: listingblock
4646 .. container:: content
4650 gen-model2cli: starting CLI generator
4651 --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json
4653 .. container:: paragraph
4655 and then run the generator application producing all CLI
4656 Editor commands and printing them to standard out.
4658 Application: Websocket Clients (Echo and Console)
4659 -------------------------------------------------
4661 .. container:: paragraph
4663 **Status: Production**
4665 .. container:: paragraph
4667 The application launcher also provides a Websocket echo
4668 client and a Websocket console client. The echo client
4669 connects to APEX and prints all events it receives from
4670 APEX. The console client connects to APEX, reads input from
4671 the command line, and sends this input as events to APEX.
4673 +------------------------------------------------------------+--------------------------------------------------------------+
4674 | Unix, Cygwin | Windows |
4675 +============================================================+==============================================================+
4676 | .. container:: | .. container:: |
4678 | .. container:: listingblock | .. container:: listingblock |
4680 | .. container:: content | .. container:: content |
4682 | .. code:: | .. code:: |
4684 | # $APEX_HOME/bin/apexApps.sh ws-echo [args] | > %APEX_HOME%\bin\apexApps.bat ws-echo [args] |
4685 | # $APEX_HOME/bin/apexApps.sh ws-console [args] | > %APEX_HOME%\bin\apexApps.bat ws-console [args] |
4686 +------------------------------------------------------------+--------------------------------------------------------------+
4688 .. container:: paragraph
4690 The arguments are the same for both applications:
4692 .. container:: ulist
4694 - ``-p`` defines the Websocket port to connect to (defaults
4697 - ``-s`` defines the host on which a Websocket server is
4698 running (defaults to ``localhost``)
4700 .. container:: paragraph
4702 A discussion on how to use these two applications to build
4703 an APEX system is detailed HowTo-Websockets.
4710 .. container:: paragraph
4712 Consider a scenario where a supermarket chain called
4713 *HyperM* controls how it sells items in a policy-based
4714 manner. Each time an item is processed by *HyperM*'s
4715 point-of-sale (PoS) system an event is generated and
4716 published about that item of stock being sold. This event
4717 can then be used to update stock levels, etc..
4719 .. container:: paragraph
4721 *HyperM* want to extend this approach to allow some checks
4722 to be performed before the sale can be completed. This can
4723 be achieved by requesting a policy-controlled decision as
4724 each item is processed by for sale by each PoS system. The
4725 decision process is integrated with *HyperM*'s other IT
4726 systems that manage stock control, sourcing and purchasing,
4727 personnel systems, etc.
4729 .. container:: paragraph
4731 In this document we will show how APEX and APEX Policies can
4732 be used to achieve this, starting with a simple policy,
4733 building up to more complicated policy that demonstrates the
4742 .. container:: paragraph
4744 Each time a PoS system processes a sales item an event
4745 with the following format is emitted:
4747 .. table:: Table 1. Sale Input Event
4749 +----------------------+----------------------+-----------------------+
4750 | Event | Fields | Description |
4751 +======================+======================+=======================+
4752 | SALE_INPUT | time, sale_ID, | Event indicating a |
4753 | | amount, item_ID, | sale of an item is |
4754 | | quantity, | occurring |
4755 | | assistant_ID, | |
4756 | | branch_ID, notes, … | |
4757 +----------------------+----------------------+-----------------------+
4759 .. container:: paragraph
4761 In each ``SALE_INPUT`` event the ``sale_ID`` field is a
4762 unique ID generated by the PoS system. A timestamp for
4763 the event is stored in the ``time`` field. The ``amount``
4764 field refers to the value of the item(s) to be sold (in
4765 cents). The ``item_ID`` field is a unique identifier for
4766 each item type, and can be used to retrieve more
4767 information about the item from *HyperM*'s stock control
4768 system. The ``quantity`` field refers to the quantity of
4769 the item to be sold. The ``assistant_ID`` field is a
4770 unique identifier for the PoS operator, and can be used
4771 to retrieve more information about the operator from the
4772 *HyperM*'s personnel system. Since *HyperM* has many
4773 branches the ``branch_ID`` identifies the shop. The
4774 ``notes`` field contains arbitrary notes about the sale.
4776 Sales Decision Event
4777 ####################
4779 .. container:: paragraph
4781 After a ``SALE_INPUT`` event is emitted by the PoS system
4782 *HyperM*'s policy-based controlled sales checking system
4783 emits a Sale Authorization Event indicating whether the
4784 sale is authorized or denied. The PoS system can then
4785 listen for this event before continuing with the sale.
4787 .. table:: Table 2. Sale Authorisation Event
4789 +----------------------+----------------------+-----------------------+
4790 | Event | Fields | Description |
4791 +======================+======================+=======================+
4792 | SALE_AUTH | sale_ID, time, | Event indicating a |
4793 | | authorized, amount, | sale of an item is |
4794 | | item_ID, quantity, | authorized or denied |
4795 | | assistant_ID, | |
4796 | | branch_ID, notes, | |
4798 +----------------------+----------------------+-----------------------+
4800 .. container:: paragraph
4802 In each ``SALE_AUTH`` event the ``sale_ID`` field is
4803 copied from the ``SALE_INPUT`` event that trigger the
4804 decision request. The ``SALE_AUTH`` event is also
4805 timestamped using the ``time`` field, and a field called
4806 ``authorised`` is set to ``true`` or ``false`` depending
4807 on whether the sale is authorized or denied. The
4808 ``message`` field carries an optional message about why a
4809 sale was not authorized. The other fields from the
4810 ``SALE_INPUT`` event are also included for completeness.
4812 Stock Control: Items
4813 ####################
4815 .. container:: paragraph
4817 *HyperM* maintains information about each item for sale
4818 in a database table called ``ITEMS``.
4820 .. table:: Table 3. Items Database
4822 +----------------------+----------------------+-----------------------+
4823 | Table | Fields | Description |
4824 +======================+======================+=======================+
4825 | ITEMS | item_ID, | Database table |
4826 | | description, | describing each item |
4827 | | cost_price, barcode, | for sale |
4828 | | supplier_ID, | |
4829 | | category, … | |
4830 +----------------------+----------------------+-----------------------+
4832 .. container:: paragraph
4834 The database table ``ITEMS`` has a row for each items
4835 that *HyperM* sells. Each item is identified by an
4836 ``item_ID`` value. The ``description`` field stores a
4837 description of the item. The cost price of the item is
4838 given in ``cost_price``. The barcode of the item is
4839 encoded in ``barcode``, while the item supplier is
4840 identified by ``supplier_ID``. Items may also be
4841 classified into categories using the ``category`` field.
4842 Useful categories might include: ``soft drinks``,
4843 ``alcoholic drinks``, ``cigarettes``, ``knives``,
4844 ``confectionery``, ``bakery``, ``fruit&vegetables``,
4847 Personnel System: Assistants
4848 ############################
4850 .. table:: Table 4. Assistants Database
4852 +----------------------+----------------------+-----------------------+
4853 | Table | Fields | Description |
4854 +======================+======================+=======================+
4855 | ASSISTANTS | assistant_ID, | Database table |
4856 | | surname, firstname, | describing each |
4857 | | middlename, age, | *HyperM* sales |
4858 | | grade, phone_number, | assistant |
4860 +----------------------+----------------------+-----------------------+
4862 .. container:: paragraph
4864 The database table ``ASSISTANTS`` has a row for each
4865 sales assistant employed by *HyperM*. Each assistant is
4866 identified by an ``assistant_ID`` value, with their name
4867 given in the ``firstname``, ``middlename`` and
4868 ``surname`` fields. The assistant’s age in years is given
4869 in ``age``, while their phone number is contained in the
4870 ``phone_number`` field. The assistant’s grade is encoded
4871 in ``grade``. Useful values for ``grade`` might include:
4872 ``trainee``, ``operator``, ``supervisor``, etc..
4875 ####################
4877 .. table:: Table 5. Branches Database
4879 +----------------------+----------------------+-----------------------+
4880 | Table | Fields | Description |
4881 +======================+======================+=======================+
4882 | BRANCHES | branch_ID, | Database table |
4883 | | branch_Name, | describing each |
4884 | | category, street, | *HyperM* branch |
4885 | | city, country, | |
4886 | | postcode, … | |
4887 +----------------------+----------------------+-----------------------+
4889 .. container:: paragraph
4891 *HyperM* operates a number of branches. Each branch is
4892 described in the ``BRANCHES`` database table. Each branch
4893 is identified by a ``branch_ID``, with a branch name
4894 given in ``branch_Name``. The address for the branch is
4895 encoded in ``street``, ``city``, ``country`` and
4896 ``postcode``. The branch category is given in the
4897 ``category`` field. Useful values for ``category`` might
4898 include: ``Small``, ``Large``, ``Super``, ``Hyper``,
4906 .. container:: paragraph
4908 For the first version of our policy, let’s start with
4909 something simple. Let us assume that there exists some
4910 restriction that alcohol products cannot be sold before
4911 11:30am. In this section we will go through the necessary
4912 steps to define a policy that can enforce this for
4915 .. container:: ulist
4917 - Alcohol cannot be sold before 11:30am.
4919 Create the an new empty Policy Model ``MyFirstPolicyModel``
4920 ###########################################################
4922 .. container:: paragraph
4924 Since an organisation like *HyperM* may have many
4925 policies covering many different domains, policies should
4926 be grouped into policy sets. In order to edit or deploy a
4927 policy, or policy set, the definition of the policy(ies)
4928 and all required events, tasks, states, etc., are grouped
4929 together into a 'Policy Model'. An organization might
4930 define many Policy Models, each containing a different
4933 .. container:: paragraph
4935 So the first step is to create a new empty Policy Model
4936 called ``MyFirstPolicyModel``. Using the APEX Policy
4937 Editor, click on the 'File' menus and select 'New'. Then
4938 define our new policy model called
4939 ``MyFirstPolicyModel``. Use the 'Generate UUID' button to
4940 create a new unique ID for the policy model, and fill in
4941 a description for the policy model. Press the ``Submit``
4942 button to save your changes.
4944 .. container:: imageblock
4946 .. container:: content
4948 |File > New to create a new Policy Model|
4950 .. container:: title
4952 Figure 4. Create a new Policy Model 1/2
4954 .. container:: imageblock
4956 .. container:: content
4958 |Create a new Policy Model|
4960 .. container:: title
4962 Figure 5. Create a new Policy Model 2/2
4964 Create the input event ``SALE_INPUT`` and the output event ``SALE_AUTH``
4965 ########################################################################
4967 .. container:: paragraph
4969 Using the APEX Policy Editor, click on the 'Events' tab.
4970 In the 'Events' pane, right click and select 'New':
4972 .. container:: imageblock
4974 .. container:: content
4976 |Right click to create a new event|
4978 .. container:: title
4980 Figure 6. Create a new Event type
4982 .. container:: paragraph
4984 Create a new event type called ``SALE_INPUT``. Use the
4985 'Generate UUID' button to create a new unique ID for the
4986 event type, and fill in a description for the event. Add
4987 a namespace, e.g. ``com.hyperm``. We can add hard-coded
4988 strings for the ``Source`` and ``Target``, e.g. ``POS``
4989 and ``APEX``. At this stage we will not add any parameter
4990 fields, we will leave this until later. Use the
4991 ``Submit`` button to create the event.
4993 .. container:: imageblock
4995 .. container:: content
4997 |Fill in the necessary information for the
4998 'SALE_INPUT' event and click 'Submit'|
5000 .. container:: title
5002 Figure 7. Populate the ``SALE_INPUT`` event
5004 .. container:: paragraph
5006 Repeat the same steps for a new event type called
5007 ``SALE_AUTH``. Just use ``APEX`` as source and ``POS`` as
5008 target, since this is the output event coming from APEX
5009 going to the sales point.
5011 .. container:: paragraph
5013 Before we can add parameter fields to an event we must
5014 first define APEX Context Item Schemas that can be used
5017 .. container:: paragraph
5019 To create new item schemas, click on the 'Context Item
5020 Schemas' tab. In that 'Context Item Schemas' pane, right
5021 click and select 'Create new ContextSchema'.
5023 .. container:: imageblock
5025 .. container:: content
5027 |Right click to create a new Item Schema|
5029 .. container:: title
5031 Figure 8. Create new Data Types
5033 .. container:: paragraph
5035 Create item schemas with the following characteristics,
5036 each with its own unique UUID:
5038 .. table:: Table 6. Item Schemas
5040 +-------------------+-----------------+-----------------+----------------------+
5041 | Name | Schema Flavour | Schema | Description |
5042 | | | Definition | |
5043 +===================+=================+=================+======================+
5044 | timestamp_type | Java | java.lang.Long | A type for |
5045 | | | | ``time`` values |
5046 +-------------------+-----------------+-----------------+----------------------+
5047 | sale_ID_type | Java | java.lang.Long | A type for |
5048 | | | | ``sale_ID`` |
5050 +-------------------+-----------------+-----------------+----------------------+
5051 | price_type | Java | java.lang.Long | A type for |
5052 | | | | ``amount``/``price`` |
5054 +-------------------+-----------------+-----------------+----------------------+
5055 | item_ID_type | Java | java.lang.Long | A type for |
5056 | | | | ``item_ID`` |
5058 +-------------------+-----------------+-----------------+----------------------+
5059 | assistant_ID_type | Java | java.lang.Long | A type for |
5060 | | | | ``assistant_ID`` |
5062 +-------------------+-----------------+-----------------+----------------------+
5063 | quantity_type | Java | java.lang.Integ | A type for |
5064 | | | er | ``quantity`` |
5066 +-------------------+-----------------+-----------------+----------------------+
5067 | branch_ID_type | Java | java.lang.Long | A type for |
5068 | | | | ``branch_ID`` |
5070 +-------------------+-----------------+-----------------+----------------------+
5071 | notes_type | Java | java.lang.Strin | A type for |
5072 | | | g | ``notes`` |
5074 +-------------------+-----------------+-----------------+----------------------+
5075 | authorised_type | Java | java.lang.Boole | A type for |
5076 | | | an | ``authorised`` |
5078 +-------------------+-----------------+-----------------+----------------------+
5079 | message_type | Java | java.lang.Strin | A type for |
5080 | | | g | ``message`` |
5082 +-------------------+-----------------+-----------------+----------------------+
5084 .. container:: imageblock
5086 .. container:: content
5088 |Create a new Item Schema|
5090 .. container:: title
5092 Figure 9. Create new Item Schemas
5094 .. container:: paragraph
5096 The item schemas can now be seen on the 'Context Item
5097 Schemas' tab, and can be updated at any time by
5098 right-clicking on the item schemas on the 'Context Item
5099 Schemas' tab. Now we can go back to the event definitions
5100 for ``SALE_INPUT`` and ``SALE_AUTH`` and add some
5105 .. container:: title
5109 .. container:: paragraph
5111 APEX natively supports schema definitions in ``Java`` and ``Avro``.
5113 .. container:: paragraph
5115 ``Java`` schema definitions are simply the name of a Java Class. There are some restrictions:
5117 .. container:: ulist
5119 - the class must be instantiatable, i.e. not an Java interface or abstract class
5121 - primitive types are not supported, i.e. use ``java.lang.Integer`` instead of ``int``, etc.
5123 - it must be possible to find the class, i.e. the class must be contained in the Java classpath.
5125 .. container:: paragraph
5127 ``Avro`` schema definitions can be any valid `Avro <https://avro.apache.org/docs/current/spec.html>`__
5128 schema. For events using fields defined with ``Avro`` schemas, any incoming event containing that field must
5129 contain a value that conforms to the Avro schema.
5131 .. container:: paragraph
5133 Click on the 'Events' tab, then right click the
5134 ``SALE_INPUT`` row and select 'Edit Event
5135 :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`
5136 event add the following event parameters:
5138 .. table:: Table 7. Event Parameter Fields for the ``SALE_INPUT`` Event
5140 +----------------------+----------------------+-----------------------+
5141 | Parameter Name | Parameter Type | Optional |
5142 +======================+======================+=======================+
5143 | time | timestamp_type | no |
5144 +----------------------+----------------------+-----------------------+
5145 | sale_ID | sale_ID_type | no |
5146 +----------------------+----------------------+-----------------------+
5147 | amount | price_type | no |
5148 +----------------------+----------------------+-----------------------+
5149 | item_ID | item_ID_type | no |
5150 +----------------------+----------------------+-----------------------+
5151 | quantity | quantity_type | no |
5152 +----------------------+----------------------+-----------------------+
5153 | assistant_ID | assistant_ID_type | no |
5154 +----------------------+----------------------+-----------------------+
5155 | branch_ID | branch_ID_type | no |
5156 +----------------------+----------------------+-----------------------+
5157 | notes | notes_type | *yes* |
5158 +----------------------+----------------------+-----------------------+
5160 .. container:: paragraph
5162 Remember to click the 'Submit' button at the bottom of
5163 the event definition pane.
5166 Optional Fields in APEX Events
5167 Parameter fields can be *optional* in events. If a parameter is not marked as *optional* then by default it
5168 is *mandatory*, so it must appear in any input event passed to APEX. If an *optional* field is not set
5169 for an output event then value will be set to ``null``.
5171 .. container:: imageblock
5173 .. container:: content
5175 |Add new event parameters to an event|
5177 .. container:: title
5179 Figure 10. Add typed parameter fields to an event
5181 .. container:: paragraph
5183 Select the ``SALE_AUTH`` event and add the following
5186 .. table:: Table 8. Event Parameter Fields for the ``SALE_AUTH`` Event
5188 +----------------------+----------------------+-----------------------+
5189 | Parameter Name | Parameter Type | no |
5190 +======================+======================+=======================+
5191 | sale_ID | sale_ID_type | no |
5192 +----------------------+----------------------+-----------------------+
5193 | time | timestamp_type | no |
5194 +----------------------+----------------------+-----------------------+
5195 | authorised | authorised_type | no |
5196 +----------------------+----------------------+-----------------------+
5197 | message | message_type | *yes* |
5198 +----------------------+----------------------+-----------------------+
5199 | amount | price_type | no |
5200 +----------------------+----------------------+-----------------------+
5201 | item_ID | item_ID_type | no |
5202 +----------------------+----------------------+-----------------------+
5203 | assistant_ID | assistant_ID_type | no |
5204 +----------------------+----------------------+-----------------------+
5205 | quantity | quantity_type | no |
5206 +----------------------+----------------------+-----------------------+
5207 | branch_ID | branch_ID_type | no |
5208 +----------------------+----------------------+-----------------------+
5209 | notes | notes_type | *yes* |
5210 +----------------------+----------------------+-----------------------+
5212 .. container:: paragraph
5214 Remember to click the 'Submit' button at the bottom of
5215 the event definition pane.
5217 .. container:: paragraph
5219 The events for our policy are now defined.
5221 Create a new Policy and add the *"No Booze before 11:30"* check
5222 ###############################################################
5224 .. container:: paragraph
5226 APEX policies are defined using a state-machine model.
5227 Each policy comprises one or more *states* that can be
5228 individually executed. Where there is more than one
5229 *state* the states are chained together to form a
5230 `Directed Acyclic Graph
5231 (DAG) <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__
5232 of states. A *state* is triggered by passing it a single
5233 input (or 'trigger') event and once executed each state
5234 then emits an output event. For each *state* the logic
5235 for the *state* is embedded in one or more *tasks*. Each
5236 *task* contains specific *task logic* that is executed by
5237 the APEX execution environment each time the *task* is
5238 invoked. Where there is more than one *task* in a *state*
5239 then the *state* also defines some *task selection logic*
5240 to select an appropriate task each time the *state* is
5243 .. container:: paragraph
5245 Therefore, to create a new policy we must first define
5248 .. container:: paragraph
5250 To create a new Task click on the 'Tasks' tab. In the
5251 'Tasks' pane, right click and select 'Create new Task'.
5252 Create a new Task called ``MorningBoozeCheck``. Use the
5253 'Generate UUID' button to create a new unique ID for the
5254 task, and fill in a description for the task.
5256 .. container:: imageblock
5258 .. container:: content
5260 |Right click to create a new task|
5262 .. container:: title
5264 Figure 11. Create a new Task
5266 .. container:: paragraph
5268 Tasks are configured with a set of *input fields* and a
5269 set of *output fields*. To add new input/output fields
5270 for a task use the 'Add Task Input Field' and 'Add Task
5271 Output Field' button. The list of input and out fields to
5272 add for the ``MorningBoozeCheck`` task are given below.
5273 The input fields are drawn from the parameters in the
5274 state’s input event, and the task’s output fields are
5275 used to populate the state’s output event. The task’s
5276 input and output fields must be a subset of the event
5277 parameters defined for the input and output events for
5278 any state that uses that task. (You may have noticed that
5279 the input and output fields for the ``MorningBoozeCheck``
5280 task have the exact same names and reuse the item schemas
5281 that we used for the parameters in the ``SALE_INPUT`` and
5282 ``SALE_AUTH`` events respectively).
5284 .. table:: Table 9. Input fields for ``MorningBoozeCheck`` task
5286 +-----------------------------------+-----------------------------------+
5287 | Parameter Name | Parameter Type |
5288 +===================================+===================================+
5289 | time | timestamp_type |
5290 +-----------------------------------+-----------------------------------+
5291 | sale_ID | sale_ID_type |
5292 +-----------------------------------+-----------------------------------+
5293 | amount | price_type |
5294 +-----------------------------------+-----------------------------------+
5295 | item_ID | item_ID_type |
5296 +-----------------------------------+-----------------------------------+
5297 | quantity | quantity_type |
5298 +-----------------------------------+-----------------------------------+
5299 | assistant_ID | assistant_ID_type |
5300 +-----------------------------------+-----------------------------------+
5301 | branch_ID | branch_ID_type |
5302 +-----------------------------------+-----------------------------------+
5303 | notes | notes_type |
5304 +-----------------------------------+-----------------------------------+
5306 .. table:: Table 10. Output fields for ``MorningBoozeCheck`` task
5308 +-----------------------------------+-----------------------------------+
5309 | Parameter Name | Parameter Type |
5310 +===================================+===================================+
5311 | sale_ID | sale_ID_type |
5312 +-----------------------------------+-----------------------------------+
5313 | time | timestamp_type |
5314 +-----------------------------------+-----------------------------------+
5315 | authorised | authorised_type |
5316 +-----------------------------------+-----------------------------------+
5317 | message | message_type |
5318 +-----------------------------------+-----------------------------------+
5319 | amount | price_type |
5320 +-----------------------------------+-----------------------------------+
5321 | item_ID | item_ID_type |
5322 +-----------------------------------+-----------------------------------+
5323 | assistant_ID | assistant_ID_type |
5324 +-----------------------------------+-----------------------------------+
5325 | quantity | quantity_type |
5326 +-----------------------------------+-----------------------------------+
5327 | branch_ID | branch_ID_type |
5328 +-----------------------------------+-----------------------------------+
5329 | notes | notes_type |
5330 +-----------------------------------+-----------------------------------+
5332 .. container:: imageblock
5334 .. container:: content
5336 |Add input and out fields for the task|
5338 .. container:: title
5340 Figure 12. Add input and out fields for the Task
5342 .. container:: paragraph
5344 Each task must include some 'Task Logic' that implements
5345 the behaviour for the task. Task logic can be defined in
5346 a number of different ways using a choice of languages.
5347 For this task we will author the logic using the
5348 Java-like scripting language called
5349 ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__.
5351 .. container:: paragraph
5353 For simplicity use the following code for the task logic.
5354 Paste the script text into the 'Task Logic' box, and use
5355 "MVEL" as the 'Task Logic Type / Flavour'.
5357 .. container:: paragraph
5359 This logic assumes that all items with ``item_ID``
5360 between 1000 and 2000 contain alcohol, which is not very
5361 realistic, but we will see a better approach for this
5362 later. It also uses the standard ``Java`` time utilities
5363 to check if the current time is between ``00:00:00 GMT``
5364 and ``11:30:00 GMT``. For a detailed guide to how to
5365 write your own logic in
5366 ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__,
5367 ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__ or one
5368 of the other supported languages please refer to APEX
5371 .. container:: listingblock
5373 .. container:: title
5375 MVEL code for the ``MorningBoozeCheck`` task
5377 .. container:: content
5382 * ============LICENSE_START=======================================================
5383 * Copyright (C) 2016-2018 Ericsson. All rights reserved.
5384 * ================================================================================
5385 * Licensed under the Apache License, Version 2.0 (the "License");
5386 * you may not use this file except in compliance with the License.
5387 * You may obtain a copy of the License at
5389 * http://www.apache.org/licenses/LICENSE-2.0
5391 * Unless required by applicable law or agreed to in writing, software
5392 * distributed under the License is distributed on an "AS IS" BASIS,
5393 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
5394 * See the License for the specific language governing permissions and
5395 * limitations under the License.
5397 * SPDX-License-Identifier: Apache-2.0
5398 * ============LICENSE_END=========================================================
5400 import java.util.Date;
5401 import java.util.Calendar;
5402 import java.util.TimeZone;
5403 import java.text.SimpleDateFormat;
5405 logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'");
5407 outFields.put("amount" , inFields.get("amount"));
5408 outFields.put("assistant_ID", inFields.get("assistant_ID"));
5409 outFields.put("notes" , inFields.get("notes"));
5410 outFields.put("quantity" , inFields.get("quantity"));
5411 outFields.put("branch_ID" , inFields.get("branch_ID"));
5412 outFields.put("item_ID" , inFields.get("item_ID"));
5413 outFields.put("time" , inFields.get("time"));
5414 outFields.put("sale_ID" , inFields.get("sale_ID"));
5416 item_id = inFields.get("item_ID");
5418 //The events used later to test this task use GMT timezone!
5419 gmt = TimeZone.getTimeZone("GMT");
5420 timenow = Calendar.getInstance(gmt);
5421 df = new SimpleDateFormat("HH:mm:ss z");
5422 df.setTimeZone(gmt);
5423 timenow.setTimeInMillis(inFields.get("time"));
5425 midnight = timenow.clone();
5427 timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
5428 timenow.get(Calendar.DATE),0,0,0);
5429 eleven30 = timenow.clone();
5431 timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
5432 timenow.get(Calendar.DATE),11,30,0);
5434 itemisalcohol = false;
5435 if(item_id != null && item_id >=1000 && item_id < 2000)
5436 itemisalcohol = true;
5439 && timenow.after(midnight) && timenow.before(eleven30)){
5440 outFields.put("authorised", false);
5441 outFields.put("message", "Sale not authorised by policy task "+subject.taskName+
5442 " for time "+df.format(timenow.getTime())+
5443 ". Alcohol can not be sold between "+df.format(midnight.getTime())+
5444 " and "+df.format(eleven30.getTime()));
5448 outFields.put("authorised", true);
5449 outFields.put("message", "Sale authorised by policy task "+subject.taskName+
5450 " for time "+df.format(timenow.getTime()));
5455 This task checks if a sale request is for an item that is an alcoholic drink.
5456 If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not
5457 authorised. Otherwise the sale is authorised.
5458 In this implementation we assume that items with item_ID value between 1000 and
5459 2000 are all alcoholic drinks :-)
5462 .. container:: imageblock
5464 .. container:: content
5466 |Add task logic the task|
5468 .. container:: title
5470 Figure 13. Add Task Logic the Task
5472 .. container:: paragraph
5474 An alternative version of the same logic is available in
5475 JavaScript. Just use "JAVASCRIPT" as the 'Task Logic Type
5478 .. container:: listingblock
5480 .. container:: title
5482 Javascript alternative for the ``MorningBoozeCheck``
5485 .. container:: content
5490 * ============LICENSE_START=======================================================
5491 * Copyright (C) 2016-2018 Ericsson. All rights reserved.
5492 * ================================================================================
5493 * Licensed under the Apache License, Version 2.0 (the "License");
5494 * you may not use this file except in compliance with the License.
5495 * You may obtain a copy of the License at
5497 * http://www.apache.org/licenses/LICENSE-2.0
5499 * Unless required by applicable law or agreed to in writing, software
5500 * distributed under the License is distributed on an "AS IS" BASIS,
5501 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
5502 * See the License for the specific language governing permissions and
5503 * limitations under the License.
5505 * SPDX-License-Identifier: Apache-2.0
5506 * ============LICENSE_END=========================================================
5509 var returnValueType = Java.type("java.lang.Boolean");
5510 var returnValue = new returnValueType(true);
5512 // Load compatibility script for imports etc
5513 load("nashorn:mozilla_compat.js");
5514 importPackage(java.text);
5515 importClass(java.text.SimpleDateFormat);
5517 executor.logger.info("Task Execution: '"+executor.subject.id+"'. Input Fields: '"+executor.inFields+"'");
5519 executor.outFields.put("amount" , executor.inFields.get("amount"));
5520 executor.outFields.put("assistant_ID", executor.inFields.get("assistant_ID"));
5521 executor.outFields.put("notes" , executor.inFields.get("notes"));
5522 executor.outFields.put("quantity" , executor.inFields.get("quantity"));
5523 executor.outFields.put("branch_ID" , executor.inFields.get("branch_ID"));
5524 executor.outFields.put("item_ID" , executor.inFields.get("item_ID"));
5525 executor.outFields.put("time" , executor.inFields.get("time"));
5526 executor.outFields.put("sale_ID" , executor.inFields.get("sale_ID"));
5528 item_id = executor.inFields.get("item_ID");
5530 //All times in this script are in GMT/UTC since the policy and events assume time is in GMT.
5531 var timenow_gmt = new Date(Number(executor.inFields.get("time")));
5533 var midnight_gmt = new Date(Number(executor.inFields.get("time")));
5534 midnight_gmt.setUTCHours(0,0,0,0);
5536 var eleven30_gmt = new Date(Number(executor.inFields.get("time")));
5537 eleven30_gmt.setUTCHours(11,30,0,0);
5539 var timeformatter = new java.text.SimpleDateFormat("HH:mm:ss z");
5541 var itemisalcohol = false;
5542 if(item_id != null && item_id >=1000 && item_id < 2000)
5543 itemisalcohol = true;
5546 && timenow_gmt.getTime() >= midnight_gmt.getTime()
5547 && timenow_gmt.getTime() < eleven30_gmt.getTime()) {
5549 executor.outFields.put("authorised", false);
5550 executor.outFields.put("message", "Sale not authorised by policy task " +
5551 executor.subject.taskName+ " for time " + timeformatter.format(timenow_gmt.getTime()) +
5552 ". Alcohol can not be sold between " + timeformatter.format(midnight_gmt.getTime()) +
5553 " and " + timeformatter.format(eleven30_gmt.getTime()));
5556 executor.outFields.put("authorised", true);
5557 executor.outFields.put("message", "Sale authorised by policy task " +
5558 executor.subject.taskName + " for time "+timeformatter.format(timenow_gmt.getTime()));
5562 This task checks if a sale request is for an item that is an alcoholic drink.
5563 If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not
5564 authorised. Otherwise the sale is authorised.
5565 In this implementation we assume that items with item_ID value between 1000 and
5566 2000 are all alcoholic drinks :-)
5569 .. container:: paragraph
5571 The task definition is now complete so click the 'Submit'
5572 button to save the task. The task can now be seen on the
5573 'Tasks' tab, and can be updated at any time by
5574 right-clicking on the task on the 'Task' tab. Now that we
5575 have created our task, we can can create a policy that
5578 .. container:: paragraph
5580 To create a new Policy click on the 'Policies' tab. In
5581 the 'Policies' pane, right click and select 'Create new
5584 .. container:: paragraph
5586 Create a new Policy called ``MyFirstPolicy``. Use the
5587 'Generate UUID' button to create a new unique ID for the
5588 policy, and fill in a description for the policy. Use
5589 'FREEFORM' as the 'Policy Flavour'.
5591 .. container:: paragraph
5593 Each policy must have at least one state. Since this is
5594 'freeform' policy we can add as many states as we wish.
5595 Let’s start with one state. Add a new state called
5596 ``BoozeAuthDecide`` to this ``MyFirstPolicy`` policy
5597 using the 'Add new State' button after filling in the
5598 name of our new state.
5600 .. container:: imageblock
5602 .. container:: content
5604 |Create a new policy|
5606 .. container:: title
5608 Figure 14. Create a new Policy
5610 .. container:: paragraph
5612 Each state must uses one input event type. For this new
5613 state select the ``SALE_INPUT`` event as the input event.
5615 .. container:: paragraph
5617 Each policy must define a 'First State' and a 'Policy
5618 Trigger Event'. The 'Policy Trigger Event' is the input
5619 event for the policy as a whole. This event is then
5620 passed to the first state in the chain of states in the
5621 policy, therefore the 'Policy Trigger Event' will be the
5622 input event for the first state. Each policy can only
5623 have one 'First State'. For our ``MyFirstPolicy`` policy,
5624 select ``BoozeAuthDecide`` as the 'First State'. This
5625 will automatically select ``SALE_INPUT`` as the 'Policy
5626 Trigger Event' for our policy.
5628 .. container:: imageblock
5630 .. container:: content
5634 .. container:: title
5636 Figure 15. Create a new State
5638 .. container:: paragraph
5640 In this case we will create a reference the pre-existing
5641 ``MorningBoozeCheck`` task that we defined above using
5642 the 'Add New Task' button. Select the
5643 ``MorningBoozeCheck`` task, and use the name of the task
5644 as the 'Local Name' for the task.
5646 .. container:: paragraph
5648 in the case where a state references more than one task,
5649 a 'Default Task' must be selected for the state and some
5650 logic ('Task Selection Logic') must be specified to
5651 select the appropriate task at execution time. Since our
5652 new state ``BoozeAuthDecide`` only has one task the
5653 default task is automatically selected and no 'Task
5654 Selection Logic' is required.
5657 .. container:: title
5659 State Output Mappings
5661 .. container:: paragraph
5663 In a 'Policy' 'State' a 'State Output Mapping' has 3 roles:
5664 1) Select which 'State' should be executed next, 2) Select
5665 the type of the state’s 'Outgoing Event', and 3)
5666 Populate the state’s 'Outgoing Event'. This is how states are
5667 chained together to form a (`Directed Acyclic Graph
5668 (DAG) <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__ )
5669 of states. The final state(s) of a policy are those that do
5670 not select any 'next' state. Since a 'State' can only
5671 accept a single type of event, the type of the event emitted
5672 by a previous 'State' must be match the incoming event type
5673 of the next 'State'. This is also how the last state(s) in
5674 a policy can emit events of different types. The 'State
5675 Output Mapping' is also responsible for taking the
5676 fields that are output by the task executed in the state and
5677 populating the state’s output event before it is emitted.
5679 .. container:: paragraph
5681 Each 'Task' referenced in 'State' must have a defined
5682 'Output Mapping' to take the output of the task, select an
5683 'Outgoing Event' type for the state, populate the state’s
5684 outgoing event, and then select the next state to be
5687 .. container:: paragraph
5689 There are 2 basic types of output mappings:
5691 .. container:: olist arabic
5693 #. **Direct Output Mappings** have a single value for
5694 'Next State' and a single value for 'State Output
5695 Event'. The outgoing event for the state is
5696 automatically created, any outgoing event parameters
5697 that were present in the incoming event are copied
5698 into the outgoing event, then any task output fields
5699 that have the same name and type as parameters in the
5700 outgoing event are automatically copied into
5703 #. **Logic-based State Output Mappings / Finalizers**
5704 have some logic defined that dynamically selects
5705 and creates the 'State Outgoing Event', manages
5706 the population of the outgoing event parameters
5707 (perhaps changing or adding to the outputs from the
5708 task), and then dynamically selects the next state to
5709 be executed (if any).
5711 .. container:: paragraph
5713 Each task reference must also have an associated 'Output
5714 State Mapping' so we need an 'Output State Mapping' for
5715 the ``BoozeAuthDecide`` state to use when the
5716 ``MorningBoozeCheck`` task is executed. The simplest type
5717 of output mapping is a 'Direct Output Mapping'.
5719 .. container:: paragraph
5721 Create a new 'Direct Output Mapping' for the state called
5722 ``MorningBoozeCheck_Output_Direct`` using the 'Add New
5723 Direct State Output Mapping' button. Select ``SALE_AUTH``
5724 as the output event and select ``None`` for the next
5725 state value. We can then select this output mapping for
5726 use when the the ``MorningBoozeCheck`` task is executed.
5727 Since there is only state, and only one task for that
5728 state, this output mapping ensures that the
5729 ``BoozeAuthDecide`` state is the only state executed and
5730 the state (and the policy) can only emit events of type
5731 ``SALE_AUTH``. (You may remember that the output fields
5732 for the ``MorningBoozeCheck`` task have the exact same
5733 names and reuse the item schemas that we used for the
5734 parameters in ``SALE_AUTH`` event. The
5735 ``MorningBoozeCheck_Output_Direct`` direct output mapping
5736 can now automatically copy the values from the
5737 ``MorningBoozeCheck`` task directly into outgoing
5738 ``SALE_AUTH`` events.)
5740 .. container:: imageblock
5742 .. container:: content
5744 |Add a Task and Output Mapping|
5746 .. container:: title
5748 Figure 16. Add a Task and Output Mapping
5750 .. container:: paragraph
5752 Click the 'Submit' button to complete the definition of
5753 our ``MyFirstPolicy`` policy. The policy
5754 ``MyFirstPolicy`` can now be seen in the list of policies
5755 on the 'Policies' tab, and can be updated at any time by
5756 right-clicking on the policy on the 'Policies' tab.
5758 .. container:: paragraph
5760 The ``MyFirstPolicyModel``, including our
5761 ``MyFirstPolicy`` policy can now be checked for errors.
5762 Click on the 'Model' menu and select 'Validate'. The
5763 model should validate without any 'Warning' or 'Error'
5764 messages. If you see any 'Error' or 'Warning' messages,
5765 carefully read the message as a hint to find where you
5766 might have made a mistake when defining some aspect of
5769 .. container:: imageblock
5771 .. container:: content
5773 |Validate the policy model for error using the 'Model'
5774 > 'Validate' menu item|
5776 .. container:: title
5778 Figure 17. Validate a Policy Model
5780 .. container:: paragraph
5782 Congratulations, you have now completed your first APEX
5783 policy. The policy model containing our new policy can
5784 now be exported from the editor and saved. Click on the
5785 'File' menu and select 'Download' to save the policy
5786 model in JSON format. The exported policy model is then
5787 available in the directory you selected, for instance
5788 ``$APEX_HOME/examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json``.
5789 The exported policy can now be loaded into the APEX
5790 Policy Engine, or can be re-loaded and edited by the APEX
5793 .. container:: imageblock
5795 .. container:: content
5797 |Download the completed policy model using the 'File'
5798 > 'Download' menu item|
5800 .. container:: title
5802 Figure 18. Export a Policy Model
5807 .. container:: paragraph
5809 To start a new APEX Engine you can use the following
5810 configuration. In a full APEX installation you can find
5811 this configuration in
5812 ``$APEX_HOME/examples/config/MyFirstPolicy/1/MyFirstPolicyConfigStdin2StdoutJsonEvent.json``.
5813 This configuration expects incoming events to be in
5814 ``JSON`` format and to be passed into the APEX Engine
5815 from ``stdin``, and result events will be printed in
5816 ``JSON`` format to ``stdout``. This configuration loads
5817 the policy model stored in the file
5818 'MyFirstPolicyModel_0.0.1.json' as exported from the APEX
5819 Editor. Note, you may need to edit this file to provide
5820 the full path to wherever you stored the exported policy
5823 .. container:: listingblock
5825 .. container:: title
5827 JSON to load and execute *My First Policy*, read input
5828 JSON events from ``stdin``, and emit output events to
5831 .. container:: content
5836 "engineServiceParameters" : {
5837 "name" : "MyFirstPolicyApexEngine",
5838 "version" : "0.0.1",
5840 "instanceCount" : 4,
5841 "deploymentPort" : 12345,
5842 "policyModelFileName" : "examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json",
5843 "engineParameters" : {
5844 "executorParameters" : {
5846 "parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
5849 "parameterClassName" : "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"
5854 "eventOutputParameters": {
5856 "carrierTechnologyParameters" : {
5857 "carrierTechnology" : "FILE",
5862 "eventProtocolParameters" : {
5863 "eventProtocol" : "JSON"
5867 "eventInputParameters": {
5869 "carrierTechnologyParameters" : {
5870 "carrierTechnology" : "FILE",
5875 "eventProtocolParameters" : {
5876 "eventProtocol" : "JSON"
5882 .. container:: paragraph
5884 To test the policy try paste the following events into
5885 the console as the APEX engine executes:
5887 .. table:: Table 11. Inputs and Outputs when testing *My First Policy*
5889 +------------------------------------------+-------------------------------------------+-----------+
5890 | Input Event (JSON) | Output Event (JSON) | comment |
5891 +==========================================+===========================================+===========+
5892 | .. container:: | .. container:: | Request |
5894 | .. container:: listingblock | .. container:: listingblock | non-alcoh |
5896 | | .. container:: content | item |
5897 | .. container:: content | | (``item_I |
5898 | | .. code:: | D=5123``) |
5900 | .. code:: | { | *10:13:09 |
5901 | | "name": "SALE_AUTH", | * |
5903 | { | "version": "0.0.1", | *Tuesday, |
5904 | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | 10 |
5905 | "name" : "SALE_INPUT", | "source": "", | January |
5906 | "version": "0.0.1", | "target": "", | 2017*. |
5907 | "time" : 1483351989000, | "amount": 299, | Sale is |
5908 | "sale_ID": 99999991, | "assistant_ID": 23, | authorize |
5909 | "amount": 299, | "authorised": true, | d. |
5910 | "item_ID": 5123, | "branch_ID": 1, | |
5911 | "quantity": 1, | "item_ID": 5123, | |
5912 | "assistant_ID": 23, | "message": "Sale authorised | |
5913 | "branch_ID": 1, | by policy task MorningBo | |
5914 | "notes": "Special Offer!!" | ozeCheck for time 10:13:09 | |
5916 | | "notes": "Special Offer!!", | |
5917 | | "quantity": 1, | |
5918 | | "sale_ID": 99999991, | |
5919 | | "time": 1483351989000 | |
5924 +------------------------------------------+-------------------------------------------+-----------+
5925 | .. container:: | .. container:: | Request |
5927 | .. container:: listingblock | .. container:: listingblock | alcohol |
5929 | .. container:: content | .. container:: content | (``item_I |
5931 | .. code:: | .. code:: | at |
5934 | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | on |
5935 | "name": "SALE_INPUT", | "name": "SALE_AUTH", | *Monday, |
5936 | "version": "0.0.1", | "source": "", | 02 |
5937 | "time": 1483346466000, | "target": "", | January |
5938 | "sale_ID": 99999992, | "amount": 1249, | 2017*. |
5939 | "version": "0.0.1", | "assistant_ID": 12, | |
5940 | "amount": 1249, | "authorised": false, | Sale is |
5941 | "item_ID": 1012, | "branch_ID": 2, | not |
5942 | "quantity": 1, | "item_ID": 1012, | authorize |
5943 | "assistant_ID": 12, | "message": "Sale not | d. |
5944 | "branch_ID": 2 | authorised by policy task | |
5945 | } | MorningBoozeCheck for time | |
5946 | | 08:41:06 GMT. Alcohol can | |
5947 | | not be sold between | |
5948 | | 00:00:00 GMT and 11:30:00 | |
5950 | | "notes": null, | |
5951 | | "quantity": 1, | |
5952 | | "sale_ID": 99999992, | |
5953 | | "time": 1483346466000 | |
5955 +------------------------------------------+-------------------------------------------+-----------+
5956 | .. container:: | .. container:: | Request |
5958 | .. container:: listingblock | .. container:: listingblock | alcohol |
5960 | | .. container:: content | D=1943``) |
5961 | .. container:: content | | at |
5962 | | .. code:: | *20:17:13 |
5964 | .. code:: | { | on |
5965 | | "name": "SALE_AUTH", | *Tuesday, |
5966 | { | "version": "0.0.1", | 20 |
5967 | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | December |
5968 | "name" : "SALE_INPUT", | "source": "", | 2016*. |
5969 | "version": "0.0.1", | "target": "", | |
5970 | "time" : 1482265033000, | "amount": 4799, | Sale is |
5971 | "sale_ID": 99999993, | "assistant_ID": 9, | authorize |
5972 | "amount": 4799, | "authorised": true, | d. |
5973 | "item_ID": 1943, | "branch_ID": 3, | |
5974 | "quantity": 2, | "item_ID": 1943, | |
5975 | "assistant_ID": 9, | "message": "Sale authorised | |
5976 | "branch_ID": 3 | by policy task MorningBo | |
5977 | } | ozeCheck for time 20:17:13 | |
5979 | | "notes": null, | |
5980 | | "quantity": 2, | |
5981 | | "sale_ID": 99999993, | |
5982 | | "time": 1482265033000 | |
5984 +------------------------------------------+-------------------------------------------+-----------+
5986 4.3.6. Policy 1 in CLI Editor
5987 #############################
5989 .. container:: paragraph
5991 An equivalent version of the ``MyFirstPolicyModel``
5992 policy model can again be generated using the APEX CLI
5993 editor. A sample APEX CLI script is shown below:
5995 .. container:: listingblock
5997 .. container:: title
5999 APEX CLI Editor code for Policy 1
6001 .. container:: content
6005 #-------------------------------------------------------------------------------
6006 # ============LICENSE_START=======================================================
6007 # Copyright (C) 2016-2018 Ericsson. All rights reserved.
6008 # ================================================================================
6009 # Licensed under the Apache License, Version 2.0 (the "License");
6010 # you may not use this file except in compliance with the License.
6011 # You may obtain a copy of the License at
6013 # http://www.apache.org/licenses/LICENSE-2.0
6015 # Unless required by applicable law or agreed to in writing, software
6016 # distributed under the License is distributed on an "AS IS" BASIS,
6017 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
6018 # See the License for the specific language governing permissions and
6019 # limitations under the License.
6021 # SPDX-License-Identifier: Apache-2.0
6022 # ============LICENSE_END=========================================================
6023 #-------------------------------------------------------------------------------
6025 model create name=MyFirstPolicyModel version=0.0.1 uuid=540226fb-55ee-4f0e-a444-983a0494818e description="This is my first Apex Policy Model."
6027 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
6029 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
6031 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
6033 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
6035 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
6037 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
6039 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
6041 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
6043 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
6045 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
6047 task create name=MorningBoozeCheck version=0.0.1 uuid=3351b0f4-cf06-4fa2-8823-edf67bd30223 description=LS
6048 This task checks if the sales request is for an item that contains alcohol.
6049 If the local time is between 00:00:00 and 11:30:00 then the sale is not authorised. Otherwise the sale is authorised.
6050 In this implementation we assume that all items with item_ID values between 1000 and 2000 contain alcohol :-)
6052 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
6053 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
6054 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
6055 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
6056 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
6057 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
6058 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
6059 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
6060 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
6061 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
6062 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
6063 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
6064 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
6065 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
6066 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
6067 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1
6068 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
6069 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true
6070 task logic create name=MorningBoozeCheck version=0.0.1 logicFlavour=MVEL logic=LS
6072 * ============LICENSE_START=======================================================
6073 * Copyright (C) 2016-2018 Ericsson. All rights reserved.
6074 * ================================================================================
6075 * Licensed under the Apache License, Version 2.0 (the "License");
6076 * you may not use this file except in compliance with the License.
6077 * You may obtain a copy of the License at
6079 * http://www.apache.org/licenses/LICENSE-2.0
6081 * Unless required by applicable law or agreed to in writing, software
6082 * distributed under the License is distributed on an "AS IS" BASIS,
6083 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
6084 * See the License for the specific language governing permissions and
6085 * limitations under the License.
6087 * SPDX-License-Identifier: Apache-2.0
6088 * ============LICENSE_END=========================================================
6090 import java.util.Date;
6091 import java.util.Calendar;
6092 import java.util.TimeZone;
6093 import java.text.SimpleDateFormat;
6095 logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'");
6097 outFields.put("amount" , inFields.get("amount"));
6098 outFields.put("assistant_ID", inFields.get("assistant_ID"));
6099 outFields.put("notes" , inFields.get("notes"));
6100 outFields.put("quantity" , inFields.get("quantity"));
6101 outFields.put("branch_ID" , inFields.get("branch_ID"));
6102 outFields.put("item_ID" , inFields.get("item_ID"));
6103 outFields.put("time" , inFields.get("time"));
6104 outFields.put("sale_ID" , inFields.get("sale_ID"));
6106 item_id = inFields.get("item_ID");
6108 //The events used later to test this task use GMT timezone!
6109 gmt = TimeZone.getTimeZone("GMT");
6110 timenow = Calendar.getInstance(gmt);
6111 df = new SimpleDateFormat("HH:mm:ss z");
6112 df.setTimeZone(gmt);
6113 timenow.setTimeInMillis(inFields.get("time"));
6115 midnight = timenow.clone();
6117 timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
6118 timenow.get(Calendar.DATE),0,0,0);
6119 eleven30 = timenow.clone();
6121 timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
6122 timenow.get(Calendar.DATE),11,30,0);
6124 itemisalcohol = false;
6125 if(item_id != null && item_id >=1000 && item_id < 2000)
6126 itemisalcohol = true;
6129 && timenow.after(midnight) && timenow.before(eleven30)){
6130 outFields.put("authorised", false);
6131 outFields.put("message", "Sale not authorised by policy task "+subject.taskName+
6132 " for time "+df.format(timenow.getTime())+
6133 ". Alcohol can not be sold between "+df.format(midnight.getTime())+
6134 " and "+df.format(eleven30.getTime()));
6138 outFields.put("authorised", true);
6139 outFields.put("message", "Sale authorised by policy task "+subject.taskName+
6140 " for time "+df.format(timenow.getTime()));
6145 This task checks if a sale request is for an item that is an alcoholic drink.
6146 If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not
6147 authorised. Otherwise the sale is authorised.
6148 In this implementation we assume that items with item_ID value between 1000 and
6149 2000 are all alcoholic drinks :-)
6153 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"
6154 event parameter create name=SALE_AUTH version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1
6155 event parameter create name=SALE_AUTH version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
6156 event parameter create name=SALE_AUTH version=0.0.1 parName=authorised schemaName=authorised_type schemaVersion=0.0.1
6157 event parameter create name=SALE_AUTH version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
6158 event parameter create name=SALE_AUTH version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
6159 event parameter create name=SALE_AUTH version=0.0.1 parName=message schemaName=message_type schemaVersion=0.0.1 optional=true
6160 event parameter create name=SALE_AUTH version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
6161 event parameter create name=SALE_AUTH version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1
6162 event parameter create name=SALE_AUTH version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
6163 event parameter create name=SALE_AUTH version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1
6165 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"
6166 event parameter create name=SALE_INPUT version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1
6167 event parameter create name=SALE_INPUT version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
6168 event parameter create name=SALE_INPUT version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
6169 event parameter create name=SALE_INPUT version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
6170 event parameter create name=SALE_INPUT version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
6171 event parameter create name=SALE_INPUT version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1
6172 event parameter create name=SALE_INPUT version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
6173 event parameter create name=SALE_INPUT version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1
6176 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
6177 policy state create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide triggerName=SALE_INPUT triggerVersion=0.0.1 defaultTaskName=MorningBoozeCheck defaultTaskVersion=0.0.1
6178 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
6179 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
6186 .. container:: paragraph
6188 *HyperM* have just opened a new branch in a different
6189 country, but that country has different rules about when
6190 alcohol can be sold! In this section we will go through
6191 the necessary steps to extend our policy to enforce this
6194 .. container:: ulist
6196 - In some branches alcohol cannot be sold before 1pm,
6197 and not at all on Sundays.
6199 .. container:: paragraph
6201 Although there are a number of ways to accomplish this
6202 the easiest approach for us is to define another task and
6203 then select which task is appropriate at runtime
6204 depending on the branch identifier in the incoming event.
6206 Extend the Policy with the new Scenario
6207 #######################################
6209 .. container:: paragraph
6211 To create a new Task click on the 'Tasks' tab. In the
6212 'Tasks' pane, right click and select 'Create new Task':
6214 .. container:: paragraph
6216 Create a new Task called ``MorningBoozeCheckAlt1``. Use
6217 the 'Generate UUID' button to create a new unique ID for
6218 the task, and fill in a description for the task. Select
6219 the same input and output fields that we used earlier
6220 when we defined the ``MorningBoozeCheck`` task earlier.
6222 .. table:: Table 12. Input fields for ``MorningBoozeCheckAlt1`` task
6224 +-----------------------------------+-----------------------------------+
6225 | Parameter Name | Parameter Type |
6226 +===================================+===================================+
6227 | time | timestamp_type |
6228 +-----------------------------------+-----------------------------------+
6229 | sale_ID | sale_ID_type |
6230 +-----------------------------------+-----------------------------------+
6231 | amount | price_type |
6232 +-----------------------------------+-----------------------------------+
6233 | item_ID | item_ID_type |
6234 +-----------------------------------+-----------------------------------+
6235 | quantity | quantity_type |
6236 +-----------------------------------+-----------------------------------+
6237 | assistant_ID | assistant_ID_type |
6238 +-----------------------------------+-----------------------------------+
6239 | branch_ID | branch_ID_type |
6240 +-----------------------------------+-----------------------------------+
6241 | notes | notes_type |
6242 +-----------------------------------+-----------------------------------+
6244 .. table:: Table 13. Output fields for ``MorningBoozeCheckAlt1`` task
6246 +-----------------------------------+-----------------------------------+
6247 | Parameter Name | Parameter Type |
6248 +===================================+===================================+
6249 | sale_ID | sale_ID_type |
6250 +-----------------------------------+-----------------------------------+
6251 | time | timestamp_type |
6252 +-----------------------------------+-----------------------------------+
6253 | authorised | authorised_type |
6254 +-----------------------------------+-----------------------------------+
6255 | message | message_type |
6256 +-----------------------------------+-----------------------------------+
6257 | amount | price_type |
6258 +-----------------------------------+-----------------------------------+
6259 | item_ID | item_ID_type |
6260 +-----------------------------------+-----------------------------------+
6261 | assistant_ID | assistant_ID_type |
6262 +-----------------------------------+-----------------------------------+
6263 | quantity | quantity_type |
6264 +-----------------------------------+-----------------------------------+
6265 | branch_ID | branch_ID_type |
6266 +-----------------------------------+-----------------------------------+
6267 | notes | notes_type |
6268 +-----------------------------------+-----------------------------------+
6270 .. container:: paragraph
6272 This task also requires some 'Task Logic' to implement
6273 the new behaviour for this task.
6275 .. container:: paragraph
6277 For simplicity use the following code for the task logic.
6278 It again assumes that all items with ``item_ID`` between
6279 1000 and 2000 contain alcohol. We again use the standard
6280 ``Java`` time utilities to check if the current time is
6281 between ``00:00:00 CET`` and ``13:00:00 CET`` or if it is
6284 .. container:: paragraph
6286 For this task we will again author the logic using the
6287 ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__
6288 scripting language. Sample task logic code (specified in
6289 ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__) is
6290 given below. For a detailed guide to how to write your
6292 ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__,
6293 ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__ or one
6294 of the other supported languages please refer to APEX
6297 .. container:: listingblock
6299 .. container:: title
6301 MVEL code for the ``MorningBoozeCheckAlt1`` task
6303 .. container:: content
6308 * ============LICENSE_START=======================================================
6309 * Copyright (C) 2016-2018 Ericsson. All rights reserved.
6310 * ================================================================================
6311 * Licensed under the Apache License, Version 2.0 (the "License");
6312 * you may not use this file except in compliance with the License.
6313 * You may obtain a copy of the License at
6315 * http://www.apache.org/licenses/LICENSE-2.0
6317 * Unless required by applicable law or agreed to in writing, software
6318 * distributed under the License is distributed on an "AS IS" BASIS,
6319 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
6320 * See the License for the specific language governing permissions and
6321 * limitations under the License.
6323 * SPDX-License-Identifier: Apache-2.0
6324 * ============LICENSE_END=========================================================
6326 import java.util.Date;
6327 import java.util.Calendar;
6328 import java.util.TimeZone;
6329 import java.text.SimpleDateFormat;
6331 logger.info("Task Execution: '"+subject.id+"'. Input Event: '"+inFields+"'");
6333 outFields.put("amount" , inFields.get("amount"));
6334 outFields.put("assistant_ID", inFields.get("assistant_ID"));
6335 outFields.put("notes" , inFields.get("notes"));
6336 outFields.put("quantity" , inFields.get("quantity"));
6337 outFields.put("branch_ID" , inFields.get("branch_ID"));
6338 outFields.put("item_ID" , inFields.get("item_ID"));
6339 outFields.put("time" , inFields.get("time"));
6340 outFields.put("sale_ID" , inFields.get("sale_ID"));
6342 item_id = inFields.get("item_ID");
6344 //The events used later to test this task use CET timezone!
6345 cet = TimeZone.getTimeZone("CET");
6346 timenow = Calendar.getInstance(cet);
6347 df = new SimpleDateFormat("HH:mm:ss z");
6348 df.setTimeZone(cet);
6349 timenow.setTimeInMillis(inFields.get("time"));
6351 midnight = timenow.clone();
6353 timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
6354 timenow.get(Calendar.DATE),0,0,0);
6355 onepm = timenow.clone();
6357 timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
6358 timenow.get(Calendar.DATE),13,0,0);
6360 itemisalcohol = false;
6361 if(item_id != null && item_id >=1000 && item_id < 2000)
6362 itemisalcohol = true;
6364 if( itemisalcohol &&
6365 ( (timenow.after(midnight) && timenow.before(onepm))
6367 (timenow.get(Calendar.DAY_OF_WEEK) == Calendar.SUNDAY)
6369 outFields.put("authorised", false);
6370 outFields.put("message", "Sale not authorised by policy task "+subject.taskName+
6371 " for time "+df.format(timenow.getTime())+
6372 ". Alcohol can not be sold between "+df.format(midnight.getTime())+
6373 " and "+df.format(onepm.getTime()) +" or on Sunday");
6377 outFields.put("authorised", true);
6378 outFields.put("message", "Sale authorised by policy task "+subject.taskName+
6379 " for time "+df.format(timenow.getTime()));
6384 This task checks if a sale request is for an item that is an alcoholic drink.
6385 If the local time is between 00:00:00 CET and 13:00:00 CET then the sale is not authorised.
6386 Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised.
6387 In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks :-)
6390 .. container:: imageblock
6392 .. container:: content
6394 |Create a new alternative task MorningBoozeCheckAlt1|
6396 .. container:: title
6398 Figure 19. Create a new Task
6400 .. container:: paragraph
6402 The task definition is now complete so click the 'Submit'
6403 button to save the task. Now that we have created our
6404 task, we can can add this task to the single pre-existing
6405 state (``BoozeAuthDecide``) in our policy.
6407 .. container:: paragraph
6409 To edit the ``BoozeAuthDecide`` state in our policy click
6410 on the 'Policies' tab. In the 'Policies' pane, right
6411 click on our ``MyFirstPolicy`` policy and select 'Edit'.
6412 Navigate to the ``BoozeAuthDecide`` state in the 'states'
6413 section at the bottom of the policy definition pane.
6415 .. container:: imageblock
6417 .. container:: content
6419 |Right click to edit a policy|
6421 .. container:: title
6423 Figure 20. Edit a Policy
6425 .. container:: paragraph
6427 To add our new task ``MorningBoozeCheckAlt1``, scroll
6428 down to the ``BoozeAuthDecide`` state in the 'States'
6429 section. In the 'State Tasks' section for
6430 ``BoozeAuthDecide`` use the 'Add new task' button. Select
6431 our new ``MorningBoozeCheckAlt1`` task, and use the name
6432 of the task as the 'Local Name' for the task. The
6433 ``MorningBoozeCheckAlt1`` task can reuse the same
6434 ``MorningBoozeCheck_Output_Direct`` 'Direct State Output
6435 Mapping' that we used for the ``MorningBoozeCheck`` task.
6436 (Recall that the role of the 'State Output Mapping' is to
6437 select the output event for the state, and select the
6438 next state to be executed. These both remain the same as
6441 .. container:: paragraph
6443 Since our state has more than one task we must define
6444 some logic to determine which task should be used each
6445 time the state is executed. This *task selection logic*
6446 is defined in the state definition. For our
6447 ``BoozeAuthDecide`` state we want the choice of which
6448 task to use to be based on the ``branch_ID`` from which
6449 the ``SALE_INPUT`` event originated. For simplicity sake
6450 let us assume that branches with ``branch_ID`` between
6451 ``0`` and ``999`` should use the ``MorningBoozeCheck``
6452 task, and the branches with with ``branch_ID`` between
6453 ``1000`` and ``1999`` should use the
6454 ``MorningBoozeCheckAlt1`` task.
6456 .. container:: paragraph
6458 This time, for variety, we will author the task selection
6460 ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__
6461 scripting language. Sample task selection logic code
6463 ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__)
6464 is given below. Paste the script text into the 'Task
6465 Selection Logic' box, and use "JAVASCRIPT" as the 'Task
6466 Selection Logic Type / Flavour'. It is necessary to mark
6467 one of the tasks as the 'Default Task' so that the task
6468 selection logic always has a fallback default option in
6469 cases where a particular task cannot be selected. In this
6470 case the ``MorningBoozeCheck`` task can be the default
6473 .. container:: listingblock
6475 .. container:: title
6477 JavaScript code for the ``BoozeAuthDecide`` task
6480 .. container:: content
6485 * ============LICENSE_START=======================================================
6486 * Copyright (C) 2016-2018 Ericsson. All rights reserved.
6487 * ================================================================================
6488 * Licensed under the Apache License, Version 2.0 (the "License");
6489 * you may not use this file except in compliance with the License.
6490 * You may obtain a copy of the License at
6492 * http://www.apache.org/licenses/LICENSE-2.0
6494 * Unless required by applicable law or agreed to in writing, software
6495 * distributed under the License is distributed on an "AS IS" BASIS,
6496 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
6497 * See the License for the specific language governing permissions and
6498 * limitations under the License.
6500 * SPDX-License-Identifier: Apache-2.0
6501 * ============LICENSE_END=========================================================
6505 var returnValueType = Java.type("java.lang.Boolean");
6506 var returnValue = new returnValueType(true);
6508 executor.logger.info("Task Selection Execution: '"+executor.subject.id+
6509 "'. Input Event: '"+executor.inFields+"'");
6511 branchid = executor.inFields.get("branch_ID");
6512 taskorig = executor.subject.getTaskKey("MorningBoozeCheck");
6513 taskalt = executor.subject.getTaskKey("MorningBoozeCheckAlt1");
6514 taskdef = executor.subject.getDefaultTaskKey();
6516 if(branchid >=0 && branchid <1000){
6517 taskorig.copyTo(executor.selectedTask);
6519 else if (branchid >=1000 && branchid <2000){
6520 taskalt.copyTo(executor.selectedTask);
6523 taskdef.copyTo(executor.selectedTask);
6527 This task selection logic selects task "MorningBoozeCheck" for branches with
6528 0<=branch_ID<1000 and selects task "MorningBoozeCheckAlt1" for branches with
6529 1000<=branch_ID<2000. Otherwise the default task is selected.
6530 In this case the default task is also "MorningBoozeCheck"
6533 .. container:: imageblock
6535 .. container:: content
6537 |State definition with 2 Tasks and Task Selection
6540 .. container:: title
6542 Figure 21. State definition with 2 Tasks and Task
6545 .. container:: paragraph
6547 When complete don’t forget to click the 'Submit' button
6548 at the bottom of 'Policies' pane for our
6549 ``MyFirstPolicy`` policy after updating the
6550 ``BoozeAuthDecide`` state.
6552 .. container:: paragraph
6554 Congratulations, you have now completed the second step
6555 towards your first APEX policy. The policy model
6556 containing our new policy can again be validated and
6557 exported from the editor and saved as shown in Step 1.
6559 .. container:: paragraph
6561 The exported policy model is then available in the
6562 directory you selected, as
6563 `MyFirstPolicyModel_0.0.1.json <files/mfp-files/2/MyFirstPolicyModel_0.0.1.json>`__.
6564 The exported policy can now be loaded into the APEX
6565 Policy Engine, or can be re-loaded and edited by the APEX
6571 .. container:: paragraph
6573 To start a new APEX Engine you can use the following
6574 configuration. In a full APEX installation you can find
6575 this configuration in
6576 ``$APEX_HOME/examples/config/MyFirstPolicy/2/MyFirstPolicyConfigStdin2StdoutJsonEvent.json``.
6577 Note, this has changed from the configuration file in
6578 Step 1 to enable the ``JAVASCRIPT`` executor for our new
6579 'Task Selection Logic'.
6581 .. container:: listingblock
6583 .. container:: title
6585 JSON to load and execute *My First Policy*, read input
6586 JSON events from ``stdin``, and emit output events to
6589 .. container:: content
6594 "engineServiceParameters" : {
6595 "name" : "MyFirstPolicyApexEngine",
6596 "version" : "0.0.1",
6598 "instanceCount" : 4,
6599 "deploymentPort" : 12345,
6600 "policyModelFileName" : "examples/models/MyFirstPolicy/2/MyFirstPolicyModel_0.0.1.json",
6601 "engineParameters" : {
6602 "executorParameters" : {
6604 "parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
6607 "parameterClassName" : "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"
6612 "eventOutputParameters": {
6614 "carrierTechnologyParameters" : {
6615 "carrierTechnology" : "FILE",
6620 "eventProtocolParameters" : {
6621 "eventProtocol" : "JSON"
6625 "eventInputParameters": {
6627 "carrierTechnologyParameters" : {
6628 "carrierTechnology" : "FILE",
6633 "eventProtocolParameters" : {
6634 "eventProtocol" : "JSON"
6640 .. container:: paragraph
6642 To test the policy try paste the following events into
6643 the console as the APEX engine executes. Note, all tests
6644 from Step 1 will still work perfectly since none of those
6645 events originate from a branch with ``branch_ID`` between
6646 ``1000`` and ``2000``. The 'Task Selection Logic' will
6647 therefore pick the ``MorningBoozeCheck`` task as
6648 expected, and will therefore give the same results.
6650 .. table:: Table 14. Inputs and Outputs when testing *My First Policy*
6652 +----------------------------------------------+------------------------------------------------------------+---------------------------+
6653 | Input Event (JSON) | Output Event (JSON) | comment |
6654 +==============================================+============================================================+===========================+
6655 | .. container:: | .. container:: | Request to buy |
6656 | | | alcohol item |
6657 | .. container:: listingblock | .. container:: listingblock | (``item_ID=1249``) |
6659 | | | at *08:41:06 |
6660 | | .. container:: content | GMT* on *Monday, |
6661 | .. container:: content | | 02 January |
6662 | | .. code:: | 2017*. |
6664 | | { | Sale is not |
6665 | .. code:: | "nameSpace": "com.hyperm", | authorized. Uses |
6666 | | "name": "SALE_AUTH", | the |
6667 | | "version": "0.0.1", | ``MorningBoozeCheck`` |
6668 | { | "source": "", | |
6669 | "nameSpace": "com.hyperm", | "target": "", | task. |
6670 | "name": "SALE_INPUT", | "amount": 1249, | |
6671 | "version": "0.0.1", | "assistant_ID":12, | Note this test |
6672 | "time": 1483346466000, | "authorised": false, | is copied from |
6673 | "sale_ID": 99999992, | "branch_ID": 2, | Step 1 above, |
6674 | "amount": 1249, | "item_ID": 1012, | and demonstrates |
6675 | "item_ID": 1012, | "message": "Sale not authorised by policy ta | that the |
6676 | "quantity": 1, | sk MorningBoozeCheck for time 08:41:06 GMT.| original |
6677 | "assistant_ID": 12, | Alcohol can not be sold between 00:00:00 | ``MorningBoozeCheck`` |
6678 | "branch_ID": 2 | GMT and 11:30:00 GMT", | |
6679 | } | "notes": null, | task is |
6680 | | "quantity": 1, | executed. |
6681 | | "sale_ID": 99999992, | |
6682 | | "time": 1483346466000 | |
6684 +----------------------------------------------+------------------------------------------------------------+---------------------------+
6685 | .. container:: | .. container:: | Request to buy |
6687 | .. container:: listingblock | .. container:: listingblock | (``item_ID=1047``) |
6689 | | | at *10:14:33* on |
6690 | | .. container:: content | *Thursday, 22 |
6691 | .. container:: content | | December 2016*. |
6694 | | { | authorized. Uses |
6695 | .. code:: | "nameSpace" : "com.hyperm", | the |
6696 | | "name" : "SALE_AUTH", | ``MorningBoozeCheckAlt1`` |
6697 | | "version" : "0.0.1", | task. |
6698 | { | "source" : "", | |
6699 | | "target" : "", | |
6700 | "nameSpace": "com.hyperm", | "sale_ID" : 99999981, | |
6701 | "name": "SALE_INPUT", | "amount" : 299, | |
6702 | "version": "0.0.1", | "assistant_ID": 1212, | |
6703 | "time": 1482398073000, | "notes" : null, | |
6704 | "sale_ID": 99999981, | "quantity" : 1, | |
6705 | "amount": 299, | "branch_ID" : 1002, | |
6706 | "item_ID": 1047, | "item_ID" : 1047, | |
6707 | "quantity": 1, | "authorised" : false, | |
6708 | "assistant_ID": 1212, | "time" : 1482398073000, | |
6709 | "branch_ID": 1002 | "message" : "Sale not authorised by policy t | |
6710 | } | ask MorningBoozeCheckAlt1 fortime | |
6711 | | 10:14:33 CET. Alcohol can not be sold | |
6712 | | between 00:00:00 CET and 13:00:00 CET or on | |
6715 +----------------------------------------------+------------------------------------------------------------+---------------------------+
6716 | .. container:: | .. container:: | Request to buy |
6718 | .. container:: listingblock | .. container:: listingblock | (``item_ID=1443``) |
6720 | | | at *17:19:37* on |
6721 | | .. container:: content | *Sunday, 18 |
6722 | .. container:: content | | December 2016*. |
6725 | | { | authorized. Uses |
6726 | .. code:: | "nameSpace" : "com.hyperm", | the |
6727 | | | ``MorningBoozeCheckAlt1`` |
6728 | | "name" : "SALE_AUTH", | task. |
6730 | "nameSpace": "com.hyperm", | "version" : "0.0.1", | |
6731 | "name": "SALE_INPUT", | "source" : "", | |
6732 | "version": "0.0.1", | "target" : "", | |
6733 | "time": 1482077977000, | "sale_ID" : 99999982, | |
6734 | "sale_ID": 99999982, | "amount" : 2199, | |
6735 | "amount": 2199, | "assistant_ID" : 94, | |
6736 | "item_ID": 1443, | "notes" : "Buy 3, get 1 free!!", | |
6737 | "quantity": 12, | "quantity" : 12, | |
6738 | "assistant_ID": 94, | "branch_ID" : 1003, | |
6739 | "branch_ID": 1003, | "item_ID" : 1443, | |
6740 | "notes": "Buy 3, get 1 free!!" | "authorised" : false, | |
6741 | } | "time" : 1482077977000, | |
6742 | | "message" : "Sale not authorised by policy t | |
6743 | | ask MorningBoozeCheckAlt1 for | |
6744 | | time 17:19:37 CET. Alcohol c | |
6745 | | an not be sold between 00:00: | |
6746 | | 00 CET and 13:00:00 CET or on | |
6748 +----------------------------------------------+------------------------------------------------------------+---------------------------+
6749 | .. container:: | .. container:: | Request to buy |
6750 | | | non-alcoholic |
6751 | .. container:: listingblock | .. container:: listingblock | item |
6752 | | | (``item_ID=5321``) |
6754 | | .. container:: content | at *11:13:09* on |
6755 | .. container:: content | | *Monday, 2 |
6756 | | .. code:: | January 2017*. |
6759 | .. code:: | "nameSpace" : "com.hyperm", | authorized. Uses |
6760 | | "name" : "SALE_AUTH", | the |
6761 | { | "version" : "0.0.1", | ``MorningBoozeCheckAlt1`` |
6762 | "nameSpace": "com.hyperm", | "source" : "", | task. |
6763 | "name": "SALE_INPUT", | "target" : "", | |
6764 | "version": "0.0.1", | "sale_ID" : 99999983, | |
6765 | "time": 1483351989000, | "amount" : 699, | |
6766 | "sale_ID": 99999983, | "assistant_ID" : 2323, | |
6767 | "amount": 699, | "notes" : "", | |
6768 | "item_ID": 5321, | "quantity" : 1, | |
6769 | "quantity": 1, | "branch_ID" : 1001, | |
6770 | "assistant_ID": 2323, | "item_ID" : 5321, | |
6771 | "branch_ID": 1001, | "authorised" : true, | |
6772 | "notes": "" | "time" : 1483351989000, | |
6773 | } | "message" : "Sale authorised by policy task | |
6774 | | MorningBoozeCheckAlt1 for time 11:13:09 CET"| |
6776 +----------------------------------------------+------------------------------------------------------------+---------------------------+
6778 Policy 2 in CLI Editor
6779 ######################
6781 .. container:: paragraph
6783 An equivalent version of the ``MyFirstPolicyModel``
6784 policy model can again be generated using the APEX CLI
6785 editor. A sample APEX CLI script is shown below:
6787 .. container:: listingblock
6789 .. container:: title
6791 APEX CLI Editor code for Policy 2
6793 .. container:: content
6797 #-------------------------------------------------------------------------------
6798 # ============LICENSE_START=======================================================
6799 # Copyright (C) 2016-2018 Ericsson. All rights reserved.
6800 # ================================================================================
6801 # Licensed under the Apache License, Version 2.0 (the "License");
6802 # you may not use this file except in compliance with the License.
6803 # You may obtain a copy of the License at
6805 # http://www.apache.org/licenses/LICENSE-2.0
6807 # Unless required by applicable law or agreed to in writing, software
6808 # distributed under the License is distributed on an "AS IS" BASIS,
6809 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
6810 # See the License for the specific language governing permissions and
6811 # limitations under the License.
6813 # SPDX-License-Identifier: Apache-2.0
6814 # ============LICENSE_END=========================================================
6815 #-------------------------------------------------------------------------------
6817 model create name=MyFirstPolicyModel version=0.0.1 uuid=540226fb-55ee-4f0e-a444-983a0494818e description="This is my first Apex Policy Model."
6819 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
6821 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
6823 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
6825 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
6827 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
6829 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
6831 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
6833 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
6835 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
6837 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
6839 task create name=MorningBoozeCheck version=0.0.1 uuid=3351b0f4-cf06-4fa2-8823-edf67bd30223 description=LS
6840 This task checks if the sales request is for an item that contains alcohol.
6841 If the local time is between 00:00:00 and 11:30:00 then the sale is not authorised. Otherwise the sale is authorised.
6842 In this implementation we assume that all items with item_ID values between 1000 and 2000 contain alcohol :-)
6844 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
6845 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
6846 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
6847 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
6848 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
6849 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
6850 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
6851 task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
6852 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
6853 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
6854 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
6855 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
6856 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
6857 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
6858 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
6859 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1
6860 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
6861 task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true
6862 task logic create name=MorningBoozeCheck version=0.0.1 logicFlavour=MVEL logic=LS
6864 * ============LICENSE_START=======================================================
6865 * Copyright (C) 2016-2018 Ericsson. All rights reserved.
6866 * ================================================================================
6867 * Licensed under the Apache License, Version 2.0 (the "License");
6868 * you may not use this file except in compliance with the License.
6869 * You may obtain a copy of the License at
6871 * http://www.apache.org/licenses/LICENSE-2.0
6873 * Unless required by applicable law or agreed to in writing, software
6874 * distributed under the License is distributed on an "AS IS" BASIS,
6875 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
6876 * See the License for the specific language governing permissions and
6877 * limitations under the License.
6879 * SPDX-License-Identifier: Apache-2.0
6880 * ============LICENSE_END=========================================================
6882 import java.util.Date;
6883 import java.util.Calendar;
6884 import java.util.TimeZone;
6885 import java.text.SimpleDateFormat;
6887 logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'");
6889 outFields.put("amount" , inFields.get("amount"));
6890 outFields.put("assistant_ID", inFields.get("assistant_ID"));
6891 outFields.put("notes" , inFields.get("notes"));
6892 outFields.put("quantity" , inFields.get("quantity"));
6893 outFields.put("branch_ID" , inFields.get("branch_ID"));
6894 outFields.put("item_ID" , inFields.get("item_ID"));
6895 outFields.put("time" , inFields.get("time"));
6896 outFields.put("sale_ID" , inFields.get("sale_ID"));
6898 item_id = inFields.get("item_ID");
6900 //The events used later to test this task use GMT timezone!
6901 gmt = TimeZone.getTimeZone("GMT");
6902 timenow = Calendar.getInstance(gmt);
6903 df = new SimpleDateFormat("HH:mm:ss z");
6904 df.setTimeZone(gmt);
6905 timenow.setTimeInMillis(inFields.get("time"));
6907 midnight = timenow.clone();
6909 timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
6910 timenow.get(Calendar.DATE),0,0,0);
6911 eleven30 = timenow.clone();
6913 timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
6914 timenow.get(Calendar.DATE),11,30,0);
6916 itemisalcohol = false;
6917 if(item_id != null && item_id >=1000 && item_id < 2000)
6918 itemisalcohol = true;
6921 && timenow.after(midnight) && timenow.before(eleven30)){
6922 outFields.put("authorised", false);
6923 outFields.put("message", "Sale not authorised by policy task "+subject.taskName+
6924 " for time "+df.format(timenow.getTime())+
6925 ". Alcohol can not be sold between "+df.format(midnight.getTime())+
6926 " and "+df.format(eleven30.getTime()));
6930 outFields.put("authorised", true);
6931 outFields.put("message", "Sale authorised by policy task "+subject.taskName+
6932 " for time "+df.format(timenow.getTime()));
6937 This task checks if a sale request is for an item that is an alcoholic drink.
6938 If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not
6939 authorised. Otherwise the sale is authorised.
6940 In this implementation we assume that items with item_ID value between 1000 and
6941 2000 are all alcoholic drinks :-)
6945 task create name=MorningBoozeCheckAlt1 version=0.0.1 uuid=bc6d90c9-c902-4686-afd3-925b30e39990 description=LS
6946 This task checks if a sale request is for an item that is an alcoholic drink.
6947 If the local time is between 00:00:00 CET and 13:00:00 CET then the sale is not authorised.
6948 Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised.
6949 In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks
6951 task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
6952 task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
6953 task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
6954 task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
6955 task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
6956 task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
6957 task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
6958 task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
6959 task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
6960 task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
6961 task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
6962 task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
6963 task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
6964 task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
6965 task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
6966 task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1
6967 task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
6968 task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true
6969 task logic create name=MorningBoozeCheckAlt1 version=0.0.1 logicFlavour=MVEL logic=LS
6971 * ============LICENSE_START=======================================================
6972 * Copyright (C) 2016-2018 Ericsson. All rights reserved.
6973 * ================================================================================
6974 * Licensed under the Apache License, Version 2.0 (the "License");
6975 * you may not use this file except in compliance with the License.
6976 * You may obtain a copy of the License at
6978 * http://www.apache.org/licenses/LICENSE-2.0
6980 * Unless required by applicable law or agreed to in writing, software
6981 * distributed under the License is distributed on an "AS IS" BASIS,
6982 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
6983 * See the License for the specific language governing permissions and
6984 * limitations under the License.
6986 * SPDX-License-Identifier: Apache-2.0
6987 * ============LICENSE_END=========================================================
6989 import java.util.Date;
6990 import java.util.Calendar;
6991 import java.util.TimeZone;
6992 import java.text.SimpleDateFormat;
6994 logger.info("Task Execution: '"+subject.id+"'. Input Event: '"+inFields+"'");
6996 outFields.put("amount" , inFields.get("amount"));
6997 outFields.put("assistant_ID", inFields.get("assistant_ID"));
6998 outFields.put("notes" , inFields.get("notes"));
6999 outFields.put("quantity" , inFields.get("quantity"));
7000 outFields.put("branch_ID" , inFields.get("branch_ID"));
7001 outFields.put("item_ID" , inFields.get("item_ID"));
7002 outFields.put("time" , inFields.get("time"));
7003 outFields.put("sale_ID" , inFields.get("sale_ID"));
7005 item_id = inFields.get("item_ID");
7007 //The events used later to test this task use CET timezone!
7008 cet = TimeZone.getTimeZone("CET");
7009 timenow = Calendar.getInstance(cet);
7010 df = new SimpleDateFormat("HH:mm:ss z");
7011 df.setTimeZone(cet);
7012 timenow.setTimeInMillis(inFields.get("time"));
7014 midnight = timenow.clone();
7016 timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
7017 timenow.get(Calendar.DATE),0,0,0);
7018 onepm = timenow.clone();
7020 timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
7021 timenow.get(Calendar.DATE),13,0,0);
7023 itemisalcohol = false;
7024 if(item_id != null && item_id >=1000 && item_id < 2000)
7025 itemisalcohol = true;
7027 if( itemisalcohol &&
7028 ( (timenow.after(midnight) && timenow.before(onepm))
7030 (timenow.get(Calendar.DAY_OF_WEEK) == Calendar.SUNDAY)
7032 outFields.put("authorised", false);
7033 outFields.put("message", "Sale not authorised by policy task "+subject.taskName+
7034 " for time "+df.format(timenow.getTime())+
7035 ". Alcohol can not be sold between "+df.format(midnight.getTime())+
7036 " and "+df.format(onepm.getTime()) +" or on Sunday");
7040 outFields.put("authorised", true);
7041 outFields.put("message", "Sale authorised by policy task "+subject.taskName+
7042 " for time "+df.format(timenow.getTime()));
7047 This task checks if a sale request is for an item that is an alcoholic drink.
7048 If the local time is between 00:00:00 CET and 13:00:00 CET then the sale is not authorised.
7049 Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised.
7050 In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks :-)
7054 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"
7055 event parameter create name=SALE_AUTH version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1
7056 event parameter create name=SALE_AUTH version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
7057 event parameter create name=SALE_AUTH version=0.0.1 parName=authorised schemaName=authorised_type schemaVersion=0.0.1
7058 event parameter create name=SALE_AUTH version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
7059 event parameter create name=SALE_AUTH version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
7060 event parameter create name=SALE_AUTH version=0.0.1 parName=message schemaName=message_type schemaVersion=0.0.1 optional=true
7061 event parameter create name=SALE_AUTH version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
7062 event parameter create name=SALE_AUTH version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1
7063 event parameter create name=SALE_AUTH version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
7064 event parameter create name=SALE_AUTH version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1
7066 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"
7067 event parameter create name=SALE_INPUT version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1
7068 event parameter create name=SALE_INPUT version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
7069 event parameter create name=SALE_INPUT version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
7070 event parameter create name=SALE_INPUT version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
7071 event parameter create name=SALE_INPUT version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
7072 event parameter create name=SALE_INPUT version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1
7073 event parameter create name=SALE_INPUT version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
7074 event parameter create name=SALE_INPUT version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1
7077 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
7078 policy state create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide triggerName=SALE_INPUT triggerVersion=0.0.1 defaultTaskName=MorningBoozeCheck defaultTaskVersion=0.0.1
7079 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
7080 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
7081 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
7082 policy state selecttasklogic create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide logicFlavour=JAVASCRIPT logic=LS
7084 * ============LICENSE_START=======================================================
7085 * Copyright (C) 2016-2018 Ericsson. All rights reserved.
7086 * ================================================================================
7087 * Licensed under the Apache License, Version 2.0 (the "License");
7088 * you may not use this file except in compliance with the License.
7089 * You may obtain a copy of the License at
7091 * http://www.apache.org/licenses/LICENSE-2.0
7093 * Unless required by applicable law or agreed to in writing, software
7094 * distributed under the License is distributed on an "AS IS" BASIS,
7095 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
7096 * See the License for the specific language governing permissions and
7097 * limitations under the License.
7099 * SPDX-License-Identifier: Apache-2.0
7100 * ============LICENSE_END=========================================================
7103 var returnValueType = Java.type("java.lang.Boolean");
7104 var returnValue = new returnValueType(true);
7106 executor.logger.info("Task Selection Execution: '"+executor.subject.id+"'. Input Event: '"+executor.inFields+"'");
7108 branchid = executor.inFields.get("branch_ID");
7109 taskorig = executor.subject.getTaskKey("MorningBoozeCheck");
7110 taskalt = executor.subject.getTaskKey("MorningBoozeCheckAlt1");
7111 taskdef = executor.subject.getDefaultTaskKey();
7113 if(branchid >=0 && branchid <1000){
7114 taskorig.copyTo(executor.selectedTask);
7116 else if (branchid >=1000 && branchid <2000){
7117 taskalt.copyTo(executor.selectedTask);
7120 taskdef.copyTo(executor.selectedTask);
7124 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"
7131 Introduction to APEX Logging
7132 ----------------------------
7134 .. container:: paragraph
7136 All APEX components make extensive use of logging using the
7137 logging façade `SLF4J <https://www.slf4j.org/>`__ with the
7138 backend `Logback <https://logback.qos.ch/>`__. Both are used
7139 off-the-shelve, so the standard documentation and
7140 configuration apply to APEX logging. For details on how to
7141 work with logback please see the `logback
7142 manual <https://logback.qos.ch/manual/index.html>`__.
7144 .. container:: paragraph
7146 The APEX applications is the logback configuration file
7147 ``$APEX_HOME/etc/logback.xml`` (Windows:
7148 ``%APEX_HOME%\etc\logback.xml``). The logging backend is set
7149 to no debug, i.e. logs from the logging framework should be
7152 .. container:: paragraph
7154 The configurable log levels work as expected:
7156 .. container:: ulist
7158 - *error* (or *ERROR*) is used for serious errors in the
7161 - *warn* (or *WARN*) is used for warnings, which in general
7162 can be ignored but might indicate some deeper problems
7164 - *info* (or *INFO*) is used to provide generally
7165 interesting messages for startup and policy execution
7167 - *debug* (or *DEBUG*) provides more details on startup and
7170 - *trace* (or *TRACE*) gives full details on every aspect
7171 of the APEX engine from start to end
7173 .. container:: paragraph
7175 The loggers can also be configured as expected. The standard
7176 configuration (after installing APEX) uses log level *info*
7177 on all APEX classes (components).
7179 .. container:: paragraph
7181 The applications and scripts in ``$APEX_HOME/bin`` (Windows:
7182 ``%APEX_HOME\bin``) are configured to use the logback
7183 configuration ``$APEX_HOME/etc/logback.xml`` (Windows:
7184 ``%APEX_HOME\etc\logback.xml``). There are multiple ways to
7185 use different logback configurations, for instance:
7187 .. container:: ulist
7189 - Maintain multiple configurations in ``etc``, for instance
7190 a ``logback-debug.xml`` for deep debugging and a
7191 ``logback-production.xml`` for APEX in production mode,
7192 then copy the required configuration file to the used
7193 ``logback.xml`` prior starting APEX
7195 - Edit the scripts in ``bin`` to use a different logback
7196 configuration file (only recommended if you are familiar
7197 with editing bash scripts or windows batch files)
7199 Standard Logging Configuration
7200 ------------------------------
7202 .. container:: paragraph
7204 The standard logging configuration defines a context *APEX*,
7205 which is used in the standard output pattern. The location
7206 for log files is defined in the property ``logDir`` and set
7207 to ``/var/log/onap/policy/apex-pdp``. The standard status
7208 listener is set to *NOP* and the overall logback
7209 configuration is set to no debug.
7211 .. container:: listingblock
7213 .. container:: content
7218 <configuration debug="false">
7219 <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
7221 <contextName>Apex</contextName>
7222 <property name="logDir" value="/var/log/onap/policy/apex-pdp/" />
7228 .. container:: paragraph
7230 The first appender defined is called ``STDOUT`` for logs to standard
7233 .. container:: listingblock
7235 .. container:: content
7240 <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
7242 <Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern>
7246 .. container:: paragraph
7248 The root level logger then is set to the level *info* using the
7249 standard out appender.
7251 .. container:: listingblock
7253 .. container:: content
7259 <appender-ref ref="STDOUT" />
7262 .. container:: paragraph
7264 The second appender is called ``FILE``. It writes logs to a file
7267 .. container:: listingblock
7269 .. container:: content
7274 <appender name="FILE" class="ch.qos.logback.core.FileAppender">
7275 <file>${logDir}/apex.log</file>
7277 <pattern>%d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full}</pattern>
7281 .. container:: paragraph
7283 The third appender is called ``CTXT_FILE``. It writes logs to a file
7286 .. container:: listingblock
7288 .. container:: content
7293 <appender name="CTXT_FILE" class="ch.qos.logback.core.FileAppender">
7294 <file>${logDir}/apex_ctxt.log</file>
7296 <pattern>%d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full}</pattern>
7300 .. container:: paragraph
7302 The last definitions are for specific loggers. The first logger
7303 captures all standard APEX classes. It is configured for log level
7304 *info* and uses the standard output and file appenders. The second
7305 logger captures APEX context classes responsible for context
7306 monitoring. It is configured for log level *trace* and uses the
7307 context file appender.
7309 .. container:: listingblock
7311 .. container:: content
7317 <logger name="org.onap.policy.apex" level="info" additivity="false">
7318 <appender-ref ref="STDOUT" />
7319 <appender-ref ref="FILE" />
7322 <logger name="org.onap.policy.apex.core.context.monitoring" level="TRACE" additivity="false">
7323 <appender-ref ref="CTXT_FILE" />
7326 Adding Logback Status and Debug
7327 -------------------------------
7329 .. container:: paragraph
7331 To activate logback status messages change the status listener
7332 from 'NOP' to for instance console.
7334 .. container:: listingblock
7336 .. container:: content
7340 <statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener" />
7342 .. container:: paragraph
7344 To activate all logback debugging, for instance to debug a new
7345 logback configuration, activate the debug attribute in the
7348 .. container:: listingblock
7350 .. container:: content
7354 <configuration debug="true">
7358 Logging External Components
7359 ---------------------------
7361 .. container:: paragraph
7363 Logback can also be configured to log any other, external
7364 components APEX is using, if they are using the common logging
7367 .. container:: paragraph
7369 For instance, the context component of APEX is using *Infinispan*
7370 and one can add a logger for this external component. The
7371 following example adds a logger for *Infinispan* using the
7372 standard output appender.
7374 .. container:: listingblock
7376 .. container:: content
7380 <logger name="org.infinispan" level="INFO" additivity="false">
7381 <appender-ref ref="STDOUT" />
7384 .. container:: paragraph
7386 Another example is Apache Zookeeper. The following example adds a
7387 logger for Zookeeper using the standard outout appender.
7389 .. container:: listingblock
7391 .. container:: content
7395 <logger name="org.apache.zookeeper.ClientCnxn" level="INFO" additivity="false">
7396 <appender-ref ref="STDOUT" />
7399 Configuring loggers for Policy Logic
7400 ------------------------------------
7402 .. container:: paragraph
7404 The logging for the logic inside a policy (task logic, task
7405 selection logic, state finalizer logic) can be configured separate
7406 from standard logging. The logger for policy logic is
7407 ``org.onap.policy.apex.executionlogging``. The following example
7410 .. container:: ulist
7412 - a new appender for standard out using a very simple pattern
7413 (simply the actual message)
7415 - a logger for policy logic to standard out using the new
7416 appender and the already described file appender.
7418 .. container:: listingblock
7420 .. container:: content
7424 <appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender">
7426 <pattern>policy: %msg\n</pattern>
7430 <logger name="org.onap.policy.apex.executionlogging" level="info" additivity="false">
7431 <appender-ref ref="POLICY_APPENDER_STDOUT" />
7432 <appender-ref ref="FILE" />
7435 .. container:: paragraph
7437 It is also possible to use specific logging for parts of policy
7438 logic. The following example defines a logger for task logic.
7440 .. container:: listingblock
7442 .. container:: content
7446 <logger name="org.onap.policy.apex.executionlogging.TaskExecutionLogging" level="TRACE" additivity="false">
7447 <appender-ref ref="POLICY_APPENDER_STDOUT" />
7450 Rolling File Appenders
7451 ----------------------
7453 .. container:: paragraph
7455 Rolling file appenders are a good option for more complex logging
7456 of a production or complex testing APEX installation. The standard
7457 logback configuration can be used for these use cases. This
7458 section gives two examples for the standard logging and for
7461 .. container:: paragraph
7463 First the standard logging. The following example defines a
7464 rolling file appender. The appender rolls over on a daily basis.
7465 It allows for a file size of 100 MB.
7467 .. container:: listingblock
7469 .. container:: content
7473 <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
7474 <file>${logDir}/apex.log</file>
7475 <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
7476 <!-- rollover daily -->
7477 <!-- <fileNamePattern>xstream-%d{yyyy-MM-dd}.%i.txt</fileNamePattern> -->
7478 <fileNamePattern>${logDir}/apex_%d{yyyy-MM-dd}.%i.log.gz
7480 <maxHistory>4</maxHistory>
7481 <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
7482 <!-- or whenever the file size reaches 100MB -->
7483 <maxFileSize>100MB</maxFileSize>
7484 </timeBasedFileNamingAndTriggeringPolicy>
7488 %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %ex{full} %n
7493 .. container:: paragraph
7495 A very similar configuration can be used for a rolling file
7496 appender logging APEX context.
7498 .. container:: listingblock
7500 .. container:: content
7504 <appender name="CTXT-FILE"
7505 class="ch.qos.logback.core.rolling.RollingFileAppender">
7506 <file>${logDir}/apex_ctxt.log</file>
7507 <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
7508 <fileNamePattern>${logDir}/apex_ctxt_%d{yyyy-MM-dd}.%i.log.gz
7510 <maxHistory>4</maxHistory>
7511 <timeBasedFileNamingAndTriggeringPolicy
7512 class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
7513 <maxFileSize>100MB</maxFileSize>
7514 </timeBasedFileNamingAndTriggeringPolicy>
7518 %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %ex{full} %n
7523 Example Configuration for Logging Logic
7524 ---------------------------------------
7526 .. container:: paragraph
7528 The following example shows a configuration that logs policy logic
7529 to standard out and a file (*info*). All other APEX components are
7530 logging to a file (*debug*).. This configuration an be used in a
7531 pre-production phase with the APEX engine still running in a
7532 separate terminal to monitor policy execution. This logback
7533 configuration is in the APEX installation as
7534 ``etc/logback-logic.xml``.
7536 .. container:: listingblock
7538 .. container:: content
7542 <configuration debug="false">
7543 <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
7545 <contextName>Apex</contextName>
7546 <property name="logDir" value="/var/log/onap/policy/apex-pdp/" />
7548 <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
7550 <Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern>
7554 <appender name="FILE" class="ch.qos.logback.core.FileAppender">
7555 <file>${logDir}/apex.log</file>
7558 %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}
7563 <appender name="POLICY_APPENDER_STDOUT" class="ch.qos.logback.core.ConsoleAppender">
7565 <pattern>policy: %msg\n</pattern>
7569 <root level="error">
7570 <appender-ref ref="STDOUT" />
7573 <logger name="org.onap.policy.apex" level="debug" additivity="false">
7574 <appender-ref ref="FILE" />
7577 <logger name="org.onap.policy.apex.executionlogging" level="info" additivity="false">
7578 <appender-ref ref="POLICY_APPENDER_STDOUT" />
7579 <appender-ref ref="FILE" />
7583 Example Configuration for a Production Server
7584 ---------------------------------------------
7586 .. container:: paragraph
7588 The following example shows a configuration that logs all APEX
7589 components, including policy logic, to a file (*debug*). This
7590 configuration an be used in a production phase with the APEX
7591 engine being executed as a service on a system without console
7592 output. This logback configuration is in the APEX installation as
7593 ``logback-server.xml``
7595 .. container:: listingblock
7597 .. container:: content
7601 <configuration debug="false">
7602 <statusListener class="ch.qos.logback.core.status.NopStatusListener" />
7604 <contextName>Apex</contextName>
7605 <property name="logDir" value="/var/log/onap/policy/apex-pdp/" />
7607 <appender name="FILE" class="ch.qos.logback.core.FileAppender">
7608 <file>${logDir}/apex.log</file>
7611 %d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}
7616 <root level="debug">
7617 <appender-ref ref="FILE" />
7620 <logger name="org.onap.policy.apex.executionlogging" level="debug" additivity="false">
7621 <appender-ref ref="FILE" />
7625 Building a System with Websocket Backend
7626 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7631 .. container:: paragraph
7633 Websocket is a protocol to run sockets of HTTP. Since it in
7634 essence a socket, the connection is realized between a
7635 server (waiting for connections) and a client (connecting to
7636 a server). Server/client separation is only important for
7637 connection establishment, once connected, everyone can
7638 send/receive on the same socket (as any standard socket
7641 .. container:: paragraph
7643 Standard Websocket implementations are simple, no
7644 publish/subscribe and no special event handling. Most
7645 servers simply send all incoming messages to all
7646 connections. There is a PubSub definition on top of
7647 Websocket called `WAMP <http://wamp-proto.org/>`__. APEX
7648 does not support WAMP at the moment.
7653 .. container:: paragraph
7656 356 <http://www.oracle.com/technetwork/articles/java/jsr356-1937161.html>`__
7657 defines the standard Websocket API. This JSR is part of Jave
7658 EE 7 standard. For Java SE, several implementations exist in
7659 open source. Since Websockets are a stable standard and
7660 simple, most implementations are stable and ready to use. A
7661 lot of products support Websockets, like Spring, JBoss,
7662 Netty, … there are also Kafka extensions for Websockets.
7664 Websocket Example Code for Websocket clients (FOSS)
7665 ---------------------------------------------------
7667 .. container:: paragraph
7669 There are a lot of implementations and examples available on
7670 Github for Websocket clients. If one is using Java EE 7,
7671 then one can also use the native Websocket implementation.
7672 Good examples for clients using simply Java SE are here:
7674 .. container:: ulist
7677 implementation <https://github.com/TooTallNate/Java-WebSocket>`__
7679 - `Websocket sending client example, using
7680 AWT <https://github.com/TooTallNate/Java-WebSocket/blob/master/src/main/example/ChatClient.java>`__
7682 - `Websocket receiving client example (simple echo
7683 client) <https://github.com/TooTallNate/Java-WebSocket/blob/master/src/main/example/ExampleClient.java>`__
7685 .. container:: paragraph
7687 For Java EE, the native Websocket API is explained here:
7689 .. container:: ulist
7692 docs <http://www.oracle.com/technetwork/articles/java/jsr356-1937161.html>`__
7695 example <http://www.programmingforliving.com/2013/08/jsr-356-java-api-for-websocket-client-api.html>`__
7697 BCP: Websocket Configuration
7698 ----------------------------
7700 .. container:: paragraph
7702 The probably best is to configure APEX for Websocket servers
7703 for input (ingress, consume) and output (egress, produce)
7704 interfaces. This means that APEX will start Websocket
7705 servers on named ports and wait for clients to connect.
7706 Advantage: once APEX is running all connectivity
7707 infrastructure is running as well. Consequence: if APEX is
7708 not running, everyone else is in the dark, too.
7710 .. container:: paragraph
7712 The best protocol to be used is JSON string. Each event on
7713 any interface is then a string with a JSON encoding. JSON
7714 string is a little bit slower than byte code, but we doubt
7715 that this will be noticeable. A further advantage of JSON
7716 strings over Websockets with APEX starting the servers: it
7717 is very easy to connect web browsers to such a system.
7718 Simple connect the web browser to the APEX sockets and
7719 send/read JSON strings.
7721 .. container:: paragraph
7723 Once APEX is started you simply connect Websocket clients to
7724 it, and send/receive event. When APEX is terminated, the
7725 Websocket servers go down, and the clients will be
7726 disconnected. APEX does not (yet) support auto-client
7727 reconnect nor WAMP, so clients might need to be restarted or
7728 reconnected manually after an APEX boot.
7730 Demo with VPN Policy Model
7731 --------------------------
7733 .. container:: paragraph
7735 We assume that you have an APEX installation using the full
7736 package, i.e. APEX with all examples, of version ``0.5.6``
7737 or higher. We will use the VPN policy from the APEX examples
7740 .. container:: paragraph
7742 Now, have the following ready to start the demo:
7744 .. container:: ulist
7746 - 3 terminals on the host where APEX is running (we need 1
7747 for APEX and 1 for each client)
7749 - the events in the file
7750 ``$APEX_HOME/examples/events/VPN/SetupEvents.json`` open
7751 in an editor (we need to send those events to APEX)
7753 - the events in the file
7754 ``$APEX_HOME/examples/events/VPN/Link09Events.json`` open
7755 in an editor (we need to send those events to APEX)
7757 A Websocket Configuration for the VPN Domain
7758 ############################################
7760 .. container:: paragraph
7762 Create a new APEX configuration using the VPN policy
7763 model and configuring APEX as discussed above for
7764 Websockets. Copy the following configuration into
7765 ``$APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json``
7767 ``%APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json``):
7769 .. container:: listingblock
7771 .. container:: content
7777 "engineServiceParameters" : {
7778 "name" : "VPNApexEngine",
7779 "version" : "0.0.1",
7781 "instanceCount" : 1,
7782 "deploymentPort" : 12345,
7783 "policyModelFileName" : "examples/models/VPN/VPNPolicyModelAvro.json",
7784 "engineParameters" : {
7785 "executorParameters" : {
7787 "parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
7790 "contextParameters" : {
7791 "parameterClassName" : "org.onap.policy.apex.context.parameters.ContextParameters",
7792 "schemaParameters":{
7794 "parameterClassName" : "org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters"
7800 "producerCarrierTechnologyParameters" : {
7801 "carrierTechnology" : "WEBSOCKET",
7802 "parameterClassName" : "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",
7808 "producerEventProtocolParameters" : {
7809 "eventProtocol" : "JSON"
7811 "consumerCarrierTechnologyParameters" : {
7812 "carrierTechnology" : "WEBSOCKET",
7813 "parameterClassName" : "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",
7819 "consumerEventProtocolParameters" : {
7820 "eventProtocol" : "JSON"
7827 .. container:: paragraph
7829 In a new terminal, start APEX with the new configuration for
7830 Websocket-Server ingress/egress:
7832 .. container:: listingblock
7834 .. container:: content
7839 #: $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json
7841 .. container:: listingblock
7843 .. container:: content
7848 #: %APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json
7850 .. container:: paragraph
7852 Wait for APEX to start, it takes a while to create all Websocket
7853 servers (about 8 seconds on a standard laptop without cached
7854 binaries). depending on your log messages, you will see no (some, a
7855 lot) log messages. If APEX starts correctly, the last few messages
7858 .. container:: listingblock
7860 .. container:: content
7865 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)
7866 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 ...
7867 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
7868 Started Apex service
7870 .. container:: paragraph
7872 APEX is running in the new terminal and will produce output when the
7873 policy is triggered/executed.
7875 Run the Websocket Echo Client
7876 #############################
7878 .. container:: paragraph
7880 The echo client is included in an APEX full installation. To run
7881 the client, open a new shell (Unix, Cygwin) or command prompt
7882 (``cmd`` on Windows). Then use the APEX application launcher to
7886 APEX engine needs to run first
7887 The example assumes that an APEX engine configured for *produce* carrier technology Websocket and *JSON* event protocol is executed first.
7889 +---------------------------------------------------------+-----------------------------------------------------------+
7890 | Unix, Cygwin | Windows |
7891 +=========================================================+===========================================================+
7892 | .. container:: | .. container:: |
7894 | .. container:: listingblock | .. container:: listingblock |
7896 | .. container:: content | .. container:: content |
7898 | .. code:: | .. code:: |
7900 | # $APEX_HOME/bin/apexApps.sh ws-echo [args] | > %APEX_HOME%\bin\apexApps.bat ws-echo [args] |
7901 +---------------------------------------------------------+-----------------------------------------------------------+
7903 .. container:: paragraph
7905 Use the following command line arguments for server and port of
7906 the Websocket server. The port should be the same as configured in
7907 the APEX engine. The server host should be the host on which the
7908 APEX engine is running
7910 .. container:: ulist
7912 - ``-p`` defines the Websocket port to connect to (defaults to
7915 - ``-s`` defines the host on which a Websocket server is running
7916 (defaults to ``localhost``)
7918 .. container:: paragraph
7920 Let’s assume that there is an APEX engine running, configured for
7921 produce Websocket carrier technology, as server, for port 42452,
7922 with produce event protocol JSON,. If we start the console client
7923 on the same host, we can omit the ``-s`` options. We start the
7926 .. container:: listingblock
7928 .. container:: content
7932 # $APEX_HOME/bin/apexApps.sh ws-echo -p 42452 (1)
7933 > %APEX_HOME%\bin\apexApps.bat ws-echo -p 42452 (2)
7935 .. container:: colist arabic
7937 +-------+--------------------------------+
7938 | **1** | Start client on Unix or Cygwin |
7939 +-------+--------------------------------+
7940 | **2** | Start client on Windows |
7941 +-------+--------------------------------+
7943 .. container:: paragraph
7945 Once started successfully, the client will produce the following
7946 messages (assuming we used ``-p 42452`` and an APEX engine is
7947 running on ``localhost`` with the same port:
7949 .. container:: listingblock
7951 .. container:: content
7955 ws-simple-echo: starting simple event echo
7956 --> server: localhost
7959 Once started, the application will simply print out all received events to standard out.
7960 Each received event will be prefixed by '---' and suffixed by '===='
7963 ws-simple-echo: opened connection to APEX (Web Socket Protocol Handshake)
7965 Run the Websocket Console Client
7966 ################################
7968 .. container:: paragraph
7970 The console client is included in an APEX full installation. To
7971 run the client, open a new shell (Unix, Cygwin) or command prompt
7972 (``cmd`` on Windows). Then use the APEX application launcher to
7976 APEX engine needs to run first
7977 The example assumes that an APEX engine configured for *consume* carrier technology Websocket and *JSON* event
7978 protocol is executed first.
7980 +------------------------------------------------------------+--------------------------------------------------------------+
7981 | Unix, Cygwin | Windows |
7982 +============================================================+==============================================================+
7983 | .. container:: | .. container:: |
7985 | .. container:: listingblock | .. container:: listingblock |
7987 | .. container:: content | .. container:: content |
7989 | .. code:: | .. code:: |
7991 | # $APEX_HOME/bin/apexApps.sh ws-console [args] | > %APEX_HOME%\bin\apexApps.bat ws-console [args] |
7992 +------------------------------------------------------------+--------------------------------------------------------------+
7994 .. container:: paragraph
7996 Use the following command line arguments for server and port of
7997 the Websocket server. The port should be the same as configured in
7998 the APEX engine. The server host should be the host on which the
7999 APEX engine is running
8001 .. container:: ulist
8003 - ``-p`` defines the Websocket port to connect to (defaults to
8006 - ``-s`` defines the host on which a Websocket server is running
8007 (defaults to ``localhost``)
8009 .. container:: paragraph
8011 Let’s assume that there is an APEX engine running, configured for
8012 consume Websocket carrier technology, as server, for port 42450,
8013 with consume event protocol JSON,. If we start the console client
8014 on the same host, we can omit the ``-s`` options. We start the
8017 .. container:: listingblock
8019 .. container:: content
8023 # $APEX_HOME/bin/apexApps.sh ws-console -p 42450 (1)
8024 > %APEX_HOME%\bin\apexApps.sh ws-console -p 42450 (2)
8026 .. container:: colist arabic
8028 +-------+--------------------------------+
8029 | **1** | Start client on Unix or Cygwin |
8030 +-------+--------------------------------+
8031 | **2** | Start client on Windows |
8032 +-------+--------------------------------+
8034 .. container:: paragraph
8036 Once started successfully, the client will produce the following
8037 messages (assuming we used ``-p 42450`` and an APEX engine is
8038 running on ``localhost`` with the same port:
8040 .. container:: listingblock
8042 .. container:: content
8046 ws-simple-console: starting simple event console
8047 --> server: localhost
8050 - terminate the application typing 'exit<enter>' or using 'CTRL+C'
8051 - events are created by a non-blank starting line and terminated by a blank line
8054 ws-simple-console: opened connection to APEX (Web Socket Protocol Handshake)
8059 .. container:: paragraph
8061 Now you have the full system up and running:
8063 .. container:: ulist
8065 - Terminal 1: APEX ready and loaded
8067 - Terminal 2: an echo client, printing received messages produced
8070 - Terminal 2: a console client, waiting for input on the console
8071 (standard in) and sending text to APEX
8073 .. container:: paragraph
8075 We started the engine with the VPN policy example. So all the
8076 events we are using now are located in files in the following
8079 .. container:: listingblock
8081 .. container:: content
8086 #: $APEX_HOME/examples/events/VPN
8087 > %APEX_HOME%\examples\events\VPN
8089 .. container:: paragraph
8091 To sends events, simply copy the content of the event files into
8092 Terminal 3 (the console client). It will read multi-line JSON text
8093 and send the events. So copy the content of ``SetupEvents.json`` into
8094 the client. APEX will trigger a policy and produce some output, the
8095 echo client will also print some events created in the policy. In
8096 Terminal 1 (APEX) you’ll see some status messages from the policy as:
8098 .. container:: listingblock
8100 .. container:: content
8105 {Link=L09, LinkUp=true}
8107 outFields: {Link=L09, LinkUp=true}
8108 {Link=L10, LinkUp=true}
8111 outFields: {Link=L10, LinkUp=true}
8112 {CustomerName=C, LinkList=L09 L10, SlaDT=300, YtdDT=300}
8114 C 300 300 [L09, L10]
8115 outFields: {CustomerName=C, LinkList=L09 L10, SlaDT=300, YtdDT=300}
8116 {CustomerName=A, LinkList=L09 L10, SlaDT=300, YtdDT=50}
8119 C 300 300 [L09, L10]
8120 outFields: {CustomerName=A, LinkList=L09 L10, SlaDT=300, YtdDT=50}
8121 {CustomerName=D, LinkList=L09 L10, SlaDT=300, YtdDT=400}
8124 C 300 300 [L09, L10]
8125 D 300 400 [L09, L10]
8126 outFields: {CustomerName=D, LinkList=L09 L10, SlaDT=300, YtdDT=400}
8127 {CustomerName=B, LinkList=L09 L10, SlaDT=300, YtdDT=299}
8130 B 300 299 [L09, L10]
8131 C 300 300 [L09, L10]
8132 D 300 400 [L09, L10]
8133 outFields: {CustomerName=B, LinkList=L09 L10, SlaDT=300, YtdDT=299}
8135 .. container:: paragraph
8137 In Terminal 2 (echo-client) you see the received events, the last two
8140 .. container:: listingblock
8142 .. container:: content
8147 ws-simple-echo: received
8148 ---------------------------------
8150 "name": "VPNCustomerCtxtActEvent",
8152 "nameSpace": "org.onap.policy.apex.domains.vpn.events",
8155 "CustomerName": "C",
8156 "LinkList": "L09 L10",
8160 =================================
8162 ws-simple-echo: received
8163 ---------------------------------
8165 "name": "VPNCustomerCtxtActEvent",
8167 "nameSpace": "org.onap.policy.apex.domains.vpn.events",
8170 "CustomerName": "D",
8171 "LinkList": "L09 L10",
8175 =================================
8177 .. container:: paragraph
8179 Congratulations, you have triggered a policy in APEX using
8180 Websockets, the policy did run through, created events, picked up by
8183 .. container:: paragraph
8185 Now you can send the Link 09 and Link 10 events, they will trigger
8186 the actual VPN policy and some calculations are made. Let’s take the
8187 Link 09 events from ``Link09Events.json``, copy them all into
8188 Terminal 3 (the console). APEX will run the policy (with some status
8189 output), and the echo client will receive and print events.
8191 .. container:: paragraph
8193 To terminate the applications, simply press ``CTRL+C`` in Terminal 1
8194 (APEX). This will also terminate the echo-client in Terminal 2. Then
8195 type ``exit<enter>`` in Terminal 3 (or ``CTRL+C``) to terminate the
8205 Last updated 2018-09-10 15:38:16 IST
8207 .. |Extract the TAR archive| image:: images/install-guide/win-extract-tar-gz.png
8208 .. |Extract the APEX distribution| image:: images/install-guide/win-extract-tar.png
8209 .. |REST Editor Start Screen| image:: images/install-guide/rest-start.png
8210 .. |REST Editor with loaded SampleDomain Policy Model| image:: images/install-guide/rest-loaded.png
8211 .. |APEX Configuration Matrix| image:: images/apex-intro/ApexEngineConfig.png
8212 .. |File > New to create a new Policy Model| image:: images/mfp/MyFirstPolicy_P1_newPolicyModel1.png
8213 .. |Create a new Policy Model| image:: images/mfp/MyFirstPolicy_P1_newPolicyModel2.png
8214 .. |Right click to create a new event| image:: images/mfp/MyFirstPolicy_P1_newEvent1.png
8215 .. |Fill in the necessary information for the 'SALE_INPUT' event and click 'Submit'| image:: images/mfp/MyFirstPolicy_P1_newEvent2.png
8216 .. |Right click to create a new Item Schema| image:: images/mfp/MyFirstPolicy_P1_newItemSchema1.png
8217 .. |Create a new Item Schema| image:: images/mfp/MyFirstPolicy_P1_newItemSchema2.png
8218 .. |Add new event parameters to an event| image:: images/mfp/MyFirstPolicy_P1_newEvent3.png
8219 .. |Right click to create a new task| image:: images/mfp/MyFirstPolicy_P1_newTask1.png
8220 .. |Add input and out fields for the task| image:: images/mfp/MyFirstPolicy_P1_newTask2.png
8221 .. |Add task logic the task| image:: images/mfp/MyFirstPolicy_P1_newTask3.png
8222 .. |Create a new policy| image:: images/mfp/MyFirstPolicy_P1_newPolicy1.png
8223 .. |Create a state| image:: images/mfp/MyFirstPolicy_P1_newState1.png
8224 .. |Add a Task and Output Mapping| image:: images/mfp/MyFirstPolicy_P1_newState2.png
8225 .. |Validate the policy model for error using the 'Model' > 'Validate' menu item| image:: images/mfp/MyFirstPolicy_P1_validatePolicyModel.png
8226 .. |Download the completed policy model using the 'File' > 'Download' menu item| image:: images/mfp/MyFirstPolicy_P1_exportPolicyModel1.png
8227 .. |Create a new alternative task MorningBoozeCheckAlt1| image:: images/mfp/MyFirstPolicy_P2_newTask1.png
8228 .. |Right click to edit a policy| image:: images/mfp/MyFirstPolicy_P2_editPolicy1.png
8229 .. |State definition with 2 Tasks and Task Selection Logic| image:: images/mfp/MyFirstPolicy_P2_editState1.png
Code Review / policy / parent.git / blob