Blame - docs/apex/APEX-User-Manual.rst - onap/policy/parent

2019-07-11 12:57:49 +0000

[diff] [blame]

495

.. important::

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.

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

499

500

.. container:: paragraph

501

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:

.. container:: ulist

- Unix, Cygwin: ``/usr/local/src/apex``

509

510

- Windows: ``C:\dev\apex``

511

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

512

+-------------------------------------------------------+--------------------------------------------------------+

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

513

| Unix, Cygwin | Windows |

514

+=======================================================+========================================================+

515

| .. container:: | .. container:: |

516

| | |

517

| .. container:: content | .. container:: content |

518

| | |

519

| .. code:: | .. code:: |

520

| :number-lines: | :number-lines: |

521

| | |

522

| # cd /usr/local/src/apex | >c: |

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

523

| # mvn clean install -Pdocker -DskipTests | >cd \dev\apex |

524

| | >mvn clean install -Pdocker -DskipTests |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

525

+-------------------------------------------------------+--------------------------------------------------------+

526

527

.. container:: paragraph

528

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.

535

536

.. container:: paragraph

537

538

When Maven is finished with the build, the final screen should look

539

similar to this (omitting some ``success`` lines):

540

541

.. container:: listingblock

542

543

.. container:: content

544

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

545

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

546

:number-lines:

547

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] ------------------------------------------------------------------------

556

[INFO] BUILD SUCCESS

557

[INFO] ------------------------------------------------------------------------

558

[INFO] Total time: 03:43 min

559

[INFO] Finished at: 2018-09-03T11:56:01+01:00

560

[INFO] ------------------------------------------------------------------------

561

562

.. container:: paragraph

563

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.

567

568

+-----------------------------------------------------------------------------------------------------------------------------+

569

| Unix, Cygwin |

570

+=============================================================================================================================+

571

| .. container:: |

572

| |

573

| .. container:: listingblock |

| |

| .. code:: |

| :number-lines: |

| |

| # cd packages/apex-pdp-package-full/target |

579

| # ls -l |

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

+-----------------------------------------------------------------------------------------------------------------------------+

596

597

+-----------------------------------------------------------------------------------------------------------------------------+

598

| Windows |

599

+=============================================================================================================================+

600

| .. container:: |

601

| |

602

| .. container:: listingblock |

| |

| .. code:: |

| :number-lines: |

| |

| >cd packages\apex-pdp-package-full\target |

608

| >dir |

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

+-----------------------------------------------------------------------------------------------------------------------------+

629

630

.. container:: paragraph

631

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.

Installation Layout

-------------------

.. container:: paragraph

640

641

A full installation of APEX comes with the following layout.

642

643

.. container:: listingblock

644

645

.. container:: content

::

$APEX_HOME

├───bin (1)

├───etc (2)

│ ├───editor

│ ├───hazelcast

│ ├───infinispan

│ └───META-INF

├───examples (3)

│ ├───config (4)

│ ├───docker (5)

│ ├───events (6)

│ ├───html (7)

│ ├───models (8)

│ └───scripts (9)

├───lib (10)

│ └───applications (11)

665

└───war (12)

666

667

.. container:: colist arabic

668

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 |

679

| | started |

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 |

687

| | exampples |

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 |

699

| | examples) |

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 |

706

| | JAR files |

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

+-----------------------------------+-----------------------------------+

System Configuration

--------------------

.. container:: paragraph

719

720

Once APEX is installed, a few configurations need to be done:

.. container:: ulist

- Create an APEX user and an APEX group (optional, if not

725

installed using RPM and DPKG)

726

727

- Create environment settings for ``APEX_HOME`` and

728

``APEX_USER``, required by the start scripts

729

730

- Change settings of the logging framework (optional)

731

732

- Create directories for logging, required (execution might fail

733

if directories do not exist or cannot be created)

APEX User and Group

###################

.. container:: paragraph

739

740

On smaller installations and test systems, APEX can run as any

741

user or group.

742

743

.. container:: paragraph

744

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

749

choose.

750

751

.. container:: paragraph

752

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

757

APEX is installed.

758

759

.. container:: listingblock

760

761

.. container:: content

762

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

763

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

764

:number-lines:

765

766

# sudo groupadd apexuser

767

# sudo useradd -g apexuser apexuser

768

# sudo chown -R apexuser:apexuser <apex-dir>

769

770

.. container:: paragraph

771

772

For other operating systems please consult your manual or system

773

administrator.

774

775

Environment Settings: APEX_HOME and APEX_USER

776

#############################################

777

778

.. container:: paragraph

779

780

The provided start scripts for APEX require two environment

variables being set:

.. container:: ulist

- ``APEX_USER`` with the user under whos name and permission APEX

786

should be started (Unix only)

787

788

- ``APEX_HOME`` with the directory where APEX is installed (Unix,

789

Windows, Cygwin)

790

791

.. container:: paragraph

792

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.

797

798

+------------------------------------------------+---------------------------------------------------------+

799

| Unix, Cygwin (bash/tcsh) | Windows |

800

+================================================+=========================================================+

801

| .. container:: | .. container:: |

802

| | |

803

| .. container:: content | .. container:: content |

804

| | |

805

| .. code:: | .. code:: |

806

| :number-lines: | :number-lines: |

807

| | |

808

| # export APEX_USER=apexuser | >set APEX_HOME=C:\apex\apex-full-2.0.0-SNAPSHOT |

809

| # cd /opt/app/policy/apex-pdp | |

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

810

| # export APEX_HOME=`pwd` | |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

811

| | |

812

+------------------------------------------------+ |

813

| .. container:: | |

814

| | |

815

| .. container:: content | |

816

| | |

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

817

| .. code::tcsh | |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

818

| :number-lines: | |

819

| | |

820

| # setenv APEX_USER apexuser | |

821

| # cd /opt/app/policy/apex-pdp | |

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

822

| # setenv APEX_HOME `pwd` | |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

823

| | |

824

+------------------------------------------------+---------------------------------------------------------+

825

| .. container:: | .. container:: |

826

| | |

827

| .. container:: content | .. container:: content |

828

| | |

829

| .. code:: | .. code:: |

830

| :number-lines: | :number-lines: |

831

| | |

832

| # env | grep APEX | >set APEX_HOME |

833

| # APEX_USER=apexuser | APEX_HOME=\apex\apex-full-2.0.0-SNAPSHOT |

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

834

| # APEX_HOME=/opt/app/policy/apex-pdp | |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

835

| | |

836

+------------------------------------------------+---------------------------------------------------------+

837

838

Making Environment Settings Permanent (Unix, Cygwin)

839

====================================================

840

841

.. container:: paragraph

842

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

846

847

Making Environment Settings Permanent (Windows)

848

===============================================

849

850

.. container:: paragraph

On Windows 7 do

.. container:: ulist

- Click on the **Start** Menu

857

858

- Right click on **Computer**

859

860

- Select **Properties**

861

862

.. container:: paragraph

On Windows 8/10 do

.. container:: ulist

- Click on the **Start** Menu

- Select **System**

.. container:: paragraph

873

874

Then do the following

.. container:: ulist

- Select **Advanced System Settings**

879

880

- On the **Advanced** tab, click the **Environment Variables**

881

button

882

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"

886

887

.. container:: paragraph

888

889

For the settings to take effect, an application needs to be

890

restarted (e.g. any open ``cmd`` window).

891

892

Edit the APEX Logging Settings

893

##############################

894

895

.. container:: paragraph

896

897

Configure the APEX logging settings to your requirements, for

instance:

.. container:: ulist

- change the directory where logs are written to, or

903

904

- change the log levels

905

906

.. container:: paragraph

907

908

Edit the file ``$APEX_HOME/etc/logback.xml`` for any required

909

changes. To change the log directory change the line

910

911

.. container:: paragraph

912

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

913

``<property name="logDir" value="/var/log/onap/policy/apex-pdp/" />``

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

914

915

.. container:: paragraph

to

.. container:: paragraph

920

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

921

``<property name="logDir" value="/PATH/TO/LOG/DIRECTORY/" />``

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

922

923

.. container:: paragraph

924

925

On Windows, it is recommended to change the log directory to:

926

927

.. container:: paragraph

928

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

929

``<property name="logDir" value="C:/apex/apex-full-2.0.0-SNAPSHOT/logs" />``

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

930

931

.. container:: paragraph

932

933

Note: Be careful about when to use ``\`` vs. ``/`` as the path

934

separator!

935

936

Create Directories for Logging

937

##############################

938

939

.. container:: paragraph

940

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

944

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

945

+-----------------------------------------------------------------------+-------------------------------------------------------+

946

| Unix, Cygwin | Windows |

947

+=======================================================================+=======================================================+

948

| .. container:: | .. container:: |

949

| | |

950

| .. container:: content | .. container:: content |

951

| | |

952

| .. code:: | .. code:: |

953

| :number-lines: | :number-lines: |

954

| | |

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

+-----------------------------------------------------------------------+-------------------------------------------------------+

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

958

959

Verify the APEX Installation

960

----------------------------

961

962

.. container:: paragraph

963

964

When APEX is installed and all settings are realized, the

965

installation can be verified.

966

967

Verify Installation - run Engine

968

################################

969

970

.. container:: paragraph

971

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.

979

980

.. container:: listingblock

981

982

.. container:: content

983

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

984

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

985

:number-lines:

986

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

996

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

1001

configuration file

1002

-v,--version outputs the version of Apex

1003

1004

Verify Installation - run an Example

1005

####################################

1006

1007

.. container:: paragraph

1008

1009

A full APEX installation comes with several examples. Here, we can

1010

fully verify the installation by running one of the examples.

1011

1012

.. container:: paragraph

1013

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.

1019

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

1020

.. container:: paragraph

1021

1022

On Unix/Linux flavoured platforms, give the commands below:

1023

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1024

.. container:: listingblock

1025

1026

.. container:: content

1027

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

1028

.. code::

1029

:number-lines:

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1030

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

1031

sudo su - apexuser

1032

export APEX_HOME <path to apex installation>

1033

export APEX_USER apexuser

1034

1035

.. container:: paragraph

1036

1037

You can now try to run apex.

1038

1039

.. container:: listingblock

1040

1041

.. container:: content

.. code::

:number-lines:

# $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)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1049

1050

.. container:: colist arabic

+-------+---------+

| **1** | UNIX |

+-------+---------+

| **2** | Cygwin |

+-------+---------+

| **3** | Windows |

+-------+---------+

.. container:: paragraph

1061

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

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)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1064

1065

.. container:: listingblock

1066

1067

.. container:: content

1068

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1069

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1070

:number-lines:

1071

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

1086

1087

.. container:: paragraph

1088

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.

1091

1092

.. container:: paragraph

1093

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

1096

policy.

1097

1098

.. container:: paragraph

1099

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.

1105

1106

+-------------------------------------------------------------+-------------------------------------------------------------+

1107

| Input Event | Example Output Event |

1108

+=============================================================+=============================================================+

1109

| .. container:: | .. container:: |

1110

| | |

1111

| .. container:: content | .. container:: content |

1112

| | |

1113

| .. code:: | .. code:: |

1114

| :number-lines: | :number-lines: |

1115

| | |

1116

| { | { |

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 |

1134

| | } |

1135

+-------------------------------------------------------------+-------------------------------------------------------------+

1136

1137

.. container:: paragraph

1138

1139

Terminate APEX by simply using ``CTRL+C`` in the console.

1140

1141

Verify a Full Installation - REST Editor

1142

########################################

1143

1144

.. container:: paragraph

1145

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

1149

follows.

1150

1151

.. container:: listingblock

1152

1153

.. container:: content

1154

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1155

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1156

:number-lines:

1157

1158

# $APEX_HOME/bin/apexApps.sh rest-editor

1159

1160

.. container:: listingblock

1161

1162

.. container:: content

1163

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1164

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1165

:number-lines:

1166

1167

>%APEX_HOME%\bin\apexApps.bat rest-editor

1168

1169

.. container:: paragraph

1170

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

1175

should be:

1176

1177

.. container:: listingblock

1178

1179

.. container:: content

1180

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1181

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1182

:number-lines:

1183

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/

1190

1191

.. container:: paragraph

1192

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

1196

follows.

1197

1198

.. container:: imageblock

1199

1200

.. container:: content

1201

1202

|REST Editor Start Screen|

.. container:: title

Figure 1. REST Editor Start Screen

1207

1208

.. container:: paragraph

1209

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.

1216

1217

.. container:: imageblock

1218

1219

.. container:: content

1220

1221

|REST Editor with loaded SampleDomain Policy Model|

.. container:: title

Figure 2. REST Editor with loaded SampleDomain Policy Model

1226

1227

.. container:: paragraph

1228

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.

1232

1233

Installing WAR Applications

1234

---------------------------

1235

1236

.. container:: paragraph

1237

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

1243

1244

.. container:: paragraph

1245

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.

1250

1251

.. container:: paragraph

1252

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

1256

running.

1257

1258

.. container:: paragraph

1259

1260

There are multiple ways to install the APEX WAR applications:

.. container:: ulist

- copy the ``.war`` file into the Tomcat ``webapps`` folder

1265

1266

- use the Tomcat ``Manager App`` to deploy via the web interface

1267

1268

- deploy using a REST call to Tomcat

1269

1270

.. container:: paragraph

1271

1272

For details on how to install ``war`` files please consult the

1273

`Tomcat

1274

Documentation <https://tomcat.apache.org/tomcat-9.0-doc/index.html>`__

1275

or the `Manager App

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.

1281

1282

.. container:: paragraph

1283

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.

1287

1288

.. container:: paragraph

1289

1290

The current APEX version provides the following WAR applications:

.. container:: ulist

- client-deployment-2.0.0-SNAPSHOT.war - a client to deploy new

1295

policy models to a running engine

1296

1297

- client-editor-2.0.0-SNAPSHOT.war - the standard policy REST

1298

editor GUI

1299

1300

- client-monitoring-2.0.0-SNAPSHOT.war - a client for monitoring

1301

a running APEX engine

1302

1303

- client-full-2.0.0-SNAPSHOT.war - a full client with a

1304

one-stop-access to deployment, monitoring, and REST editor

1305

1306

- examples-servlet-2.0.0-SNAPSHOT.war - an example APEX servlet

1307

1308

Running APEX in Docker

1309

----------------------

1310

1311

.. container:: paragraph

1312

1313

Since APEX is in ONAP, we provide a full virtualization

1314

environment for the engine.

Run in ONAP

###########

.. container:: paragraph

1320

1321

Running APEX from the ONAP docker repository only requires 2

1322

commands:

1323

1324

.. container:: olist arabic

1325

1326

#. Log into the ONAP docker repo

1327

1328

.. container:: listingblock

1329

1330

.. container:: content

::

docker login -u docker -p docker nexus3.onap.org:10003

1335

1336

.. container:: olist arabic

1337

1338

#. Run the APEX docker image

1339

1340

.. container:: listingblock

1341

1342

.. container:: content

::

docker run -it --rm nexus3.onap.org:10003/onap/policy-apex-pdp:latest

Build a Docker Image

####################

.. container:: paragraph

1352

1353

Alternatively, one can use the Dockerfile defined in the Docker

1354

package to build an image.

1355

1356

.. container:: listingblock

.. container:: title

APEX Dockerfile

.. container:: content

1363

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1364

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

:number-lines:

#

# Docker file to build an image that runs APEX on Java 8 in Ubuntu

#

FROM ubuntu:16.04

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 && \

1376

apt-get update && \

1377

apt-get install -y openjdk-8-jdk

1378

1379

# Create apex user and group

1380

RUN groupadd apexuser

1381

RUN useradd --create-home -g apexuser apexuser

1382

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

# Unpack the tarball

RUN mkdir /packages

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

1393

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

1398

1399

# Copy examples to Apex user area

1400

RUN cp -pr /opt/app/policy/apex-pdp/examples /home/apexuser

RUN apt-get clean

RUN chown -R apexuser:apexuser /home/apexuser/*

1405

1406

USER apexuser

1407

ENV PATH /opt/app/policy/apex-pdp/bin:$PATH

1408

WORKDIR /home/apexuser

1409

1410

APEX Configurations Explained

1411

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

1412

1413

Introduction to APEX Configuration

1414

----------------------------------

1415

1416

.. container:: paragraph

1417

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.

1426

1427

.. container:: imageblock

1428

1429

.. container:: content

1430

1431

|APEX Configuration Matrix|

.. container:: title

Figure 3. APEX Configuration Matrix

1436

1437

.. container:: paragraph

1438

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.

1443

1444

General Configuration Format

1445

----------------------------

1446

1447

.. container:: paragraph

1448

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:

1453

1454

.. container:: listingblock

1455

1456

.. container:: content

1457

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1458

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1459

1460

{

1461

"engineServiceParameters":{

1462

... (1)

1463

"engineParameters":{ (2)

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1464

"executorParameters":{...}, (3)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1465

"contextParameters":{...} (4)

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1466

"taskParameters":[...] (5)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1467

}

1468

},

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1469

"eventInputParameters":{ (6)

1470

"input1":{ (7)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1471

"carrierTechnologyParameters":{...},

1472

"eventProtocolParameters":{...}

1473

},

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1474

"input2":{...}, (8)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1475

"carrierTechnologyParameters":{...},

1476

"eventProtocolParameters":{...}

1477

},

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1478

... (9)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1479

},

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1480

"eventOutputParameters":{ (10)

1481

"output1":{ (11)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1482

"carrierTechnologyParameters":{...},

1483

"eventProtocolParameters":{...}

1484

},

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1485

"output2":{ (12)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1486

"carrierTechnologyParameters":{...},

1487

"eventProtocolParameters":{...}

1488

},

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1489

... (13)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

}

}

.. container:: colist arabic

1494

1495

+-----------------------------------+-----------------------------------+

1496

| **1** | main engine configuration |

1497

+-----------------------------------+-----------------------------------+

1498

| **2** | engine parameters for plugin |

1499

| | configurations (execution |

1500

| | environments and context |

1501

| | handling) |

1502

+-----------------------------------+-----------------------------------+

1503

| **3** | engine specific parameters, |

1504

| | mainly for executor plugins |

1505

+-----------------------------------+-----------------------------------+

1506

| **4** | context specific parameters, e.g. |

1507

| | for context schemas, persistence, |

1508

| | etc. |

1509

+-----------------------------------+-----------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1510

| **5** | list of task parameters that |

1511

| | should be made available in task |

1512

| | logic (optional). |

1513

+-----------------------------------+-----------------------------------+

1514

| **6** | configuration of the input |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1515

| | interface |

1516

+-----------------------------------+-----------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1517

| **7** | an example input called |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1518

| | ``input1`` with carrier |

1519

| | technology and event protocol |

1520

+-----------------------------------+-----------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1521

| **8** | an example input called |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1522

| | ``input2`` with carrier |

1523

| | technology and event protocol |

1524

+-----------------------------------+-----------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1525

| **9** | any further input configuration |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1526

+-----------------------------------+-----------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1527

| **10** | configuration of the output |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1528

| | interface |

1529

+-----------------------------------+-----------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1530

| **11** | an example output called |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1531

| | ``output1`` with carrier |

1532

| | technology and event protocol |

1533

+-----------------------------------+-----------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1534

| **12** | an example output called |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1535

| | ``output2`` with carrier |

1536

| | technology and event protocol |

1537

+-----------------------------------+-----------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1538

| **13** | any further output configuration |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1539

+-----------------------------------+-----------------------------------+

1540

1541

Engine Service Parameters

1542

-------------------------

1543

1544

.. container:: paragraph

1545

1546

The configuration provides a number of parameters to

1547

configure the engine. An example configuration with

1548

explanations of all options is shown below.

1549

1550

.. container:: listingblock

1551

1552

.. container:: content

1553

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1554

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1555

1556

"engineServiceParameters" : {

1557

"name" : "AADMApexEngine", (1)

1558

"version" : "0.0.1", (2)

1559

"id" : 45, (3)

1560

"instanceCount" : 4, (4)

1561

"deploymentPort" : 12345, (5)

1562

"policyModelFileName" : "examples/models/VPN/VPNPolicyModelJava.json", (6)

1563

"periodicEventPeriod": 1000, (7)

1564

"engineParameters":{ (8)

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1565

"executorParameters":{...}, (9)

1566

"contextParameters":{...}, (10)

1567

"taskParameters":[...] (11)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

}

}

.. container:: colist arabic

1572

1573

+-----------------------------------+-----------------------------------+

1574

| **1** | a name for the engine. The engine |

1575

| | name is used to create a key in a |

1576

| | runtime engine. An name matching |

1577

| | the following regular expression |

1578

| | can be used here: |

1579

| | ``[A-Za-z0-9\\-_\\.]+`` |

1580

+-----------------------------------+-----------------------------------+

1581

| **2** | a version of the engine, use |

1582

| | semantic versioning as explained |

1583

| | here: `Semantic |

1584

| | Versioning <http://semver.org/>`_ |

1585

| | _. |

1586

| | This version is used in a runtime |

1587

| | engine to create a version of the |

1588

| | engine. For that reason, the |

1589

| | version must match the following |

1590

| | regular expression ``[A-Z0-9.]+`` |

1591

+-----------------------------------+-----------------------------------+

1592

| **3** | a numeric identifier for the |

1593

| | engine |

1594

+-----------------------------------+-----------------------------------+

1595

| **4** | the number of threads (policy |

1596

| | instances executed in parallel) |

1597

| | the engine should use, use ``1`` |

1598

| | for single threaded engines |

1599

+-----------------------------------+-----------------------------------+

1600

| **5** | the port for the deployment |

1601

| | Websocket connection to the |

1602

| | engine |

1603

+-----------------------------------+-----------------------------------+

1604

| **6** | the model file to load into the |

1605

| | engine on startup (optional) |

1606

+-----------------------------------+-----------------------------------+

1607

| **7** | an optional timer for periodic |

1608

| | policies, in milliseconds (a |

1609

| | defined periodic policy will be |

1610

| | executed every ``X`` |

1611

| | milliseconds), not used of not |

1612

| | set or ``0`` |

1613

+-----------------------------------+-----------------------------------+

1614

| **8** | engine parameters for plugin |

1615

| | configurations (execution |

1616

| | environments and context |

1617

| | handling) |

1618

+-----------------------------------+-----------------------------------+

1619

| **9** | engine specific parameters, |

1620

| | mainly for executor plugins |

1621

+-----------------------------------+-----------------------------------+

1622

| **10** | context specific parameters, e.g. |

1623

| | for context schemas, persistence, |

1624

| | etc. |

1625

+-----------------------------------+-----------------------------------+

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

1626

| **11** | list of task parameters that |

1627

| | should be made available in task |

1628

| | logic (optional). |

1629

+-----------------------------------+-----------------------------------+

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1630

1631

.. container:: paragraph

1632

1633

The model file is optional, it can also be specified via

1634

command line. In any case, make sure all execution and other

1635

required plug-ins for the loaded model are loaded as

1636

required.

1637

1638

Input and Output Interfaces

1639

---------------------------

1640

1641

.. container:: paragraph

1642

1643

An APEX engine has two main interfaces:

.. container:: ulist

- An *input* interface to receive events: also known as

1648

ingress interface or consumer, receiving (consuming)

1649

events commonly named triggers, and

1650

1651

- An *output* interface to publish produced events: also

1652

known as egress interface or producer, sending

1653

(publishing) events commonly named actions or action

1654

events.

1655

1656

.. container:: paragraph

1657

1658

The input and output interface is configured in terms of

1659

inputs and outputs, respectively. Each input and output is a

1660

combination of a carrier technology and an event protocol.

1661

Carrier technologies and event protocols are provided by

1662

plugins, each with its own specific configuration. Most

1663

carrier technologies can be configured for input as well as

1664

output. Most event protocols can be used for all carrier

1665

technologies. One exception is the JMS object event

1666

protocol, which can only be used for the JMS carrier

1667

technology. Some further restrictions apply (for instance

1668

for carrier technologies using bi- or uni-directional

1669

modes).

1670

1671

.. container:: paragraph

1672

1673

Input and output interface can be configured separately, in

1674

isolation, with any number of carrier technologies. The

1675

resulting general configuration options are:

.. container:: ulist

- Input interface with one or more inputs

.. container:: ulist

- each input with a carrier technology and an event

1684

protocol

1685

1686

- some inputs with optional synchronous mode

1687

1688

- some event protocols with additional parameters

1689

1690

- Output interface with one or more outputs

.. container:: ulist

- each output with a carrier technology and an event

1695

encoding

1696

1697

- some outputs with optional synchronous mode

1698

1699

- some event protocols with additional parameters

1700

1701

.. container:: paragraph

1702

1703

The configuration for input and output is contained in

1704

``eventInputParameters`` and ``eventOutputParameters``,

1705

respectively. Inside here, one can configure any number of

1706

inputs and outputs. Each of them needs to have a unique

1707

identifier (name), the content of the name is free form. The

1708

example below shows a configuration for two inputs and two

1709

outputs.

1710

1711

.. container:: listingblock

1712

1713

.. container:: content

1714

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1715

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1716

1717

"eventInputParameters": { (1)

1718

"FirstConsumer": { (2)

1719

"carrierTechnologyParameters" : {...}, (3)

1720

"eventProtocolParameters":{...}, (4)

1721

... (5)

1722

},

1723

"SecondConsumer": { (6)

1724

"carrierTechnologyParameters" : {...}, (7)

1725

"eventProtocolParameters":{...}, (8)

... (9)

},

},

"eventOutputParameters": { (10)

1730

"FirstProducer": { (11)

1731

"carrierTechnologyParameters":{...}, (12)

1732

"eventProtocolParameters":{...}, (13)

1733

... (14)

1734

},

1735

"SecondProducer": { (15)

1736

"carrierTechnologyParameters":{...}, (16)

1737

"eventProtocolParameters":{...}, (17)

... (18)

}

}

.. container:: colist arabic

1743

1744

+--------+--------------------------------------------------------------------+

1745

| **1** | input interface configuration, APEX input plugins |

1746

+--------+--------------------------------------------------------------------+

1747

| **2** | first input called ``FirstConsumer`` |

1748

+--------+--------------------------------------------------------------------+

1749

| **3** | carrier technology for plugin |

1750

+--------+--------------------------------------------------------------------+

1751

| **4** | event protocol for plugin |

1752

+--------+--------------------------------------------------------------------+

1753

| **5** | any other input configuration (e.g. event name filter, see below) |

1754

+--------+--------------------------------------------------------------------+

1755

| **6** | second input called ``SecondConsumer`` |

1756

+--------+--------------------------------------------------------------------+

1757

| **7** | carrier technology for plugin |

1758

+--------+--------------------------------------------------------------------+

1759

| **8** | event protocol for plugin |

1760

+--------+--------------------------------------------------------------------+

1761

| **9** | any other plugin configuration |

1762

+--------+--------------------------------------------------------------------+

1763

| **10** | output interface configuration, APEX output plugins |

1764

+--------+--------------------------------------------------------------------+

1765

| **11** | first output called ``FirstProducer`` |

1766

+--------+--------------------------------------------------------------------+

1767

| **12** | carrier technology for plugin |

1768

+--------+--------------------------------------------------------------------+

1769

| **13** | event protocol for plugin |

1770

+--------+--------------------------------------------------------------------+

1771

| **14** | any other plugin configuration |

1772

+--------+--------------------------------------------------------------------+

1773

| **15** | second output called ``SecondProducer`` |

1774

+--------+--------------------------------------------------------------------+

1775

| **16** | carrier technology for plugin |

1776

+--------+--------------------------------------------------------------------+

1777

| **17** | event protocol for plugin |

1778

+--------+--------------------------------------------------------------------+

1779

| **18** | any other output configuration (e.g. event name filter, see below) |

1780

+--------+--------------------------------------------------------------------+

Event Filters

#############

.. container:: paragraph

1786

1787

APEX will always send an event after a policy execution

1788

is finished. For a successful execution, the event sent

1789

is the output event created by the policy. In case the

1790

policy does not create an output event, APEX will create

1791

a new event with all input event fields plus an

1792

additional field ``exceptionMessage`` with an exception

1793

message.

1794

1795

.. container:: paragraph

1796

1797

There are situations in which this auto-generated error

1798

event might not be required or wanted:

.. container:: ulist

- when a policy failing should not result in an event

1803

send out via an output interface

1804

1805

- when the auto-generated event goes back in an APEX

1806

engine (or the same APEX engine), this can create

1807

endless loops

1808

1809

- the auto-generated event should go to a special output

1810

interface or channel

1811

1812

.. container:: paragraph

1813

1814

All of these situations are supported by a filter option

1815

using a wildecard (regular expression) configuration on

1816

APEX I/O interfaces. The parameter is called

1817

``eventNameFilter`` and the value are `Java regular

1818

expressions <https://docs.oracle.com/javase/8/docs/api/java/util/regex/Pattern.html>`__

1819

(a

1820

`tutorial <http://www.vogella.com/tutorials/JavaRegularExpressions/article.html>`__).

1821

The following code shows some examples:

1822

1823

.. container:: listingblock

1824

1825

.. container:: content

1826

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1827

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1828

1829

"eventInputParameters": {

1830

"Input1": {

1831

"carrierTechnologyParameters" : {...},

1832

"eventProtocolParameters":{...},

1833

"eventNameFilter" : "^E[Vv][Ee][Nn][Tt][0-9]004$" (1)

1834

}

1835

},

1836

"eventOutputParameters": {

1837

"Output1": {

1838

"carrierTechnologyParameters":{...},

1839

"eventProtocolParameters":{...},

1840

"eventNameFilter" : "^E[Vv][Ee][Nn][Tt][0-9]104$" (2)

}

}

Executors

---------

.. container:: paragraph

1848

1849

Executors are plugins that realize the execution of logic

1850

contained in a policy model. Logic can be in a task

1851

selector, a task, and a state finalizer. Using plugins for

1852

execution environments makes APEX very flexible to support

1853

virtually any executable logic expressions.

1854

1855

.. container:: paragraph

1856

1857

APEX 2.0.0-SNAPSHOT supports the following executors:

.. container:: ulist

- Java, for Java implemented logic

.. container:: ulist

- This executor requires logic implemented using the

1866

APEX Java interfaces.

1867

1868

- Generated JAR files must be in the classpath of the

1869

APEX engine at start time.

- Javascript

- JRuby,

- Jython,

- MVEL

.. container:: ulist

- This executor uses the latest version of the MVEL

1882

engine, which can be very hard to debug and can

1883

produce unwanted side effects during execution

1884

1885

Configure the Javascript Executor

1886

#################################

1887

1888

.. container:: paragraph

1889

1890

The Javascript executor is added to the configuration as

1891

follows:

1892

1893

.. container:: listingblock

1894

1895

.. container:: content

1896

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1897

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1898

1899

"engineServiceParameters":{

1900

"engineParameters":{

1901

"executorParameters":{

1902

"JAVASCRIPT":{

1903

"parameterClassName" :

1904

"org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"

}

}

}

}

Configure the Jython Executor

1911

#############################

1912

1913

.. container:: paragraph

1914

1915

The Jython executor is added to the configuration as

1916

follows:

1917

1918

.. container:: listingblock

1919

1920

.. container:: content

1921

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1922

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1923

1924

"engineServiceParameters":{

1925

"engineParameters":{

1926

"executorParameters":{

1927

"JYTHON":{

1928

"parameterClassName" :

1929

"org.onap.policy.apex.plugins.executor.jython.JythonExecutorParameters"

}

}

}

}

Configure the JRuby Executor

1936

############################

1937

1938

.. container:: paragraph

1939

1940

The JRuby executor is added to the configuration as

1941

follows:

1942

1943

.. container:: listingblock

1944

1945

.. container:: content

1946

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1947

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1948

1949

"engineServiceParameters":{

1950

"engineParameters":{

1951

"executorParameters":{

1952

"JRUBY":{

1953

"parameterClassName" :

1954

"org.onap.policy.apex.plugins.executor.jruby.JrubyExecutorParameters"

}

}

}

}

Configure the Java Executor

1961

###########################

1962

1963

.. container:: paragraph

1964

1965

The Java executor is added to the configuration as

1966

follows:

1967

1968

.. container:: listingblock

1969

1970

.. container:: content

1971

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1972

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1973

1974

"engineServiceParameters":{

1975

"engineParameters":{

1976

"executorParameters":{

1977

"JAVA":{

1978

"parameterClassName" :

1979

"org.onap.policy.apex.plugins.executor.java.JavaExecutorParameters"

}

}

}

}

Configure the MVEL Executor

1986

###########################

1987

1988

.. container:: paragraph

1989

1990

The MVEL executor is added to the configuration as

1991

follows:

1992

1993

.. container:: listingblock

1994

1995

.. container:: content

1996

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

1997

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

1998

1999

"engineServiceParameters":{

2000

"engineParameters":{

2001

"executorParameters":{

2002

"MVEL":{

2003

"parameterClassName" :

2004

"org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"

}

}

}

}

Context Handlers

----------------

.. container:: paragraph

2014

2015

Context handlers are responsible for all context processing.

2016

There are the following main areas:

.. container:: ulist

- Context schema: use schema handlers other than Java class

2021

(supported by default without configuration)

2022

2023

- Context distribution: distribute context across multiple

2024

APEX engines

2025

2026

- Context locking: mechanisms to lock context elements for

2027

read/write

2028

2029

- Context persistence: mechanisms to persist context

2030

2031

.. container:: paragraph

2032

2033

APEX provides plugins for each of the main areas.

2034

2035

Configure AVRO Schema Handler

2036

#############################

2037

2038

.. container:: paragraph

2039

2040

The AVRO schema handler is added to the configuration as

2041

follows:

2042

2043

.. container:: listingblock

2044

2045

.. container:: content

2046

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2047

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2048

2049

"engineServiceParameters":{

2050

"engineParameters":{

2051

"contextParameters":{

2052

"parameterClassName" : "org.onap.policy.apex.context.parameters.ContextParameters",

2053

"schemaParameters":{

2054

"Avro":{

2055

"parameterClassName" :

2056

"org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters"

}

}

}

}

}

.. container:: paragraph

2064

2065

Using the AVRO schema handler has one limitation: AVRO

2066

only supports field names that represent valid Java class

2067

names. This means only letters and the character ``_``

2068

are supported. Characters commonly used in field names,

2069

such as ``.`` and ``-``, are not supported by AVRO. for

2070

more information see `Avro Spec:

2071

Names <https://avro.apache.org/docs/1.8.1/spec.html#names>`__.

2072

2073

.. container:: paragraph

2074

2075

To work with this limitation, the APEX Avro plugin will

2076

parse a given AVRO definition and replace *all*

2077

occurrences of ``.`` and ``-`` with a ``_``. This means

that

.. container:: ulist

- In a policy model, if the AVRO schema defined a field

2083

as ``my-name`` the policy logic should access it as

2084

``my_name``

2085

2086

- In a policy model, if the AVRO schema defined a field

2087

as ``my.name`` the policy logic should access it as

2088

``my_name``

2089

2090

- There should be no field names that convert to the

same internal name

.. container:: ulist

- For instance the simultaneous use of

2096

``my_name``, ``my.name``, and ``my-name`` should

2097

be avoided

2098

2099

- If not avoided, the event processing might

2100

create unwanted side effects

2101

2102

- If field names use any other not-supported character,

2103

the AVRO plugin will reject it

.. container:: ulist

- Since AVRO uses lazy initialization, this

2108

rejection might only become visible at runtime

2109

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

2110

Configure Task Parameters

2111

#########################

2112

2113

.. container:: paragraph

2114

2115

The Task Parameters are added to the configuration as

2116

follows:

2117

2118

.. container:: listingblock

2119

2120

.. container:: content

.. code::

"engineServiceParameters": {

2125

"engineParameters": {

2126

"taskParameters": [

2127

{

2128

"key": "ParameterKey1",

2129

"value": "ParameterValue1"

2130

},

2131

{

2132

"taskId": "Task_Act0",

2133

"key": "ParameterKey2",

2134

"value": "ParameterValue2"

}

]

}

}

.. container:: paragraph

2141

2142

TaskParameters can be used to pass parameters from ApexConfig

2143

to the policy logic. In the config, these are optional.

2144

The list of task parameters provided in the config may be added

2145

to the tasks or existing task parameters in the task will be overriden.

2146

2147

.. container:: paragraph

2148

2149

If taskId is provided in ApexConfig for an entry, then that

2150

parameter is updated only for that particular task. Otherwise,

2151

the task parameter is added to all tasks.

2152

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

Carrier Technologies

--------------------

.. container:: paragraph

2157

2158

Carrier technologies define how APEX receives (input) and

2159

sends (output) events. They can be used in any combination,

2160

using asynchronous or synchronous mode. There can also be

2161

any number of carrier technologies for the input (consume)

2162

and the output (produce) interface.

2163

2164

.. container:: paragraph

2165

2166

Supported *input* technologies are:

.. container:: ulist

- Standard input, read events from the standard input

2171

(console), not suitable for APEX background servers

2172

2173

- File input, read events from a file

2174

2175

- Kafka, read events from a Kafka system

2176

2177

- Websockets, read events from a Websocket

- JMS,

- REST (synchronous and asynchronous), additionally as

2182

client or server

2183

2184

- Event Requestor, allows reading of events that have been

2185

looped back into APEX

2186

2187

.. container:: paragraph

2188

2189

Supported *output* technologies are:

.. container:: ulist

- Standard output, write events to the standard output

2194

(console), not suitable for APEX background servers

2195

2196

- File output, write events to a file

2197

2198

- Kafka, write events to a Kafka system

2199

2200

- Websockets, write events to a Websocket

- JMS

- REST (synchronous and asynchronous), additionally as

2205

client or server

2206

2207

- Event Requestor, allows events to be looped back into

2208

APEX

2209

2210

.. container:: paragraph

2211

2212

New carrier technologies can be added as plugins to APEX or

2213

developed outside APEX and added to an APEX deployment.

Standard IO

###########

.. container:: paragraph

2219

2220

Standard IO does not require a specific plugin, it is

2221

supported be default.

Standard Input

==============

.. container:: paragraph

2226

2227

APEX will take events from its standard input. This

2228

carrier is good for testing, but certainly not for a

2229

use case where APEX runs as a server. The

2230

configuration is as follows:

2231

2232

.. container:: listingblock

2233

2234

.. container:: content

::

"carrierTechnologyParameters" : {

2239

"carrierTechnology" : "FILE", (1)

2240

"parameters" : {

2241

"standardIO" : true (2)

}

}

.. container:: colist arabic

2246

2247

+-------+---------------------------------------+

2248

| **1** | standard input is considered a file |

2249

+-------+---------------------------------------+

2250

| **2** | file descriptor set to standard input |

2251

+-------+---------------------------------------+

Standard Output

===============

.. container:: paragraph

2257

2258

APEX will send events to its standard output. This

2259

carrier is good for testing, but certainly not for a

2260

use case where APEX runs as a server. The

2261

configuration is as follows:

2262

2263

.. container:: listingblock

2264

2265

.. container:: content

2266

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2267

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2268

2269

"carrierTechnologyParameters" : {

2270

"carrierTechnology" : "FILE", (1)

2271

"parameters" : {

2272

"standardIO" : true (2)

}

}

.. container:: colist arabic

2277

2278

+-------+----------------------------------------+

2279

| **1** | standard output is considered a file |

2280

+-------+----------------------------------------+

2281

| **2** | file descriptor set to standard output |

2282

+-------+----------------------------------------+

2.7.2. File IO

##############

.. container:: paragraph

2288

2289

File IO does not require a specific plugin, it is

2290

supported be default.

File Input

==========

.. container:: paragraph

2296

2297

APEX will take events from a file. The same file

2298

should not be used as an output. The configuration is

2299

as follows:

2300

2301

.. container:: listingblock

2302

2303

.. container:: content

2304

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2305

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2306

2307

"carrierTechnologyParameters" : {

2308

"carrierTechnology" : "FILE", (1)

2309

"parameters" : {

2310

"fileName" : "examples/events/SampleDomain/EventsIn.xmlfile" (2)

}

}

.. container:: colist arabic

2315

2316

+-------+------------------------------------------+

2317

| **1** | set file input |

2318

+-------+------------------------------------------+

2319

| **2** | the name of the file to read events from |

2320

+-------+------------------------------------------+

File Output

===========

.. container:: paragraph

2325

2326

APEX will write events to a file. The same file should

2327

not be used as an input. The configuration is as

2328

follows:

2329

2330

.. container:: listingblock

2331

2332

.. container:: content

2333

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2334

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2335

2336

"carrierTechnologyParameters" : {

2337

"carrierTechnology" : "FILE", (1)

2338

"parameters" : {

2339

"fileName" : "examples/events/SampleDomain/EventsOut.xmlfile" (2)

}

}

.. container:: colist arabic

2344

2345

+-------+-----------------------------------------+

2346

| **1** | set file output |

2347

+-------+-----------------------------------------+

2348

| **2** | the name of the file to write events to |

2349

+-------+-----------------------------------------+

Event Requestor IO

##################

.. container:: paragraph

2355

2356

Event Requestor IO does not require a specific plugin, it

2357

is supported be default. It should only be used with the

2358

APEX event protocol.

2359

2360

Event Requestor Input

2361

=====================

2362

2363

.. container:: paragraph

2364

2365

APEX will take events from APEX.

2366

2367

.. container:: listingblock

2368

2369

.. container:: content

2370

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2371

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2372

2373

"carrierTechnologyParameters" : {

2374

"carrierTechnology": "EVENT_REQUESTOR" (1)

2375

}

2376

2377

.. container:: colist arabic

2378

2379

+-------+---------------------------+

2380

| **1** | set event requestor input |

2381

+-------+---------------------------+

2382

2383

Event Requestor Output

2384

======================

2385

2386

.. container:: paragraph

2387

2388

APEX will write events to APEX.

2389

2390

.. container:: listingblock

2391

2392

.. container:: content

2393

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2394

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2395

2396

"carrierTechnologyParameters" : {

2397

"carrierTechnology": "EVENT_REQUESTOR" (1)

2398

}

2399

2400

Peering Event Requestors

2401

========================

2402

2403

.. container:: paragraph

2404

2405

When using event requestors, they need to be peered.

2406

This means an event requestor output needs to be

2407

peered (associated) with an event requestor input. The

2408

following example shows the use of an event requestor

2409

with the APEX event protocol and the peering of output

2410

and input.

2411

2412

.. container:: listingblock

2413

2414

.. container:: content

2415

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2416

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2417

2418

"eventInputParameters": {

2419

"EventRequestorConsumer": {

2420

"carrierTechnologyParameters": {

2421

"carrierTechnology": "EVENT_REQUESTOR" (1)

2422

},

2423

"eventProtocolParameters": {

2424

"eventProtocol": "APEX" (2)

2425

},

2426

"eventNameFilter": "InputEvent", (3)

2427

"requestorMode": true, (4)

2428

"requestorPeer": "EventRequestorProducer", (5)

2429

"requestorTimeout": 500 (6)

2430

}

2431

},

2432

"eventOutputParameters": {

2433

"EventRequestorProducer": {

2434

"carrierTechnologyParameters": {

2435

"carrierTechnology": "EVENT_REQUESTOR" (7)

2436

},

2437

"eventProtocolParameters": {

2438

"eventProtocol": "APEX" (8)

2439

},

2440

"eventNameFilter": "EventListEvent", (9)

2441

"requestorMode": true, (10)

2442

"requestorPeer": "EventRequestorConsumer", (11)

2443

"requestorTimeout": 500 (12)

}

}

.. container:: colist arabic

2448

2449

+-----------------------------------+-----------------------------------+

2450

| **1** | event requestor on a consumer |

2451

+-----------------------------------+-----------------------------------+

2452

| **2** | with APEX event protocol |

2453

+-----------------------------------+-----------------------------------+

2454

| **3** | optional filter (best to use a |

2455

| | filter to prevent unwanted events |

2456

| | on the consumer side) |

2457

+-----------------------------------+-----------------------------------+

2458

| **4** | activate requestor mode |

2459

+-----------------------------------+-----------------------------------+

2460

| **5** | the peer to the output (must |

2461

| | match the output carrier) |

2462

+-----------------------------------+-----------------------------------+

2463

| **6** | an optional timeout in |

2464

| | milliseconds |

2465

+-----------------------------------+-----------------------------------+

2466

| **7** | event requestor on a producer |

2467

+-----------------------------------+-----------------------------------+

2468

| **8** | with APEX event protocol |

2469

+-----------------------------------+-----------------------------------+

2470

| **9** | optional filter (best to use a |

2471

| | filter to prevent unwanted events |

2472

| | on the consumer side) |

2473

+-----------------------------------+-----------------------------------+

2474

| **10** | activate requestor mode |

2475

+-----------------------------------+-----------------------------------+

2476

| **11** | the peer to the output (must |

2477

| | match the input carrier) |

2478

+-----------------------------------+-----------------------------------+

2479

| **12** | an optional timeout in |

2480

| | milliseconds |

2481

+-----------------------------------+-----------------------------------+

Kafka IO

########

.. container:: paragraph

2487

2488

Kafka IO is supported by the APEX Kafka plugin. The

2489

configurations below are examples. APEX will take any

2490

configuration inside the parameter object and forward it

2491

to Kafka. More information on Kafka specific

2492

configuration parameters can be found in the Kafka

documentation:

.. container:: ulist

- `Kafka Consumer

Class <https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/consumer/KafkaConsumer.html>`__

2499

2500

- `Kafka Producer

2501

Class <https://kafka.apache.org/090/javadoc/org/apache/kafka/clients/producer/KafkaProducer.html>`__

Kafka Input

===========

.. container:: paragraph

2506

2507

APEX will receive events from the Apache Kafka

2508

messaging system. The input is uni-directional, an

2509

engine will only receive events from the input but not

2510

send any event to the input.

2511

2512

.. container:: listingblock

2513

2514

.. container:: content

2515

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2516

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2517

2518

"carrierTechnologyParameters" : {

2519

"carrierTechnology" : "KAFKA", (1)

2520

"parameterClassName" :

2521

"org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters",

2522

"parameters" : {

2523

"bootstrapServers" : "localhost:49092", (2)

2524

"groupId" : "apex-group-id", (3)

2525

"enableAutoCommit" : true, (4)

2526

"autoCommitTime" : 1000, (5)

2527

"sessionTimeout" : 30000, (6)

2528

"consumerPollTime" : 100, (7)

2529

"consumerTopicList" : ["apex-in-0", "apex-in-1"], (8)

2530

"keyDeserializer" :

2531

"org.apache.kafka.common.serialization.StringDeserializer", (9)

2532

"valueDeserializer" :

2533

"org.apache.kafka.common.serialization.StringDeserializer" (10)

}

}

.. container:: colist arabic

2538

2539

+--------+-------------------------------------+

2540

| **1** | set Kafka as carrier technology |

2541

+--------+-------------------------------------+

2542

| **2** | bootstrap server and port |

2543

+--------+-------------------------------------+

2544

| **3** | a group identifier |

2545

+--------+-------------------------------------+

2546

| **4** | flag for auto-commit |

2547

+--------+-------------------------------------+

2548

| **5** | auto-commit timeout in milliseconds |

2549

+--------+-------------------------------------+

2550

| **6** | session timeout in milliseconds |

2551

+--------+-------------------------------------+

2552

| **7** | consumer poll time in milliseconds |

2553

+--------+-------------------------------------+

2554

| **8** | consumer topic list |

2555

+--------+-------------------------------------+

2556

| **9** | key for the Kafka de-serializer |

2557

+--------+-------------------------------------+

2558

| **10** | value for the Kafka de-serializer |

2559

+--------+-------------------------------------+

Kafka Output

============

.. container:: paragraph

2564

2565

APEX will send events to the Apache Kafka messaging

2566

system. The output is uni-directional, an engine will

2567

send events to the output but not receive any event

2568

from the output.

2569

2570

.. container:: listingblock

2571

2572

.. container:: content

2573

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2574

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2575

2576

"carrierTechnologyParameters" : {

2577

"carrierTechnology" : "KAFKA", (1)

2578

"parameterClassName" :

2579

"org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters",

2580

"parameters" : {

2581

"bootstrapServers" : "localhost:49092", (2)

2582

"acks" : "all", (3)

2583

"retries" : 0, (4)

2584

"batchSize" : 16384, (5)

2585

"lingerTime" : 1, (6)

2586

"bufferMemory" : 33554432, (7)

2587

"producerTopic" : "apex-out", (8)

2588

"keySerializer" :

2589

"org.apache.kafka.common.serialization.StringSerializer", (9)

2590

"valueSerializer" :

2591

"org.apache.kafka.common.serialization.StringSerializer" (10)

}

}

.. container:: colist arabic

2596

2597

+--------+---------------------------------+

2598

| **1** | set Kafka as carrier technology |

2599

+--------+---------------------------------+

2600

| **2** | bootstrap server and port |

2601

+--------+---------------------------------+

2602

| **3** | acknowledgement strategy |

2603

+--------+---------------------------------+

2604

| **4** | number of retries |

2605

+--------+---------------------------------+

2606

| **5** | batch size |

2607

+--------+---------------------------------+

2608

| **6** | time to linger in milliseconds |

2609

+--------+---------------------------------+

2610

| **7** | buffer memory in byte |

2611

+--------+---------------------------------+

2612

| **8** | producer topic |

2613

+--------+---------------------------------+

2614

| **9** | key for the Kafka serializer |

2615

+--------+---------------------------------+

2616

| **10** | value for the Kafka serializer |

2617

+--------+---------------------------------+

JMS IO

#######

.. container:: paragraph

2623

2624

APEX supports the Java Messaging Service (JMS) as input

2625

as well as output. JMS IO is supported by the APEX JMS

2626

plugin. Input and output support an event encoding as

2627

text (JSON string) or object (serialized object). The

2628

input configuration is the same for both encodings, the

2629

output configuration differs.

JMS Input

=========

.. container:: paragraph

2634

2635

APEX will receive events from a JMS messaging system.

2636

The input is uni-directional, an engine will only

2637

receive events from the input but not send any event

2638

to the input.

2639

2640

.. container:: listingblock

2641

2642

.. container:: content

2643

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2644

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2645

2646

"carrierTechnologyParameters" : {

2647

"carrierTechnology" : "JMS", (1)

2648

"parameterClassName" :

2649

"org.onap.policy.apex.plugins.event.carrier.jms.JMSCarrierTechnologyParameters",

2650

"parameters" : { (2)

2651

"initialContextFactory" :

2652

"org.jboss.naming.remote.client.InitialContextFactory", (3)

2653

"connectionFactory" : "ConnectionFactory", (4)

2654

"providerURL" : "remote://localhost:5445", (5)

2655

"securityPrincipal" : "guest", (6)

2656

"securityCredentials" : "IAmAGuest", (7)

2657

"consumerTopic" : "jms/topic/apexIn" (8)

}

}

.. container:: colist arabic

2662

2663

+-----------------------------------+-----------------------------------+

2664

| **1** | set JMS as carrier technology |

2665

+-----------------------------------+-----------------------------------+

2666

| **2** | set all JMS specific parameters |

2667

+-----------------------------------+-----------------------------------+

2668

| **3** | the context factory, in this case |

2669

| | from JBOSS (it requires the |

2670

| | dependency |

2671

| | org.jboss:jboss-remote-naming:2.0 |

2672

| | .4.Final |

2673

| | or a different version to be in |

2674

| | the directory ``$APEX_HOME/lib`` |

2675

| | or ``%APEX_HOME%\lib`` |

2676

+-----------------------------------+-----------------------------------+

2677

| **4** | a connection factory for the JMS |

2678

| | connection |

2679

+-----------------------------------+-----------------------------------+

2680

| **5** | URL with host and port of the JMS |

2681

| | provider |

2682

+-----------------------------------+-----------------------------------+

2683

| **6** | access credentials, user name |

2684

+-----------------------------------+-----------------------------------+

2685

| **7** | access credentials, user password |

2686

+-----------------------------------+-----------------------------------+

2687

| **8** | the JMS topic to listen to |

2688

+-----------------------------------+-----------------------------------+

JMS Output with Text

====================

.. container:: paragraph

2694

2695

APEX engine send events to a JMS messaging system. The

2696

output is uni-directional, an engine will send events

2697

to the output but not receive any event from output.

2698

2699

.. container:: listingblock

2700

2701

.. container:: content

2702

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2703

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2704

2705

"carrierTechnologyParameters" : {

2706

"carrierTechnology" : "JMS", (1)

2707

"parameterClassName" :

2708

"org.onap.policy.apex.plugins.event.carrier.jms.JMSCarrierTechnologyParameters",

2709

"parameters" : { (2)

2710

"initialContextFactory" :

2711

"org.jboss.naming.remote.client.InitialContextFactory", (3)

2712

"connectionFactory" : "ConnectionFactory", (4)

2713

"providerURL" : "remote://localhost:5445", (5)

2714

"securityPrincipal" : "guest", (6)

2715

"securityCredentials" : "IAmAGuest", (7)

2716

"producerTopic" : "jms/topic/apexOut", (8)

2717

"objectMessageSending": "false" (9)

}

}

.. container:: colist arabic

2722

2723

+-----------------------------------+-----------------------------------+

2724

| **1** | set JMS as carrier technology |

2725

+-----------------------------------+-----------------------------------+

2726

| **2** | set all JMS specific parameters |

2727

+-----------------------------------+-----------------------------------+

2728

| **3** | the context factory, in this case |

2729

| | from JBOSS (it requires the |

2730

| | dependency |

2731

| | org.jboss:jboss-remote-naming:2.0 |

2732

| | .4.Final |

2733

| | or a different version to be in |

2734

| | the directory ``$APEX_HOME/lib`` |

2735

| | or ``%APEX_HOME%\lib`` |

2736

+-----------------------------------+-----------------------------------+

2737

| **4** | a connection factory for the JMS |

2738

| | connection |

2739

+-----------------------------------+-----------------------------------+

2740

| **5** | URL with host and port of the JMS |

2741

| | provider |

2742

+-----------------------------------+-----------------------------------+

2743

| **6** | access credentials, user name |

2744

+-----------------------------------+-----------------------------------+

2745

| **7** | access credentials, user password |

2746

+-----------------------------------+-----------------------------------+

2747

| **8** | the JMS topic to write to |

2748

+-----------------------------------+-----------------------------------+

2749

| **9** | set object messaging to ``false`` |

2750

| | means it sends JSON text |

2751

+-----------------------------------+-----------------------------------+

2752

2753

JMS Output with Object

2754

======================

2755

2756

.. container:: paragraph

2757

2758

To configure APEX for JMS objects on the output

2759

interface use the same configuration as above (for

2760

output). Simply change the ``objectMessageSending``

2761

parameter to ``true``.

2762

2763

Websocket (WS) IO

2764

########################

2765

2766

.. container:: paragraph

2767

2768

APEX supports the Websockets as input as well as output.

2769

WS IO is supported by the APEX Websocket plugin. This

2770

carrier technology does only support uni-directional

2771

communication. APEX will not send events to a Websocket

2772

input and any event sent to a Websocket output will

2773

result in an error log.

2774

2775

.. container:: paragraph

2776

2777

The input can be configured as client (APEX connects to

2778

an existing Websocket server) or server (APEX starts a

2779

Websocket server). The same applies to the output. Input

2780

and output can both use a client or a server

2781

configuration, or separate configurations (input as

2782

client and output as server, input as server and output

2783

as client). Each configuration should use its own

2784

dedicated port to avoid any communication loops. The

2785

configuration of a Websocket client is the same for input

2786

and output. The configuration of a Websocket server is

2787

the same for input and output.

Websocket Client

================

.. container:: paragraph

2793

2794

APEX will connect to a given Websocket server. As

2795

input, it will receive events from the server but not

2796

send any events. As output, it will send events to the

2797

server and any event received from the server will

2798

result in an error log.

2799

2800

.. container:: listingblock

2801

2802

.. container:: content

2803

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2804

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2805

2806

"carrierTechnologyParameters" : {

2807

"carrierTechnology" : "WEBSOCKET", (1)

2808

"parameterClassName" :

2809

"org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",

2810

"parameters" : {

2811

"host" : "localhost", (2)

"port" : 42451 (3)

}

}

.. container:: colist arabic

2817

2818

+-------+------------------------------------------------------+

2819

| **1** | set Websocket as carrier technology |

2820

+-------+------------------------------------------------------+

2821

| **2** | the host name on which a Websocket server is running |

2822

+-------+------------------------------------------------------+

2823

| **3** | the port of that Websocket server |

2824

+-------+------------------------------------------------------+

Websocket Server

================

.. container:: paragraph

2830

2831

APEX will start a Websocket server, which will accept

2832

any Websocket clients to connect. As input, it will

2833

receive events from the server but not send any

2834

events. As output, it will send events to the server

2835

and any event received from the server will result in

2836

an error log.

2837

2838

.. container:: listingblock

2839

2840

.. container:: content

2841

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2842

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2843

2844

"carrierTechnologyParameters" : {

2845

"carrierTechnology" : "WEBSOCKET", (1)

2846

"parameterClassName" :

2847

"org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",

2848

"parameters" : {

2849

"wsClient" : false, (2)

"port" : 42450 (3)

}

}

.. container:: colist arabic

2855

2856

+-------+------------------------------------------------------------+

2857

| **1** | set Websocket as carrier technology |

2858

+-------+------------------------------------------------------------+

2859

| **2** | disable client, so that APEX will start a Websocket server |

2860

+-------+------------------------------------------------------------+

2861

| **3** | the port for the Websocket server APEX will start |

2862

+-------+------------------------------------------------------------+

REST Client IO

##############

.. container:: paragraph

2868

2869

APEX can act as REST client on the input as well as on

2870

the output interface. The media type is

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

2871

``application/json``, so this plugin only works with

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2872

the JSON Event protocol.

REST Client Input

=================

.. container:: paragraph

2878

2879

APEX will connect to a given URL to receive events,

2880

but not send any events. The server is polled, i.e.

2881

APEX will do an HTTP GET, take the result, and then do

2882

the next GET. Any required timing needs to be handled

2883

by the server configured via the URL. For instance,

2884

the server could support a wait timeout via the URL as

2885

``?timeout=100ms``.

Henry.Sun

2019-07-22 08:32:32 +0000

[diff] [blame]

2886

The httpCodeFilter is used for filtering the status

2887

code, and it can be configured as a regular expression

2888

string. The default httpCodeFilter is "[2][0-9][0-9]"

2889

- for successful response codes.

2890

The response with HTTP status code that matches the

2891

given regular expression is forwarded to the task,

2892

otherwise it is logged as a failure.

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2893

2894

.. container:: listingblock

2895

2896

.. container:: content

2897

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2898

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2899

2900

"carrierTechnologyParameters" : {

2901

"carrierTechnology" : "RESTCLIENT", (1)

2902

"parameterClassName" :

2903

"org.onap.policy.apex.plugins.event.carrier.restclient.RESTClientCarrierTechnologyParameters",

2904

"parameters" : {

2905

"url" : "http://example.org:8080/triggers/events", (2)

Henry.Sun

2019-07-22 08:32:32 +0000

[diff] [blame]

2906

"httpCodeFilter" : "[2][0-9][0-9]" (3)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

}

}

.. container:: colist arabic

2911

Henry.Sun

2019-07-22 08:32:32 +0000

[diff] [blame]

2912

+-------+--------------------------------------------------+

2913

| **1** | set REST client as carrier technology |

2914

+-------+--------------------------------------------------+

2915

| **2** | the URL of the HTTP server for events |

2916

+-------+--------------------------------------------------+

2917

| **3** | use HTTP CODE FILTER for filtering status code |

2918

+-------+--------------------------------------------------+

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

REST Client Output

==================

.. container:: paragraph

2924

2925

APEX will connect to a given URL to send events, but

2926

not receive any events. The default HTTP operation is

2927

POST (no configuration required). To change it to PUT

2928

simply add the configuration parameter (as shown in

2929

the example below).

ning.xi

2019-07-18 07:50:10 +0000

[diff] [blame]

2930

The URL can be configured statically or tagged

2931

as ``?example.{site}.org:8080/{trig}/events``,

2932

all tags such as ``site`` and ``trig`` in the URL

Henry.Sun

2019-07-22 08:32:32 +0000

[diff] [blame]

2933

need to be set in the properties object available to

2934

the tasks. In addition, the keys should exactly match

2935

with the tags defined in url. The scope of the properties

2936

object is per HTTP call. Hence, key/value pairs set

2937

in the properties object by task are only available

2938

for that specific HTTP call.

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2939

2940

.. container:: listingblock

2941

2942

.. container:: content

2943

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

2944

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2945

2946

"carrierTechnologyParameters" : {

2947

"carrierTechnology" : "RESTCLIENT", (1)

2948

"parameterClassName" :

2949

"org.onap.policy.apex.plugins.event.carrier.restclient.RESTClientCarrierTechnologyParameters",

2950

"parameters" : {

2951

"url" : "http://example.com:8888/actions/events", (2)

ning.xi

2019-07-18 07:50:10 +0000

[diff] [blame]

2952

"url" : "http://example.{site}.com:8888/{trig}/events", (2')

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2953

"httpMethod" : "PUT" (3)

}

}

.. container:: colist arabic

2958

2959

+-------+--------------------------------------------------+

2960

| **1** | set REST client as carrier technology |

2961

+-------+--------------------------------------------------+

ning.xi

2019-07-18 07:50:10 +0000

[diff] [blame]

2962

| **2** | the static URL of the HTTP server for events |

2963

+-------+--------------------------------------------------+

2964

| **2'**| the tagged URL of the HTTP server for events |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

2965

+-------+--------------------------------------------------+

2966

| **3** | use HTTP PUT (remove this line to use HTTP POST) |

2967

+-------+--------------------------------------------------+

REST Server IO

##############

.. container:: paragraph

2973

2974

APEX supports a REST server for input and output.

2975

2976

.. container:: paragraph

2977

2978

The REST server plugin always uses a synchronous mode. A

2979

client does a HTTP GET on the APEX REST server with the

2980

input event and receives the generated output event in

2981

the server reply. This means that for the REST server

2982

there has to always to be an input with an associated

2983

output. Input or output only are not permitted.

2984

2985

.. container:: paragraph

2986

2987

The plugin will start a Grizzly server as REST server for

2988

a normal APEX engine. If the APEX engine is executed as a

2989

servlet, for instance inside Tomcat, then Tomcat will be

2990

used as REST server (this case requires configuration on

2991

Tomcat as well).

2992

2993

.. container:: paragraph

2994

2995

Some configuration restrictions apply for all scenarios:

.. container:: ulist

- Minimum port: 1024

- Maximum port: 65535

3002

3003

- The media type is ``application/json``, so this plugin

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

3004

only works with the JSON Event protocol.

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3005

3006

.. container:: paragraph

3007

3008

The URL the client calls is created using

.. container:: ulist

- the configured host and port, e.g.

3013

``http://localhost:12345``

3014

3015

- the standard path, e.g. ``/apex/``

3016

3017

- the name of the input/output, e.g. ``FirstConsumer/``

3018

3019

- the input or output name, e.g. ``EventIn``.

3020

3021

.. container:: paragraph

3022

3023

The examples above lead to the URL

3024

``http://localhost:12345/apex/FirstConsumer/EventIn``.

3025

3026

.. container:: paragraph

3027

3028

A client can also get status information of the REST

3029

server using ``/Status``, e.g.

3030

``http://localhost:12345/apex/FirstConsumer/Status``.

3031

3032

REST Server Stand-alone

3033

=======================

3034

3035

.. container:: paragraph

3036

3037

We need to configure a REST server input and a REST

3038

server output. Input and output are associated with

3039

each other via there name.

3040

3041

.. container:: paragraph

3042

3043

Timeouts for REST calls need to be set carefully. If

3044

they are too short, the call might timeout before a

3045

policy finished creating an event.

3046

3047

.. container:: paragraph

3048

3049

The following example configures the input named as

3050

``MyConsumer`` and associates an output named

3051

``MyProducer`` with it.

3052

3053

.. container:: listingblock

3054

3055

.. container:: content

3056

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3057

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3058

3059

"eventInputParameters": {

3060

"MyConsumer": {

3061

"carrierTechnologyParameters" : {

3062

"carrierTechnology" : "RESTSERVER", (1)

3063

"parameterClassName" :

3064

"org.onap.policy.apex.plugins.event.carrier.restserver.RESTServerCarrierTechnologyParameters",

3065

"parameters" : {

3066

"standalone" : true, (2)

3067

"host" : "localhost", (3)

"port" : 12345 (4)

}

},

"eventProtocolParameters":{

3072

"eventProtocol" : "JSON" (5)

3073

},

3074

"synchronousMode" : true, (6)

3075

"synchronousPeer" : "MyProducer", (7)

3076

"synchronousTimeout" : 500 (8)

}

}

.. container:: colist arabic

3081

3082

+-------+---------------------------------------+

3083

| **1** | set REST server as carrier technology |

3084

+-------+---------------------------------------+

3085

| **2** | set the server as stand-alone |

3086

+-------+---------------------------------------+

3087

| **3** | set the server host |

3088

+-------+---------------------------------------+

3089

| **4** | set the server listen port |

3090

+-------+---------------------------------------+

3091

| **5** | use JSON event protocol |

3092

+-------+---------------------------------------+

3093

| **6** | activate synchronous mode |

3094

+-------+---------------------------------------+

3095

| **7** | associate an output ``MyProducer`` |

3096

+-------+---------------------------------------+

3097

| **8** | set a timeout of 500 milliseconds |

3098

+-------+---------------------------------------+

3099

3100

.. container:: paragraph

3101

3102

The following example configures the output named as

3103

``MyProducer`` and associates the input ``MyConsumer``

3104

with it. Note that for the output there are no more

3105

paramters (such as host or port), since they are

3106

already configured in the associated input

3107

3108

.. container:: listingblock

3109

3110

.. container:: content

3111

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3112

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3113

3114

"eventOutputParameters": {

3115

"MyProducer": {

3116

"carrierTechnologyParameters":{

3117

"carrierTechnology" : "RESTSERVER",

3118

"parameterClassName" :

3119

"org.onap.policy.apex.plugins.event.carrier.restserver.RESTServerCarrierTechnologyParameters"

3120

},

3121

"eventProtocolParameters":{

3122

"eventProtocol" : "JSON"

3123

},

3124

"synchronousMode" : true,

3125

"synchronousPeer" : "MyConsumer",

3126

"synchronousTimeout" : 500

}

}

REST Server Stand-alone, multi input

3131

====================================

3132

3133

.. container:: paragraph

3134

3135

Any number of input/output pairs for REST servers can

3136

be configured. For instance, we can configure an input

3137

``FirstConsumer`` with output ``FirstProducer`` and an

3138

input ``SecondConsumer`` with output

3139

``SecondProducer``. Important is that there is always

3140

one pair of input/output.

3141

3142

REST Server Stand-alone in Servlet

3143

==================================

3144

3145

.. container:: paragraph

3146

3147

If APEX is executed as a servlet, e.g. inside Tomcat,

3148

the configuration becomes easier since the plugin can

3149

now use Tomcat as the REST server. In this scenario,

3150

there are not parameters (port, host, etc.) and the

3151

key ``standalone`` must not be used (or set to false).

3152

3153

.. container:: paragraph

3154

3155

For the Tomcat configuration, we need to add the REST

3156

server plugin, e.g.

3157

3158

.. container:: listingblock

3159

3160

.. container:: content

3161

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3162

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

...

<init-param>

...

<param-value>org.onap.policy.apex.plugins.event.carrier.restserver</param-value>

</init-param>

...

</servlet>

REST Requestor IO

##################

.. container:: paragraph

3177

3178

APEX can act as REST requestor on the input as well as on

3179

the output interface. The media type is

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

3180

``application/json``, so this plugin only works with

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3181

the JSON Event protocol.

REST Requestor Input

====================

.. container:: paragraph

3187

3188

APEX will connect to a given URL to request an input.

ning.xi

2019-07-18 07:50:10 +0000

[diff] [blame]

3189

The URL can be configured statically or tagged

3190

as ``?example.{site}.org:8080/{trig}/events``,

3191

all tags such as ``site`` and ``trig`` in the URL

Henry.Sun

2019-07-22 08:32:32 +0000

[diff] [blame]

3192

need to be set in the properties object available to

3193

the tasks. In addition, the keys should exactly match

3194

with the tags defined in url. The scope of the properties

3195

object is per HTTP call. Hence, key/value pairs set

3196

in the properties object by task are only available

3197

for that specific HTTP call.

3198

The httpCodeFilter is used for filtering the status

3199

code, and it can be configured as a regular expression

3200

string. The default httpCodeFilter is "[2][0-9][0-9]"

3201

- for successful response codes.

3202

The response with HTTP status code that matches the

3203

given regular expression is forwarded to the task,

3204

otherwise it is logged as a failure.

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3205

3206

.. container:: listingblock

3207

3208

.. container:: content

3209

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3210

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3211

3212

"carrierTechnologyParameters": {

3213

"carrierTechnology": "RESTREQUESTOR", (1)

3214

"parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters",

3215

"parameters": {

3216

"url": "http://localhost:54321/some/path/to/rest/resource", (2)

ning.xi

2019-07-18 07:50:10 +0000

[diff] [blame]

3217

"url": "http://localhost:54321/{site}/path/to/rest/{resValue}", (2')

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3218

"httpMethod": "POST", (3)

Henry.Sun

2019-07-22 08:32:32 +0000

[diff] [blame]

3219

"restRequestTimeout": 2000, (4)

3220

"httpCodeFilter" : "[2][0-9][0-9]" (5)

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

}

},

.. container:: colist arabic

3225

3226

+-------+--------------------------------------------------+

3227

| **1** | set REST requestor as carrier technology |

3228

+-------+--------------------------------------------------+

ning.xi

2019-07-18 07:50:10 +0000

[diff] [blame]

3229

| **2** | the static URL of the HTTP server for events |

3230

+-------+--------------------------------------------------+

3231

| **2'**| the tagged URL of the HTTP server for events |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3232

+-------+--------------------------------------------------+

3233

| **3** | use HTTP PUT (remove this line to use HTTP POST) |

3234

+-------+--------------------------------------------------+

3235

| **4** | request timeout in milliseconds |

3236

+-------+--------------------------------------------------+

Henry.Sun

2019-07-22 08:32:32 +0000

[diff] [blame]

3237

| **5** | use HTTP CODE FILTER for filtering status code |

3238

+-------+--------------------------------------------------+

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3239

3240

.. container:: paragraph

3241

3242

Further settings are required on the consumer to

3243

define the event that is requested, for example:

3244

3245

.. container:: listingblock

3246

3247

.. container:: content

3248

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3249

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3250

3251

"eventName": "GuardResponseEvent", (1)

3252

"eventNameFilter": "GuardResponseEvent", (2)

3253

"requestorMode": true, (3)

3254

"requestorPeer": "GuardRequestorProducer", (4)

3255

"requestorTimeout": 500 (5)

3256

3257

.. container:: colist arabic

3258

3259

+-------+---------------------------+

3260

| **1** | the event name |

3261

+-------+---------------------------+

3262

| **2** | a filter on the event |

3263

+-------+---------------------------+

3264

| **3** | the mode of the requestor |

3265

+-------+---------------------------+

3266

| **4** | a peer for the requestor |

3267

+-------+---------------------------+

3268

| **5** | a general request timeout |

3269

+-------+---------------------------+

3270

3271

REST Requestor Output

3272

=====================

3273

3274

.. container:: paragraph

3275

3276

APEX will connect to a given URL to send events, but

3277

not receive any events.

3278

3279

.. container:: listingblock

3280

3281

.. container:: content

3282

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3283

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3284

3285

"carrierTechnologyParameters": {

3286

"carrierTechnology": "RESTREQUESTOR", (1)

3287

"parameterClassName": "org.onap.policy.apex.plugins.event.carrier.restrequestor.RESTRequestorCarrierTechnologyParameters"

3288

},

3289

3290

.. container:: colist arabic

3291

3292

+-------+------------------------------------------+

3293

| **1** | set REST requestor as carrier technology |

3294

+-------+------------------------------------------+

3295

3296

.. container:: paragraph

3297

3298

Further settings are required on the consumer to

3299

define the event that is requested, for example:

3300

3301

.. container:: listingblock

3302

3303

.. container:: content

3304

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3305

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3306

3307

"eventNameFilter": "GuardRequestEvent", (1)

3308

"requestorMode": true, (2)

3309

"requestorPeer": "GuardRequestorConsumer", (3)

3310

"requestorTimeout": 500 (4)

3311

3312

.. container:: colist arabic

3313

3314

+-------+---------------------------+

3315

| **1** | a filter on the event |

3316

+-------+---------------------------+

3317

| **2** | the mode of the requestor |

3318

+-------+---------------------------+

3319

| **3** | a peer for the requestor |

3320

+-------+---------------------------+

3321

| **4** | a general request timeout |

3322

+-------+---------------------------+

3323

a.sreekumar

2020-03-16 13:36:45 +0000

[diff] [blame^]

gRPC IO

#######

.. container:: paragraph

3328

3329

APEX can send requests over gRPC at the output side, and get back

3330

response at the input side. This can be used to send requests to CDS

3331

over gRPC. The media type is ``application/json``, so this plugin

3332

only works with the JSON Event protocol.

gRPC Output

===========

.. container:: paragraph

3338

3339

APEX will connect to a given host to send a request over

3340

gRPC.

3341

3342

.. container:: listingblock

3343

3344

.. container:: content

.. code::

"carrierTechnologyParameters": {

3349

"carrierTechnology": "GRPC", (1)

3350

"parameterClassName": "org.onap.policy.apex.plugins.event.carrier.grpc.GrpcCarrierTechnologyParameters",

3351

"parameters": {

3352

"host": "cds-blueprints-processor-grpc", (2)

3353

"port": 9111, (2')

3354

"username": "ccsdkapps", (3)

3355

"password": ccsdkapps, (4)

"timeout" : 10 (5)

}

},

.. container:: colist arabic

3361

3362

+-------+--------------------------------------------------+

3363

| **1** | set GRPC as carrier technology |

3364

+-------+--------------------------------------------------+

3365

| **2** | the host to which request is sent |

3366

+-------+--------------------------------------------------+

3367

| **2'**| the value for port |

3368

+-------+--------------------------------------------------+

3369

| **3** | username required to initiate connection |

3370

+-------+--------------------------------------------------+

3371

| **4** | password required to initiate connection |

3372

+-------+--------------------------------------------------+

3373

| **5** | the timeout value for completing the request |

3374

+-------+--------------------------------------------------+

3375

3376

.. container:: paragraph

3377

3378

Further settings are required on the producer to

3379

define the event that is requested, for example:

3380

3381

.. container:: listingblock

3382

3383

.. container:: content

.. code::

"eventName": "GRPCRequestEvent", (1)

3388

"eventNameFilter": "GRPCRequestEvent", (2)

3389

"requestorMode": true, (3)

3390

"requestorPeer": "GRPCRequestConsumer", (4)

3391

"requestorTimeout": 500 (5)

3392

3393

.. container:: colist arabic

3394

3395

+-------+---------------------------+

3396

| **1** | the event name |

3397

+-------+---------------------------+

3398

| **2** | a filter on the event |

3399

+-------+---------------------------+

3400

| **3** | the mode of the requestor |

3401

+-------+---------------------------+

3402

| **4** | a peer for the requestor |

3403

+-------+---------------------------+

3404

| **5** | a general request timeout |

3405

+-------+---------------------------+

gRPC Input

==========

.. container:: paragraph

3411

3412

APEX will connect to the host specified in the producer

3413

side, anad take in response back at the consumer side.

3414

3415

.. container:: listingblock

3416

3417

.. container:: content

.. code::

"carrierTechnologyParameters": {

3422

"carrierTechnology": "GRPC", (1)

3423

"parameterClassName": "org.onap.policy.apex.plugins.event.carrier.grpc.GrpcCarrierTechnologyParameters"

3424

},

3425

3426

.. container:: colist arabic

3427

3428

+-------+------------------------------------------+

3429

| **1** | set GRPC as carrier technology |

3430

+-------+------------------------------------------+

3431

3432

.. container:: paragraph

3433

3434

Further settings are required on the consumer to

3435

define the event that is requested, for example:

3436

3437

.. container:: listingblock

3438

3439

.. container:: content

.. code::

"eventNameFilter": "GRPCResponseEvent", (1)

3444

"requestorMode": true, (2)

3445

"requestorPeer": "GRPCRequestProducer", (3)

3446

"requestorTimeout": 500 (4)

3447

3448

.. container:: colist arabic

3449

3450

+-------+---------------------------+

3451

| **1** | a filter on the event |

3452

+-------+---------------------------+

3453

| **2** | the mode of the requestor |

3454

+-------+---------------------------+

3455

| **3** | a peer for the requestor |

3456

+-------+---------------------------+

3457

| **4** | a general request timeout |

3458

+-------+---------------------------+

3459

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3460

Event Protocols, Format and Encoding

3461

------------------------------------

3462

3463

.. container:: paragraph

3464

3465

Event protocols define what event formats APEX can receive

3466

(input) and should send (output). They can be used in any

3467

combination for input and output, unless further restricted

3468

by a carrier technology plugin (for instance for JMS

3469

output). There can only be 1 event protocol per event

3470

plugin.

3471

3472

.. container:: paragraph

3473

3474

Supported *input* event protocols are:

.. container:: ulist

- JSON, the event as a JSON string

3479

3480

- APEX, an APEX event

3481

3482

- JMS object, the event as a JMS object,

3483

3484

- JMS text, the event as a JMS text,

3485

3486

- XML, the event as an XML string,

3487

3488

- YAML, the event as YAML text

3489

3490

.. container:: paragraph

3491

3492

Supported *output* event protocols are:

.. container:: ulist

- JSON, the event as a JSON string

3497

3498

- APEX, an APEX event

3499

3500

- JMS object, the event as a JMS object,

3501

3502

- JMS text, the event as a JMS text,

3503

3504

- XML, the event as an XML string,

3505

3506

- YAML, the event as YAML text

3507

3508

.. container:: paragraph

3509

3510

New event protocols can be added as plugins to APEX or

3511

developed outside APEX and added to an APEX deployment.

JSON Event

##########

.. container:: paragraph

3517

3518

The event protocol for JSON encoding does not require a

3519

specific plugin, it is supported by default. Furthermore,

3520

there is no difference in the configuration for the input

3521

and output interface.

3522

3523

.. container:: paragraph

3524

3525

For an input, APEX requires a well-formed JSON string.

3526

Well-formed here means according to the definitions of a

3527

policy. Any JSON string that is not defined as a trigger

3528

event (consume) will not be consumed (errors will be

3529

thrown). For output JSON events, APEX will always produce

3530

valid JSON strings according to the definition in the

3531

policy model.

3532

3533

.. container:: paragraph

3534

3535

The following JSON shows the configuration.

3536

3537

.. container:: listingblock

3538

3539

.. container:: content

3540

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3541

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3542

3543

"eventProtocolParameters":{

3544

"eventProtocol" : "JSON"

3545

}

3546

3547

.. container:: paragraph

3548

3549

For JSON events, there are a few more optional

3550

parameters, which allow to define a mapping for standard

3551

event fields. An APEX event must have the fields

3552

``name``, ``version``, ``source``, and ``target``

3553

defined. Sometimes it is not possible to configure a

3554

trigger or actioning system to use those fields. However,

3555

they might be in an event generated outside APEX (or used

3556

outside APEX) just with different names. To configure

3557

APEX to map between the different event names, simply add

3558

the following parameters to a JSON event:

3559

3560

.. container:: listingblock

3561

3562

.. container:: content

3563

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3564

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3565

3566

"eventProtocolParameters":{

3567

"eventProtocol" : "JSON",

3568

"nameAlias" : "policyName", (1)

3569

"versionAlias" : "policyVersion", (2)

3570

"sourceAlias" : "from", (3)

3571

"targetAlias" : "to", (4)

3572

"nameSpaceAlias": "my.name.space" (5)

3573

}

3574

3575

.. container:: colist arabic

3576

3577

+-----------------------------------+-----------------------------------+

3578

| **1** | mapping for the ``name`` field, |

3579

| | here from a field called |

3580

| | ``policyName`` |

3581

+-----------------------------------+-----------------------------------+

3582

| **2** | mapping for the ``version`` |

3583

| | field, here from a field called |

3584

| | ``policyVersion`` |

3585

+-----------------------------------+-----------------------------------+

3586

| **3** | mapping for the ``source`` field, |

3587

| | here from a field called ``from`` |

3588

| | (only for an input event) |

3589

+-----------------------------------+-----------------------------------+

3590

| **4** | mapping for the ``target`` field, |

3591

| | here from a field called ``to`` |

3592

| | (only for an output event) |

3593

+-----------------------------------+-----------------------------------+

3594

| **5** | mapping for the ``nameSpace`` |

3595

| | field, here from a field called |

3596

| | ``my.name.space`` |

3597

+-----------------------------------+-----------------------------------+

APEX Event

##########

.. container:: paragraph

3602

3603

The event protocol for APEX events does not require a

3604

specific plugin, it is supported by default. Furthermore,

3605

there is no difference in the configuration for the input

3606

and output interface.

3607

3608

.. container:: paragraph

3609

3610

For input and output APEX uses APEX events.

3611

3612

.. container:: paragraph

3613

3614

The following JSON shows the configuration.

3615

3616

.. container:: listingblock

3617

3618

.. container:: content

3619

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3620

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3621

3622

"eventProtocolParameters":{

3623

"eventProtocol" : "APEX"

}

JMS Event

#########

.. container:: paragraph

3630

3631

The event protocol for JMS is provided by the APEX JMS

3632

plugin. The plugin supports encoding as JSON text or as

3633

object. There is no difference in the configuration for

3634

the input and output interface.

JMS Text

========

.. container:: paragraph

3639

3640

If used as input, APEX will take a JMS message and

3641

extract a JSON string, then proceed as if a JSON event

3642

was received. If used as output, APEX will take the

3643

event produced by a policy, create a JSON string, and

3644

then wrap it into a JMS message.

3645

3646

.. container:: paragraph

3647

3648

The configuration for JMS text is as follows:

3649

3650

.. container:: listingblock

3651

3652

.. container:: content

3653

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3654

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3655

3656

"eventProtocolParameters":{

3657

"eventProtocol" : "JMSTEXT",

3658

"parameterClassName" :

3659

"org.onap.policy.apex.plugins.event.protocol.jms.JMSTextEventProtocolParameters"

}

JMS Object

==========

.. container:: paragraph

3665

3666

If used as input, APEX will will take a JMS message,

3667

extract a Java Bean from the ``ObjectMessage``

3668

message, construct an APEX event and put the bean on

3669

the APEX event as a parameter. If used as output, APEX

3670

will take the event produced by a policy, create a

3671

Java Bean and send it as a JMS message.

3672

3673

.. container:: paragraph

3674

3675

The configuration for JMS object is as follows:

3676

3677

.. container:: listingblock

3678

3679

.. container:: content

3680

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3681

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3682

3683

"eventProtocolParameters":{

3684

"eventProtocol" : "JMSOBJECT",

3685

"parameterClassName" :

3686

"org.onap.policy.apex.plugins.event.protocol.jms.JMSObjectEventProtocolParameters"

}

YAML Event

##########

.. container:: paragraph

3693

3694

The event protocol for YAML is provided by the APEX YAML

3695

plugin. There is no difference in the configuration for

3696

the input and output interface.

3697

3698

.. container:: paragraph

3699

3700

If used as input, APEX will consume events as YAML and

3701

map them to policy trigger events. Not well-formed YAML

3702

and not understood trigger events will be rejected. If

3703

used as output, APEX produce YAML encoded events from the

3704

event a policy produces. Those events will always be

3705

well-formed according to the definition in the policy

3706

model.

3707

3708

.. container:: paragraph

3709

3710

The following code shows the configuration.

3711

3712

.. container:: listingblock

3713

3714

.. container:: content

3715

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3716

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3717

3718

"eventProtocolParameters":{

3719

"eventProtocol" : "XML",

3720

"parameterClassName" :

3721

"org.onap.policy.apex.plugins.event.protocol.yaml.YamlEventProtocolParameters"

}

XML Event

#########

.. container:: paragraph

3727

3728

The event protocol for XML is provided by the APEX XML

3729

plugin. There is no difference in the configuration for

3730

the input and output interface.

3731

3732

.. container:: paragraph

3733

3734

If used as input, APEX will consume events as XML and map

3735

them to policy trigger events. Not well-formed XML and

3736

not understood trigger events will be rejected. If used

3737

as output, APEX produce XML encoded events from the event

3738

a policy produces. Those events will always be

3739

well-formed according to the definition in the policy

3740

model.

3741

3742

.. container:: paragraph

3743

3744

The following code shows the configuration.

3745

3746

.. container:: listingblock

3747

3748

.. container:: content

3749

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3750

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3751

3752

"eventProtocolParameters":{

3753

"eventProtocol" : "XML",

3754

"parameterClassName" :

3755

"org.onap.policy.apex.plugins.event.protocol.xml.XMLEventProtocolParameters"

3756

}

3757

3758

A configuration example

3759

-----------------------

3760

3761

.. container:: paragraph

3762

3763

The following example loads all available plug-ins.

3764

3765

.. container:: paragraph

3766

3767

Events are consumed from a Websocket, APEX as client.

3768

Consumed event format is JSON.

3769

3770

.. container:: paragraph

3771

3772

Events are produced to Kafka. Produced event format is XML.

3773

3774

.. container:: listingblock

3775

3776

.. container:: content

3777

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

3778

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

3779

3780

{

3781

"engineServiceParameters" : {

3782

"name" : "MyApexEngine",

"version" : "0.0.1",

"id" : 45,

"instanceCount" : 4,

"deploymentPort" : 12345,

3787

"policyModelFileName" : "examples/models/some-model.json",

3788

"engineParameters" : {

3789

"executorParameters" : {

3790

"JAVASCRIPT" : {

3791

"parameterClassName" :

3792

"org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"

3793

},

3794

"JYTHON" : {

3795

"parameterClassName" :

3796

"org.onap.policy.apex.plugins.executor.jython.JythonExecutorParameters"

3797

},

3798

"JRUBY" : {

3799

"parameterClassName" :

3800

"org.onap.policy.apex.plugins.executor.jruby.JrubyExecutorParameters"

3801

},

3802

"JAVA" : {

3803

"parameterClassName" :

3804

"org.onap.policy.apex.plugins.executor.java.JavaExecutorParameters"

3805

},

3806

"MVEL" : {

3807

"parameterClassName" :

3808

"org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"

3809

}

3810

},

3811

"contextParameters" : {

3812

"parameterClassName" :

3813

"org.onap.policy.apex.context.parameters.ContextParameters",

3814

"schemaParameters" : {

3815

"Avro":{

3816

"parameterClassName" :

3817

"org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters"

}

}

}

}

},

"producerCarrierTechnologyParameters" : {

3824

"carrierTechnology" : "KAFKA",

3825

"parameterClassName" :

3826

"org.onap.policy.apex.plugins.event.carrier.kafka.KAFKACarrierTechnologyParameters",

3827

"parameters" : {

3828

"bootstrapServers" : "localhost:49092",

"acks" : "all",

"retries" : 0,

"batchSize" : 16384,

"lingerTime" : 1,

"bufferMemory" : 33554432,

3834

"producerTopic" : "apex-out",

3835

"keySerializer" : "org.apache.kafka.common.serialization.StringSerializer",

3836

"valueSerializer" : "org.apache.kafka.common.serialization.StringSerializer"

3837

}

3838

},

3839

"producerEventProtocolParameters" : {

3840

"eventProtocol" : "XML",

3841

"parameterClassName" :

3842

"org.onap.policy.apex.plugins.event.protocol.xml.XMLEventProtocolParameters"

3843

},

3844

"consumerCarrierTechnologyParameters" : {

3845

"carrierTechnology" : "WEBSOCKET",

3846

"parameterClassName" :

3847

"org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",

3848

"parameters" : {

3849

"host" : "localhost",

"port" : 88888

}

},

"consumerEventProtocolParameters" : {

3854

"eventProtocol" : "JSON"

}

}

Engine and Applications of the APEX System

3859

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

3860

3861

Introduction to APEX Engine and Applications

3862

--------------------------------------------

3863

3864

.. container:: paragraph

3865

3866

The core of APEX is the APEX Engine, also known as the APEX

3867

Policy Engine or the APEX PDP (since it is in fact a Policy

3868

Decision Point). Beside this engine, an APEX system comes

3869

with a few applications intended to help with policy

3870

authoring, deployment, and execution.

3871

3872

.. container:: paragraph

3873

3874

The engine itself and most applications are started from the

3875

command line with command line arguments. This is called a

3876

Command Line Interface (CLI). Some applications require an

3877

installation on a webserver, as for instance the REST

3878

Editor. Those applications can be accessed via a web

3879

browser.

3880

3881

.. container:: paragraph

3882

3883

You can also use the available APEX APIs and applications to

3884

develop other applications as required. This includes policy

3885

languages (and associated parsers and compilers /

3886

interpreters), GUIs to access APEX or to define policies,

3887

clients to connect to APEX, etc.

3888

3889

.. container:: paragraph

3890

3891

For this documentation, we assume an installation of APEX as

3892

a full system based on a current ONAP release.

3893

3894

CLI on Unix, Windows, and Cygwin

3895

--------------------------------

3896

3897

.. container:: paragraph

3898

3899

A note on APEX CLI applications: all applications and the

3900

engine itself have been deployed and tested on different

3901

operating systems: Red Hat, Ubuntu, Debian, Mac OSX,

3902

Windows, Cygwin. Each operating system comes with its own

3903

way of configuring and executing Java. The main items here

are:

.. container:: ulist

- For UNIX systems (RHL, Ubuntu, Debian, Mac OSX), the

3909

provided bash scripts work as expected with absolute

3910

paths (e.g.

3911

``/opt/app/policy/apex-pdp/apex-pdp-2.0.0-SNAPSHOT/examples``),

3912

indirect and linked paths (e.g. ``../apex/apex``), and

3913

path substitutions using environment settings (e.g.

3914

``$APEX_HOME/bin/``)

3915

3916

- For Windows systems, the provided batch files (``.bat``)

3917

work as expected with with absolute paths (e.g.

3918

``C:\apex\apex-2.0.0-SNAPSHOT\examples``), and path

3919

substitutions using environment settings (e.g.

3920

``%APEX_HOME%\bin\``)

3921

3922

- For Cygwin system we assume a standard Cygwin

3923

installation with standard tools (mainly bash) using a

3924

Windows Java installation. This means that the bash

3925

scripts can be used as in UNIX, however any argument

3926

pointing to files and directories need to use either a

3927

DOS path (e.g.

3928

``C:\apex\apex-2.0.0-SNAPSHOT\examples\config...``) or

3929

the command ``cygpath`` with a mixed option. The reason

3930

for that is: Cygwin executes Java using UNIX paths but

3931

then runs Java as a DOS/WINDOWS process, which requires

3932

DOS paths for file access.

The APEX Engine

---------------

.. container:: paragraph

3938

3939

The APEX engine can be started in different ways, depending

3940

your requirements. All scripts are located in the APEX *bin*

3941

directory

3942

3943

.. container:: paragraph

3944

3945

On UNIX and Cygwin systems use:

.. container:: ulist

- ``apexEngine.sh`` - this script will

.. container:: ulist

- Test if ``$APEX_USER`` is set and if the user

3954

exists, terminate with an error otherwise

3955

3956

- Test if ``$APEX_HOME`` is set. If not set, it will

3957

use the default setting as

3958

``/opt/app/policy/apex-pdp/apex-pdp``. Then the set

3959

directory is tested to exist, the script will

3960

terminate if not.

3961

3962

- When all tests are passed successfully, the script

3963

will call ``apexApps.sh`` with arguments to start

3964

the APEX engine.

3965

3966

- ``apexApps.sh engine`` - this is the general APEX

3967

application launcher, which will

.. container:: ulist

- Start the engine with the argument ``engine``

3972

3973

- Test if ``$APEX_HOME`` is set and points to an

3974

existing directory. If not set or directory does

3975

not exist, script terminates.

3976

3977

- Not test for any settings of ``$APEX_USER``.

3978

3979

.. container:: paragraph

3980

3981

On Windows systems use ``apexEngine.bat`` and

3982

``apexApps.bat engine`` respectively. Note: none of the

3983

windows batch files will test for ``%APEX_USER%``.

3984

3985

.. container:: paragraph

3986

3987

Summary of alternatives to start the APEX Engine:

3988

3989

+--------------------------------------------------------+----------------------------------------------------------+

3990

| Unix, Cygwin | Windows |

3991

+========================================================+==========================================================+

3992

| .. container:: | .. container:: |

3993

| | |

3994

| .. container:: listingblock | .. container:: listingblock |

3995

| | |

3996

| .. container:: content | .. container:: content |

3997

| | |

3998

| .. code:: | .. code:: |

3999

| | |

4000

| # $APEX_HOME/bin/apexEngine.sh [args] | > %APEX_HOME%\bin\apexEngine.bat [args] |

4001

| # $APEX_HOME/bin/apexApps.sh engine [args] | > %APEX_HOME%\bin\apexApps.bat engine [args] |

4002

+--------------------------------------------------------+----------------------------------------------------------+

4003

4004

.. container:: paragraph

4005

4006

The APEX engine comes with a few CLI arguments for setting

4007

configuration and policy model. The configuration file is

4008

always required. The policy model file is only required if

4009

no model file is specified in the configuration, or if the

4010

specified model file should be over written. The option

4011

``-h`` prints a help screen.

4012

4013

.. container:: listingblock

4014

4015

.. container:: content

4016

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4017

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4018

4019

usage: org.onap.policy.apex.service.engine.main.ApexMain [options...]

4020

options

4021

-c,--config-file <CONFIG_FILE> the full path to the configuration file to use, the configuration file must be a Json file

4022

containing the Apex configuration parameters

4023

-h,--help outputs the usage of this command

4024

-m,--model-file <MODEL_FILE> the full path to the model file to use, if set it overrides the model file set in the

4025

configuration file

4026

-v,--version outputs the version of Apex

The APEX CLI Editor

-------------------

.. container:: paragraph

4032

4033

The CLI Editor allows to define policies from the command

4034

line. The application uses a simple language and supports

4035

all elements of an APEX policy. It can be used in to

different ways:

.. container:: ulist

- non-interactive, specifying a file with the commands to

4041

create a policy

4042

4043

- interactive, using the editors CLI to create a policy

4044

4045

.. container:: paragraph

4046

4047

When a policy is fully specified, the editor will generate

4048

the APEX core policy specification in JSON. This core

4049

specification is called the policy model in the APEX engine

4050

and can be used directly with the APEX engine.

4051

4052

.. container:: paragraph

4053

4054

On UNIX and Cygwin systems use:

.. container:: ulist

- ``apexCLIEditor.sh`` - simply starts the CLI editor,

4059

arguments to the script determine the mode of the editor

4060

4061

- ``apexApps.sh cli-editor`` - simply starts the CLI

4062

editor, arguments to the script determine the mode of the

4063

editor

4064

4065

.. container:: paragraph

4066

4067

On Windows systems use:

.. container:: ulist

- ``apexCLIEditor.bat`` - simply starts the CLI editor,

4072

arguments to the script determine the mode of the editor

4073

4074

- ``apexApps.bat cli-editor`` - simply starts the CLI

4075

editor, arguments to the script determine the mode of the

4076

editor

4077

4078

.. container:: paragraph

4079

4080

Summary of alternatives to start the APEX CLI Editor:

4081

4082

+------------------------------------------------------------+--------------------------------------------------------------+

4083

| Unix, Cygwin | Windows |

4084

+============================================================+==============================================================+

4085

| .. container:: | .. container:: |

4086

| | |

4087

| .. container:: listingblock | .. container:: listingblock |

4088

| | |

4089

| .. container:: content | .. container:: content |

4090

| | |

4091

| .. code:: | .. code:: |

4092

| | |

4093

| # $APEX_HOME/bin/apexCLIEditor.sh.sh [args] | > %APEX_HOME%\bin\apexCLIEditor.bat [args] |

4094

| # $APEX_HOME/bin/apexApps.sh cli-editor [args] | > %APEX_HOME%\bin\apexApps.bat cli-editor [args] |

4095

+------------------------------------------------------------+--------------------------------------------------------------+

4096

4097

.. container:: paragraph

4098

4099

The option ``-h`` provides a help screen with all command

4100

line arguments.

4101

4102

.. container:: listingblock

4103

4104

.. container:: content

4105

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4106

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4107

4108

usage: org.onap.policy.apex.auth.clieditor.ApexCLIEditorMain [options...]

4109

options

4110

-a,--model-props-file <MODEL_PROPS_FILE> name of the apex model properties file to use

4111

-c,--command-file <COMMAND_FILE> name of a file containing editor commands to run into the editor

4112

-h,--help outputs the usage of this command

4113

-i,--input-model-file <INPUT_MODEL_FILE> name of a file that contains an input model for the editor

4114

-if,--ignore-failures <IGNORE_FAILURES_FLAG> true or false, ignore failures of commands in command files and continue

4115

executing the command file

4116

-l,--log-file <LOG_FILE> name of a file that will contain command logs from the editor, will log

4117

to standard output if not specified or suppressed with "-nl" flag

4118

-m,--metadata-file <CMD_METADATA_FILE> name of the command metadata file to use

4119

-nl,--no-log if specified, no logging or output of commands to standard output or log

4120

file is carried out

4121

-nm,--no-model-output if specified, no output of a model to standard output or model output

4122

file is carried out, the user can use the "save" command in a script to

4123

save a model

4124

-o,--output-model-file <OUTPUT_MODEL_FILE> name of a file that will contain the output model for the editor, will

4125

output model to standard output if not specified or suppressed with

4126

"-nm" flag

4127

-wd,--working-directory <WORKING_DIRECTORY> the working directory that is the root for the CLI editor and is the

4128

root from which to look for included macro files

4129

a.sreekumar

717a24a

2019-07-26 13:47:42 +0000

[diff] [blame]

4130

The APEX CLI Tosca Editor

4131

-------------------------

4132

4133

.. container:: paragraph

4134

4135

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.

4136

4137

.. container:: paragraph

4138

4139

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.

4140

4141

.. container:: paragraph

4142

4143

On UNIX and Cygwin systems use:

.. container:: ulist

- ``apexCLIToscaEditor.sh`` - starts the CLI Tosca editor,

4148

all the arguments supported by the basic CLI Editor are supported in addition to the mandatory arguments needed to generate ToscaServiceTemplate.

4149

4150

- ``apexApps.sh cli-tosca-editor`` - starts the CLI Tosca editor,

4151

all the arguments supported by the basic CLI Editor are supported in addition to the mandatory arguments needed to generate ToscaServiceTemplate.

4152

4153

.. container:: paragraph

4154

4155

On Windows systems use:

.. container:: ulist

- ``apexCLIToscaEditor.bat`` - starts the CLI Tosca editor,

4160

all the arguments supported by the basic CLI Editor are supported in addition to the mandatory arguments needed to generate ToscaServiceTemplate.

4161

4162

- ``apexApps.bat cli-tosca-editor`` - starts the CLI Tosca

4163

editor, all the arguments supported by the basic CLI Editor are supported in addition to the mandatory arguments needed to generate ToscaServiceTemplate.

4164

4165

.. container:: paragraph

4166

4167

Summary of alternatives to start the APEX CLI Tosca Editor:

4168

4169

+-----------------------------------------------------------------+--------------------------------------------------------------------+

4170

| Unix, Cygwin | Windows |

4171

+=================================================================+====================================================================+

4172

| .. container:: | .. container:: |

4173

| | |

4174

| .. container:: listingblock | .. container:: listingblock |

4175

| | |

4176

| .. container:: content | .. container:: content |

4177

| | |

4178

| .. code:: | .. code:: |

4179

| | |

4180

| # $APEX_HOME/bin/apexCLIToscaEditor.sh.sh [args] | > %APEX_HOME%\bin\apexCLIToscaEditor.bat [args] |

4181

| # $APEX_HOME/bin/apexApps.sh cli-tosca-editor [args]| > %APEX_HOME%\bin\apexApps.bat cli-tosca-editor [args] |

4182

+-----------------------------------------------------------------+--------------------------------------------------------------------+

4183

4184

.. container:: paragraph

4185

4186

The option ``-h`` provides a help screen with all command

4187

line arguments.

4188

4189

.. container:: listingblock

4190

4191

.. container:: content

.. code::

usage: org.onap.policy.apex.auth.clieditor.tosca.ApexCliToscaEditorMain [options...]

4196

options

4197

-a,--model-props-file <MODEL_PROPS_FILE> name of the apex model properties file to use

4198

-ac,--apex-config-file <APEX_CONFIG_FILE> name of the file containing apex configuration details

4199

-c,--command-file <COMMAND_FILE> name of a file containing editor commands to run into the editor

4200

-h,--help outputs the usage of this command

4201

-i,--input-model-file <INPUT_MODEL_FILE> name of a file that contains an input model for the editor

4202

-if,--ignore-failures <IGNORE_FAILURES_FLAG> true or false, ignore failures of commands in command files and

4203

continue executing the command file

4204

-l,--log-file <LOG_FILE> name of a file that will contain command logs from the editor, will

4205

log to standard output if not specified or suppressed with "-nl" flag

4206

-m,--metadata-file <CMD_METADATA_FILE> name of the command metadata file to use

4207

-nl,--no-log if specified, no logging or output of commands to standard output or

4208

log file is carried out

4209

-ot,--output-tosca-file <OUTPUT_TOSCA_FILE> name of a file that will contain the output ToscaServiceTemplate

4210

-t,--tosca-template-file <TOSCA_TEMPLATE_FILE> name of the input file containing tosca template which needs to be

4211

updated with policy

4212

-wd,--working-directory <WORKING_DIRECTORY> the working directory that is the root for the CLI editor and is the

4213

root from which to look for included macro files

4214

4215

.. container:: paragraph

4216

4217

An example command to run the APEX CLI Tosca editor on windows machine is given below.

4218

4219

.. container:: listingblock

4220

4221

.. container:: content

.. code::

%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

4226

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

The APEX REST Editor

--------------------

.. container:: paragraph

4231

4232

The standard way to use the APEX REST Editor is via an

4233

installation of the *war* file on a webserver. However, the

4234

REST editor can also be started via command line. This will

4235

start a Grizzly webserver with the *war* deployed. Access to

4236

the REST Editor is then via the provided URL

4237

4238

.. container:: paragraph

4239

4240

On UNIX and Cygwin systems use:

.. container:: ulist

- ``apexRESTEditor.sh`` - simply starts the webserver with

4245

the REST editor

4246

4247

- ``apexApps.sh rest-editor`` - simply starts the webserver

4248

with the REST editor

4249

4250

.. container:: paragraph

4251

4252

On Windows systems use:

.. container:: ulist

- ``apexRESTEditor.bat`` - simply starts the webserver with

4257

the REST editor

4258

4259

- ``apexApps.bat rest-editor`` - simply starts the

4260

webserver with the REST editor

4261

4262

.. container:: paragraph

4263

4264

Summary of alternatives to start the APEX REST Editor:

4265

4266

+-------------------------------------------------------------+---------------------------------------------------------------+

4267

| Unix, Cygwin | Windows |

4268

+=============================================================+===============================================================+

4269

| .. container:: | .. container:: |

4270

| | |

4271

| .. container:: listingblock | .. container:: listingblock |

4272

| | |

4273

| .. container:: content | .. container:: content |

4274

| | |

4275

| .. code:: | .. code:: |

4276

| | |

4277

| # $APEX_HOME/bin/apexRESTEditor.sh.sh [args] | > %APEX_HOME%\bin\apexRESTEditor.bat [args] |

4278

| # $APEX_HOME/bin/apexApps.sh rest-editor [args] | > %APEX_HOME%\bin\apexApps.bat rest-editor [args] |

4279

+-------------------------------------------------------------+---------------------------------------------------------------+

4280

4281

.. container:: paragraph

4282

4283

The option ``-h`` provides a help screen with all command

4284

line arguments.

4285

4286

.. container:: listingblock

4287

4288

.. container:: content

4289

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4290

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4291

4292

usage: org.onap.policy.apex.client.editor.rest.ApexEditorMain [options...]

4293

-h,--help outputs the usage of this command

4294

-l,--listen <ADDRESS> the IP address to listen on. Default value is localhost to restrict access to the

4295

local machine only.

4296

-p,--port <PORT> port to use for the Apex RESTful editor REST calls.

4297

-t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating. Default

4298

value is -1 to run indefinitely.

4299

4300

.. container:: paragraph

4301

4302

If the REST Editor is started without any arguments the

4303

final messages will look similar to this:

4304

4305

.. container:: listingblock

4306

4307

.. container:: content

4308

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4309

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4310

4311

Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .

4312

Sep 05, 2018 11:24:30 PM org.glassfish.grizzly.http.server.NetworkListener start

4313

INFO: Started listener bound to [localhost:18989]

4314

Sep 05, 2018 11:24:30 PM org.glassfish.grizzly.http.server.HttpServer start

4315

INFO: [HttpServer] Started.

4316

Apex Editor REST endpoint (ApexEditorMain: Config=[ApexEditorParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/

4317

4318

.. container:: paragraph

4319

4320

The last line states the URL on which the REST Editor can be

4321

accessed. The example above stated

4322

``http://0.0.0.0:18989/apex/``. In a web browser use the URL

4323

``http://localhost:18989`` and the REST Editor will start.

4324

4325

The APEX Monitoring Client

4326

--------------------------

4327

4328

.. container:: paragraph

4329

4330

The standard way to use the APEX Monitoring Client is via an

4331

installation of the *war* file on a webserver. However, the

4332

Monitoring Client can also be started via command line. This

4333

will start a Grizzly webserver with the *war* deployed.

4334

Access to the Monitoring Client is then via the provided URL

4335

4336

.. container:: paragraph

4337

4338

On UNIX and Cygwin systems use:

.. container:: ulist

- ``apexApps.sh eng-monitoring`` - simply starts the

4343

webserver with the Monitoring Client

4344

4345

.. container:: paragraph

4346

4347

On Windows systems use:

.. container:: ulist

- ``apexApps.bat eng-monitoring`` - simply starts the

4352

webserver with the Monitoring Client

4353

4354

.. container:: paragraph

4355

4356

The option ``-h`` provides a help screen with all command

4357

line arguments.

4358

4359

.. container:: listingblock

4360

4361

.. container:: content

4362

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4363

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4364

4365

usage: org.onap.policy.apex.client.monitoring.rest.ApexMonitoringRestMain [options...]

4366

-h,--help outputs the usage of this command

4367

-p,--port <PORT> port to use for the Apex Services REST calls

4368

-t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating

4369

4370

.. container:: paragraph

4371

4372

If the Monitoring Client is started without any arguments

4373

the final messages will look similar to this:

4374

4375

.. container:: listingblock

4376

4377

.. container:: content

4378

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4379

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4380

4381

Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .

4382

Sep 05, 2018 11:26:20 PM org.glassfish.grizzly.http.server.NetworkListener start

4383

INFO: Started listener bound to [localhost:18989]

4384

Sep 05, 2018 11:26:20 PM org.glassfish.grizzly.http.server.HttpServer start

4385

INFO: [HttpServer] Started.

4386

Apex Services REST endpoint (ApexMonitoringRestMain: Config=[ApexMonitoringRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/

4387

4388

.. container:: paragraph

4389

4390

The last line states the URL on which the Monitoring Client

4391

can be accessed. The example above stated

4392

``http://localhost:18989/apexservices``. In a web browser

4393

use the URL ``http://localhost:18989``.

4394

4395

The APEX Deployment Client

4396

--------------------------

4397

4398

.. container:: paragraph

4399

4400

The standard way to use the APEX Deployment Client is via an

4401

installation of the *war* file on a webserver. However, the

4402

Deployment Client can also be started via command line. This

4403

will start a Grizzly webserver with the *war* deployed.

4404

Access to the Deployment Client is then via the provided URL

4405

4406

.. container:: paragraph

4407

4408

On UNIX and Cygwin systems use:

.. container:: ulist

- ``apexApps.sh eng-deployment`` - simply starts the

4413

webserver with the Deployment Client

4414

4415

.. container:: paragraph

4416

4417

On Windows systems use:

.. container:: ulist

- ``apexApps.bat eng-deployment`` - simply starts the

4422

webserver with the Deployment Client

4423

4424

.. container:: paragraph

4425

4426

The option ``-h`` provides a help screen with all command

4427

line arguments.

4428

4429

.. container:: listingblock

4430

4431

.. container:: content

4432

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4433

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4434

4435

usage: org.onap.policy.apex.client.deployment.rest.ApexDeploymentRestMain [options...]

4436

-h,--help outputs the usage of this command

4437

-p,--port <PORT> port to use for the Apex Services REST calls

4438

-t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating

4439

4440

.. container:: paragraph

4441

4442

If the Deployment Client is started without any arguments

4443

the final messages will look similar to this:

4444

4445

.. container:: listingblock

4446

4447

.. container:: content

4448

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4449

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4450

4451

Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .

4452

Sep 05, 2018 11:27:09 PM org.glassfish.grizzly.http.server.NetworkListener start

4453

INFO: Started listener bound to [localhost:18989]

4454

Sep 05, 2018 11:27:09 PM org.glassfish.grizzly.http.server.HttpServer start

4455

INFO: [HttpServer] Started.

4456

Apex Services REST endpoint (ApexDeploymentRestMain: Config=[ApexDeploymentRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/

4457

4458

.. container:: paragraph

4459

4460

The last line states the URL on which the Deployment Client

4461

can be accessed. The example above stated

4462

``http://localhost:18989/apexservices``. In a web browser

4463

use the URL ``http://localhost:18989``.

The APEX Full Client

--------------------

.. container:: paragraph

4469

4470

The APEX Full Client combines the REST Editor, the

4471

Monitoring Client, and the Deployment Client into a single

4472

application. The standard way to use the APEX Full Client is

4473

via an installation of the *war* file on a webserver.

4474

However, the Full Client can also be started via command

4475

line. This will start a Grizzly webserver with the *war*

4476

deployed. Access to the Full Client is then via the provided

4477

URL

4478

4479

.. container:: paragraph

4480

4481

On UNIX and Cygwin systems use:

.. container:: ulist

- ``apexApps.sh full-client`` - simply starts the webserver

4486

with the Full Client

4487

4488

.. container:: paragraph

4489

4490

On Windows systems use:

.. container:: ulist

- ``apexApps.bat full-client`` - simply starts the

4495

webserver with the Full Client

4496

4497

.. container:: paragraph

4498

4499

The option ``-h`` provides a help screen with all command

4500

line arguments.

4501

4502

.. container:: listingblock

4503

4504

.. container:: content

4505

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4506

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4507

4508

usage: org.onap.policy.apex.client.full.rest.ApexServicesRestMain [options...]

4509

-h,--help outputs the usage of this command

4510

-p,--port <PORT> port to use for the Apex Services REST calls

4511

-t,--time-to-live <TIME_TO_LIVE> the amount of time in seconds that the server will run for before terminating

4512

4513

.. container:: paragraph

4514

4515

If the Full Client is started without any arguments the

4516

final messages will look similar to this:

4517

4518

.. container:: listingblock

4519

4520

.. container:: content

4521

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4522

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4523

4524

Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=READY) starting at http://localhost:18989/apexservices/ . . .

4525

Sep 05, 2018 11:28:28 PM org.glassfish.grizzly.http.server.NetworkListener start

4526

INFO: Started listener bound to [localhost:18989]

4527

Sep 05, 2018 11:28:28 PM org.glassfish.grizzly.http.server.HttpServer start

4528

INFO: [HttpServer] Started.

4529

Apex Editor REST endpoint (ApexServicesRestMain: Config=[ApexServicesRestParameters: URI=http://localhost:18989/apexservices/, TTL=-1sec], State=RUNNING) started at http://localhost:18989/apexservices/

4530

4531

.. container:: paragraph

4532

4533

The last line states the URL on which the Monitoring Client

4534

can be accessed. The example above stated

4535

``http://localhost:18989/apexservices``. In a web browser

4536

use the URL ``http://localhost:18989``.

4537

4538

The APEX Application Launcher

4539

------------------------------

4540

4541

.. container:: paragraph

4542

4543

The standard applications (Engine, CLI Editor, REST Editor)

4544

come with dedicated start scripts. For all other APEX

4545

applications, we provide an application launcher.

4546

4547

.. container:: paragraph

4548

4549

On UNIX and Cygwin systems use:

.. container:: ulist

- apexApps.sh\` - simply starts the application launcher

4554

4555

.. container:: paragraph

4556

4557

On Windows systems use:

.. container:: ulist

- ``apexApps.bat`` - simply starts the application launcher

4562

4563

.. container:: paragraph

4564

4565

Summary of alternatives to start the APEX application

4566

launcher:

4567

4568

+-------------------------------------------------+---------------------------------------------------+

4569

| Unix, Cygwin | Windows |

4570

+=================================================+===================================================+

4571

| .. container:: | .. container:: |

4572

| | |

4573

| .. container:: listingblock | .. container:: listingblock |

4574

| | |

4575

| .. container:: content | .. container:: content |

4576

| | |

4577

| .. code:: | .. code:: |

4578

| | |

4579

| # $APEX_HOME/bin/apexApps.sh [args] | > %APEX_HOME%\bin\apexApps.bat [args] |

4580

+-------------------------------------------------+---------------------------------------------------+

4581

4582

.. container:: paragraph

4583

4584

The option ``-h`` provides a help screen with all launcher

4585

command line arguments.

4586

4587

.. container:: listingblock

4588

4589

.. container:: content

4590

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4591

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4592

4593

apexApps.sh - runs APEX applications

4594

4595

Usage: apexApps.sh [options] | [<application> [<application options>]]

4596

4597

Options

4598

-d <app> - describes an application

4599

-l - lists all applications supported by this script

4600

-h - this help screen

4601

4602

.. container:: paragraph

4603

4604

Using ``-l`` lists all known application the launcher can

4605

start.

4606

4607

.. container:: listingblock

4608

4609

.. container:: content

4610

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4611

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4612

4613

apexApps.sh: supported applications:

4614

--> ws-echo engine eng-monitoring full-client eng-deployment tpl-event-json model-2-cli rest-editor cli-editor ws-console

4615

4616

.. container:: paragraph

4617

4618

Using the ``-d <name>`` option describes the named

4619

application, for instance for the ``ws-console``:

4620

4621

.. container:: listingblock

4622

4623

.. container:: content

4624

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4625

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4626

4627

apexApps.sh: application 'ws-console'

4628

--> a simple console sending events to APEX, connect to APEX consumer port

4629

4630

.. container:: paragraph

4631

4632

Launching an application is done by calling the script with

4633

only the application name and any CLI arguments for the

4634

application. For instance, starting the ``ws-echo``

4635

application with port ``8888``:

4636

4637

.. container:: listingblock

4638

4639

.. container:: content

4640

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4641

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4642

4643

apexApps.sh ws-echo -p 8888

4644

4645

Application: Create Event Templates

4646

-----------------------------------

4647

4648

.. container:: paragraph

4649

4650

**Status: Experimental**

4651

4652

.. container:: paragraph

4653

4654

This application takes a policy model (JSON or XML encoded)

4655

and generates templates for events in JSON format. This can

4656

help when a policy defines rather complex trigger or action

4657

events or complex events between states. The application can

4658

produce events for the types: stimuli (policy trigger

4659

events), internal (events between policy states), and

4660

response (action events).

4661

4662

+----------------------------------------------------------------+------------------------------------------------------------------+

4663

| Unix, Cygwin | Windows |

4664

+================================================================+==================================================================+

4665

| .. container:: | .. container:: |

4666

| | |

4667

| .. container:: listingblock | .. container:: listingblock |

4668

| | |

4669

| .. container:: content | .. container:: content |

4670

| | |

4671

| .. code:: | .. code:: |

4672

| | |

4673

| # $APEX_HOME/bin/apexApps.sh tpl-event-json [args] | > %APEX_HOME%\bin\apexApps.bat tpl-event-json [args] |

4674

+----------------------------------------------------------------+------------------------------------------------------------------+

4675

4676

.. container:: paragraph

4677

4678

The option ``-h`` provides a help screen.

4679

4680

.. container:: listingblock

4681

4682

.. container:: content

4683

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4684

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4685

4686

gen-model2event v{release-version} - generates JSON templates for events generated from a policy model

4687

usage: gen-model2event

4688

-h,--help prints this help and usage screen

4689

-m,--model <MODEL-FILE> set the input policy model file

4690

-t,--type <TYPE> set the event type for generation, one of:

4691

stimuli (trigger events), response (action

4692

events), internal (events between states)

4693

-v,--version prints the application version

4694

4695

.. container:: paragraph

4696

4697

The created templates are not valid events, instead they use

4698

some markup for values one will need to change to actual

4699

values. For instance, running the tool with the *Sample

4700

Domain* policy model as:

4701

4702

.. container:: listingblock

4703

4704

.. container:: content

4705

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4706

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4707

4708

apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli

4709

4710

.. container:: paragraph

4711

4712

will produce the following status messages:

4713

4714

.. container:: listingblock

4715

4716

.. container:: content

4717

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4718

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4719

4720

gen-model2event: starting Event generator

4721

--> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json

4722

--> type: stimuli

4723

4724

.. container:: paragraph

4725

4726

and then run the generator application producing two event

4727

templates. The first template is called ``Event0000``.

4728

4729

.. container:: listingblock

4730

4731

.. container:: content

.. code::

{

"name" : "Event0000",

4737

"nameSpace" : "org.onap.policy.apex.sample.events",

4738

"version" : "0.0.1",

4739

"source" : "Outside",

4740

"target" : "Match",

4741

"TestTemperature" : ###double: 0.0###,

4742

"TestTimestamp" : ###long: 0###,

4743

"TestMatchCase" : ###integer: 0###,

4744

"TestSlogan" : "###string###"

4745

}

4746

4747

.. container:: paragraph

4748

4749

The values for the keys are marked with ``#`` and the

4750

expected type of the value. To create an actual stimuli

4751

event, all these markers need to be change to actual values,

4752

for instance:

4753

4754

.. container:: listingblock

4755

4756

.. container:: content

4757

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4758

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4759

4760

{

4761

"name" : "Event0000",

4762

"nameSpace" : "org.onap.policy.apex.sample.events",

4763

"version" : "0.0.1",

4764

"source" : "Outside",

4765

"target" : "Match",

4766

"TestTemperature" : 25,

4767

"TestTimestamp" : 123456789123456789,

4768

"TestMatchCase" : 1,

4769

"TestSlogan" : "Testing the Match Case with Temperature 25"

4770

}

4771

4772

Application: Convert a Policy Model to CLI Editor Commands

4773

----------------------------------------------------------

4774

4775

.. container:: paragraph

4776

4777

**Status: Experimental**

4778

4779

.. container:: paragraph

4780

4781

This application takes a policy model (JSON or XML encoded)

4782

and generates commands for the APEX CLI Editor. This

4783

effectively reverses a policy specification realized with

4784

the CLI Editor.

4785

4786

+-------------------------------------------------------------+---------------------------------------------------------------+

4787

| Unix, Cygwin | Windows |

4788

+=============================================================+===============================================================+

4789

| .. container:: | .. container:: |

4790

| | |

4791

| .. container:: listingblock | .. container:: listingblock |

4792

| | |

4793

| .. container:: content | .. container:: content |

4794

| | |

4795

| .. code:: | .. code:: |

4796

| | |

4797

| # $APEX_HOME/bin/apexApps.sh model-2-cli [args] | > %APEX_HOME%\bin\apexApps.bat model-2-cli [args] |

4798

+-------------------------------------------------------------+---------------------------------------------------------------+

4799

4800

.. container:: paragraph

4801

4802

The option ``-h`` provides a help screen.

4803

4804

.. container:: listingblock

4805

4806

.. container:: content

4807

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4808

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4809

4810

usage: gen-model2cli

4811

-h,--help prints this help and usage screen

4812

-m,--model <MODEL-FILE> set the input policy model file

4813

-sv,--skip-validation switch of validation of the input file

4814

-v,--version prints the application version

4815

4816

.. container:: paragraph

4817

4818

For instance, running the tool with the *Sample Domain*

4819

policy model as:

4820

4821

.. container:: listingblock

4822

4823

.. container:: content

4824

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4825

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4826

4827

apexApps.sh model-2-cli -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json

4828

4829

.. container:: paragraph

4830

4831

will produce the following status messages:

4832

4833

.. container:: listingblock

4834

4835

.. container:: content

4836

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

4837

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

4838

4839

gen-model2cli: starting CLI generator

4840

--> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json

4841

4842

.. container:: paragraph

4843

4844

and then run the generator application producing all CLI

4845

Editor commands and printing them to standard out.

4846

4847

Application: Websocket Clients (Echo and Console)

4848

-------------------------------------------------

4849

4850

.. container:: paragraph

4851

4852

**Status: Production**

4853

4854

.. container:: paragraph

4855

4856

The application launcher also provides a Websocket echo

4857

client and a Websocket console client. The echo client

4858

connects to APEX and prints all events it receives from

4859

APEX. The console client connects to APEX, reads input from

4860

the command line, and sends this input as events to APEX.

4861

4862

+------------------------------------------------------------+--------------------------------------------------------------+

4863

| Unix, Cygwin | Windows |

4864

+============================================================+==============================================================+

4865

| .. container:: | .. container:: |

4866

| | |

4867

| .. container:: listingblock | .. container:: listingblock |

4868

| | |

4869

| .. container:: content | .. container:: content |

4870

| | |

4871

| .. code:: | .. code:: |

4872

| | |

4873

| # $APEX_HOME/bin/apexApps.sh ws-echo [args] | > %APEX_HOME%\bin\apexApps.bat ws-echo [args] |

4874

| # $APEX_HOME/bin/apexApps.sh ws-console [args] | > %APEX_HOME%\bin\apexApps.bat ws-console [args] |

4875

+------------------------------------------------------------+--------------------------------------------------------------+

4876

4877

.. container:: paragraph

4878

4879

The arguments are the same for both applications:

.. container:: ulist

- ``-p`` defines the Websocket port to connect to (defaults

4884

to ``8887``)

4885

4886

- ``-s`` defines the host on which a Websocket server is

4887

running (defaults to ``localhost``)

4888

4889

.. container:: paragraph

4890

4891

A discussion on how to use these two applications to build

4892

an APEX system is detailed HowTo-Websockets.

My First Policy

^^^^^^^^^^^^^^^

Introduction

------------

.. container:: paragraph

4900

4901

Consider a scenario where a supermarket chain called

4902

*HyperM* controls how it sells items in a policy-based

4903

manner. Each time an item is processed by *HyperM*'s

4904

point-of-sale (PoS) system an event is generated and

4905

published about that item of stock being sold. This event

4906

can then be used to update stock levels, etc..

4907

4908

.. container:: paragraph

4909

4910

*HyperM* want to extend this approach to allow some checks

4911

to be performed before the sale can be completed. This can

4912

be achieved by requesting a policy-controlled decision as

4913

each item is processed by for sale by each PoS system. The

4914

decision process is integrated with *HyperM*'s other IT

4915

systems that manage stock control, sourcing and purchasing,

4916

personnel systems, etc.

4917

4918

.. container:: paragraph

4919

4920

In this document we will show how APEX and APEX Policies can

4921

be used to achieve this, starting with a simple policy,

4922

building up to more complicated policy that demonstrates the

features of APEX.

Data Models

-----------

Sales Input Event

#################

.. container:: paragraph

4932

4933

Each time a PoS system processes a sales item an event

4934

with the following format is emitted:

4935

4936

.. table:: Table 1. Sale Input Event

4937

4938

+----------------------+----------------------+-----------------------+

4939

| Event | Fields | Description |

4940

+======================+======================+=======================+

4941

| SALE_INPUT | time, sale_ID, | Event indicating a |

4942

| | amount, item_ID, | sale of an item is |

4943

| | quantity, | occurring |

4944

| | assistant_ID, | |

4945

| | branch_ID, notes, … | |

4946

+----------------------+----------------------+-----------------------+

4947

4948

.. container:: paragraph

4949

4950

In each ``SALE_INPUT`` event the ``sale_ID`` field is a

4951

unique ID generated by the PoS system. A timestamp for

4952

the event is stored in the ``time`` field. The ``amount``

4953

field refers to the value of the item(s) to be sold (in

4954

cents). The ``item_ID`` field is a unique identifier for

4955

each item type, and can be used to retrieve more

4956

information about the item from *HyperM*'s stock control

4957

system. The ``quantity`` field refers to the quantity of

4958

the item to be sold. The ``assistant_ID`` field is a

4959

unique identifier for the PoS operator, and can be used

4960

to retrieve more information about the operator from the

4961

*HyperM*'s personnel system. Since *HyperM* has many

4962

branches the ``branch_ID`` identifies the shop. The

4963

``notes`` field contains arbitrary notes about the sale.

Sales Decision Event

####################

.. container:: paragraph

4969

4970

After a ``SALE_INPUT`` event is emitted by the PoS system

4971

*HyperM*'s policy-based controlled sales checking system

4972

emits a Sale Authorization Event indicating whether the

4973

sale is authorized or denied. The PoS system can then

4974

listen for this event before continuing with the sale.

4975

4976

.. table:: Table 2. Sale Authorisation Event

4977

4978

+----------------------+----------------------+-----------------------+

4979

| Event | Fields | Description |

4980

+======================+======================+=======================+

4981

| SALE_AUTH | sale_ID, time, | Event indicating a |

4982

| | authorized, amount, | sale of an item is |

4983

| | item_ID, quantity, | authorized or denied |

4984

| | assistant_ID, | |

4985

| | branch_ID, notes, | |

4986

| | message… | |

4987

+----------------------+----------------------+-----------------------+

4988

4989

.. container:: paragraph

4990

4991

In each ``SALE_AUTH`` event the ``sale_ID`` field is

4992

copied from the ``SALE_INPUT`` event that trigger the

4993

decision request. The ``SALE_AUTH`` event is also

4994

timestamped using the ``time`` field, and a field called

4995

``authorised`` is set to ``true`` or ``false`` depending

4996

on whether the sale is authorized or denied. The

4997

``message`` field carries an optional message about why a

4998

sale was not authorized. The other fields from the

4999

``SALE_INPUT`` event are also included for completeness.

Stock Control: Items

####################

.. container:: paragraph

5005

5006

*HyperM* maintains information about each item for sale

5007

in a database table called ``ITEMS``.

5008

5009

.. table:: Table 3. Items Database

5010

5011

+----------------------+----------------------+-----------------------+

5012

| Table | Fields | Description |

5013

+======================+======================+=======================+

5014

| ITEMS | item_ID, | Database table |

5015

| | description, | describing each item |

5016

| | cost_price, barcode, | for sale |

5017

| | supplier_ID, | |

5018

| | category, … | |

5019

+----------------------+----------------------+-----------------------+

5020

5021

.. container:: paragraph

5022

5023

The database table ``ITEMS`` has a row for each items

5024

that *HyperM* sells. Each item is identified by an

5025

``item_ID`` value. The ``description`` field stores a

5026

description of the item. The cost price of the item is

5027

given in ``cost_price``. The barcode of the item is

5028

encoded in ``barcode``, while the item supplier is

5029

identified by ``supplier_ID``. Items may also be

5030

classified into categories using the ``category`` field.

5031

Useful categories might include: ``soft drinks``,

5032

``alcoholic drinks``, ``cigarettes``, ``knives``,

5033

``confectionery``, ``bakery``, ``fruit&vegetables``,

5034

``meat``, etc..

5035

5036

Personnel System: Assistants

5037

############################

5038

5039

.. table:: Table 4. Assistants Database

5040

5041

+----------------------+----------------------+-----------------------+

5042

| Table | Fields | Description |

5043

+======================+======================+=======================+

5044

| ASSISTANTS | assistant_ID, | Database table |

5045

| | surname, firstname, | describing each |

5046

| | middlename, age, | *HyperM* sales |

5047

| | grade, phone_number, | assistant |

5048

| | … | |

5049

+----------------------+----------------------+-----------------------+

5050

5051

.. container:: paragraph

5052

5053

The database table ``ASSISTANTS`` has a row for each

5054

sales assistant employed by *HyperM*. Each assistant is

5055

identified by an ``assistant_ID`` value, with their name

5056

given in the ``firstname``, ``middlename`` and

5057

``surname`` fields. The assistant’s age in years is given

5058

in ``age``, while their phone number is contained in the

5059

``phone_number`` field. The assistant’s grade is encoded

5060

in ``grade``. Useful values for ``grade`` might include:

5061

``trainee``, ``operator``, ``supervisor``, etc..

Locations: Branches

####################

.. table:: Table 5. Branches Database

5067

5068

+----------------------+----------------------+-----------------------+

5069

| Table | Fields | Description |

5070

+======================+======================+=======================+

5071

| BRANCHES | branch_ID, | Database table |

5072

| | branch_Name, | describing each |

5073

| | category, street, | *HyperM* branch |

5074

| | city, country, | |

5075

| | postcode, … | |

5076

+----------------------+----------------------+-----------------------+

5077

5078

.. container:: paragraph

5079

5080

*HyperM* operates a number of branches. Each branch is

5081

described in the ``BRANCHES`` database table. Each branch

5082

is identified by a ``branch_ID``, with a branch name

5083

given in ``branch_Name``. The address for the branch is

5084

encoded in ``street``, ``city``, ``country`` and

5085

``postcode``. The branch category is given in the

5086

``category`` field. Useful values for ``category`` might

5087

include: ``Small``, ``Large``, ``Super``, ``Hyper``,

etc..

Policy Step 1

-------------

Scenario

#########

.. container:: paragraph

5096

5097

For the first version of our policy, let’s start with

5098

something simple. Let us assume that there exists some

5099

restriction that alcohol products cannot be sold before

5100

11:30am. In this section we will go through the necessary

5101

steps to define a policy that can enforce this for

*HyperM*.

.. container:: ulist

- Alcohol cannot be sold before 11:30am.

5107

5108

Create the an new empty Policy Model ``MyFirstPolicyModel``

5109

###########################################################

5110

5111

.. container:: paragraph

5112

5113

Since an organisation like *HyperM* may have many

5114

policies covering many different domains, policies should

5115

be grouped into policy sets. In order to edit or deploy a

5116

policy, or policy set, the definition of the policy(ies)

5117

and all required events, tasks, states, etc., are grouped

5118

together into a 'Policy Model'. An organization might

5119

define many Policy Models, each containing a different

5120

set of policies.

5121

5122

.. container:: paragraph

5123

5124

So the first step is to create a new empty Policy Model

5125

called ``MyFirstPolicyModel``. Using the APEX Policy

5126

Editor, click on the 'File' menus and select 'New'. Then

5127

define our new policy model called

5128

``MyFirstPolicyModel``. Use the 'Generate UUID' button to

5129

create a new unique ID for the policy model, and fill in

5130

a description for the policy model. Press the ``Submit``

5131

button to save your changes.

5132

5133

.. container:: imageblock

5134

5135

.. container:: content

5136

5137

|File > New to create a new Policy Model|

.. container:: title

Figure 4. Create a new Policy Model 1/2

5142

5143

.. container:: imageblock

5144

5145

.. container:: content

5146

5147

|Create a new Policy Model|

.. container:: title

Figure 5. Create a new Policy Model 2/2

5152

5153

Create the input event ``SALE_INPUT`` and the output event ``SALE_AUTH``

5154

########################################################################

5155

5156

.. container:: paragraph

5157

5158

Using the APEX Policy Editor, click on the 'Events' tab.

5159

In the 'Events' pane, right click and select 'New':

5160

5161

.. container:: imageblock

5162

5163

.. container:: content

5164

5165

|Right click to create a new event|

.. container:: title

Figure 6. Create a new Event type

5170

5171

.. container:: paragraph

5172

5173

Create a new event type called ``SALE_INPUT``. Use the

5174

'Generate UUID' button to create a new unique ID for the

5175

event type, and fill in a description for the event. Add

5176

a namespace, e.g. ``com.hyperm``. We can add hard-coded

5177

strings for the ``Source`` and ``Target``, e.g. ``POS``

5178

and ``APEX``. At this stage we will not add any parameter

5179

fields, we will leave this until later. Use the

5180

``Submit`` button to create the event.

5181

5182

.. container:: imageblock

5183

5184

.. container:: content

5185

5186

|Fill in the necessary information for the

5187

'SALE_INPUT' event and click 'Submit'|

.. container:: title

Figure 7. Populate the ``SALE_INPUT`` event

5192

5193

.. container:: paragraph

5194

5195

Repeat the same steps for a new event type called

5196

``SALE_AUTH``. Just use ``APEX`` as source and ``POS`` as

5197

target, since this is the output event coming from APEX

5198

going to the sales point.

5199

5200

.. container:: paragraph

5201

5202

Before we can add parameter fields to an event we must

5203

first define APEX Context Item Schemas that can be used

5204

by those fields.

5205

5206

.. container:: paragraph

5207

5208

To create new item schemas, click on the 'Context Item

5209

Schemas' tab. In that 'Context Item Schemas' pane, right

5210

click and select 'Create new ContextSchema'.

5211

5212

.. container:: imageblock

5213

5214

.. container:: content

5215

5216

|Right click to create a new Item Schema|

.. container:: title

Figure 8. Create new Data Types

5221

5222

.. container:: paragraph

5223

5224

Create item schemas with the following characteristics,

5225

each with its own unique UUID:

5226

5227

.. table:: Table 6. Item Schemas

5228

5229

+-------------------+-----------------+-----------------+----------------------+

5230

5231

5232

+===================+=================+=================+======================+

5233

5234

5235

+-------------------+-----------------+-----------------+----------------------+

+-------------------+-----------------+-----------------+----------------------+

+-------------------+-----------------+-----------------+----------------------+

+-------------------+-----------------+-----------------+----------------------+

+-------------------+-----------------+-----------------+----------------------+

5252

5253

| | | er | ``quantity`` |

5254

5255

+-------------------+-----------------+-----------------+----------------------+

+-------------------+-----------------+-----------------+----------------------+

5260

5261

| | | g | ``notes`` |

5262

5263

+-------------------+-----------------+-----------------+----------------------+

5264

5265

| | | an | ``authorised`` |

5266

5267

+-------------------+-----------------+-----------------+----------------------+

5268

5269

| | | g | ``message`` |

5270

5271

+-------------------+-----------------+-----------------+----------------------+

5272

5273

.. container:: imageblock

5274

5275

.. container:: content

5276

5277

|Create a new Item Schema|

.. container:: title

Figure 9. Create new Item Schemas

5282

5283

.. container:: paragraph

5284

5285

The item schemas can now be seen on the 'Context Item

5286

Schemas' tab, and can be updated at any time by

5287

right-clicking on the item schemas on the 'Context Item

5288

Schemas' tab. Now we can go back to the event definitions

5289

for ``SALE_INPUT`` and ``SALE_AUTH`` and add some

5290

parameter fields.

5291

5292

.. tip

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

.. container:: title

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

5296

Field Schema types

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

5297

5298

.. container:: paragraph

5299

5300

APEX natively supports schema definitions in ``Java`` and ``Avro``.

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

5301

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

5302

.. container:: paragraph

5303

5304

``Java`` schema definitions are simply the name of a Java Class. There are some restrictions:

.. container:: ulist

- the class must be instantiatable, i.e. not an Java interface or abstract class

5309

5310

- primitive types are not supported, i.e. use ``java.lang.Integer`` instead of ``int``, etc.

5311

5312

- it must be possible to find the class, i.e. the class must be contained in the Java classpath.

5313

5314

.. container:: paragraph

5315

5316

``Avro`` schema definitions can be any valid `Avro <https://avro.apache.org/docs/current/spec.html>`__

5317

schema. For events using fields defined with ``Avro`` schemas, any incoming event containing that field must

5318

contain a value that conforms to the Avro schema.

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

5319

5320

.. container:: paragraph

5321

5322

Click on the 'Events' tab, then right click the

5323

``SALE_INPUT`` row and select 'Edit Event

5324

: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`

5325

event add the following event parameters:

5326

5327

.. table:: Table 7. Event Parameter Fields for the ``SALE_INPUT`` Event

5328

5329

+----------------------+----------------------+-----------------------+

5330

| Parameter Name | Parameter Type | Optional |

5331

+======================+======================+=======================+

5332

| time | timestamp_type | no |

5333

+----------------------+----------------------+-----------------------+

5334

| sale_ID | sale_ID_type | no |

5335

+----------------------+----------------------+-----------------------+

5336

| amount | price_type | no |

5337

+----------------------+----------------------+-----------------------+

5338

| item_ID | item_ID_type | no |

5339

+----------------------+----------------------+-----------------------+

5340

| quantity | quantity_type | no |

5341

+----------------------+----------------------+-----------------------+

5342

| assistant_ID | assistant_ID_type | no |

5343

+----------------------+----------------------+-----------------------+

5344

| branch_ID | branch_ID_type | no |

5345

+----------------------+----------------------+-----------------------+

5346

| notes | notes_type | *yes* |

5347

+----------------------+----------------------+-----------------------+

5348

5349

.. container:: paragraph

5350

5351

Remember to click the 'Submit' button at the bottom of

5352

the event definition pane.

5353

5354

.. tip::

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

5355

Optional Fields in APEX Events

5356

Parameter fields can be *optional* in events. If a parameter is not marked as *optional* then by default it

5357

is *mandatory*, so it must appear in any input event passed to APEX. If an *optional* field is not set

5358

for an output event then value will be set to ``null``.

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

5359

5360

.. container:: imageblock

5361

5362

.. container:: content

5363

5364

|Add new event parameters to an event|

.. container:: title

Figure 10. Add typed parameter fields to an event

5369

5370

.. container:: paragraph

5371

5372

Select the ``SALE_AUTH`` event and add the following

5373

event parameters:

5374

5375

.. table:: Table 8. Event Parameter Fields for the ``SALE_AUTH`` Event

5376

5377

+----------------------+----------------------+-----------------------+

5378

| Parameter Name | Parameter Type | no |

5379

+======================+======================+=======================+

5380

| sale_ID | sale_ID_type | no |

5381

+----------------------+----------------------+-----------------------+

5382

| time | timestamp_type | no |

5383

+----------------------+----------------------+-----------------------+

5384

| authorised | authorised_type | no |

5385

+----------------------+----------------------+-----------------------+

5386

| message | message_type | *yes* |

5387

+----------------------+----------------------+-----------------------+

5388

| amount | price_type | no |

5389

+----------------------+----------------------+-----------------------+

5390

| item_ID | item_ID_type | no |

5391

+----------------------+----------------------+-----------------------+

5392

| assistant_ID | assistant_ID_type | no |

5393

+----------------------+----------------------+-----------------------+

5394

| quantity | quantity_type | no |

5395

+----------------------+----------------------+-----------------------+

5396

| branch_ID | branch_ID_type | no |

5397

+----------------------+----------------------+-----------------------+

5398

| notes | notes_type | *yes* |

5399

+----------------------+----------------------+-----------------------+

5400

5401

.. container:: paragraph

5402

5403

Remember to click the 'Submit' button at the bottom of

5404

the event definition pane.

5405

5406

.. container:: paragraph

5407

5408

The events for our policy are now defined.

5409

5410

Create a new Policy and add the *"No Booze before 11:30"* check

5411

###############################################################

5412

5413

.. container:: paragraph

5414

5415

APEX policies are defined using a state-machine model.

5416

Each policy comprises one or more *states* that can be

5417

individually executed. Where there is more than one

5418

*state* the states are chained together to form a

5419

`Directed Acyclic Graph

5420

(DAG) <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__

5421

of states. A *state* is triggered by passing it a single

5422

input (or 'trigger') event and once executed each state

5423

then emits an output event. For each *state* the logic

5424

for the *state* is embedded in one or more *tasks*. Each

5425

*task* contains specific *task logic* that is executed by

5426

the APEX execution environment each time the *task* is

5427

invoked. Where there is more than one *task* in a *state*

5428

then the *state* also defines some *task selection logic*

5429

to select an appropriate task each time the *state* is

5430

executed.

5431

5432

.. container:: paragraph

5433

5434

Therefore, to create a new policy we must first define

5435

one or more tasks.

5436

5437

.. container:: paragraph

5438

5439

To create a new Task click on the 'Tasks' tab. In the

5440

'Tasks' pane, right click and select 'Create new Task'.

5441

Create a new Task called ``MorningBoozeCheck``. Use the

5442

'Generate UUID' button to create a new unique ID for the

5443

task, and fill in a description for the task.

5444

5445

.. container:: imageblock

5446

5447

.. container:: content

5448

5449

|Right click to create a new task|

.. container:: title

Figure 11. Create a new Task

5454

5455

.. container:: paragraph

5456

5457

Tasks are configured with a set of *input fields* and a

5458

set of *output fields*. To add new input/output fields

5459

for a task use the 'Add Task Input Field' and 'Add Task

5460

Output Field' button. The list of input and out fields to

5461

add for the ``MorningBoozeCheck`` task are given below.

5462

The input fields are drawn from the parameters in the

5463

state’s input event, and the task’s output fields are

5464

used to populate the state’s output event. The task’s

5465

input and output fields must be a subset of the event

5466

parameters defined for the input and output events for

5467

any state that uses that task. (You may have noticed that

5468

the input and output fields for the ``MorningBoozeCheck``

5469

task have the exact same names and reuse the item schemas

5470

that we used for the parameters in the ``SALE_INPUT`` and

5471

``SALE_AUTH`` events respectively).

5472

5473

.. table:: Table 9. Input fields for ``MorningBoozeCheck`` task

5474

5475

+-----------------------------------+-----------------------------------+

5476

| Parameter Name | Parameter Type |

5477

+===================================+===================================+

5478

| time | timestamp_type |

5479

+-----------------------------------+-----------------------------------+

5480

| sale_ID | sale_ID_type |

5481

+-----------------------------------+-----------------------------------+

5482

| amount | price_type |

5483

+-----------------------------------+-----------------------------------+

5484

| item_ID | item_ID_type |

5485

+-----------------------------------+-----------------------------------+

5486

| quantity | quantity_type |

5487

+-----------------------------------+-----------------------------------+

5488

| assistant_ID | assistant_ID_type |

5489

+-----------------------------------+-----------------------------------+

5490

| branch_ID | branch_ID_type |

5491

+-----------------------------------+-----------------------------------+

5492

| notes | notes_type |

5493

+-----------------------------------+-----------------------------------+

5494

5495

.. table:: Table 10. Output fields for ``MorningBoozeCheck`` task

5496

5497

+-----------------------------------+-----------------------------------+

5498

| Parameter Name | Parameter Type |

5499

+===================================+===================================+

5500

| sale_ID | sale_ID_type |

5501

+-----------------------------------+-----------------------------------+

5502

| time | timestamp_type |

5503

+-----------------------------------+-----------------------------------+

5504

| authorised | authorised_type |

5505

+-----------------------------------+-----------------------------------+

5506

| message | message_type |

5507

+-----------------------------------+-----------------------------------+

5508

| amount | price_type |

5509

+-----------------------------------+-----------------------------------+

5510

| item_ID | item_ID_type |

5511

+-----------------------------------+-----------------------------------+

5512

| assistant_ID | assistant_ID_type |

5513

+-----------------------------------+-----------------------------------+

5514

| quantity | quantity_type |

5515

+-----------------------------------+-----------------------------------+

5516

| branch_ID | branch_ID_type |

5517

+-----------------------------------+-----------------------------------+

5518

| notes | notes_type |

5519

+-----------------------------------+-----------------------------------+

5520

5521

.. container:: imageblock

5522

5523

.. container:: content

5524

5525

|Add input and out fields for the task|

.. container:: title

Figure 12. Add input and out fields for the Task

5530

5531

.. container:: paragraph

5532

5533

Each task must include some 'Task Logic' that implements

5534

the behaviour for the task. Task logic can be defined in

5535

a number of different ways using a choice of languages.

5536

For this task we will author the logic using the

5537

Java-like scripting language called

5538

```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__.

5539

5540

.. container:: paragraph

5541

5542

For simplicity use the following code for the task logic.

5543

Paste the script text into the 'Task Logic' box, and use

5544

"MVEL" as the 'Task Logic Type / Flavour'.

5545

5546

.. container:: paragraph

5547

5548

This logic assumes that all items with ``item_ID``

5549

between 1000 and 2000 contain alcohol, which is not very

5550

realistic, but we will see a better approach for this

5551

later. It also uses the standard ``Java`` time utilities

5552

to check if the current time is between ``00:00:00 GMT``

5553

and ``11:30:00 GMT``. For a detailed guide to how to

5554

write your own logic in

5555

```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__,

5556

```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__ or one

5557

of the other supported languages please refer to APEX

5558

Programmers Guide.

5559

5560

.. container:: listingblock

.. container:: title

MVEL code for the ``MorningBoozeCheck`` task

5565

5566

.. container:: content

5567

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

5568

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

5569

5570

/*

5571

* ============LICENSE_START=======================================================

5572

5573

* ================================================================================

5574

* Licensed under the Apache License, Version 2.0 (the "License");

5575

* you may not use this file except in compliance with the License.

5576

* You may obtain a copy of the License at

5577

*

5578

* http://www.apache.org/licenses/LICENSE-2.0

5579

*

5580

* Unless required by applicable law or agreed to in writing, software

5581

* distributed under the License is distributed on an "AS IS" BASIS,

5582

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

5583

* See the License for the specific language governing permissions and

5584

* limitations under the License.

5585

*

5586

* SPDX-License-Identifier: Apache-2.0

5587

* ============LICENSE_END=========================================================

5588

*/

5589

import java.util.Date;

5590

import java.util.Calendar;

5591

import java.util.TimeZone;

5592

import java.text.SimpleDateFormat;

5593

5594

logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'");

5595

5596

outFields.put("amount" , inFields.get("amount"));

5597

outFields.put("assistant_ID", inFields.get("assistant_ID"));

5598

outFields.put("notes" , inFields.get("notes"));

5599

outFields.put("quantity" , inFields.get("quantity"));

5600

outFields.put("branch_ID" , inFields.get("branch_ID"));

5601

outFields.put("item_ID" , inFields.get("item_ID"));

5602

outFields.put("time" , inFields.get("time"));

5603

outFields.put("sale_ID" , inFields.get("sale_ID"));

5604

5605

item_id = inFields.get("item_ID");

5606

5607

//The events used later to test this task use GMT timezone!

5608

gmt = TimeZone.getTimeZone("GMT");

5609

timenow = Calendar.getInstance(gmt);

5610

df = new SimpleDateFormat("HH:mm:ss z");

5611

df.setTimeZone(gmt);

5612

timenow.setTimeInMillis(inFields.get("time"));

5613

5614

midnight = timenow.clone();

5615

midnight.set(

5616

timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),

5617

timenow.get(Calendar.DATE),0,0,0);

5618

eleven30 = timenow.clone();

5619

eleven30.set(

5620

timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),

5621

timenow.get(Calendar.DATE),11,30,0);

5622

5623

itemisalcohol = false;

5624

if(item_id != null && item_id >=1000 && item_id < 2000)

5625

itemisalcohol = true;

5626

5627

if( itemisalcohol

5628

&& timenow.after(midnight) && timenow.before(eleven30)){

5629

outFields.put("authorised", false);

5630

outFields.put("message", "Sale not authorised by policy task "+subject.taskName+

5631

" for time "+df.format(timenow.getTime())+

5632

". Alcohol can not be sold between "+df.format(midnight.getTime())+

5633

" and "+df.format(eleven30.getTime()));

return true;

}

else{

outFields.put("authorised", true);

5638

outFields.put("message", "Sale authorised by policy task "+subject.taskName+

5639

" for time "+df.format(timenow.getTime()));

return true;

}

/*

This task checks if a sale request is for an item that is an alcoholic drink.

5645

If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not

5646

authorised. Otherwise the sale is authorised.

5647

In this implementation we assume that items with item_ID value between 1000 and

5648

2000 are all alcoholic drinks :-)

5649

*/

5650

5651

.. container:: imageblock

5652

5653

.. container:: content

5654

5655

|Add task logic the task|

.. container:: title

Figure 13. Add Task Logic the Task

5660

5661

.. container:: paragraph

5662

5663

An alternative version of the same logic is available in

5664

JavaScript. Just use "JAVASCRIPT" as the 'Task Logic Type

5665

/ Flavour' instead.

5666

5667

.. container:: listingblock

.. container:: title

Javascript alternative for the ``MorningBoozeCheck``

5672

task

5673

5674

.. container:: content

5675

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

5676

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

5677

5678

/*

5679

* ============LICENSE_START=======================================================

5680

5681

* ================================================================================

5682

* Licensed under the Apache License, Version 2.0 (the "License");

5683

* you may not use this file except in compliance with the License.

5684

* You may obtain a copy of the License at

5685

*

5686

* http://www.apache.org/licenses/LICENSE-2.0

5687

*

5688

* Unless required by applicable law or agreed to in writing, software

5689

* distributed under the License is distributed on an "AS IS" BASIS,

5690

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

5691

* See the License for the specific language governing permissions and

5692

* limitations under the License.

5693

*

5694

* SPDX-License-Identifier: Apache-2.0

5695

* ============LICENSE_END=========================================================

5696

*/

5697

5698

var returnValueType = Java.type("java.lang.Boolean");

5699

var returnValue = new returnValueType(true);

5700

5701

// Load compatibility script for imports etc

5702

load("nashorn:mozilla_compat.js");

5703

importPackage(java.text);

5704

importClass(java.text.SimpleDateFormat);

5705

5706

executor.logger.info("Task Execution: '"+executor.subject.id+"'. Input Fields: '"+executor.inFields+"'");

5707

5708

executor.outFields.put("amount" , executor.inFields.get("amount"));

5709

executor.outFields.put("assistant_ID", executor.inFields.get("assistant_ID"));

5710

executor.outFields.put("notes" , executor.inFields.get("notes"));

5711

executor.outFields.put("quantity" , executor.inFields.get("quantity"));

5712

executor.outFields.put("branch_ID" , executor.inFields.get("branch_ID"));

5713

executor.outFields.put("item_ID" , executor.inFields.get("item_ID"));

5714

executor.outFields.put("time" , executor.inFields.get("time"));

5715

executor.outFields.put("sale_ID" , executor.inFields.get("sale_ID"));

5716

5717

item_id = executor.inFields.get("item_ID");

5718

5719

//All times in this script are in GMT/UTC since the policy and events assume time is in GMT.

5720

var timenow_gmt = new Date(Number(executor.inFields.get("time")));

5721

5722

var midnight_gmt = new Date(Number(executor.inFields.get("time")));

5723

midnight_gmt.setUTCHours(0,0,0,0);

5724

5725

var eleven30_gmt = new Date(Number(executor.inFields.get("time")));

5726

eleven30_gmt.setUTCHours(11,30,0,0);

5727

5728

var timeformatter = new java.text.SimpleDateFormat("HH:mm:ss z");

5729

5730

var itemisalcohol = false;

5731

if(item_id != null && item_id >=1000 && item_id < 2000)

5732

itemisalcohol = true;

5733

5734

if( itemisalcohol

5735

&& timenow_gmt.getTime() >= midnight_gmt.getTime()

5736

&& timenow_gmt.getTime() < eleven30_gmt.getTime()) {

5737

5738

executor.outFields.put("authorised", false);

5739

executor.outFields.put("message", "Sale not authorised by policy task " +

5740

executor.subject.taskName+ " for time " + timeformatter.format(timenow_gmt.getTime()) +

5741

". Alcohol can not be sold between " + timeformatter.format(midnight_gmt.getTime()) +

5742

" and " + timeformatter.format(eleven30_gmt.getTime()));

5743

}

5744

else{

5745

executor.outFields.put("authorised", true);

5746

executor.outFields.put("message", "Sale authorised by policy task " +

5747

executor.subject.taskName + " for time "+timeformatter.format(timenow_gmt.getTime()));

}

/*

This task checks if a sale request is for an item that is an alcoholic drink.

5752

If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not

5753

authorised. Otherwise the sale is authorised.

5754

In this implementation we assume that items with item_ID value between 1000 and

5755

2000 are all alcoholic drinks :-)

5756

*/

5757

5758

.. container:: paragraph

5759

5760

The task definition is now complete so click the 'Submit'

5761

button to save the task. The task can now be seen on the

5762

'Tasks' tab, and can be updated at any time by

5763

right-clicking on the task on the 'Task' tab. Now that we

5764

have created our task, we can can create a policy that

5765

uses that task.

5766

5767

.. container:: paragraph

5768

5769

To create a new Policy click on the 'Policies' tab. In

5770

the 'Policies' pane, right click and select 'Create new

5771

Policy':

5772

5773

.. container:: paragraph

5774

5775

Create a new Policy called ``MyFirstPolicy``. Use the

5776

'Generate UUID' button to create a new unique ID for the

5777

policy, and fill in a description for the policy. Use

5778

'FREEFORM' as the 'Policy Flavour'.

5779

5780

.. container:: paragraph

5781

5782

Each policy must have at least one state. Since this is

5783

'freeform' policy we can add as many states as we wish.

5784

Let’s start with one state. Add a new state called

5785

``BoozeAuthDecide`` to this ``MyFirstPolicy`` policy

5786

using the 'Add new State' button after filling in the

5787

name of our new state.

5788

5789

.. container:: imageblock

5790

5791

.. container:: content

5792

5793

|Create a new policy|

.. container:: title

Figure 14. Create a new Policy

5798

5799

.. container:: paragraph

5800

5801

Each state must uses one input event type. For this new

5802

state select the ``SALE_INPUT`` event as the input event.

5803

5804

.. container:: paragraph

5805

5806

Each policy must define a 'First State' and a 'Policy

5807

Trigger Event'. The 'Policy Trigger Event' is the input

5808

event for the policy as a whole. This event is then

5809

passed to the first state in the chain of states in the

5810

policy, therefore the 'Policy Trigger Event' will be the

5811

input event for the first state. Each policy can only

5812

have one 'First State'. For our ``MyFirstPolicy`` policy,

5813

select ``BoozeAuthDecide`` as the 'First State'. This

5814

will automatically select ``SALE_INPUT`` as the 'Policy

5815

Trigger Event' for our policy.

5816

5817

.. container:: imageblock

5818

5819

.. container:: content

|Create a state|

.. container:: title

Figure 15. Create a new State

5826

5827

.. container:: paragraph

5828

5829

In this case we will create a reference the pre-existing

5830

``MorningBoozeCheck`` task that we defined above using

5831

the 'Add New Task' button. Select the

5832

``MorningBoozeCheck`` task, and use the name of the task

5833

as the 'Local Name' for the task.

5834

5835

.. container:: paragraph

5836

5837

in the case where a state references more than one task,

5838

a 'Default Task' must be selected for the state and some

5839

logic ('Task Selection Logic') must be specified to

5840

select the appropriate task at execution time. Since our

5841

new state ``BoozeAuthDecide`` only has one task the

5842

default task is automatically selected and no 'Task

5843

Selection Logic' is required.

5844

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

5845

.. note::

5846

.. container:: title

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

5847

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

5848

State Output Mappings

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

5849

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

5850

.. container:: paragraph

5851

5852

In a 'Policy' 'State' a 'State Output Mapping' has 3 roles:

5853

1) Select which 'State' should be executed next, 2) Select

5854

the type of the state’s 'Outgoing Event', and 3)

5855

Populate the state’s 'Outgoing Event'. This is how states are

5856

chained together to form a (`Directed Acyclic Graph

5857

(DAG) <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__ )

5858

of states. The final state(s) of a policy are those that do

5859

not select any 'next' state. Since a 'State' can only

5860

accept a single type of event, the type of the event emitted

5861

by a previous 'State' must be match the incoming event type

5862

of the next 'State'. This is also how the last state(s) in

5863

a policy can emit events of different types. The 'State

5864

Output Mapping' is also responsible for taking the

5865

fields that are output by the task executed in the state and

5866

populating the state’s output event before it is emitted.

5867

5868

.. container:: paragraph

5869

5870

Each 'Task' referenced in 'State' must have a defined

5871

'Output Mapping' to take the output of the task, select an

5872

'Outgoing Event' type for the state, populate the state’s

5873

outgoing event, and then select the next state to be

5874

executed (if any).

5875

5876

.. container:: paragraph

5877

5878

There are 2 basic types of output mappings:

5879

5880

.. container:: olist arabic

5881

5882

#. **Direct Output Mappings** have a single value for

5883

'Next State' and a single value for 'State Output

5884

Event'. The outgoing event for the state is

5885

automatically created, any outgoing event parameters

5886

that were present in the incoming event are copied

5887

into the outgoing event, then any task output fields

5888

that have the same name and type as parameters in the

5889

outgoing event are automatically copied into

5890

the outgoing event.

5891

5892

#. **Logic-based State Output Mappings / Finalizers**

5893

have some logic defined that dynamically selects

5894

and creates the 'State Outgoing Event', manages

5895

the population of the outgoing event parameters

5896

(perhaps changing or adding to the outputs from the

5897

task), and then dynamically selects the next state to

5898

be executed (if any).

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

5899

5900

.. container:: paragraph

5901

5902

Each task reference must also have an associated 'Output

5903

State Mapping' so we need an 'Output State Mapping' for

5904

the ``BoozeAuthDecide`` state to use when the

5905

``MorningBoozeCheck`` task is executed. The simplest type

5906

of output mapping is a 'Direct Output Mapping'.

5907

5908

.. container:: paragraph

5909

5910

Create a new 'Direct Output Mapping' for the state called

5911

``MorningBoozeCheck_Output_Direct`` using the 'Add New

5912

Direct State Output Mapping' button. Select ``SALE_AUTH``

5913

as the output event and select ``None`` for the next

5914

state value. We can then select this output mapping for

5915

use when the the ``MorningBoozeCheck`` task is executed.

5916

Since there is only state, and only one task for that

5917

state, this output mapping ensures that the

5918

``BoozeAuthDecide`` state is the only state executed and

5919

the state (and the policy) can only emit events of type

5920

``SALE_AUTH``. (You may remember that the output fields

5921

for the ``MorningBoozeCheck`` task have the exact same

5922

names and reuse the item schemas that we used for the

5923

parameters in ``SALE_AUTH`` event. The

5924

``MorningBoozeCheck_Output_Direct`` direct output mapping

5925

can now automatically copy the values from the

5926

``MorningBoozeCheck`` task directly into outgoing

5927

``SALE_AUTH`` events.)

5928

5929

.. container:: imageblock

5930

5931

.. container:: content

5932

5933

|Add a Task and Output Mapping|

.. container:: title

Figure 16. Add a Task and Output Mapping

5938

5939

.. container:: paragraph

5940

5941

Click the 'Submit' button to complete the definition of

5942

our ``MyFirstPolicy`` policy. The policy

5943

``MyFirstPolicy`` can now be seen in the list of policies

5944

on the 'Policies' tab, and can be updated at any time by

5945

right-clicking on the policy on the 'Policies' tab.

5946

5947

.. container:: paragraph

5948

5949

The ``MyFirstPolicyModel``, including our

5950

``MyFirstPolicy`` policy can now be checked for errors.

5951

Click on the 'Model' menu and select 'Validate'. The

5952

model should validate without any 'Warning' or 'Error'

5953

messages. If you see any 'Error' or 'Warning' messages,

5954

carefully read the message as a hint to find where you

5955

might have made a mistake when defining some aspect of

5956

your policy model.

5957

5958

.. container:: imageblock

5959

5960

.. container:: content

5961

5962

|Validate the policy model for error using the 'Model'

5963

> 'Validate' menu item|

.. container:: title

Figure 17. Validate a Policy Model

5968

5969

.. container:: paragraph

5970

5971

Congratulations, you have now completed your first APEX

5972

policy. The policy model containing our new policy can

5973

now be exported from the editor and saved. Click on the

5974

'File' menu and select 'Download' to save the policy

5975

model in JSON format. The exported policy model is then

5976

available in the directory you selected, for instance

5977

``$APEX_HOME/examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json``.

5978

The exported policy can now be loaded into the APEX

5979

Policy Engine, or can be re-loaded and edited by the APEX

5980

Policy Editor.

5981

5982

.. container:: imageblock

5983

5984

.. container:: content

5985

5986

|Download the completed policy model using the 'File'

5987

> 'Download' menu item|

.. container:: title

Figure 18. Export a Policy Model

Test Policy Step 1

##################

.. container:: paragraph

5997

5998

To start a new APEX Engine you can use the following

5999

configuration. In a full APEX installation you can find

6000

this configuration in

6001

``$APEX_HOME/examples/config/MyFirstPolicy/1/MyFirstPolicyConfigStdin2StdoutJsonEvent.json``.

6002

This configuration expects incoming events to be in

6003

``JSON`` format and to be passed into the APEX Engine

6004

from ``stdin``, and result events will be printed in

6005

``JSON`` format to ``stdout``. This configuration loads

6006

the policy model stored in the file

6007

'MyFirstPolicyModel_0.0.1.json' as exported from the APEX

6008

Editor. Note, you may need to edit this file to provide

6009

the full path to wherever you stored the exported policy

6010

model file.

6011

6012

.. container:: listingblock

.. container:: title

JSON to load and execute *My First Policy*, read input

6017

JSON events from ``stdin``, and emit output events to

6018

``stdout``

6019

6020

.. container:: content

.. code::

{

"engineServiceParameters" : {

6026

"name" : "MyFirstPolicyApexEngine",

"version" : "0.0.1",

"id" : 101,

"instanceCount" : 4,

"deploymentPort" : 12345,

6031

"policyModelFileName" : "examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json",

6032

"engineParameters" : {

6033

"executorParameters" : {

6034

"MVEL" : {

6035

"parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"

6036

},

6037

"JAVASCRIPT" : {

6038

"parameterClassName" : "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"

}

}

}

},

"eventOutputParameters": {

6044

"FirstProducer": {

6045

"carrierTechnologyParameters" : {

6046

"carrierTechnology" : "FILE",

"parameters" : {

"standardIO" : true

}

},

"eventProtocolParameters" : {

6052

"eventProtocol" : "JSON"

}

}

},

"eventInputParameters": {

6057

"FirstConsumer": {

6058

"carrierTechnologyParameters" : {

6059

"carrierTechnology" : "FILE",

"parameters" : {

"standardIO" : true

}

},

"eventProtocolParameters" : {

6065

"eventProtocol" : "JSON"

}

}

}

}

.. container:: paragraph

6072

6073

To test the policy try paste the following events into

6074

the console as the APEX engine executes:

6075

6076

.. table:: Table 11. Inputs and Outputs when testing *My First Policy*

6077

6078

+------------------------------------------+-------------------------------------------+-----------+

6079

| Input Event (JSON) | Output Event (JSON) | comment |

6080

+==========================================+===========================================+===========+

6081

| .. container:: | .. container:: | Request |

6082

| | | to buy a |

6083

| .. container:: listingblock | .. container:: listingblock | non-alcoh |

6084

| | | olic |

6085

| | .. container:: content | item |

6086

| .. container:: content | | (``item_I |

6087

| | .. code:: | D=5123``) |

6088

| | | at |

6089

| .. code:: | { | *10:13:09 |

6090

| | "name": "SALE_AUTH", | * |

6091

| | | on |

6092

| { | "version": "0.0.1", | *Tuesday, |

6093

| "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | 10 |

6094

| "name" : "SALE_INPUT", | "source": "", | January |

6095

| "version": "0.0.1", | "target": "", | 2017*. |

6096

| "time" : 1483351989000, | "amount": 299, | Sale is |

6097

| "sale_ID": 99999991, | "assistant_ID": 23, | authorize |

6098

| "amount": 299, | "authorised": true, | d. |

6099

| "item_ID": 5123, | "branch_ID": 1, | |

6100

| "quantity": 1, | "item_ID": 5123, | |

6101

| "assistant_ID": 23, | "message": "Sale authorised | |

6102

| "branch_ID": 1, | by policy task MorningBo | |

6103

| "notes": "Special Offer!!" | ozeCheck for time 10:13:09 | |

6104

| } | GMT", | |

6105

| | "notes": "Special Offer!!", | |

6106

| | "quantity": 1, | |

6107

| | "sale_ID": 99999991, | |

6108

| | "time": 1483351989000 | |

| | } | |

| | | |

| | | |

| | | |

+------------------------------------------+-------------------------------------------+-----------+

6114

| .. container:: | .. container:: | Request |

6115

| | | to buy |

6116

| .. container:: listingblock | .. container:: listingblock | alcohol |

6117

| | | item |

6118

| .. container:: content | .. container:: content | (``item_I |

6119

| | | D=1249``) |

6120

| .. code:: | .. code:: | at |

6121

| | | *08:41:06 |

6122

| { | { | * |

6123

| "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | on |

6124

| "name": "SALE_INPUT", | "name": "SALE_AUTH", | *Monday, |

6125

| "version": "0.0.1", | "source": "", | 02 |

6126

| "time": 1483346466000, | "target": "", | January |

6127

| "sale_ID": 99999992, | "amount": 1249, | 2017*. |

6128

| "version": "0.0.1", | "assistant_ID": 12, | |

6129

| "amount": 1249, | "authorised": false, | Sale is |

6130

| "item_ID": 1012, | "branch_ID": 2, | not |

6131

| "quantity": 1, | "item_ID": 1012, | authorize |

6132

| "assistant_ID": 12, | "message": "Sale not | d. |

6133

| "branch_ID": 2 | authorised by policy task | |

6134

| } | MorningBoozeCheck for time | |

6135

| | 08:41:06 GMT. Alcohol can | |

6136

| | not be sold between | |

6137

| | 00:00:00 GMT and 11:30:00 | |

6138

| | GMT", | |

6139

| | "notes": null, | |

6140

| | "quantity": 1, | |

6141

| | "sale_ID": 99999992, | |

6142

| | "time": 1483346466000 | |

6143

| | } | |

6144

+------------------------------------------+-------------------------------------------+-----------+

6145

| .. container:: | .. container:: | Request |

6146

| | | to buy |

6147

| .. container:: listingblock | .. container:: listingblock | alcohol |

6148

| | | (``item_I |

6149

| | .. container:: content | D=1943``) |

6150

| .. container:: content | | at |

6151

| | .. code:: | *20:17:13 |

6152

| | | * |

6153

| .. code:: | { | on |

6154

| | "name": "SALE_AUTH", | *Tuesday, |

6155

| { | "version": "0.0.1", | 20 |

6156

| "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | December |

6157

| "name" : "SALE_INPUT", | "source": "", | 2016*. |

6158

| "version": "0.0.1", | "target": "", | |

6159

| "time" : 1482265033000, | "amount": 4799, | Sale is |

6160

| "sale_ID": 99999993, | "assistant_ID": 9, | authorize |

6161

| "amount": 4799, | "authorised": true, | d. |

6162

| "item_ID": 1943, | "branch_ID": 3, | |

6163

| "quantity": 2, | "item_ID": 1943, | |

6164

| "assistant_ID": 9, | "message": "Sale authorised | |

6165

| "branch_ID": 3 | by policy task MorningBo | |

6166

| } | ozeCheck for time 20:17:13 | |

6167

| | GMT", | |

6168

| | "notes": null, | |

6169

| | "quantity": 2, | |

6170

| | "sale_ID": 99999993, | |

6171

| | "time": 1482265033000 | |

6172

| | } | |

6173

+------------------------------------------+-------------------------------------------+-----------+

6174

6175

4.3.6. Policy 1 in CLI Editor

6176

#############################

6177

6178

.. container:: paragraph

6179

6180

An equivalent version of the ``MyFirstPolicyModel``

6181

policy model can again be generated using the APEX CLI

6182

editor. A sample APEX CLI script is shown below:

6183

6184

.. container:: listingblock

.. container:: title

APEX CLI Editor code for Policy 1

6189

6190

.. container:: content

6191

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

6192

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

6193

6194

#-------------------------------------------------------------------------------

6195

# ============LICENSE_START=======================================================

6196

6197

# ================================================================================

6198

# Licensed under the Apache License, Version 2.0 (the "License");

6199

# you may not use this file except in compliance with the License.

6200

# You may obtain a copy of the License at

6201

#

6202

# http://www.apache.org/licenses/LICENSE-2.0

6203

#

6204

# Unless required by applicable law or agreed to in writing, software

6205

# distributed under the License is distributed on an "AS IS" BASIS,

6206

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

6207

# See the License for the specific language governing permissions and

6208

# limitations under the License.

6209

#

6210

# SPDX-License-Identifier: Apache-2.0

6211

# ============LICENSE_END=========================================================

6212

#-------------------------------------------------------------------------------

6213

6214

model create name=MyFirstPolicyModel version=0.0.1 uuid=540226fb-55ee-4f0e-a444-983a0494818e description="This is my first Apex Policy Model."

6215

6216

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

6217

6218

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

6219

6220

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

6221

6222

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

6223

6224

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

6225

6226

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

6227

6228

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

6229

6230

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

6231

6232

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

6233

6234

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

6235

6236

task create name=MorningBoozeCheck version=0.0.1 uuid=3351b0f4-cf06-4fa2-8823-edf67bd30223 description=LS

6237

This task checks if the sales request is for an item that contains alcohol.

6238

If the local time is between 00:00:00 and 11:30:00 then the sale is not authorised. Otherwise the sale is authorised.

6239

In this implementation we assume that all items with item_ID values between 1000 and 2000 contain alcohol :-)

6240

LE

6241

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1

6242

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1

6243

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1

6244

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true

6245

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1

6246

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1

6247

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1

6248

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1

6249

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1

6250

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1

6251

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1

6252

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true

6253

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1

6254

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1

6255

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1

6256

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1

6257

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1

6258

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true

6259

task logic create name=MorningBoozeCheck version=0.0.1 logicFlavour=MVEL logic=LS

6260

/*

6261

* ============LICENSE_START=======================================================

6262

6263

* ================================================================================

6264

* Licensed under the Apache License, Version 2.0 (the "License");

6265

* you may not use this file except in compliance with the License.

6266

* You may obtain a copy of the License at

6267

*

6268

* http://www.apache.org/licenses/LICENSE-2.0

6269

*

6270

* Unless required by applicable law or agreed to in writing, software

6271

* distributed under the License is distributed on an "AS IS" BASIS,

6272

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

6273

* See the License for the specific language governing permissions and

6274

* limitations under the License.

6275

*

6276

* SPDX-License-Identifier: Apache-2.0

6277

* ============LICENSE_END=========================================================

6278

*/

6279

import java.util.Date;

6280

import java.util.Calendar;

6281

import java.util.TimeZone;

6282

import java.text.SimpleDateFormat;

6283

6284

logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'");

6285

6286

outFields.put("amount" , inFields.get("amount"));

6287

outFields.put("assistant_ID", inFields.get("assistant_ID"));

6288

outFields.put("notes" , inFields.get("notes"));

6289

outFields.put("quantity" , inFields.get("quantity"));

6290

outFields.put("branch_ID" , inFields.get("branch_ID"));

6291

outFields.put("item_ID" , inFields.get("item_ID"));

6292

outFields.put("time" , inFields.get("time"));

6293

outFields.put("sale_ID" , inFields.get("sale_ID"));

6294

6295

item_id = inFields.get("item_ID");

6296

6297

//The events used later to test this task use GMT timezone!

6298

gmt = TimeZone.getTimeZone("GMT");

6299

timenow = Calendar.getInstance(gmt);

6300

df = new SimpleDateFormat("HH:mm:ss z");

6301

df.setTimeZone(gmt);

6302

timenow.setTimeInMillis(inFields.get("time"));

6303

6304

midnight = timenow.clone();

6305

midnight.set(

6306

timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),

6307

timenow.get(Calendar.DATE),0,0,0);

6308

eleven30 = timenow.clone();

6309

eleven30.set(

6310

timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),

6311

timenow.get(Calendar.DATE),11,30,0);

6312

6313

itemisalcohol = false;

6314

if(item_id != null && item_id >=1000 && item_id < 2000)

6315

itemisalcohol = true;

6316

6317

if( itemisalcohol

6318

&& timenow.after(midnight) && timenow.before(eleven30)){

6319

outFields.put("authorised", false);

6320

outFields.put("message", "Sale not authorised by policy task "+subject.taskName+

6321

" for time "+df.format(timenow.getTime())+

6322

". Alcohol can not be sold between "+df.format(midnight.getTime())+

6323

" and "+df.format(eleven30.getTime()));

return true;

}

else{

outFields.put("authorised", true);

6328

outFields.put("message", "Sale authorised by policy task "+subject.taskName+

6329

" for time "+df.format(timenow.getTime()));

return true;

}

/*

This task checks if a sale request is for an item that is an alcoholic drink.

6335

If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not

6336

authorised. Otherwise the sale is authorised.

6337

In this implementation we assume that items with item_ID value between 1000 and

6338

2000 are all alcoholic drinks :-)

*/

LE

event create name=SALE_AUTH version=0.0.1 uuid=c4500941-3f98-4080-a9cc-5b9753ed050b description="An event emitted by the Policy to indicate whether the sale of an item has been authorised" nameSpace=com.hyperm source="APEX" target="POS"

6343

event parameter create name=SALE_AUTH version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1

6344

event parameter create name=SALE_AUTH version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1

6345

event parameter create name=SALE_AUTH version=0.0.1 parName=authorised schemaName=authorised_type schemaVersion=0.0.1

6346

event parameter create name=SALE_AUTH version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1

6347

event parameter create name=SALE_AUTH version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1

6348

event parameter create name=SALE_AUTH version=0.0.1 parName=message schemaName=message_type schemaVersion=0.0.1 optional=true

6349

event parameter create name=SALE_AUTH version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true

6350

event parameter create name=SALE_AUTH version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1

6351

event parameter create name=SALE_AUTH version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1

6352

event parameter create name=SALE_AUTH version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1

6353

6354

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"

6355

event parameter create name=SALE_INPUT version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1

6356

event parameter create name=SALE_INPUT version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1

6357

event parameter create name=SALE_INPUT version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1

6358

event parameter create name=SALE_INPUT version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1

6359

event parameter create name=SALE_INPUT version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true

6360

event parameter create name=SALE_INPUT version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1

6361

event parameter create name=SALE_INPUT version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1

6362

event parameter create name=SALE_INPUT version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1

6363

6364

6365

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

6366

policy state create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide triggerName=SALE_INPUT triggerVersion=0.0.1 defaultTaskName=MorningBoozeCheck defaultTaskVersion=0.0.1

6367

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

6368

policy state taskref create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide taskLocalName=MorningBoozeCheck taskName=MorningBoozeCheck taskVersion=0.0.1 outputType=DIRECT outputName=MorningBoozeCheck_Output_Direct

Policy Step 2

-------------

Scenario

#########

.. container:: paragraph

6376

6377

*HyperM* have just opened a new branch in a different

6378

country, but that country has different rules about when

6379

alcohol can be sold! In this section we will go through

6380

the necessary steps to extend our policy to enforce this

for *HyperM*.

.. container:: ulist

- In some branches alcohol cannot be sold before 1pm,

6386

and not at all on Sundays.

6387

6388

.. container:: paragraph

6389

6390

Although there are a number of ways to accomplish this

6391

the easiest approach for us is to define another task and

6392

then select which task is appropriate at runtime

6393

depending on the branch identifier in the incoming event.

6394

6395

Extend the Policy with the new Scenario

6396

#######################################

6397

6398

.. container:: paragraph

6399

6400

To create a new Task click on the 'Tasks' tab. In the

6401

'Tasks' pane, right click and select 'Create new Task':

6402

6403

.. container:: paragraph

6404

6405

Create a new Task called ``MorningBoozeCheckAlt1``. Use

6406

the 'Generate UUID' button to create a new unique ID for

6407

the task, and fill in a description for the task. Select

6408

the same input and output fields that we used earlier

6409

when we defined the ``MorningBoozeCheck`` task earlier.

6410

6411

.. table:: Table 12. Input fields for ``MorningBoozeCheckAlt1`` task

6412

6413

+-----------------------------------+-----------------------------------+

6414

| Parameter Name | Parameter Type |

6415

+===================================+===================================+

6416

| time | timestamp_type |

6417

+-----------------------------------+-----------------------------------+

6418

| sale_ID | sale_ID_type |

6419

+-----------------------------------+-----------------------------------+

6420

| amount | price_type |

6421

+-----------------------------------+-----------------------------------+

6422

| item_ID | item_ID_type |

6423

+-----------------------------------+-----------------------------------+

6424

| quantity | quantity_type |

6425

+-----------------------------------+-----------------------------------+

6426

| assistant_ID | assistant_ID_type |

6427

+-----------------------------------+-----------------------------------+

6428

| branch_ID | branch_ID_type |

6429

+-----------------------------------+-----------------------------------+

6430

| notes | notes_type |

6431

+-----------------------------------+-----------------------------------+

6432

6433

.. table:: Table 13. Output fields for ``MorningBoozeCheckAlt1`` task

6434

6435

+-----------------------------------+-----------------------------------+

6436

| Parameter Name | Parameter Type |

6437

+===================================+===================================+

6438

| sale_ID | sale_ID_type |

6439

+-----------------------------------+-----------------------------------+

6440

| time | timestamp_type |

6441

+-----------------------------------+-----------------------------------+

6442

| authorised | authorised_type |

6443

+-----------------------------------+-----------------------------------+

6444

| message | message_type |

6445

+-----------------------------------+-----------------------------------+

6446

| amount | price_type |

6447

+-----------------------------------+-----------------------------------+

6448

| item_ID | item_ID_type |

6449

+-----------------------------------+-----------------------------------+

6450

| assistant_ID | assistant_ID_type |

6451

+-----------------------------------+-----------------------------------+

6452

| quantity | quantity_type |

6453

+-----------------------------------+-----------------------------------+

6454

| branch_ID | branch_ID_type |

6455

+-----------------------------------+-----------------------------------+

6456

| notes | notes_type |

6457

+-----------------------------------+-----------------------------------+

6458

6459

.. container:: paragraph

6460

6461

This task also requires some 'Task Logic' to implement

6462

the new behaviour for this task.

6463

6464

.. container:: paragraph

6465

6466

For simplicity use the following code for the task logic.

6467

It again assumes that all items with ``item_ID`` between

6468

1000 and 2000 contain alcohol. We again use the standard

6469

``Java`` time utilities to check if the current time is

6470

between ``00:00:00 CET`` and ``13:00:00 CET`` or if it is

6471

``Sunday``.

6472

6473

.. container:: paragraph

6474

6475

For this task we will again author the logic using the

6476

```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__

6477

scripting language. Sample task logic code (specified in

6478

```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__) is

6479

given below. For a detailed guide to how to write your

6480

own logic in

6481

```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__,

6482

```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__ or one

6483

of the other supported languages please refer to APEX

6484

Programmers Guide.

6485

6486

.. container:: listingblock

.. container:: title

MVEL code for the ``MorningBoozeCheckAlt1`` task

6491

6492

.. container:: content

6493

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

6494

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

6495

6496

/*

6497

* ============LICENSE_START=======================================================

6498

6499

* ================================================================================

6500

* Licensed under the Apache License, Version 2.0 (the "License");

6501

* you may not use this file except in compliance with the License.

6502

* You may obtain a copy of the License at

6503

*

6504

* http://www.apache.org/licenses/LICENSE-2.0

6505

*

6506

* Unless required by applicable law or agreed to in writing, software

6507

* distributed under the License is distributed on an "AS IS" BASIS,

6508

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

6509

* See the License for the specific language governing permissions and

6510

* limitations under the License.

6511

*

6512

* SPDX-License-Identifier: Apache-2.0

6513

* ============LICENSE_END=========================================================

6514

*/

6515

import java.util.Date;

6516

import java.util.Calendar;

6517

import java.util.TimeZone;

6518

import java.text.SimpleDateFormat;

6519

6520

logger.info("Task Execution: '"+subject.id+"'. Input Event: '"+inFields+"'");

6521

6522

outFields.put("amount" , inFields.get("amount"));

6523

outFields.put("assistant_ID", inFields.get("assistant_ID"));

6524

outFields.put("notes" , inFields.get("notes"));

6525

outFields.put("quantity" , inFields.get("quantity"));

6526

outFields.put("branch_ID" , inFields.get("branch_ID"));

6527

outFields.put("item_ID" , inFields.get("item_ID"));

6528

outFields.put("time" , inFields.get("time"));

6529

outFields.put("sale_ID" , inFields.get("sale_ID"));

6530

6531

item_id = inFields.get("item_ID");

6532

6533

//The events used later to test this task use CET timezone!

6534

cet = TimeZone.getTimeZone("CET");

6535

timenow = Calendar.getInstance(cet);

6536

df = new SimpleDateFormat("HH:mm:ss z");

6537

df.setTimeZone(cet);

6538

timenow.setTimeInMillis(inFields.get("time"));

6539

6540

midnight = timenow.clone();

6541

midnight.set(

6542

timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),

6543

timenow.get(Calendar.DATE),0,0,0);

6544

onepm = timenow.clone();

6545

onepm.set(

6546

timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),

6547

timenow.get(Calendar.DATE),13,0,0);

6548

6549

itemisalcohol = false;

6550

if(item_id != null && item_id >=1000 && item_id < 2000)

6551

itemisalcohol = true;

6552

6553

if( itemisalcohol &&

6554

( (timenow.after(midnight) && timenow.before(onepm))

6555

||

6556

(timenow.get(Calendar.DAY_OF_WEEK) == Calendar.SUNDAY)

6557

)){

6558

outFields.put("authorised", false);

6559

outFields.put("message", "Sale not authorised by policy task "+subject.taskName+

6560

" for time "+df.format(timenow.getTime())+

6561

". Alcohol can not be sold between "+df.format(midnight.getTime())+

6562

" and "+df.format(onepm.getTime()) +" or on Sunday");

return true;

}

else{

outFields.put("authorised", true);

6567

outFields.put("message", "Sale authorised by policy task "+subject.taskName+

6568

" for time "+df.format(timenow.getTime()));

return true;

}

/*

This task checks if a sale request is for an item that is an alcoholic drink.

6574

If the local time is between 00:00:00 CET and 13:00:00 CET then the sale is not authorised.

6575

Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised.

6576

In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks :-)

6577

*/

6578

6579

.. container:: imageblock

6580

6581

.. container:: content

6582

6583

|Create a new alternative task MorningBoozeCheckAlt1|

.. container:: title

Figure 19. Create a new Task

6588

6589

.. container:: paragraph

6590

6591

The task definition is now complete so click the 'Submit'

6592

button to save the task. Now that we have created our

6593

task, we can can add this task to the single pre-existing

6594

state (``BoozeAuthDecide``) in our policy.

6595

6596

.. container:: paragraph

6597

6598

To edit the ``BoozeAuthDecide`` state in our policy click

6599

on the 'Policies' tab. In the 'Policies' pane, right

6600

click on our ``MyFirstPolicy`` policy and select 'Edit'.

6601

Navigate to the ``BoozeAuthDecide`` state in the 'states'

6602

section at the bottom of the policy definition pane.

6603

6604

.. container:: imageblock

6605

6606

.. container:: content

6607

6608

|Right click to edit a policy|

.. container:: title

Figure 20. Edit a Policy

6613

6614

.. container:: paragraph

6615

6616

To add our new task ``MorningBoozeCheckAlt1``, scroll

6617

down to the ``BoozeAuthDecide`` state in the 'States'

6618

section. In the 'State Tasks' section for

6619

``BoozeAuthDecide`` use the 'Add new task' button. Select

6620

our new ``MorningBoozeCheckAlt1`` task, and use the name

6621

of the task as the 'Local Name' for the task. The

6622

``MorningBoozeCheckAlt1`` task can reuse the same

6623

``MorningBoozeCheck_Output_Direct`` 'Direct State Output

6624

Mapping' that we used for the ``MorningBoozeCheck`` task.

6625

(Recall that the role of the 'State Output Mapping' is to

6626

select the output event for the state, and select the

6627

next state to be executed. These both remain the same as

6628

before.)

6629

6630

.. container:: paragraph

6631

6632

Since our state has more than one task we must define

6633

some logic to determine which task should be used each

6634

time the state is executed. This *task selection logic*

6635

is defined in the state definition. For our

6636

``BoozeAuthDecide`` state we want the choice of which

6637

task to use to be based on the ``branch_ID`` from which

6638

the ``SALE_INPUT`` event originated. For simplicity sake

6639

let us assume that branches with ``branch_ID`` between

6640

``0`` and ``999`` should use the ``MorningBoozeCheck``

6641

task, and the branches with with ``branch_ID`` between

6642

``1000`` and ``1999`` should use the

6643

``MorningBoozeCheckAlt1`` task.

6644

6645

.. container:: paragraph

6646

6647

This time, for variety, we will author the task selection

6648

logic using the

6649

```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__

6650

scripting language. Sample task selection logic code

6651

(specified in

6652

```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__)

6653

is given below. Paste the script text into the 'Task

6654

Selection Logic' box, and use "JAVASCRIPT" as the 'Task

6655

Selection Logic Type / Flavour'. It is necessary to mark

6656

one of the tasks as the 'Default Task' so that the task

6657

selection logic always has a fallback default option in

6658

cases where a particular task cannot be selected. In this

6659

case the ``MorningBoozeCheck`` task can be the default

6660

task.

6661

6662

.. container:: listingblock

.. container:: title

JavaScript code for the ``BoozeAuthDecide`` task

6667

selection logic

6668

6669

.. container:: content

6670

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

6671

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

6672

6673

/*

6674

* ============LICENSE_START=======================================================

6675

6676

* ================================================================================

6677

* Licensed under the Apache License, Version 2.0 (the "License");

6678

* you may not use this file except in compliance with the License.

6679

* You may obtain a copy of the License at

6680

*

6681

* http://www.apache.org/licenses/LICENSE-2.0

6682

*

6683

* Unless required by applicable law or agreed to in writing, software

6684

* distributed under the License is distributed on an "AS IS" BASIS,

6685

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

6686

* See the License for the specific language governing permissions and

6687

* limitations under the License.

6688

*

6689

* SPDX-License-Identifier: Apache-2.0

6690

* ============LICENSE_END=========================================================

*/

var returnValueType = Java.type("java.lang.Boolean");

6695

var returnValue = new returnValueType(true);

6696

6697

executor.logger.info("Task Selection Execution: '"+executor.subject.id+

6698

"'. Input Event: '"+executor.inFields+"'");

6699

6700

branchid = executor.inFields.get("branch_ID");

6701

taskorig = executor.subject.getTaskKey("MorningBoozeCheck");

6702

taskalt = executor.subject.getTaskKey("MorningBoozeCheckAlt1");

6703

taskdef = executor.subject.getDefaultTaskKey();

6704

6705

if(branchid >=0 && branchid <1000){

6706

taskorig.copyTo(executor.selectedTask);

6707

}

6708

else if (branchid >=1000 && branchid <2000){

6709

taskalt.copyTo(executor.selectedTask);

6710

}

6711

else{

6712

taskdef.copyTo(executor.selectedTask);

}

/*

This task selection logic selects task "MorningBoozeCheck" for branches with

6717

0<=branch_ID<1000 and selects task "MorningBoozeCheckAlt1" for branches with

6718

1000<=branch_ID<2000. Otherwise the default task is selected.

6719

In this case the default task is also "MorningBoozeCheck"

6720

*/

6721

6722

.. container:: imageblock

6723

6724

.. container:: content

6725

6726

|State definition with 2 Tasks and Task Selection

Logic|

.. container:: title

Figure 21. State definition with 2 Tasks and Task

6732

Selection Logic

6733

6734

.. container:: paragraph

6735

6736

When complete don’t forget to click the 'Submit' button

6737

at the bottom of 'Policies' pane for our

6738

``MyFirstPolicy`` policy after updating the

6739

``BoozeAuthDecide`` state.

6740

6741

.. container:: paragraph

6742

6743

Congratulations, you have now completed the second step

6744

towards your first APEX policy. The policy model

6745

containing our new policy can again be validated and

6746

exported from the editor and saved as shown in Step 1.

6747

6748

.. container:: paragraph

6749

6750

The exported policy model is then available in the

6751

directory you selected, as

6752

`MyFirstPolicyModel_0.0.1.json <files/mfp-files/2/MyFirstPolicyModel_0.0.1.json>`__.

6753

The exported policy can now be loaded into the APEX

6754

Policy Engine, or can be re-loaded and edited by the APEX

Policy Editor.

Test Policy Step 2

##################

.. container:: paragraph

6761

6762

To start a new APEX Engine you can use the following

6763

configuration. In a full APEX installation you can find

6764

this configuration in

6765

``$APEX_HOME/examples/config/MyFirstPolicy/2/MyFirstPolicyConfigStdin2StdoutJsonEvent.json``.

6766

Note, this has changed from the configuration file in

6767

Step 1 to enable the ``JAVASCRIPT`` executor for our new

6768

'Task Selection Logic'.

6769

6770

.. container:: listingblock

.. container:: title

JSON to load and execute *My First Policy*, read input

6775

JSON events from ``stdin``, and emit output events to

6776

``stdout``

6777

6778

.. container:: content

6779

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

6780

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

6781

6782

{

6783

"engineServiceParameters" : {

6784

"name" : "MyFirstPolicyApexEngine",

"version" : "0.0.1",

"id" : 102,

"instanceCount" : 4,

"deploymentPort" : 12345,

6789

"policyModelFileName" : "examples/models/MyFirstPolicy/2/MyFirstPolicyModel_0.0.1.json",

6790

"engineParameters" : {

6791

"executorParameters" : {

6792

"MVEL" : {

6793

"parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"

6794

},

6795

"JAVASCRIPT" : {

6796

"parameterClassName" : "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"

}

}

}

},

"eventOutputParameters": {

6802

"FirstProducer": {

6803

"carrierTechnologyParameters" : {

6804

"carrierTechnology" : "FILE",

"parameters" : {

"standardIO" : true

}

},

"eventProtocolParameters" : {

6810

"eventProtocol" : "JSON"

}

}

},

"eventInputParameters": {

6815

"FirstConsumer": {

6816

"carrierTechnologyParameters" : {

6817

"carrierTechnology" : "FILE",

"parameters" : {

"standardIO" : true

}

},

"eventProtocolParameters" : {

6823

"eventProtocol" : "JSON"

}

}

}

}

.. container:: paragraph

6830

6831

To test the policy try paste the following events into

6832

the console as the APEX engine executes. Note, all tests

6833

from Step 1 will still work perfectly since none of those

6834

events originate from a branch with ``branch_ID`` between

6835

``1000`` and ``2000``. The 'Task Selection Logic' will

6836

therefore pick the ``MorningBoozeCheck`` task as

6837

expected, and will therefore give the same results.

6838

6839

.. table:: Table 14. Inputs and Outputs when testing *My First Policy*

6840

6841

+----------------------------------------------+------------------------------------------------------------+---------------------------+

6842

| Input Event (JSON) | Output Event (JSON) | comment |

6843

+==============================================+============================================================+===========================+

6844

| .. container:: | .. container:: | Request to buy |

6845

| | | alcohol item |

6846

| .. container:: listingblock | .. container:: listingblock | (``item_ID=1249``) |

6847

| | | |

6848

| | | at *08:41:06 |

6849

| | .. container:: content | GMT* on *Monday, |

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

6850

| .. container:: content | | 02 January |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

6851

| | .. code:: | 2017*. |

6852

| | | |

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

6853

| | { | Sale is not |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

6854

| .. code:: | "nameSpace": "com.hyperm", | authorized. Uses |

6855

| | "name": "SALE_AUTH", | the |

6856

| | "version": "0.0.1", | ``MorningBoozeCheck`` |

6857

| { | "source": "", | |

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

6858

| "nameSpace": "com.hyperm", | "target": "", | task. |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

6859

| "name": "SALE_INPUT", | "amount": 1249, | |

6860

| "version": "0.0.1", | "assistant_ID":12, | Note this test |

6861

| "time": 1483346466000, | "authorised": false, | is copied from |

6862

| "sale_ID": 99999992, | "branch_ID": 2, | Step 1 above, |

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

6863

| "amount": 1249, | "item_ID": 1012, | and demonstrates |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

6864

| "item_ID": 1012, | "message": "Sale not authorised by policy ta | that the |

6865

| "quantity": 1, | sk MorningBoozeCheck for time 08:41:06 GMT.| original |

6866

| "assistant_ID": 12, | Alcohol can not be sold between 00:00:00 | ``MorningBoozeCheck`` |

6867

| "branch_ID": 2 | GMT and 11:30:00 GMT", | |

6868

| } | "notes": null, | task is |

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

6869

| | "quantity": 1, | executed. |

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

6870

| | "sale_ID": 99999992, | |

6871

| | "time": 1483346466000 | |

6872

| | } | |

6873

+----------------------------------------------+------------------------------------------------------------+---------------------------+

6874

| .. container:: | .. container:: | Request to buy |

6875

| | | alcohol |

6876

| .. container:: listingblock | .. container:: listingblock | (``item_ID=1047``) |

6877

| | | |

6878

| | | at *10:14:33* on |

6879

| | .. container:: content | *Thursday, 22 |

6880

| .. container:: content | | December 2016*. |

6881

| | .. code:: | |

6882

| | | Sale is not |

6883

| | { | authorized. Uses |

6884

| .. code:: | "nameSpace" : "com.hyperm", | the |

6885

| | "name" : "SALE_AUTH", | ``MorningBoozeCheckAlt1`` |

6886

| | "version" : "0.0.1", | task. |

6887

| { | "source" : "", | |

6888

| | "target" : "", | |

6889

| "nameSpace": "com.hyperm", | "sale_ID" : 99999981, | |

6890

| "name": "SALE_INPUT", | "amount" : 299, | |

6891

| "version": "0.0.1", | "assistant_ID": 1212, | |

6892

| "time": 1482398073000, | "notes" : null, | |

6893

| "sale_ID": 99999981, | "quantity" : 1, | |

6894

| "amount": 299, | "branch_ID" : 1002, | |

6895

| "item_ID": 1047, | "item_ID" : 1047, | |

6896

| "quantity": 1, | "authorised" : false, | |

6897

| "assistant_ID": 1212, | "time" : 1482398073000, | |

6898

| "branch_ID": 1002 | "message" : "Sale not authorised by policy t | |

6899

| } | ask MorningBoozeCheckAlt1 fortime | |

6900

| | 10:14:33 CET. Alcohol can not be sold | |

6901

| | between 00:00:00 CET and 13:00:00 CET or on | |

6902

| | Sunday" | |

6903

| | } | |

6904

+----------------------------------------------+------------------------------------------------------------+---------------------------+

6905

| .. container:: | .. container:: | Request to buy |

6906

| | | alcohol |

6907

| .. container:: listingblock | .. container:: listingblock | (``item_ID=1443``) |

6908

| | | |

6909

| | | at *17:19:37* on |

6910

| | .. container:: content | *Sunday, 18 |

6911

| .. container:: content | | December 2016*. |

6912

| | .. code:: | |

6913

| | | Sale is not |

6914

| | { | authorized. Uses |

6915

| .. code:: | "nameSpace" : "com.hyperm", | the |

6916

| | | ``MorningBoozeCheckAlt1`` |

6917

| | "name" : "SALE_AUTH", | task. |

6918

| { | | |

6919

| "nameSpace": "com.hyperm", | "version" : "0.0.1", | |

6920

| "name": "SALE_INPUT", | "source" : "", | |

6921

| "version": "0.0.1", | "target" : "", | |

6922

| "time": 1482077977000, | "sale_ID" : 99999982, | |

6923

| "sale_ID": 99999982, | "amount" : 2199, | |

6924

| "amount": 2199, | "assistant_ID" : 94, | |

6925

| "item_ID": 1443, | "notes" : "Buy 3, get 1 free!!", | |

6926

| "quantity": 12, | "quantity" : 12, | |

6927

| "assistant_ID": 94, | "branch_ID" : 1003, | |

6928

| "branch_ID": 1003, | "item_ID" : 1443, | |

6929

| "notes": "Buy 3, get 1 free!!" | "authorised" : false, | |

6930

| } | "time" : 1482077977000, | |

6931

| | "message" : "Sale not authorised by policy t | |

6932

| | ask MorningBoozeCheckAlt1 for | |

6933

| | time 17:19:37 CET. Alcohol c | |

6934

| | an not be sold between 00:00: | |

6935

| | 00 CET and 13:00:00 CET or on | |

6936

| | Sunday" | |

6937

+----------------------------------------------+------------------------------------------------------------+---------------------------+

6938

| .. container:: | .. container:: | Request to buy |

6939

| | | non-alcoholic |

6940

| .. container:: listingblock | .. container:: listingblock | item |

6941

| | | (``item_ID=5321``) |

6942

| | | |

6943

| | .. container:: content | at *11:13:09* on |

6944

| .. container:: content | | *Monday, 2 |

6945

| | .. code:: | January 2017*. |

6946

| | | |

6947

| | { | Sale is |

6948

| .. code:: | "nameSpace" : "com.hyperm", | authorized. Uses |

6949

| | "name" : "SALE_AUTH", | the |

6950

| { | "version" : "0.0.1", | ``MorningBoozeCheckAlt1`` |

6951

| "nameSpace": "com.hyperm", | "source" : "", | task. |

6952

| "name": "SALE_INPUT", | "target" : "", | |

6953

| "version": "0.0.1", | "sale_ID" : 99999983, | |

6954

| "time": 1483351989000, | "amount" : 699, | |

6955

| "sale_ID": 99999983, | "assistant_ID" : 2323, | |

6956

| "amount": 699, | "notes" : "", | |

6957

| "item_ID": 5321, | "quantity" : 1, | |

6958

| "quantity": 1, | "branch_ID" : 1001, | |

6959

| "assistant_ID": 2323, | "item_ID" : 5321, | |

6960

| "branch_ID": 1001, | "authorised" : true, | |

6961

| "notes": "" | "time" : 1483351989000, | |

6962

| } | "message" : "Sale authorised by policy task | |

6963

| | MorningBoozeCheckAlt1 for time 11:13:09 CET"| |

6964

| | } | |

6965

+----------------------------------------------+------------------------------------------------------------+---------------------------+

6966

6967

Policy 2 in CLI Editor

6968

######################

6969

6970

.. container:: paragraph

6971

6972

An equivalent version of the ``MyFirstPolicyModel``

6973

policy model can again be generated using the APEX CLI

6974

editor. A sample APEX CLI script is shown below:

6975

6976

.. container:: listingblock

.. container:: title

APEX CLI Editor code for Policy 2

6981

6982

.. container:: content

6983

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

6984

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

6985

6986

#-------------------------------------------------------------------------------

6987

# ============LICENSE_START=======================================================

6988

6989

# ================================================================================

6990

# Licensed under the Apache License, Version 2.0 (the "License");

6991

# you may not use this file except in compliance with the License.

6992

# You may obtain a copy of the License at

6993

#

6994

# http://www.apache.org/licenses/LICENSE-2.0

6995

#

6996

# Unless required by applicable law or agreed to in writing, software

6997

# distributed under the License is distributed on an "AS IS" BASIS,

6998

# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

6999

# See the License for the specific language governing permissions and

7000

# limitations under the License.

7001

#

7002

# SPDX-License-Identifier: Apache-2.0

7003

# ============LICENSE_END=========================================================

7004

#-------------------------------------------------------------------------------

7005

7006

model create name=MyFirstPolicyModel version=0.0.1 uuid=540226fb-55ee-4f0e-a444-983a0494818e description="This is my first Apex Policy Model."

7007

7008

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

7009

7010

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

7011

7012

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

7013

7014

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

7015

7016

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

7017

7018

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

7019

7020

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

7021

7022

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

7023

7024

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

7025

7026

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

7027

7028

task create name=MorningBoozeCheck version=0.0.1 uuid=3351b0f4-cf06-4fa2-8823-edf67bd30223 description=LS

7029

This task checks if the sales request is for an item that contains alcohol.

7030

If the local time is between 00:00:00 and 11:30:00 then the sale is not authorised. Otherwise the sale is authorised.

7031

In this implementation we assume that all items with item_ID values between 1000 and 2000 contain alcohol :-)

7032

LE

7033

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1

7034

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1

7035

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1

7036

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true

7037

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1

7038

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1

7039

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1

7040

task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1

7041

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1

7042

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1

7043

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1

7044

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true

7045

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1

7046

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1

7047

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1

7048

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1

7049

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1

7050

task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true

7051

task logic create name=MorningBoozeCheck version=0.0.1 logicFlavour=MVEL logic=LS

7052

/*

7053

* ============LICENSE_START=======================================================

7054

7055

* ================================================================================

7056

* Licensed under the Apache License, Version 2.0 (the "License");

7057

* you may not use this file except in compliance with the License.

7058

* You may obtain a copy of the License at

7059

*

7060

* http://www.apache.org/licenses/LICENSE-2.0

7061

*

7062

* Unless required by applicable law or agreed to in writing, software

7063

* distributed under the License is distributed on an "AS IS" BASIS,

7064

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

7065

* See the License for the specific language governing permissions and

7066

* limitations under the License.

7067

*

7068

* SPDX-License-Identifier: Apache-2.0

7069

* ============LICENSE_END=========================================================

7070

*/

7071

import java.util.Date;

7072

import java.util.Calendar;

7073

import java.util.TimeZone;

7074

import java.text.SimpleDateFormat;

7075

7076

logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'");

7077

7078

outFields.put("amount" , inFields.get("amount"));

7079

outFields.put("assistant_ID", inFields.get("assistant_ID"));

7080

outFields.put("notes" , inFields.get("notes"));

7081

outFields.put("quantity" , inFields.get("quantity"));

7082

outFields.put("branch_ID" , inFields.get("branch_ID"));

7083

outFields.put("item_ID" , inFields.get("item_ID"));

7084

outFields.put("time" , inFields.get("time"));

7085

outFields.put("sale_ID" , inFields.get("sale_ID"));

7086

7087

item_id = inFields.get("item_ID");

7088

7089

//The events used later to test this task use GMT timezone!

7090

gmt = TimeZone.getTimeZone("GMT");

7091

timenow = Calendar.getInstance(gmt);

7092

df = new SimpleDateFormat("HH:mm:ss z");

7093

df.setTimeZone(gmt);

7094

timenow.setTimeInMillis(inFields.get("time"));

7095

7096

midnight = timenow.clone();

7097

midnight.set(

7098

timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),

7099

timenow.get(Calendar.DATE),0,0,0);

7100

eleven30 = timenow.clone();

7101

eleven30.set(

7102

timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),

7103

timenow.get(Calendar.DATE),11,30,0);

7104

7105

itemisalcohol = false;

7106

if(item_id != null && item_id >=1000 && item_id < 2000)

7107

itemisalcohol = true;

7108

7109

if( itemisalcohol

7110

&& timenow.after(midnight) && timenow.before(eleven30)){

7111

outFields.put("authorised", false);

7112

outFields.put("message", "Sale not authorised by policy task "+subject.taskName+

7113

" for time "+df.format(timenow.getTime())+

7114

". Alcohol can not be sold between "+df.format(midnight.getTime())+

7115

" and "+df.format(eleven30.getTime()));

return true;

}

else{

outFields.put("authorised", true);

7120

outFields.put("message", "Sale authorised by policy task "+subject.taskName+

7121

" for time "+df.format(timenow.getTime()));

return true;

}

/*

This task checks if a sale request is for an item that is an alcoholic drink.

7127

If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not

7128

authorised. Otherwise the sale is authorised.

7129

In this implementation we assume that items with item_ID value between 1000 and

7130

2000 are all alcoholic drinks :-)

*/

LE

task create name=MorningBoozeCheckAlt1 version=0.0.1 uuid=bc6d90c9-c902-4686-afd3-925b30e39990 description=LS

7135

This task checks if a sale request is for an item that is an alcoholic drink.

7136

If the local time is between 00:00:00 CET and 13:00:00 CET then the sale is not authorised.

7137

Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised.

7138

In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks

7139

LE

7140

task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1

7141

task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1

7142

task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1

7143

task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true

7144

task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1

7145

task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1

7146

task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1

7147

task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1

7148

task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1

7149

task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1

7150

task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1

7151

task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true

7152

task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1

7153

task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1

7154

task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1

7155

task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1

7156

task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1

7157

task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true

7158

task logic create name=MorningBoozeCheckAlt1 version=0.0.1 logicFlavour=MVEL logic=LS

7159

/*

7160

* ============LICENSE_START=======================================================

7161

7162

* ================================================================================

7163

* Licensed under the Apache License, Version 2.0 (the "License");

7164

* you may not use this file except in compliance with the License.

7165

* You may obtain a copy of the License at

7166

*

7167

* http://www.apache.org/licenses/LICENSE-2.0

7168

*

7169

* Unless required by applicable law or agreed to in writing, software

7170

* distributed under the License is distributed on an "AS IS" BASIS,

7171

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

7172

* See the License for the specific language governing permissions and

7173

* limitations under the License.

7174

*

7175

* SPDX-License-Identifier: Apache-2.0

7176

* ============LICENSE_END=========================================================

7177

*/

7178

import java.util.Date;

7179

import java.util.Calendar;

7180

import java.util.TimeZone;

7181

import java.text.SimpleDateFormat;

7182

7183

logger.info("Task Execution: '"+subject.id+"'. Input Event: '"+inFields+"'");

7184

7185

outFields.put("amount" , inFields.get("amount"));

7186

outFields.put("assistant_ID", inFields.get("assistant_ID"));

7187

outFields.put("notes" , inFields.get("notes"));

7188

outFields.put("quantity" , inFields.get("quantity"));

7189

outFields.put("branch_ID" , inFields.get("branch_ID"));

7190

outFields.put("item_ID" , inFields.get("item_ID"));

7191

outFields.put("time" , inFields.get("time"));

7192

outFields.put("sale_ID" , inFields.get("sale_ID"));

7193

7194

item_id = inFields.get("item_ID");

7195

7196

//The events used later to test this task use CET timezone!

7197

cet = TimeZone.getTimeZone("CET");

7198

timenow = Calendar.getInstance(cet);

7199

df = new SimpleDateFormat("HH:mm:ss z");

7200

df.setTimeZone(cet);

7201

timenow.setTimeInMillis(inFields.get("time"));

7202

7203

midnight = timenow.clone();

7204

midnight.set(

7205

timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),

7206

timenow.get(Calendar.DATE),0,0,0);

7207

onepm = timenow.clone();

7208

onepm.set(

7209

timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),

7210

timenow.get(Calendar.DATE),13,0,0);

7211

7212

itemisalcohol = false;

7213

if(item_id != null && item_id >=1000 && item_id < 2000)

7214

itemisalcohol = true;

7215

7216

if( itemisalcohol &&

7217

( (timenow.after(midnight) && timenow.before(onepm))

7218

||

7219

(timenow.get(Calendar.DAY_OF_WEEK) == Calendar.SUNDAY)

7220

)){

7221

outFields.put("authorised", false);

7222

outFields.put("message", "Sale not authorised by policy task "+subject.taskName+

7223

" for time "+df.format(timenow.getTime())+

7224

". Alcohol can not be sold between "+df.format(midnight.getTime())+

7225

" and "+df.format(onepm.getTime()) +" or on Sunday");

return true;

}

else{

outFields.put("authorised", true);

7230

outFields.put("message", "Sale authorised by policy task "+subject.taskName+

7231

" for time "+df.format(timenow.getTime()));

return true;

}

/*

This task checks if a sale request is for an item that is an alcoholic drink.

7237

If the local time is between 00:00:00 CET and 13:00:00 CET then the sale is not authorised.

7238

Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised.

7239

In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks :-)

*/

LE

event create name=SALE_AUTH version=0.0.1 uuid=c4500941-3f98-4080-a9cc-5b9753ed050b description="An event emitted by the Policy to indicate whether the sale of an item has been authorised" nameSpace=com.hyperm source="APEX" target="POS"

7244

event parameter create name=SALE_AUTH version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1

7245

event parameter create name=SALE_AUTH version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1

7246

event parameter create name=SALE_AUTH version=0.0.1 parName=authorised schemaName=authorised_type schemaVersion=0.0.1

7247

event parameter create name=SALE_AUTH version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1

7248

event parameter create name=SALE_AUTH version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1

7249

event parameter create name=SALE_AUTH version=0.0.1 parName=message schemaName=message_type schemaVersion=0.0.1 optional=true

7250

event parameter create name=SALE_AUTH version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true

7251

event parameter create name=SALE_AUTH version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1

7252

event parameter create name=SALE_AUTH version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1

7253

event parameter create name=SALE_AUTH version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1

7254

7255

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"

7256

event parameter create name=SALE_INPUT version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1

7257

event parameter create name=SALE_INPUT version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1

7258

event parameter create name=SALE_INPUT version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1

7259

event parameter create name=SALE_INPUT version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1

7260

event parameter create name=SALE_INPUT version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true

7261

event parameter create name=SALE_INPUT version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1

7262

event parameter create name=SALE_INPUT version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1

7263

event parameter create name=SALE_INPUT version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1

7264

7265

7266

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

7267

policy state create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide triggerName=SALE_INPUT triggerVersion=0.0.1 defaultTaskName=MorningBoozeCheck defaultTaskVersion=0.0.1

7268

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

7269

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

7270

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

7271

policy state selecttasklogic create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide logicFlavour=JAVASCRIPT logic=LS

7272

/*

7273

* ============LICENSE_START=======================================================

7274

7275

* ================================================================================

7276

* Licensed under the Apache License, Version 2.0 (the "License");

7277

* you may not use this file except in compliance with the License.

7278

* You may obtain a copy of the License at

7279

*

7280

* http://www.apache.org/licenses/LICENSE-2.0

7281

*

7282

* Unless required by applicable law or agreed to in writing, software

7283

* distributed under the License is distributed on an "AS IS" BASIS,

7284

* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

7285

* See the License for the specific language governing permissions and

7286

* limitations under the License.

7287

*

7288

* SPDX-License-Identifier: Apache-2.0

7289

* ============LICENSE_END=========================================================

7290

*/

7291

7292

var returnValueType = Java.type("java.lang.Boolean");

7293

var returnValue = new returnValueType(true);

7294

7295

executor.logger.info("Task Selection Execution: '"+executor.subject.id+"'. Input Event: '"+executor.inFields+"'");

7296

7297

branchid = executor.inFields.get("branch_ID");

7298

taskorig = executor.subject.getTaskKey("MorningBoozeCheck");

7299

taskalt = executor.subject.getTaskKey("MorningBoozeCheckAlt1");

7300

taskdef = executor.subject.getDefaultTaskKey();

7301

7302

if(branchid >=0 && branchid <1000){

7303

taskorig.copyTo(executor.selectedTask);

7304

}

7305

else if (branchid >=1000 && branchid <2000){

7306

taskalt.copyTo(executor.selectedTask);

7307

}

7308

else{

7309

taskdef.copyTo(executor.selectedTask);

}

/*

This task selection logic selects task "MorningBoozeCheck" for branches with 0<=branch_ID<1000 and selects task "MorningBoozeCheckAlt1" for branches with 1000<=branch_ID<2000. Otherwise the default task is selected. In this case the default task is also "MorningBoozeCheck"

*/

LE

APEX Logging

^^^^^^^^^^^^

Introduction to APEX Logging

7321

----------------------------

7322

7323

.. container:: paragraph

7324

7325

All APEX components make extensive use of logging using the

7326

logging façade `SLF4J <https://www.slf4j.org/>`__ with the

7327

backend `Logback <https://logback.qos.ch/>`__. Both are used

7328

off-the-shelve, so the standard documentation and

7329

configuration apply to APEX logging. For details on how to

7330

work with logback please see the `logback

7331

manual <https://logback.qos.ch/manual/index.html>`__.

7332

7333

.. container:: paragraph

7334

7335

The APEX applications is the logback configuration file

7336

``$APEX_HOME/etc/logback.xml`` (Windows:

7337

``%APEX_HOME%\etc\logback.xml``). The logging backend is set

7338

to no debug, i.e. logs from the logging framework should be

7339

hidden at runtime.

7340

7341

.. container:: paragraph

7342

7343

The configurable log levels work as expected:

.. container:: ulist

- *error* (or *ERROR*) is used for serious errors in the

7348

APEX runtime engine

7349

7350

- *warn* (or *WARN*) is used for warnings, which in general

7351

can be ignored but might indicate some deeper problems

7352

7353

- *info* (or *INFO*) is used to provide generally

7354

interesting messages for startup and policy execution

7355

7356

- *debug* (or *DEBUG*) provides more details on startup and

7357

policy execution

7358

7359

- *trace* (or *TRACE*) gives full details on every aspect

7360

of the APEX engine from start to end

7361

7362

.. container:: paragraph

7363

7364

The loggers can also be configured as expected. The standard

7365

configuration (after installing APEX) uses log level *info*

7366

on all APEX classes (components).

7367

7368

.. container:: paragraph

7369

7370

The applications and scripts in ``$APEX_HOME/bin`` (Windows:

7371

``%APEX_HOME\bin``) are configured to use the logback

7372

configuration ``$APEX_HOME/etc/logback.xml`` (Windows:

7373

``%APEX_HOME\etc\logback.xml``). There are multiple ways to

7374

use different logback configurations, for instance:

.. container:: ulist

- Maintain multiple configurations in ``etc``, for instance

7379

a ``logback-debug.xml`` for deep debugging and a

7380

``logback-production.xml`` for APEX in production mode,

7381

then copy the required configuration file to the used

7382

``logback.xml`` prior starting APEX

7383

7384

- Edit the scripts in ``bin`` to use a different logback

7385

configuration file (only recommended if you are familiar

7386

with editing bash scripts or windows batch files)

7387

7388

Standard Logging Configuration

7389

------------------------------

7390

7391

.. container:: paragraph

7392

7393

The standard logging configuration defines a context *APEX*,

7394

which is used in the standard output pattern. The location

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7395

for log files is defined in the property ``logDir`` and set

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7396

to ``/var/log/onap/policy/apex-pdp``. The standard status

7397

listener is set to *NOP* and the overall logback

7398

configuration is set to no debug.

7399

7400

.. container:: listingblock

7401

7402

.. container:: content

7403

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7404

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

:number-lines:

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7411

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

...appenders

...loggers

</configuration>

.. container:: paragraph

7418

7419

The first appender defined is called ``STDOUT`` for logs to standard

7420

out.

7421

7422

.. container:: listingblock

7423

7424

.. container:: content

7425

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7426

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

:number-lines:

<Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern>

</encoder>

</appender>

.. container:: paragraph

7436

7437

The root level logger then is set to the level *info* using the

7438

standard out appender.

7439

7440

.. container:: listingblock

7441

7442

.. container:: content

7443

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7444

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

:number-lines:

<appender-ref ref="STDOUT" />

7449

</root>

7450

7451

.. container:: paragraph

7452

7453

The second appender is called ``FILE``. It writes logs to a file

7454

``apex.log``.

7455

7456

.. container:: listingblock

7457

7458

.. container:: content

7459

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7460

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

:number-lines:

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7464

<file>${logDir}/apex.log</file>

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7465

7466

<pattern>%d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full}</pattern>

</encoder>

</appender>

.. container:: paragraph

7471

7472

The third appender is called ``CTXT_FILE``. It writes logs to a file

7473

``apex_ctxt.log``.

7474

7475

.. container:: listingblock

7476

7477

.. container:: content

7478

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7479

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

:number-lines:

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7483

<file>${logDir}/apex_ctxt.log</file>

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7484

7485

<pattern>%d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full}</pattern>

</encoder>

</appender>

.. container:: paragraph

7490

7491

The last definitions are for specific loggers. The first logger

7492

captures all standard APEX classes. It is configured for log level

7493

*info* and uses the standard output and file appenders. The second

7494

logger captures APEX context classes responsible for context

7495

monitoring. It is configured for log level *trace* and uses the

7496

context file appender.

7497

7498

.. container:: listingblock

7499

7500

.. container:: content

7501

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7502

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

:number-lines:

<appender-ref ref="STDOUT" />

7508

<appender-ref ref="FILE" />

</logger>

<appender-ref ref="CTXT_FILE" />

7513

</logger>

7514

7515

Adding Logback Status and Debug

7516

-------------------------------

7517

7518

.. container:: paragraph

7519

7520

To activate logback status messages change the status listener

7521

from 'NOP' to for instance console.

7522

7523

.. container:: listingblock

7524

7525

.. container:: content

7526

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7527

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

.. container:: paragraph

7532

7533

To activate all logback debugging, for instance to debug a new

7534

logback configuration, activate the debug attribute in the

7535

configuration.

7536

7537

.. container:: listingblock

7538

7539

.. container:: content

7540

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7541

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

...

</configuration>

Logging External Components

7548

---------------------------

7549

7550

.. container:: paragraph

7551

7552

Logback can also be configured to log any other, external

7553

components APEX is using, if they are using the common logging

7554

framework.

7555

7556

.. container:: paragraph

7557

7558

For instance, the context component of APEX is using *Infinispan*

7559

and one can add a logger for this external component. The

7560

following example adds a logger for *Infinispan* using the

7561

standard output appender.

7562

7563

.. container:: listingblock

7564

7565

.. container:: content

7566

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7567

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7568

7569

7570

<appender-ref ref="STDOUT" />

7571

</logger>

7572

7573

.. container:: paragraph

7574

7575

Another example is Apache Zookeeper. The following example adds a

7576

logger for Zookeeper using the standard outout appender.

7577

7578

.. container:: listingblock

7579

7580

.. container:: content

7581

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7582

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7583

7584

7585

<appender-ref ref="STDOUT" />

7586

</logger>

7587

7588

Configuring loggers for Policy Logic

7589

------------------------------------

7590

7591

.. container:: paragraph

7592

7593

The logging for the logic inside a policy (task logic, task

7594

selection logic, state finalizer logic) can be configured separate

7595

from standard logging. The logger for policy logic is

7596

``org.onap.policy.apex.executionlogging``. The following example

defines

.. container:: ulist

- a new appender for standard out using a very simple pattern

7602

(simply the actual message)

7603

7604

- a logger for policy logic to standard out using the new

7605

appender and the already described file appender.

7606

7607

.. container:: listingblock

7608

7609

.. container:: content

7610

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7611

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

<pattern>policy: %msg\n</pattern>

</encoder>

</appender>

<appender-ref ref="POLICY_APPENDER_STDOUT" />

7621

<appender-ref ref="FILE" />

7622

</logger>

7623

7624

.. container:: paragraph

7625

7626

It is also possible to use specific logging for parts of policy

7627

logic. The following example defines a logger for task logic.

7628

7629

.. container:: listingblock

7630

7631

.. container:: content

7632

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7633

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7634

7635

7636

<appender-ref ref="POLICY_APPENDER_STDOUT" />

7637

</logger>

7638

7639

Rolling File Appenders

7640

----------------------

7641

7642

.. container:: paragraph

7643

7644

Rolling file appenders are a good option for more complex logging

7645

of a production or complex testing APEX installation. The standard

7646

logback configuration can be used for these use cases. This

7647

section gives two examples for the standard logging and for

7648

context logging.

7649

7650

.. container:: paragraph

7651

7652

First the standard logging. The following example defines a

7653

rolling file appender. The appender rolls over on a daily basis.

7654

It allows for a file size of 100 MB.

7655

7656

.. container:: listingblock

7657

7658

.. container:: content

7659

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7660

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7661

7662

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7663

<file>${logDir}/apex.log</file>

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7664

7665

7666

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7667

<fileNamePattern>${logDir}/apex_%d{yyyy-MM-dd}.%i.log.gz

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

</fileNamePattern>

7672

7673

</timeBasedFileNamingAndTriggeringPolicy>

</rollingPolicy>

%d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %ex{full} %n

</pattern>

</encoder>

</appender>

.. container:: paragraph

7683

7684

A very similar configuration can be used for a rolling file

7685

appender logging APEX context.

7686

7687

.. container:: listingblock

7688

7689

.. container:: content

7690

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7691

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7692

7693

<appender name="CTXT-FILE"

7694

class="ch.qos.logback.core.rolling.RollingFileAppender">

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7695

<file>${logDir}/apex_ctxt.log</file>

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7696

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7697

<fileNamePattern>${logDir}/apex_ctxt_%d{yyyy-MM-dd}.%i.log.gz

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7698

</fileNamePattern>

7699

7700

<timeBasedFileNamingAndTriggeringPolicy

7701

class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">

7702

7703

</timeBasedFileNamingAndTriggeringPolicy>

</rollingPolicy>

%d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %ex{full} %n

</pattern>

</encoder>

</appender>

Example Configuration for Logging Logic

7713

---------------------------------------

7714

7715

.. container:: paragraph

7716

7717

The following example shows a configuration that logs policy logic

7718

to standard out and a file (*info*). All other APEX components are

7719

logging to a file (*debug*).. This configuration an be used in a

7720

pre-production phase with the APEX engine still running in a

7721

separate terminal to monitor policy execution. This logback

7722

configuration is in the APEX installation as

7723

``etc/logback-logic.xml``.

7724

7725

.. container:: listingblock

7726

7727

.. container:: content

7728

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7729

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7735

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

<Pattern>%d %contextName [%t] %level %logger{36} - %msg%n</Pattern>

</encoder>

</appender>

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7744

<file>${logDir}/apex.log</file>

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7745

7746

7747

%d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}

</pattern>

</encoder>

</appender>

<pattern>policy: %msg\n</pattern>

</encoder>

</appender>

<appender-ref ref="STDOUT" />

</root>

<appender-ref ref="FILE" />

</logger>

<appender-ref ref="POLICY_APPENDER_STDOUT" />

7768

<appender-ref ref="FILE" />

</logger>

</configuration>

Example Configuration for a Production Server

7773

---------------------------------------------

7774

7775

.. container:: paragraph

7776

7777

The following example shows a configuration that logs all APEX

7778

components, including policy logic, to a file (*debug*). This

7779

configuration an be used in a production phase with the APEX

7780

engine being executed as a service on a system without console

7781

output. This logback configuration is in the APEX installation as

7782

``logback-server.xml``

7783

7784

.. container:: listingblock

7785

7786

.. container:: content

7787

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7788

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7794

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7795

7796

liamfallon

2019-11-28 15:14:07 +0000

[diff] [blame]

7797

<file>${logDir}/apex.log</file>

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

7798

7799

7800

%d %-5relative [procId=${processId}] [%thread] %-5level%logger{26} - %msg %n %ex{full}

</pattern>

</encoder>

</appender>

<appender-ref ref="FILE" />

</root>

<appender-ref ref="FILE" />

</logger>

</configuration>

Building a System with Websocket Backend

7815

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Websockets

----------

.. container:: paragraph

7821

7822

Websocket is a protocol to run sockets of HTTP. Since it in

7823

essence a socket, the connection is realized between a

7824

server (waiting for connections) and a client (connecting to

7825

a server). Server/client separation is only important for

7826

connection establishment, once connected, everyone can

7827

send/receive on the same socket (as any standard socket

7828

would allow).

7829

7830

.. container:: paragraph

7831

7832

Standard Websocket implementations are simple, no

7833

publish/subscribe and no special event handling. Most

7834

servers simply send all incoming messages to all

7835

connections. There is a PubSub definition on top of

7836

Websocket called `WAMP <http://wamp-proto.org/>`__. APEX

7837

does not support WAMP at the moment.

Websocket in Java

-----------------

.. container:: paragraph

7843

7844

In Java, `JSR

7845

356 <http://www.oracle.com/technetwork/articles/java/jsr356-1937161.html>`__

7846

defines the standard Websocket API. This JSR is part of Jave

7847

EE 7 standard. For Java SE, several implementations exist in

7848

open source. Since Websockets are a stable standard and

7849

simple, most implementations are stable and ready to use. A

7850

lot of products support Websockets, like Spring, JBoss,

7851

Netty, … there are also Kafka extensions for Websockets.

7852

7853

Websocket Example Code for Websocket clients (FOSS)

7854

---------------------------------------------------

7855

7856

.. container:: paragraph

7857

7858

There are a lot of implementations and examples available on

7859

Github for Websocket clients. If one is using Java EE 7,

7860

then one can also use the native Websocket implementation.

7861

Good examples for clients using simply Java SE are here:

.. container:: ulist

- `Websocket

implementation <https://github.com/TooTallNate/Java-WebSocket>`__

7867

7868

- `Websocket sending client example, using

7869

AWT <https://github.com/TooTallNate/Java-WebSocket/blob/master/src/main/example/ChatClient.java>`__

7870

7871

- `Websocket receiving client example (simple echo

7872

client) <https://github.com/TooTallNate/Java-WebSocket/blob/master/src/main/example/ExampleClient.java>`__

7873

7874

.. container:: paragraph

7875

7876

For Java EE, the native Websocket API is explained here:

.. container:: ulist

- `Oracle

docs <http://www.oracle.com/technetwork/articles/java/jsr356-1937161.html>`__

7882

7883

- link: `An

7884

example <http://www.programmingforliving.com/2013/08/jsr-356-java-api-for-websocket-client-api.html>`__

7885

7886

BCP: Websocket Configuration

7887

----------------------------

7888

7889

.. container:: paragraph

7890

7891

The probably best is to configure APEX for Websocket servers

7892

for input (ingress, consume) and output (egress, produce)

7893

interfaces. This means that APEX will start Websocket

7894

servers on named ports and wait for clients to connect.

7895

Advantage: once APEX is running all connectivity

7896

infrastructure is running as well. Consequence: if APEX is

7897

not running, everyone else is in the dark, too.

7898

7899

.. container:: paragraph

7900

7901

The best protocol to be used is JSON string. Each event on

7902

any interface is then a string with a JSON encoding. JSON

7903

string is a little bit slower than byte code, but we doubt

7904

that this will be noticeable. A further advantage of JSON

7905

strings over Websockets with APEX starting the servers: it

7906

is very easy to connect web browsers to such a system.

7907

Simple connect the web browser to the APEX sockets and

7908

send/read JSON strings.

7909

7910

.. container:: paragraph

7911

7912

Once APEX is started you simply connect Websocket clients to

7913

it, and send/receive event. When APEX is terminated, the

7914

Websocket servers go down, and the clients will be

7915

disconnected. APEX does not (yet) support auto-client

7916

reconnect nor WAMP, so clients might need to be restarted or

7917

reconnected manually after an APEX boot.

7918

7919

Demo with VPN Policy Model

7920

--------------------------

7921

7922

.. container:: paragraph

7923

7924

We assume that you have an APEX installation using the full

7925

package, i.e. APEX with all examples, of version ``0.5.6``

7926

or higher. We will use the VPN policy from the APEX examples

7927

here.

7928

7929

.. container:: paragraph

7930

7931

Now, have the following ready to start the demo:

.. container:: ulist

- 3 terminals on the host where APEX is running (we need 1

7936

for APEX and 1 for each client)

7937

7938

- the events in the file

7939

``$APEX_HOME/examples/events/VPN/SetupEvents.json`` open

7940

in an editor (we need to send those events to APEX)

7941

7942

- the events in the file

7943

``$APEX_HOME/examples/events/VPN/Link09Events.json`` open

7944

in an editor (we need to send those events to APEX)

7945

7946

A Websocket Configuration for the VPN Domain

7947

############################################

7948

7949

.. container:: paragraph

7950

7951

Create a new APEX configuration using the VPN policy

7952

model and configuring APEX as discussed above for

7953

Websockets. Copy the following configuration into

7954

``$APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json``

7955

(for Windows use

7956

``%APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json``):

7957

7958

.. container:: listingblock

7959

7960

.. container:: content

7961

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

7962

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

:number-lines:

{

"engineServiceParameters" : {

7967

"name" : "VPNApexEngine",

"version" : "0.0.1",

"id" : 45,

"instanceCount" : 1,

"deploymentPort" : 12345,

7972

"policyModelFileName" : "examples/models/VPN/VPNPolicyModelAvro.json",

7973

"engineParameters" : {

7974

"executorParameters" : {

7975

"MVEL" : {

7976

"parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"

7977

}

7978

},

7979

"contextParameters" : {

7980

"parameterClassName" : "org.onap.policy.apex.context.parameters.ContextParameters",

7981

"schemaParameters":{

7982

"Avro":{

7983

"parameterClassName" : "org.onap.policy.apex.plugins.context.schema.avro.AvroSchemaHelperParameters"

}

}

}

}

},

"producerCarrierTechnologyParameters" : {

7990

"carrierTechnology" : "WEBSOCKET",

7991

"parameterClassName" : "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",

"parameters" : {

"wsClient" : false,

"port" : 42452

}

},

"producerEventProtocolParameters" : {

7998

"eventProtocol" : "JSON"

7999

},

8000

"consumerCarrierTechnologyParameters" : {

8001

"carrierTechnology" : "WEBSOCKET",

8002

"parameterClassName" : "org.onap.policy.apex.plugins.event.carrier.websocket.WEBSOCKETCarrierTechnologyParameters",

"parameters" : {

"wsClient" : false,

"port" : 42450

}

},

"consumerEventProtocolParameters" : {

8009

"eventProtocol" : "JSON"

}

}

Start APEX Engine

#################

.. container:: paragraph

8017

8018

In a new terminal, start APEX with the new configuration for

8019

Websocket-Server ingress/egress:

8020

8021

.. container:: listingblock

8022

8023

.. container:: content

8024

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8025

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8026

:number-lines:

8027

8028

#: $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/VPN/Ws2WsServerAvroContextJsonEvent.json

8029

8030

.. container:: listingblock

8031

8032

.. container:: content

8033

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8034

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8035

:number-lines:

8036

8037

#: %APEX_HOME%\bin\apexEngine.bat -c %APEX_HOME%\examples\config\VPN\Ws2WsServerAvroContextJsonEvent.json

8038

8039

.. container:: paragraph

8040

8041

Wait for APEX to start, it takes a while to create all Websocket

8042

servers (about 8 seconds on a standard laptop without cached

8043

binaries). depending on your log messages, you will see no (some, a

8044

lot) log messages. If APEX starts correctly, the last few messages

8045

you should see are:

8046

8047

.. container:: listingblock

8048

8049

.. container:: content

8050

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8051

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8052

:number-lines:

8053

8054

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)

8055

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

8056

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

8057

Started Apex service

8058

8059

.. container:: paragraph

8060

8061

APEX is running in the new terminal and will produce output when the

8062

policy is triggered/executed.

8063

8064

Run the Websocket Echo Client

8065

#############################

8066

8067

.. container:: paragraph

8068

8069

The echo client is included in an APEX full installation. To run

8070

the client, open a new shell (Unix, Cygwin) or command prompt

8071

(``cmd`` on Windows). Then use the APEX application launcher to

8072

start the client.

8073

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

8074

.. important::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8075

APEX engine needs to run first

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8076

The example assumes that an APEX engine configured for *produce* carrier technology Websocket and *JSON* event protocol is executed first.

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8077

8078

+---------------------------------------------------------+-----------------------------------------------------------+

8079

| Unix, Cygwin | Windows |

8080

+=========================================================+===========================================================+

8081

| .. container:: | .. container:: |

8082

| | |

8083

| .. container:: listingblock | .. container:: listingblock |

8084

| | |

8085

| .. container:: content | .. container:: content |

8086

| | |

8087

| .. code:: | .. code:: |

8088

| | |

8089

| # $APEX_HOME/bin/apexApps.sh ws-echo [args] | > %APEX_HOME%\bin\apexApps.bat ws-echo [args] |

8090

+---------------------------------------------------------+-----------------------------------------------------------+

8091

8092

.. container:: paragraph

8093

8094

Use the following command line arguments for server and port of

8095

the Websocket server. The port should be the same as configured in

8096

the APEX engine. The server host should be the host on which the

8097

APEX engine is running

.. container:: ulist

- ``-p`` defines the Websocket port to connect to (defaults to

8102

``8887``)

8103

8104

- ``-s`` defines the host on which a Websocket server is running

8105

(defaults to ``localhost``)

8106

8107

.. container:: paragraph

8108

8109

Let’s assume that there is an APEX engine running, configured for

8110

produce Websocket carrier technology, as server, for port 42452,

8111

with produce event protocol JSON,. If we start the console client

8112

on the same host, we can omit the ``-s`` options. We start the

8113

console client as:

8114

8115

.. container:: listingblock

8116

8117

.. container:: content

8118

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8119

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8120

8121

# $APEX_HOME/bin/apexApps.sh ws-echo -p 42452 (1)

8122

> %APEX_HOME%\bin\apexApps.bat ws-echo -p 42452 (2)

8123

8124

.. container:: colist arabic

8125

8126

+-------+--------------------------------+

8127

| **1** | Start client on Unix or Cygwin |

8128

+-------+--------------------------------+

8129

| **2** | Start client on Windows |

8130

+-------+--------------------------------+

8131

8132

.. container:: paragraph

8133

8134

Once started successfully, the client will produce the following

8135

messages (assuming we used ``-p 42452`` and an APEX engine is

8136

running on ``localhost`` with the same port:

8137

8138

.. container:: listingblock

8139

8140

.. container:: content

8141

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8142

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8143

8144

ws-simple-echo: starting simple event echo

8145

--> server: localhost

8146

--> port: 42452

8147

8148

Once started, the application will simply print out all received events to standard out.

8149

Each received event will be prefixed by '---' and suffixed by '===='

8150

8151

8152

ws-simple-echo: opened connection to APEX (Web Socket Protocol Handshake)

8153

8154

Run the Websocket Console Client

8155

################################

8156

8157

.. container:: paragraph

8158

8159

The console client is included in an APEX full installation. To

8160

run the client, open a new shell (Unix, Cygwin) or command prompt

8161

(``cmd`` on Windows). Then use the APEX application launcher to

8162

start the client.

8163

liamfallon

2019-10-03 13:42:08 +0100

[diff] [blame]

8164

.. important::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8165

APEX engine needs to run first

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8166

The example assumes that an APEX engine configured for *consume* carrier technology Websocket and *JSON* event

8167

protocol is executed first.

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8168

8169

+------------------------------------------------------------+--------------------------------------------------------------+

8170

| Unix, Cygwin | Windows |

8171

+============================================================+==============================================================+

8172

| .. container:: | .. container:: |

8173

| | |

8174

| .. container:: listingblock | .. container:: listingblock |

8175

| | |

8176

| .. container:: content | .. container:: content |

8177

| | |

8178

| .. code:: | .. code:: |

8179

| | |

8180

| # $APEX_HOME/bin/apexApps.sh ws-console [args] | > %APEX_HOME%\bin\apexApps.bat ws-console [args] |

8181

+------------------------------------------------------------+--------------------------------------------------------------+

8182

8183

.. container:: paragraph

8184

8185

Use the following command line arguments for server and port of

8186

the Websocket server. The port should be the same as configured in

8187

the APEX engine. The server host should be the host on which the

8188

APEX engine is running

.. container:: ulist

- ``-p`` defines the Websocket port to connect to (defaults to

8193

``8887``)

8194

8195

- ``-s`` defines the host on which a Websocket server is running

8196

(defaults to ``localhost``)

8197

8198

.. container:: paragraph

8199

8200

Let’s assume that there is an APEX engine running, configured for

8201

consume Websocket carrier technology, as server, for port 42450,

8202

with consume event protocol JSON,. If we start the console client

8203

on the same host, we can omit the ``-s`` options. We start the

8204

console client as:

8205

8206

.. container:: listingblock

8207

8208

.. container:: content

8209

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8210

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8211

8212

# $APEX_HOME/bin/apexApps.sh ws-console -p 42450 (1)

8213

> %APEX_HOME%\bin\apexApps.sh ws-console -p 42450 (2)

8214

8215

.. container:: colist arabic

8216

8217

+-------+--------------------------------+

8218

| **1** | Start client on Unix or Cygwin |

8219

+-------+--------------------------------+

8220

| **2** | Start client on Windows |

8221

+-------+--------------------------------+

8222

8223

.. container:: paragraph

8224

8225

Once started successfully, the client will produce the following

8226

messages (assuming we used ``-p 42450`` and an APEX engine is

8227

running on ``localhost`` with the same port:

8228

8229

.. container:: listingblock

8230

8231

.. container:: content

8232

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8233

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8234

8235

ws-simple-console: starting simple event console

8236

--> server: localhost

8237

--> port: 42450

8238

8239

- terminate the application typing 'exit<enter>' or using 'CTRL+C'

8240

- events are created by a non-blank starting line and terminated by a blank line

8241

8242

8243

ws-simple-console: opened connection to APEX (Web Socket Protocol Handshake)

Send Events

###########

.. container:: paragraph

8249

8250

Now you have the full system up and running:

.. container:: ulist

- Terminal 1: APEX ready and loaded

8255

8256

- Terminal 2: an echo client, printing received messages produced

8257

by the VPN policy

8258

8259

- Terminal 2: a console client, waiting for input on the console

8260

(standard in) and sending text to APEX

8261

8262

.. container:: paragraph

8263

8264

We started the engine with the VPN policy example. So all the

8265

events we are using now are located in files in the following

8266

example directory:

8267

8268

.. container:: listingblock

8269

8270

.. container:: content

8271

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8272

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8273

:number-lines:

8274

8275

#: $APEX_HOME/examples/events/VPN

8276

> %APEX_HOME%\examples\events\VPN

8277

8278

.. container:: paragraph

8279

8280

To sends events, simply copy the content of the event files into

8281

Terminal 3 (the console client). It will read multi-line JSON text

8282

and send the events. So copy the content of ``SetupEvents.json`` into

8283

the client. APEX will trigger a policy and produce some output, the

8284

echo client will also print some events created in the policy. In

8285

Terminal 1 (APEX) you’ll see some status messages from the policy as:

8286

8287

.. container:: listingblock

8288

8289

.. container:: content

8290

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8291

.. code::

ramverma

2019-07-10 11:25:37 +0000

[diff] [blame]

8292

:number-lines:

8293

8294

{Link=L09, LinkUp=true}

8295

L09 true

8296

outFields: {Link=L09, LinkUp=true}

8297

{Link=L10, LinkUp=true}

8298

L09 true

8299

L10 true

8300

outFields: {Link=L10, LinkUp=true}

8301

{CustomerName=C, LinkList=L09 L10, SlaDT=300, YtdDT=300}

8302

*** Customers ***

8303

C 300 300 [L09, L10]

8304

outFields: {CustomerName=C, LinkList=L09 L10, SlaDT=300, YtdDT=300}

8305

{CustomerName=A, LinkList=L09 L10, SlaDT=300, YtdDT=50}

*** Customers ***

A 300 50 [L09, L10]

C 300 300 [L09, L10]

outFields: {CustomerName=A, LinkList=L09 L10, SlaDT=300, YtdDT=50}

8310

{CustomerName=D, LinkList=L09 L10, SlaDT=300, YtdDT=400}

*** Customers ***

A 300 50 [L09, L10]

C 300 300 [L09, L10]

D 300 400 [L09, L10]

outFields: {CustomerName=D, LinkList=L09 L10, SlaDT=300, YtdDT=400}

8316

{CustomerName=B, LinkList=L09 L10, SlaDT=300, YtdDT=299}

*** Customers ***

A 300 50 [L09, L10]

B 300 299 [L09, L10]

C 300 300 [L09, L10]

D 300 400 [L09, L10]

outFields: {CustomerName=B, LinkList=L09 L10, SlaDT=300, YtdDT=299}

8323

8324

.. container:: paragraph

8325

8326

In Terminal 2 (echo-client) you see the received events, the last two

8327

should look like:

8328

8329

.. container:: listingblock

8330

8331

.. container:: content

8332

ramverma

2019-07-11 12:57:49 +0000

[diff] [blame]

8333

.. code::

ramverma