X-Git-Url: https://gerrit.onap.org/r/gitweb?a=blobdiff_plain;f=docs%2Fapex%2FAPEX-User-Manual.rst;h=50468a22006d35584c110dd10e2aeef22f8deb99;hb=9e67eb79f13bfc4bd536dae5ddaf12b8aa8a5dca;hp=10201c0f7cee45e036a6a0bac505e4e54db8b0d4;hpb=94fae9ace91dd0a6611ad163989f027dffe7a758;p=policy%2Fparent.git diff --git a/docs/apex/APEX-User-Manual.rst b/docs/apex/APEX-User-Manual.rst index 10201c0f..50468a22 100644 --- a/docs/apex/APEX-User-Manual.rst +++ b/docs/apex/APEX-User-Manual.rst @@ -1025,12 +1025,12 @@ Verify Installation - run an Example .. container:: content - .. code:: + .. code:: :number-lines: - sudo su - apexuser - export APEX_HOME - export APEX_USER apexuser + sudo su - apexuser + export APEX_HOME + export APEX_USER apexuser .. container:: paragraph @@ -1040,7 +1040,7 @@ Verify Installation - run an Example .. container:: content - .. code:: + .. code:: :number-lines: # $APEX_HOME/bin/apexEngine.sh -c $APEX_HOME/examples/config/SampleDomain/Stdin2StdoutJsonEventJava.json (1) @@ -4535,8 +4535,8 @@ The APEX Full Client ``http://localhost:18989/apexservices``. In a web browser use the URL ``http://localhost:18989``. - The APEX Application Launcher ------------------------------- +The APEX Application Launcher +----------------------------- .. container:: paragraph @@ -4891,2750 +4891,327 @@ Application: Websocket Clients (Echo and Console) A discussion on how to use these two applications to build an APEX system is detailed HowTo-Websockets. -My First Policy -^^^^^^^^^^^^^^^ +APEX Logging +^^^^^^^^^^^^ + +Introduction to APEX Logging +---------------------------- -Introduction ------------- .. container:: paragraph - Consider a scenario where a supermarket chain called - *HyperM* controls how it sells items in a policy-based - manner. Each time an item is processed by *HyperM*'s - point-of-sale (PoS) system an event is generated and - published about that item of stock being sold. This event - can then be used to update stock levels, etc.. + All APEX components make extensive use of logging using the + logging façade `SLF4J `__ with the + backend `Logback `__. Both are used + off-the-shelve, so the standard documentation and + configuration apply to APEX logging. For details on how to + work with logback please see the `logback + manual `__. .. container:: paragraph - *HyperM* want to extend this approach to allow some checks - to be performed before the sale can be completed. This can - be achieved by requesting a policy-controlled decision as - each item is processed by for sale by each PoS system. The - decision process is integrated with *HyperM*'s other IT - systems that manage stock control, sourcing and purchasing, - personnel systems, etc. + The APEX applications is the logback configuration file + ``$APEX_HOME/etc/logback.xml`` (Windows: + ``%APEX_HOME%\etc\logback.xml``). The logging backend is set + to no debug, i.e. logs from the logging framework should be + hidden at runtime. .. container:: paragraph - In this document we will show how APEX and APEX Policies can - be used to achieve this, starting with a simple policy, - building up to more complicated policy that demonstrates the - features of APEX. - -Data Models ------------ + The configurable log levels work as expected: -Sales Input Event -################# + .. container:: ulist - .. container:: paragraph + - *error* (or *ERROR*) is used for serious errors in the + APEX runtime engine - Each time a PoS system processes a sales item an event - with the following format is emitted: + - *warn* (or *WARN*) is used for warnings, which in general + can be ignored but might indicate some deeper problems - .. table:: Table 1. Sale Input Event + - *info* (or *INFO*) is used to provide generally + interesting messages for startup and policy execution - +----------------------+----------------------+-----------------------+ - | Event | Fields | Description | - +======================+======================+=======================+ - | SALE_INPUT | time, sale_ID, | Event indicating a | - | | amount, item_ID, | sale of an item is | - | | quantity, | occurring | - | | assistant_ID, | | - | | branch_ID, notes, …​ | | - +----------------------+----------------------+-----------------------+ + - *debug* (or *DEBUG*) provides more details on startup and + policy execution - .. container:: paragraph + - *trace* (or *TRACE*) gives full details on every aspect + of the APEX engine from start to end - In each ``SALE_INPUT`` event the ``sale_ID`` field is a - unique ID generated by the PoS system. A timestamp for - the event is stored in the ``time`` field. The ``amount`` - field refers to the value of the item(s) to be sold (in - cents). The ``item_ID`` field is a unique identifier for - each item type, and can be used to retrieve more - information about the item from *HyperM*'s stock control - system. The ``quantity`` field refers to the quantity of - the item to be sold. The ``assistant_ID`` field is a - unique identifier for the PoS operator, and can be used - to retrieve more information about the operator from the - *HyperM*'s personnel system. Since *HyperM* has many - branches the ``branch_ID`` identifies the shop. The - ``notes`` field contains arbitrary notes about the sale. - -Sales Decision Event -#################### + .. container:: paragraph - .. container:: paragraph + The loggers can also be configured as expected. The standard + configuration (after installing APEX) uses log level *info* + on all APEX classes (components). - After a ``SALE_INPUT`` event is emitted by the PoS system - *HyperM*'s policy-based controlled sales checking system - emits a Sale Authorization Event indicating whether the - sale is authorized or denied. The PoS system can then - listen for this event before continuing with the sale. - - .. table:: Table 2. Sale Authorisation Event - - +----------------------+----------------------+-----------------------+ - | Event | Fields | Description | - +======================+======================+=======================+ - | SALE_AUTH | sale_ID, time, | Event indicating a | - | | authorized, amount, | sale of an item is | - | | item_ID, quantity, | authorized or denied | - | | assistant_ID, | | - | | branch_ID, notes, | | - | | message…​ | | - +----------------------+----------------------+-----------------------+ + .. container:: paragraph - .. container:: paragraph + The applications and scripts in ``$APEX_HOME/bin`` (Windows: + ``%APEX_HOME\bin``) are configured to use the logback + configuration ``$APEX_HOME/etc/logback.xml`` (Windows: + ``%APEX_HOME\etc\logback.xml``). There are multiple ways to + use different logback configurations, for instance: - In each ``SALE_AUTH`` event the ``sale_ID`` field is - copied from the ``SALE_INPUT`` event that trigger the - decision request. The ``SALE_AUTH`` event is also - timestamped using the ``time`` field, and a field called - ``authorised`` is set to ``true`` or ``false`` depending - on whether the sale is authorized or denied. The - ``message`` field carries an optional message about why a - sale was not authorized. The other fields from the - ``SALE_INPUT`` event are also included for completeness. - -Stock Control: Items -#################### + .. container:: ulist - .. container:: paragraph + - Maintain multiple configurations in ``etc``, for instance + a ``logback-debug.xml`` for deep debugging and a + ``logback-production.xml`` for APEX in production mode, + then copy the required configuration file to the used + ``logback.xml`` prior starting APEX - *HyperM* maintains information about each item for sale - in a database table called ``ITEMS``. + - Edit the scripts in ``bin`` to use a different logback + configuration file (only recommended if you are familiar + with editing bash scripts or windows batch files) - .. table:: Table 3. Items Database +Standard Logging Configuration +------------------------------ - +----------------------+----------------------+-----------------------+ - | Table | Fields | Description | - +======================+======================+=======================+ - | ITEMS | item_ID, | Database table | - | | description, | describing each item | - | | cost_price, barcode, | for sale | - | | supplier_ID, | | - | | category, …​ | | - +----------------------+----------------------+-----------------------+ + .. container:: paragraph - .. container:: paragraph + The standard logging configuration defines a context *APEX*, + which is used in the standard output pattern. The location + for log files is defined in the property ``logDir`` and set + to ``/var/log/onap/policy/apex-pdp``. The standard status + listener is set to *NOP* and the overall logback + configuration is set to no debug. - The database table ``ITEMS`` has a row for each items - that *HyperM* sells. Each item is identified by an - ``item_ID`` value. The ``description`` field stores a - description of the item. The cost price of the item is - given in ``cost_price``. The barcode of the item is - encoded in ``barcode``, while the item supplier is - identified by ``supplier_ID``. Items may also be - classified into categories using the ``category`` field. - Useful categories might include: ``soft drinks``, - ``alcoholic drinks``, ``cigarettes``, ``knives``, - ``confectionery``, ``bakery``, ``fruit&vegetables``, - ``meat``, etc.. - -Personnel System: Assistants -############################ + .. container:: listingblock - .. table:: Table 4. Assistants Database + .. container:: content - +----------------------+----------------------+-----------------------+ - | Table | Fields | Description | - +======================+======================+=======================+ - | ASSISTANTS | assistant_ID, | Database table | - | | surname, firstname, | describing each | - | | middlename, age, | *HyperM* sales | - | | grade, phone_number, | assistant | - | | …​ | | - +----------------------+----------------------+-----------------------+ + .. code:: + :number-lines: - .. container:: paragraph + + - The database table ``ASSISTANTS`` has a row for each - sales assistant employed by *HyperM*. Each assistant is - identified by an ``assistant_ID`` value, with their name - given in the ``firstname``, ``middlename`` and - ``surname`` fields. The assistant’s age in years is given - in ``age``, while their phone number is contained in the - ``phone_number`` field. The assistant’s grade is encoded - in ``grade``. Useful values for ``grade`` might include: - ``trainee``, ``operator``, ``supervisor``, etc.. - -Locations: Branches -#################### + Apex + - .. table:: Table 5. Branches Database + ...appenders + ...loggers + - +----------------------+----------------------+-----------------------+ - | Table | Fields | Description | - +======================+======================+=======================+ - | BRANCHES | branch_ID, | Database table | - | | branch_Name, | describing each | - | | category, street, | *HyperM* branch | - | | city, country, | | - | | postcode, …​ | | - +----------------------+----------------------+-----------------------+ +.. container:: paragraph - .. container:: paragraph + The first appender defined is called ``STDOUT`` for logs to standard + out. - *HyperM* operates a number of branches. Each branch is - described in the ``BRANCHES`` database table. Each branch - is identified by a ``branch_ID``, with a branch name - given in ``branch_Name``. The address for the branch is - encoded in ``street``, ``city``, ``country`` and - ``postcode``. The branch category is given in the - ``category`` field. Useful values for ``category`` might - include: ``Small``, ``Large``, ``Super``, ``Hyper``, - etc.. +.. container:: listingblock -Policy Step 1 -------------- + .. container:: content -Scenario -######### - .. container:: paragraph + .. code:: + :number-lines: - For the first version of our policy, let’s start with - something simple. Let us assume that there exists some - restriction that alcohol products cannot be sold before - 11:30am. In this section we will go through the necessary - steps to define a policy that can enforce this for - *HyperM*. + + + %d %contextName [%t] %level %logger{36} - %msg%n + + - .. container:: ulist +.. container:: paragraph - - Alcohol cannot be sold before 11:30am. + The root level logger then is set to the level *info* using the + standard out appender. -Create the an new empty Policy Model ``MyFirstPolicyModel`` -########################################################### +.. container:: listingblock - .. container:: paragraph + .. container:: content - Since an organisation like *HyperM* may have many - policies covering many different domains, policies should - be grouped into policy sets. In order to edit or deploy a - policy, or policy set, the definition of the policy(ies) - and all required events, tasks, states, etc., are grouped - together into a 'Policy Model'. An organization might - define many Policy Models, each containing a different - set of policies. + .. code:: + :number-lines: - .. container:: paragraph + + + - So the first step is to create a new empty Policy Model - called ``MyFirstPolicyModel``. Using the APEX Policy - Editor, click on the 'File' menus and select 'New'. Then - define our new policy model called - ``MyFirstPolicyModel``. Use the 'Generate UUID' button to - create a new unique ID for the policy model, and fill in - a description for the policy model. Press the ``Submit`` - button to save your changes. +.. container:: paragraph - .. container:: imageblock + The second appender is called ``FILE``. It writes logs to a file + ``apex.log``. - .. container:: content +.. container:: listingblock - |File > New to create a new Policy Model| + .. container:: content - .. container:: title + .. code:: + :number-lines: - Figure 4. Create a new Policy Model 1/2 + + ${logDir}/apex.log + + %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full} + + - .. container:: imageblock +.. container:: paragraph - .. container:: content + The third appender is called ``CTXT_FILE``. It writes logs to a file + ``apex_ctxt.log``. - |Create a new Policy Model| +.. container:: listingblock - .. container:: title + .. container:: content - Figure 5. Create a new Policy Model 2/2 + .. code:: + :number-lines: -Create the input event ``SALE_INPUT`` and the output event ``SALE_AUTH`` -######################################################################## + + ${logDir}/apex_ctxt.log + + %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full} + + - .. container:: paragraph +.. container:: paragraph - Using the APEX Policy Editor, click on the 'Events' tab. - In the 'Events' pane, right click and select 'New': + The last definitions are for specific loggers. The first logger + captures all standard APEX classes. It is configured for log level + *info* and uses the standard output and file appenders. The second + logger captures APEX context classes responsible for context + monitoring. It is configured for log level *trace* and uses the + context file appender. - .. container:: imageblock +.. container:: listingblock - .. container:: content + .. container:: content - |Right click to create a new event| + .. code:: + :number-lines: - .. container:: title - Figure 6. Create a new Event type + + + + - .. container:: paragraph + + + - Create a new event type called ``SALE_INPUT``. Use the - 'Generate UUID' button to create a new unique ID for the - event type, and fill in a description for the event. Add - a namespace, e.g. ``com.hyperm``. We can add hard-coded - strings for the ``Source`` and ``Target``, e.g. ``POS`` - and ``APEX``. At this stage we will not add any parameter - fields, we will leave this until later. Use the - ``Submit`` button to create the event. +Adding Logback Status and Debug +------------------------------- - .. container:: imageblock + .. container:: paragraph - .. container:: content + To activate logback status messages change the status listener + from 'NOP' to for instance console. - |Fill in the necessary information for the - 'SALE_INPUT' event and click 'Submit'| + .. container:: listingblock - .. container:: title + .. container:: content - Figure 7. Populate the ``SALE_INPUT`` event + .. code:: - .. container:: paragraph + - Repeat the same steps for a new event type called - ``SALE_AUTH``. Just use ``APEX`` as source and ``POS`` as - target, since this is the output event coming from APEX - going to the sales point. + .. container:: paragraph - .. container:: paragraph + To activate all logback debugging, for instance to debug a new + logback configuration, activate the debug attribute in the + configuration. - Before we can add parameter fields to an event we must - first define APEX Context Item Schemas that can be used - by those fields. + .. container:: listingblock - .. container:: paragraph + .. container:: content - To create new item schemas, click on the 'Context Item - Schemas' tab. In that 'Context Item Schemas' pane, right - click and select 'Create new ContextSchema'. + .. code:: - .. container:: imageblock + + ... + - .. container:: content +Logging External Components +--------------------------- - |Right click to create a new Item Schema| + .. container:: paragraph - .. container:: title + Logback can also be configured to log any other, external + components APEX is using, if they are using the common logging + framework. - Figure 8. Create new Data Types + .. container:: paragraph - .. container:: paragraph + For instance, the context component of APEX is using *Infinispan* + and one can add a logger for this external component. The + following example adds a logger for *Infinispan* using the + standard output appender. - Create item schemas with the following characteristics, - each with its own unique UUID: - - .. table:: Table 6. Item Schemas - - +-------------------+-----------------+-----------------+----------------------+ - | Name | Schema Flavour | Schema | Description | - | | | Definition | | - +===================+=================+=================+======================+ - | timestamp_type | Java | java.lang.Long | A type for | - | | | | ``time`` values | - +-------------------+-----------------+-----------------+----------------------+ - | sale_ID_type | Java | java.lang.Long | A type for | - | | | | ``sale_ID`` | - | | | | values | - +-------------------+-----------------+-----------------+----------------------+ - | price_type | Java | java.lang.Long | A type for | - | | | | ``amount``/``price`` | - | | | | values | - +-------------------+-----------------+-----------------+----------------------+ - | item_ID_type | Java | java.lang.Long | A type for | - | | | | ``item_ID`` | - | | | | values | - +-------------------+-----------------+-----------------+----------------------+ - | assistant_ID_type | Java | java.lang.Long | A type for | - | | | | ``assistant_ID`` | - | | | | values | - +-------------------+-----------------+-----------------+----------------------+ - | quantity_type | Java | java.lang.Integ | A type for | - | | | er | ``quantity`` | - | | | | values | - +-------------------+-----------------+-----------------+----------------------+ - | branch_ID_type | Java | java.lang.Long | A type for | - | | | | ``branch_ID`` | - | | | | values | - +-------------------+-----------------+-----------------+----------------------+ - | notes_type | Java | java.lang.Strin | A type for | - | | | g | ``notes`` | - | | | | values | - +-------------------+-----------------+-----------------+----------------------+ - | authorised_type | Java | java.lang.Boole | A type for | - | | | an | ``authorised`` | - | | | | values | - +-------------------+-----------------+-----------------+----------------------+ - | message_type | Java | java.lang.Strin | A type for | - | | | g | ``message`` | - | | | | values | - +-------------------+-----------------+-----------------+----------------------+ - - .. container:: imageblock + .. container:: listingblock - .. container:: content + .. container:: content - |Create a new Item Schema| + .. code:: - .. container:: title + + + - Figure 9. Create new Item Schemas + .. container:: paragraph - .. container:: paragraph + Another example is Apache Zookeeper. The following example adds a + logger for Zookeeper using the standard outout appender. - The item schemas can now be seen on the 'Context Item - Schemas' tab, and can be updated at any time by - right-clicking on the item schemas on the 'Context Item - Schemas' tab. Now we can go back to the event definitions - for ``SALE_INPUT`` and ``SALE_AUTH`` and add some - parameter fields. + .. container:: listingblock - .. tip + .. container:: content - .. container:: title + .. code:: - Field Schema types + + + - .. container:: paragraph +Configuring loggers for Policy Logic +------------------------------------ - APEX natively supports schema definitions in ``Java`` and ``Avro``. + .. container:: paragraph - .. container:: paragraph + The logging for the logic inside a policy (task logic, task + selection logic, state finalizer logic) can be configured separate + from standard logging. The logger for policy logic is + ``org.onap.policy.apex.executionlogging``. The following example + defines - ``Java`` schema definitions are simply the name of a Java Class. There are some restrictions: + .. container:: ulist - .. container:: ulist + - a new appender for standard out using a very simple pattern + (simply the actual message) - - the class must be instantiatable, i.e. not an Java interface or abstract class + - a logger for policy logic to standard out using the new + appender and the already described file appender. - - primitive types are not supported, i.e. use ``java.lang.Integer`` instead of ``int``, etc. + .. container:: listingblock - - it must be possible to find the class, i.e. the class must be contained in the Java classpath. + .. container:: content - .. container:: paragraph + .. code:: - ``Avro`` schema definitions can be any valid `Avro `__ - schema. For events using fields defined with ``Avro`` schemas, any incoming event containing that field must - contain a value that conforms to the Avro schema. + + + policy: %msg\n + + - .. container:: paragraph + + + + - Click on the 'Events' tab, then right click the - ``SALE_INPUT`` row and select 'Edit Event - :literal:`SALE_INPUT’. To add a new event parameter use the 'Add Event Parameter' button at the bottom of the screen. For the `SALE_INPUT` - event add the following event parameters: - - .. table:: Table 7. Event Parameter Fields for the ``SALE_INPUT`` Event - - +----------------------+----------------------+-----------------------+ - | Parameter Name | Parameter Type | Optional | - +======================+======================+=======================+ - | time | timestamp_type | no | - +----------------------+----------------------+-----------------------+ - | sale_ID | sale_ID_type | no | - +----------------------+----------------------+-----------------------+ - | amount | price_type | no | - +----------------------+----------------------+-----------------------+ - | item_ID | item_ID_type | no | - +----------------------+----------------------+-----------------------+ - | quantity | quantity_type | no | - +----------------------+----------------------+-----------------------+ - | assistant_ID | assistant_ID_type | no | - +----------------------+----------------------+-----------------------+ - | branch_ID | branch_ID_type | no | - +----------------------+----------------------+-----------------------+ - | notes | notes_type | *yes* | - +----------------------+----------------------+-----------------------+ + .. container:: paragraph - .. container:: paragraph + It is also possible to use specific logging for parts of policy + logic. The following example defines a logger for task logic. - Remember to click the 'Submit' button at the bottom of - the event definition pane. + .. container:: listingblock - .. tip:: - Optional Fields in APEX Events - Parameter fields can be *optional* in events. If a parameter is not marked as *optional* then by default it - is *mandatory*, so it must appear in any input event passed to APEX. If an *optional* field is not set - for an output event then value will be set to ``null``. + .. container:: content - .. container:: imageblock + .. code:: - .. container:: content - - |Add new event parameters to an event| - - .. container:: title - - Figure 10. Add typed parameter fields to an event - - .. container:: paragraph - - Select the ``SALE_AUTH`` event and add the following - event parameters: - - .. table:: Table 8. Event Parameter Fields for the ``SALE_AUTH`` Event - - +----------------------+----------------------+-----------------------+ - | Parameter Name | Parameter Type | no | - +======================+======================+=======================+ - | sale_ID | sale_ID_type | no | - +----------------------+----------------------+-----------------------+ - | time | timestamp_type | no | - +----------------------+----------------------+-----------------------+ - | authorised | authorised_type | no | - +----------------------+----------------------+-----------------------+ - | message | message_type | *yes* | - +----------------------+----------------------+-----------------------+ - | amount | price_type | no | - +----------------------+----------------------+-----------------------+ - | item_ID | item_ID_type | no | - +----------------------+----------------------+-----------------------+ - | assistant_ID | assistant_ID_type | no | - +----------------------+----------------------+-----------------------+ - | quantity | quantity_type | no | - +----------------------+----------------------+-----------------------+ - | branch_ID | branch_ID_type | no | - +----------------------+----------------------+-----------------------+ - | notes | notes_type | *yes* | - +----------------------+----------------------+-----------------------+ - - .. container:: paragraph - - Remember to click the 'Submit' button at the bottom of - the event definition pane. - - .. container:: paragraph - - The events for our policy are now defined. - -Create a new Policy and add the *"No Booze before 11:30"* check -############################################################### - - .. container:: paragraph - - APEX policies are defined using a state-machine model. - Each policy comprises one or more *states* that can be - individually executed. Where there is more than one - *state* the states are chained together to form a - `Directed Acyclic Graph - (DAG) `__ - of states. A *state* is triggered by passing it a single - input (or 'trigger') event and once executed each state - then emits an output event. For each *state* the logic - for the *state* is embedded in one or more *tasks*. Each - *task* contains specific *task logic* that is executed by - the APEX execution environment each time the *task* is - invoked. Where there is more than one *task* in a *state* - then the *state* also defines some *task selection logic* - to select an appropriate task each time the *state* is - executed. - - .. container:: paragraph - - Therefore, to create a new policy we must first define - one or more tasks. - - .. container:: paragraph - - To create a new Task click on the 'Tasks' tab. In the - 'Tasks' pane, right click and select 'Create new Task'. - Create a new Task called ``MorningBoozeCheck``. Use the - 'Generate UUID' button to create a new unique ID for the - task, and fill in a description for the task. - - .. container:: imageblock - - .. container:: content - - |Right click to create a new task| - - .. container:: title - - Figure 11. Create a new Task - - .. container:: paragraph - - Tasks are configured with a set of *input fields* and a - set of *output fields*. To add new input/output fields - for a task use the 'Add Task Input Field' and 'Add Task - Output Field' button. The list of input and out fields to - add for the ``MorningBoozeCheck`` task are given below. - The input fields are drawn from the parameters in the - state’s input event, and the task’s output fields are - used to populate the state’s output event. The task’s - input and output fields must be a subset of the event - parameters defined for the input and output events for - any state that uses that task. (You may have noticed that - the input and output fields for the ``MorningBoozeCheck`` - task have the exact same names and reuse the item schemas - that we used for the parameters in the ``SALE_INPUT`` and - ``SALE_AUTH`` events respectively). - - .. table:: Table 9. Input fields for ``MorningBoozeCheck`` task - - +-----------------------------------+-----------------------------------+ - | Parameter Name | Parameter Type | - +===================================+===================================+ - | time | timestamp_type | - +-----------------------------------+-----------------------------------+ - | sale_ID | sale_ID_type | - +-----------------------------------+-----------------------------------+ - | amount | price_type | - +-----------------------------------+-----------------------------------+ - | item_ID | item_ID_type | - +-----------------------------------+-----------------------------------+ - | quantity | quantity_type | - +-----------------------------------+-----------------------------------+ - | assistant_ID | assistant_ID_type | - +-----------------------------------+-----------------------------------+ - | branch_ID | branch_ID_type | - +-----------------------------------+-----------------------------------+ - | notes | notes_type | - +-----------------------------------+-----------------------------------+ - - .. table:: Table 10. Output fields for ``MorningBoozeCheck`` task - - +-----------------------------------+-----------------------------------+ - | Parameter Name | Parameter Type | - +===================================+===================================+ - | sale_ID | sale_ID_type | - +-----------------------------------+-----------------------------------+ - | time | timestamp_type | - +-----------------------------------+-----------------------------------+ - | authorised | authorised_type | - +-----------------------------------+-----------------------------------+ - | message | message_type | - +-----------------------------------+-----------------------------------+ - | amount | price_type | - +-----------------------------------+-----------------------------------+ - | item_ID | item_ID_type | - +-----------------------------------+-----------------------------------+ - | assistant_ID | assistant_ID_type | - +-----------------------------------+-----------------------------------+ - | quantity | quantity_type | - +-----------------------------------+-----------------------------------+ - | branch_ID | branch_ID_type | - +-----------------------------------+-----------------------------------+ - | notes | notes_type | - +-----------------------------------+-----------------------------------+ - - .. container:: imageblock - - .. container:: content - - |Add input and out fields for the task| - - .. container:: title - - Figure 12. Add input and out fields for the Task - - .. container:: paragraph - - Each task must include some 'Task Logic' that implements - the behaviour for the task. Task logic can be defined in - a number of different ways using a choice of languages. - For this task we will author the logic using the - Java-like scripting language called - ```MVEL`` `__. - - .. container:: paragraph - - For simplicity use the following code for the task logic. - Paste the script text into the 'Task Logic' box, and use - "MVEL" as the 'Task Logic Type / Flavour'. - - .. container:: paragraph - - This logic assumes that all items with ``item_ID`` - between 1000 and 2000 contain alcohol, which is not very - realistic, but we will see a better approach for this - later. It also uses the standard ``Java`` time utilities - to check if the current time is between ``00:00:00 GMT`` - and ``11:30:00 GMT``. For a detailed guide to how to - write your own logic in - ```JavaScript`` `__, - ```MVEL`` `__ or one - of the other supported languages please refer to APEX - Programmers Guide. - - .. container:: listingblock - - .. container:: title - - MVEL code for the ``MorningBoozeCheck`` task - - .. container:: content - - .. code:: - - /* - * ============LICENSE_START======================================================= - * Copyright (C) 2016-2018 Ericsson. All rights reserved. - * ================================================================================ - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - * SPDX-License-Identifier: Apache-2.0 - * ============LICENSE_END========================================================= - */ - import java.util.Date; - import java.util.Calendar; - import java.util.TimeZone; - import java.text.SimpleDateFormat; - - logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'"); - - outFields.put("amount" , inFields.get("amount")); - outFields.put("assistant_ID", inFields.get("assistant_ID")); - outFields.put("notes" , inFields.get("notes")); - outFields.put("quantity" , inFields.get("quantity")); - outFields.put("branch_ID" , inFields.get("branch_ID")); - outFields.put("item_ID" , inFields.get("item_ID")); - outFields.put("time" , inFields.get("time")); - outFields.put("sale_ID" , inFields.get("sale_ID")); - - item_id = inFields.get("item_ID"); - - //The events used later to test this task use GMT timezone! - gmt = TimeZone.getTimeZone("GMT"); - timenow = Calendar.getInstance(gmt); - df = new SimpleDateFormat("HH:mm:ss z"); - df.setTimeZone(gmt); - timenow.setTimeInMillis(inFields.get("time")); - - midnight = timenow.clone(); - midnight.set( - timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), - timenow.get(Calendar.DATE),0,0,0); - eleven30 = timenow.clone(); - eleven30.set( - timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), - timenow.get(Calendar.DATE),11,30,0); - - itemisalcohol = false; - if(item_id != null && item_id >=1000 && item_id < 2000) - itemisalcohol = true; - - if( itemisalcohol - && timenow.after(midnight) && timenow.before(eleven30)){ - outFields.put("authorised", false); - outFields.put("message", "Sale not authorised by policy task "+subject.taskName+ - " for time "+df.format(timenow.getTime())+ - ". Alcohol can not be sold between "+df.format(midnight.getTime())+ - " and "+df.format(eleven30.getTime())); - return true; - } - else{ - outFields.put("authorised", true); - outFields.put("message", "Sale authorised by policy task "+subject.taskName+ - " for time "+df.format(timenow.getTime())); - return true; - } - - /* - This task checks if a sale request is for an item that is an alcoholic drink. - If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not - authorised. Otherwise the sale is authorised. - In this implementation we assume that items with item_ID value between 1000 and - 2000 are all alcoholic drinks :-) - */ - - .. container:: imageblock - - .. container:: content - - |Add task logic the task| - - .. container:: title - - Figure 13. Add Task Logic the Task - - .. container:: paragraph - - An alternative version of the same logic is available in - JavaScript. Just use "JAVASCRIPT" as the 'Task Logic Type - / Flavour' instead. - - .. container:: listingblock - - .. container:: title - - Javascript alternative for the ``MorningBoozeCheck`` - task - - .. container:: content - - .. code:: - - /* - * ============LICENSE_START======================================================= - * Copyright (C) 2016-2018 Ericsson. All rights reserved. - * ================================================================================ - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - * SPDX-License-Identifier: Apache-2.0 - * ============LICENSE_END========================================================= - */ - - var returnValueType = Java.type("java.lang.Boolean"); - var returnValue = new returnValueType(true); - - // Load compatibility script for imports etc - load("nashorn:mozilla_compat.js"); - importPackage(java.text); - importClass(java.text.SimpleDateFormat); - - executor.logger.info("Task Execution: '"+executor.subject.id+"'. Input Fields: '"+executor.inFields+"'"); - - executor.outFields.put("amount" , executor.inFields.get("amount")); - executor.outFields.put("assistant_ID", executor.inFields.get("assistant_ID")); - executor.outFields.put("notes" , executor.inFields.get("notes")); - executor.outFields.put("quantity" , executor.inFields.get("quantity")); - executor.outFields.put("branch_ID" , executor.inFields.get("branch_ID")); - executor.outFields.put("item_ID" , executor.inFields.get("item_ID")); - executor.outFields.put("time" , executor.inFields.get("time")); - executor.outFields.put("sale_ID" , executor.inFields.get("sale_ID")); - - item_id = executor.inFields.get("item_ID"); - - //All times in this script are in GMT/UTC since the policy and events assume time is in GMT. - var timenow_gmt = new Date(Number(executor.inFields.get("time"))); - - var midnight_gmt = new Date(Number(executor.inFields.get("time"))); - midnight_gmt.setUTCHours(0,0,0,0); - - var eleven30_gmt = new Date(Number(executor.inFields.get("time"))); - eleven30_gmt.setUTCHours(11,30,0,0); - - var timeformatter = new java.text.SimpleDateFormat("HH:mm:ss z"); - - var itemisalcohol = false; - if(item_id != null && item_id >=1000 && item_id < 2000) - itemisalcohol = true; - - if( itemisalcohol - && timenow_gmt.getTime() >= midnight_gmt.getTime() - && timenow_gmt.getTime() < eleven30_gmt.getTime()) { - - executor.outFields.put("authorised", false); - executor.outFields.put("message", "Sale not authorised by policy task " + - executor.subject.taskName+ " for time " + timeformatter.format(timenow_gmt.getTime()) + - ". Alcohol can not be sold between " + timeformatter.format(midnight_gmt.getTime()) + - " and " + timeformatter.format(eleven30_gmt.getTime())); - } - else{ - executor.outFields.put("authorised", true); - executor.outFields.put("message", "Sale authorised by policy task " + - executor.subject.taskName + " for time "+timeformatter.format(timenow_gmt.getTime())); - } - - /* - This task checks if a sale request is for an item that is an alcoholic drink. - If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not - authorised. Otherwise the sale is authorised. - In this implementation we assume that items with item_ID value between 1000 and - 2000 are all alcoholic drinks :-) - */ - - .. container:: paragraph - - The task definition is now complete so click the 'Submit' - button to save the task. The task can now be seen on the - 'Tasks' tab, and can be updated at any time by - right-clicking on the task on the 'Task' tab. Now that we - have created our task, we can can create a policy that - uses that task. - - .. container:: paragraph - - To create a new Policy click on the 'Policies' tab. In - the 'Policies' pane, right click and select 'Create new - Policy': - - .. container:: paragraph - - Create a new Policy called ``MyFirstPolicy``. Use the - 'Generate UUID' button to create a new unique ID for the - policy, and fill in a description for the policy. Use - 'FREEFORM' as the 'Policy Flavour'. - - .. container:: paragraph - - Each policy must have at least one state. Since this is - 'freeform' policy we can add as many states as we wish. - Let’s start with one state. Add a new state called - ``BoozeAuthDecide`` to this ``MyFirstPolicy`` policy - using the 'Add new State' button after filling in the - name of our new state. - - .. container:: imageblock - - .. container:: content - - |Create a new policy| - - .. container:: title - - Figure 14. Create a new Policy - - .. container:: paragraph - - Each state must uses one input event type. For this new - state select the ``SALE_INPUT`` event as the input event. - - .. container:: paragraph - - Each policy must define a 'First State' and a 'Policy - Trigger Event'. The 'Policy Trigger Event' is the input - event for the policy as a whole. This event is then - passed to the first state in the chain of states in the - policy, therefore the 'Policy Trigger Event' will be the - input event for the first state. Each policy can only - have one 'First State'. For our ``MyFirstPolicy`` policy, - select ``BoozeAuthDecide`` as the 'First State'. This - will automatically select ``SALE_INPUT`` as the 'Policy - Trigger Event' for our policy. - - .. container:: imageblock - - .. container:: content - - |Create a state| - - .. container:: title - - Figure 15. Create a new State - - .. container:: paragraph - - In this case we will create a reference the pre-existing - ``MorningBoozeCheck`` task that we defined above using - the 'Add New Task' button. Select the - ``MorningBoozeCheck`` task, and use the name of the task - as the 'Local Name' for the task. - - .. container:: paragraph - - in the case where a state references more than one task, - a 'Default Task' must be selected for the state and some - logic ('Task Selection Logic') must be specified to - select the appropriate task at execution time. Since our - new state ``BoozeAuthDecide`` only has one task the - default task is automatically selected and no 'Task - Selection Logic' is required. - - .. note:: - .. container:: title - - State Output Mappings - - .. container:: paragraph - - In a 'Policy' 'State' a 'State Output Mapping' has 3 roles: - 1) Select which 'State' should be executed next, 2) Select - the type of the state’s 'Outgoing Event', and 3) - Populate the state’s 'Outgoing Event'. This is how states are - chained together to form a (`Directed Acyclic Graph - (DAG) `__ ) - of states. The final state(s) of a policy are those that do - not select any 'next' state. Since a 'State' can only - accept a single type of event, the type of the event emitted - by a previous 'State' must be match the incoming event type - of the next 'State'. This is also how the last state(s) in - a policy can emit events of different types. The 'State - Output Mapping' is also responsible for taking the - fields that are output by the task executed in the state and - populating the state’s output event before it is emitted. - - .. container:: paragraph - - Each 'Task' referenced in 'State' must have a defined - 'Output Mapping' to take the output of the task, select an - 'Outgoing Event' type for the state, populate the state’s - outgoing event, and then select the next state to be - executed (if any). - - .. container:: paragraph - - There are 2 basic types of output mappings: - - .. container:: olist arabic - - #. **Direct Output Mappings** have a single value for - 'Next State' and a single value for 'State Output - Event'. The outgoing event for the state is - automatically created, any outgoing event parameters - that were present in the incoming event are copied - into the outgoing event, then any task output fields - that have the same name and type as parameters in the - outgoing event are automatically copied into - the outgoing event. - - #. **Logic-based State Output Mappings / Finalizers** - have some logic defined that dynamically selects - and creates the 'State Outgoing Event', manages - the population of the outgoing event parameters - (perhaps changing or adding to the outputs from the - task), and then dynamically selects the next state to - be executed (if any). - - .. container:: paragraph - - Each task reference must also have an associated 'Output - State Mapping' so we need an 'Output State Mapping' for - the ``BoozeAuthDecide`` state to use when the - ``MorningBoozeCheck`` task is executed. The simplest type - of output mapping is a 'Direct Output Mapping'. - - .. container:: paragraph - - Create a new 'Direct Output Mapping' for the state called - ``MorningBoozeCheck_Output_Direct`` using the 'Add New - Direct State Output Mapping' button. Select ``SALE_AUTH`` - as the output event and select ``None`` for the next - state value. We can then select this output mapping for - use when the the ``MorningBoozeCheck`` task is executed. - Since there is only state, and only one task for that - state, this output mapping ensures that the - ``BoozeAuthDecide`` state is the only state executed and - the state (and the policy) can only emit events of type - ``SALE_AUTH``. (You may remember that the output fields - for the ``MorningBoozeCheck`` task have the exact same - names and reuse the item schemas that we used for the - parameters in ``SALE_AUTH`` event. The - ``MorningBoozeCheck_Output_Direct`` direct output mapping - can now automatically copy the values from the - ``MorningBoozeCheck`` task directly into outgoing - ``SALE_AUTH`` events.) - - .. container:: imageblock - - .. container:: content - - |Add a Task and Output Mapping| - - .. container:: title - - Figure 16. Add a Task and Output Mapping - - .. container:: paragraph - - Click the 'Submit' button to complete the definition of - our ``MyFirstPolicy`` policy. The policy - ``MyFirstPolicy`` can now be seen in the list of policies - on the 'Policies' tab, and can be updated at any time by - right-clicking on the policy on the 'Policies' tab. - - .. container:: paragraph - - The ``MyFirstPolicyModel``, including our - ``MyFirstPolicy`` policy can now be checked for errors. - Click on the 'Model' menu and select 'Validate'. The - model should validate without any 'Warning' or 'Error' - messages. If you see any 'Error' or 'Warning' messages, - carefully read the message as a hint to find where you - might have made a mistake when defining some aspect of - your policy model. - - .. container:: imageblock - - .. container:: content - - |Validate the policy model for error using the 'Model' - > 'Validate' menu item| - - .. container:: title - - Figure 17. Validate a Policy Model - - .. container:: paragraph - - Congratulations, you have now completed your first APEX - policy. The policy model containing our new policy can - now be exported from the editor and saved. Click on the - 'File' menu and select 'Download' to save the policy - model in JSON format. The exported policy model is then - available in the directory you selected, for instance - ``$APEX_HOME/examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json``. - The exported policy can now be loaded into the APEX - Policy Engine, or can be re-loaded and edited by the APEX - Policy Editor. - - .. container:: imageblock - - .. container:: content - - |Download the completed policy model using the 'File' - > 'Download' menu item| - - .. container:: title - - Figure 18. Export a Policy Model - -Test Policy Step 1 -################## - - .. container:: paragraph - - To start a new APEX Engine you can use the following - configuration. In a full APEX installation you can find - this configuration in - ``$APEX_HOME/examples/config/MyFirstPolicy/1/MyFirstPolicyConfigStdin2StdoutJsonEvent.json``. - This configuration expects incoming events to be in - ``JSON`` format and to be passed into the APEX Engine - from ``stdin``, and result events will be printed in - ``JSON`` format to ``stdout``. This configuration loads - the policy model stored in the file - 'MyFirstPolicyModel_0.0.1.json' as exported from the APEX - Editor. Note, you may need to edit this file to provide - the full path to wherever you stored the exported policy - model file. - - .. container:: listingblock - - .. container:: title - - JSON to load and execute *My First Policy*, read input - JSON events from ``stdin``, and emit output events to - ``stdout`` - - .. container:: content - - .. code:: - - { - "engineServiceParameters" : { - "name" : "MyFirstPolicyApexEngine", - "version" : "0.0.1", - "id" : 101, - "instanceCount" : 4, - "deploymentPort" : 12345, - "policyModelFileName" : "examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json", - "engineParameters" : { - "executorParameters" : { - "MVEL" : { - "parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters" - }, - "JAVASCRIPT" : { - "parameterClassName" : "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters" - } - } - } - }, - "eventOutputParameters": { - "FirstProducer": { - "carrierTechnologyParameters" : { - "carrierTechnology" : "FILE", - "parameters" : { - "standardIO" : true - } - }, - "eventProtocolParameters" : { - "eventProtocol" : "JSON" - } - } - }, - "eventInputParameters": { - "FirstConsumer": { - "carrierTechnologyParameters" : { - "carrierTechnology" : "FILE", - "parameters" : { - "standardIO" : true - } - }, - "eventProtocolParameters" : { - "eventProtocol" : "JSON" - } - } - } - } - - .. container:: paragraph - - To test the policy try paste the following events into - the console as the APEX engine executes: - - .. table:: Table 11. Inputs and Outputs when testing *My First Policy* - - +------------------------------------------+-------------------------------------------+-----------+ - | Input Event (JSON) | Output Event (JSON) | comment | - +==========================================+===========================================+===========+ - | .. container:: | .. container:: | Request | - | | | to buy a | - | .. container:: listingblock | .. container:: listingblock | non-alcoh | - | | | olic | - | | .. container:: content | item | - | .. container:: content | | (``item_I | - | | .. code:: | D=5123``) | - | | | at | - | .. code:: | { | *10:13:09 | - | | "name": "SALE_AUTH", | * | - | | | on | - | { | "version": "0.0.1", | *Tuesday, | - | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | 10 | - | "name" : "SALE_INPUT", | "source": "", | January | - | "version": "0.0.1", | "target": "", | 2017*. | - | "time" : 1483351989000, | "amount": 299, | Sale is | - | "sale_ID": 99999991, | "assistant_ID": 23, | authorize | - | "amount": 299, | "authorised": true, | d. | - | "item_ID": 5123, | "branch_ID": 1, | | - | "quantity": 1, | "item_ID": 5123, | | - | "assistant_ID": 23, | "message": "Sale authorised | | - | "branch_ID": 1, | by policy task MorningBo | | - | "notes": "Special Offer!!" | ozeCheck for time 10:13:09 | | - | } | GMT", | | - | | "notes": "Special Offer!!", | | - | | "quantity": 1, | | - | | "sale_ID": 99999991, | | - | | "time": 1483351989000 | | - | | } | | - | | | | - | | | | - | | | | - +------------------------------------------+-------------------------------------------+-----------+ - | .. container:: | .. container:: | Request | - | | | to buy | - | .. container:: listingblock | .. container:: listingblock | alcohol | - | | | item | - | .. container:: content | .. container:: content | (``item_I | - | | | D=1249``) | - | .. code:: | .. code:: | at | - | | | *08:41:06 | - | { | { | * | - | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | on | - | "name": "SALE_INPUT", | "name": "SALE_AUTH", | *Monday, | - | "version": "0.0.1", | "source": "", | 02 | - | "time": 1483346466000, | "target": "", | January | - | "sale_ID": 99999992, | "amount": 1249, | 2017*. | - | "version": "0.0.1", | "assistant_ID": 12, | | - | "amount": 1249, | "authorised": false, | Sale is | - | "item_ID": 1012, | "branch_ID": 2, | not | - | "quantity": 1, | "item_ID": 1012, | authorize | - | "assistant_ID": 12, | "message": "Sale not | d. | - | "branch_ID": 2 | authorised by policy task | | - | } | MorningBoozeCheck for time | | - | | 08:41:06 GMT. Alcohol can | | - | | not be sold between | | - | | 00:00:00 GMT and 11:30:00 | | - | | GMT", | | - | | "notes": null, | | - | | "quantity": 1, | | - | | "sale_ID": 99999992, | | - | | "time": 1483346466000 | | - | | } | | - +------------------------------------------+-------------------------------------------+-----------+ - | .. container:: | .. container:: | Request | - | | | to buy | - | .. container:: listingblock | .. container:: listingblock | alcohol | - | | | (``item_I | - | | .. container:: content | D=1943``) | - | .. container:: content | | at | - | | .. code:: | *20:17:13 | - | | | * | - | .. code:: | { | on | - | | "name": "SALE_AUTH", | *Tuesday, | - | { | "version": "0.0.1", | 20 | - | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | December | - | "name" : "SALE_INPUT", | "source": "", | 2016*. | - | "version": "0.0.1", | "target": "", | | - | "time" : 1482265033000, | "amount": 4799, | Sale is | - | "sale_ID": 99999993, | "assistant_ID": 9, | authorize | - | "amount": 4799, | "authorised": true, | d. | - | "item_ID": 1943, | "branch_ID": 3, | | - | "quantity": 2, | "item_ID": 1943, | | - | "assistant_ID": 9, | "message": "Sale authorised | | - | "branch_ID": 3 | by policy task MorningBo | | - | } | ozeCheck for time 20:17:13 | | - | | GMT", | | - | | "notes": null, | | - | | "quantity": 2, | | - | | "sale_ID": 99999993, | | - | | "time": 1482265033000 | | - | | } | | - +------------------------------------------+-------------------------------------------+-----------+ - -4.3.6. Policy 1 in CLI Editor -############################# - - .. container:: paragraph - - An equivalent version of the ``MyFirstPolicyModel`` - policy model can again be generated using the APEX CLI - editor. A sample APEX CLI script is shown below: - - .. container:: listingblock - - .. container:: title - - APEX CLI Editor code for Policy 1 - - .. container:: content - - .. code:: - - #------------------------------------------------------------------------------- - # ============LICENSE_START======================================================= - # Copyright (C) 2016-2018 Ericsson. All rights reserved. - # ================================================================================ - # Licensed under the Apache License, Version 2.0 (the "License"); - # you may not use this file except in compliance with the License. - # You may obtain a copy of the License at - # - # http://www.apache.org/licenses/LICENSE-2.0 - # - # Unless required by applicable law or agreed to in writing, software - # distributed under the License is distributed on an "AS IS" BASIS, - # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - # See the License for the specific language governing permissions and - # limitations under the License. - # - # SPDX-License-Identifier: Apache-2.0 - # ============LICENSE_END========================================================= - #------------------------------------------------------------------------------- - - model create name=MyFirstPolicyModel version=0.0.1 uuid=540226fb-55ee-4f0e-a444-983a0494818e description="This is my first Apex Policy Model." - - schema create name=assistant_ID_type version=0.0.1 uuid=36df4c71-9616-4206-8b53-976a5cd4bd87 description="A type for 'assistant_ID' values" flavour=Java schema=java.lang.Long - - schema create name=authorised_type version=0.0.1 uuid=d48b619e-d00d-4008-b884-02d76ea4350b description="A type for 'authorised' values" flavour=Java schema=java.lang.Boolean - - schema create name=branch_ID_type version=0.0.1 uuid=6468845f-4122-4128-8e49-0f52c26078b5 description="A type for 'branch_ID' values" flavour=Java schema=java.lang.Long - - schema create name=item_ID_type version=0.0.1 uuid=4f227ff1-aee0-453a-b6b6-9a4b2e0da932 description="A type for 'item_ID' values" flavour=Java schema=java.lang.Long - - schema create name=message_type version=0.0.1 uuid=ad1431bb-3155-4e73-b5a3-b89bee498749 description="A type for 'message' values" flavour=Java schema=java.lang.String - - schema create name=notes_type version=0.0.1 uuid=eecfde90-896c-4343-8f9c-2603ced94e2d description="A type for 'notes' values" flavour=Java schema=java.lang.String - - schema create name=price_type version=0.0.1 uuid=52c2fc45-fd8c-463c-bd6f-d91b0554aea7 description="A type for 'amount'/'price' values" flavour=Java schema=java.lang.Long - - schema create name=quantity_type version=0.0.1 uuid=ac3d9842-80af-4a98-951c-bd79a431c613 description="A type for 'quantity' values" flavour=Java schema=java.lang.Integer - - schema create name=sale_ID_type version=0.0.1 uuid=cca47d74-7754-4a61-b163-ca31f66b157b description="A type for 'sale_ID' values" flavour=Java schema=java.lang.Long - - schema create name=timestamp_type version=0.0.1 uuid=fd594e88-411d-4a94-b2be-697b3a0d7adf description="A type for 'time' values" flavour=Java schema=java.lang.Long - - task create name=MorningBoozeCheck version=0.0.1 uuid=3351b0f4-cf06-4fa2-8823-edf67bd30223 description=LS - This task checks if the sales request is for an item that contains alcohol. - If the local time is between 00:00:00 and 11:30:00 then the sale is not authorised. Otherwise the sale is authorised. - In this implementation we assume that all items with item_ID values between 1000 and 2000 contain alcohol :-) - LE - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true - task logic create name=MorningBoozeCheck version=0.0.1 logicFlavour=MVEL logic=LS - /* - * ============LICENSE_START======================================================= - * Copyright (C) 2016-2018 Ericsson. All rights reserved. - * ================================================================================ - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - * SPDX-License-Identifier: Apache-2.0 - * ============LICENSE_END========================================================= - */ - import java.util.Date; - import java.util.Calendar; - import java.util.TimeZone; - import java.text.SimpleDateFormat; - - logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'"); - - outFields.put("amount" , inFields.get("amount")); - outFields.put("assistant_ID", inFields.get("assistant_ID")); - outFields.put("notes" , inFields.get("notes")); - outFields.put("quantity" , inFields.get("quantity")); - outFields.put("branch_ID" , inFields.get("branch_ID")); - outFields.put("item_ID" , inFields.get("item_ID")); - outFields.put("time" , inFields.get("time")); - outFields.put("sale_ID" , inFields.get("sale_ID")); - - item_id = inFields.get("item_ID"); - - //The events used later to test this task use GMT timezone! - gmt = TimeZone.getTimeZone("GMT"); - timenow = Calendar.getInstance(gmt); - df = new SimpleDateFormat("HH:mm:ss z"); - df.setTimeZone(gmt); - timenow.setTimeInMillis(inFields.get("time")); - - midnight = timenow.clone(); - midnight.set( - timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), - timenow.get(Calendar.DATE),0,0,0); - eleven30 = timenow.clone(); - eleven30.set( - timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), - timenow.get(Calendar.DATE),11,30,0); - - itemisalcohol = false; - if(item_id != null && item_id >=1000 && item_id < 2000) - itemisalcohol = true; - - if( itemisalcohol - && timenow.after(midnight) && timenow.before(eleven30)){ - outFields.put("authorised", false); - outFields.put("message", "Sale not authorised by policy task "+subject.taskName+ - " for time "+df.format(timenow.getTime())+ - ". Alcohol can not be sold between "+df.format(midnight.getTime())+ - " and "+df.format(eleven30.getTime())); - return true; - } - else{ - outFields.put("authorised", true); - outFields.put("message", "Sale authorised by policy task "+subject.taskName+ - " for time "+df.format(timenow.getTime())); - return true; - } - - /* - This task checks if a sale request is for an item that is an alcoholic drink. - If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not - authorised. Otherwise the sale is authorised. - In this implementation we assume that items with item_ID value between 1000 and - 2000 are all alcoholic drinks :-) - */ - LE - - event create name=SALE_AUTH version=0.0.1 uuid=c4500941-3f98-4080-a9cc-5b9753ed050b description="An event emitted by the Policy to indicate whether the sale of an item has been authorised" nameSpace=com.hyperm source="APEX" target="POS" - event parameter create name=SALE_AUTH version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=authorised schemaName=authorised_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=message schemaName=message_type schemaVersion=0.0.1 optional=true - event parameter create name=SALE_AUTH version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true - event parameter create name=SALE_AUTH version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1 - - event create name=SALE_INPUT version=0.0.1 uuid=4f04aa98-e917-4f4a-882a-c75ba5a99374 description="An event raised by the PoS system each time an item is scanned for purchase" nameSpace=com.hyperm source="POS" target="APEX" - event parameter create name=SALE_INPUT version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true - event parameter create name=SALE_INPUT version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1 - - - policy create name=MyFirstPolicy version=0.0.1 uuid=6c5e410f-489a-46ff-964e-982ce6e8b6d0 description="This is my first Apex policy. It checks if a sale should be authorised or not." template=FREEFORM firstState=BoozeAuthDecide - policy state create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide triggerName=SALE_INPUT triggerVersion=0.0.1 defaultTaskName=MorningBoozeCheck defaultTaskVersion=0.0.1 - policy state output create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide outputName=MorningBoozeCheck_Output_Direct eventName=SALE_AUTH eventVersion=0.0.1 nextState=NULL - policy state taskref create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide taskLocalName=MorningBoozeCheck taskName=MorningBoozeCheck taskVersion=0.0.1 outputType=DIRECT outputName=MorningBoozeCheck_Output_Direct - -Policy Step 2 -------------- - -Scenario -######### - .. container:: paragraph - - *HyperM* have just opened a new branch in a different - country, but that country has different rules about when - alcohol can be sold! In this section we will go through - the necessary steps to extend our policy to enforce this - for *HyperM*. - - .. container:: ulist - - - In some branches alcohol cannot be sold before 1pm, - and not at all on Sundays. - - .. container:: paragraph - - Although there are a number of ways to accomplish this - the easiest approach for us is to define another task and - then select which task is appropriate at runtime - depending on the branch identifier in the incoming event. - -Extend the Policy with the new Scenario -####################################### - - .. container:: paragraph - - To create a new Task click on the 'Tasks' tab. In the - 'Tasks' pane, right click and select 'Create new Task': - - .. container:: paragraph - - Create a new Task called ``MorningBoozeCheckAlt1``. Use - the 'Generate UUID' button to create a new unique ID for - the task, and fill in a description for the task. Select - the same input and output fields that we used earlier - when we defined the ``MorningBoozeCheck`` task earlier. - - .. table:: Table 12. Input fields for ``MorningBoozeCheckAlt1`` task - - +-----------------------------------+-----------------------------------+ - | Parameter Name | Parameter Type | - +===================================+===================================+ - | time | timestamp_type | - +-----------------------------------+-----------------------------------+ - | sale_ID | sale_ID_type | - +-----------------------------------+-----------------------------------+ - | amount | price_type | - +-----------------------------------+-----------------------------------+ - | item_ID | item_ID_type | - +-----------------------------------+-----------------------------------+ - | quantity | quantity_type | - +-----------------------------------+-----------------------------------+ - | assistant_ID | assistant_ID_type | - +-----------------------------------+-----------------------------------+ - | branch_ID | branch_ID_type | - +-----------------------------------+-----------------------------------+ - | notes | notes_type | - +-----------------------------------+-----------------------------------+ - - .. table:: Table 13. Output fields for ``MorningBoozeCheckAlt1`` task - - +-----------------------------------+-----------------------------------+ - | Parameter Name | Parameter Type | - +===================================+===================================+ - | sale_ID | sale_ID_type | - +-----------------------------------+-----------------------------------+ - | time | timestamp_type | - +-----------------------------------+-----------------------------------+ - | authorised | authorised_type | - +-----------------------------------+-----------------------------------+ - | message | message_type | - +-----------------------------------+-----------------------------------+ - | amount | price_type | - +-----------------------------------+-----------------------------------+ - | item_ID | item_ID_type | - +-----------------------------------+-----------------------------------+ - | assistant_ID | assistant_ID_type | - +-----------------------------------+-----------------------------------+ - | quantity | quantity_type | - +-----------------------------------+-----------------------------------+ - | branch_ID | branch_ID_type | - +-----------------------------------+-----------------------------------+ - | notes | notes_type | - +-----------------------------------+-----------------------------------+ - - .. container:: paragraph - - This task also requires some 'Task Logic' to implement - the new behaviour for this task. - - .. container:: paragraph - - For simplicity use the following code for the task logic. - It again assumes that all items with ``item_ID`` between - 1000 and 2000 contain alcohol. We again use the standard - ``Java`` time utilities to check if the current time is - between ``00:00:00 CET`` and ``13:00:00 CET`` or if it is - ``Sunday``. - - .. container:: paragraph - - For this task we will again author the logic using the - ```MVEL`` `__ - scripting language. Sample task logic code (specified in - ```MVEL`` `__) is - given below. For a detailed guide to how to write your - own logic in - ```JavaScript`` `__, - ```MVEL`` `__ or one - of the other supported languages please refer to APEX - Programmers Guide. - - .. container:: listingblock - - .. container:: title - - MVEL code for the ``MorningBoozeCheckAlt1`` task - - .. container:: content - - .. code:: - - /* - * ============LICENSE_START======================================================= - * Copyright (C) 2016-2018 Ericsson. All rights reserved. - * ================================================================================ - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - * SPDX-License-Identifier: Apache-2.0 - * ============LICENSE_END========================================================= - */ - import java.util.Date; - import java.util.Calendar; - import java.util.TimeZone; - import java.text.SimpleDateFormat; - - logger.info("Task Execution: '"+subject.id+"'. Input Event: '"+inFields+"'"); - - outFields.put("amount" , inFields.get("amount")); - outFields.put("assistant_ID", inFields.get("assistant_ID")); - outFields.put("notes" , inFields.get("notes")); - outFields.put("quantity" , inFields.get("quantity")); - outFields.put("branch_ID" , inFields.get("branch_ID")); - outFields.put("item_ID" , inFields.get("item_ID")); - outFields.put("time" , inFields.get("time")); - outFields.put("sale_ID" , inFields.get("sale_ID")); - - item_id = inFields.get("item_ID"); - - //The events used later to test this task use CET timezone! - cet = TimeZone.getTimeZone("CET"); - timenow = Calendar.getInstance(cet); - df = new SimpleDateFormat("HH:mm:ss z"); - df.setTimeZone(cet); - timenow.setTimeInMillis(inFields.get("time")); - - midnight = timenow.clone(); - midnight.set( - timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), - timenow.get(Calendar.DATE),0,0,0); - onepm = timenow.clone(); - onepm.set( - timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), - timenow.get(Calendar.DATE),13,0,0); - - itemisalcohol = false; - if(item_id != null && item_id >=1000 && item_id < 2000) - itemisalcohol = true; - - if( itemisalcohol && - ( (timenow.after(midnight) && timenow.before(onepm)) - || - (timenow.get(Calendar.DAY_OF_WEEK) == Calendar.SUNDAY) - )){ - outFields.put("authorised", false); - outFields.put("message", "Sale not authorised by policy task "+subject.taskName+ - " for time "+df.format(timenow.getTime())+ - ". Alcohol can not be sold between "+df.format(midnight.getTime())+ - " and "+df.format(onepm.getTime()) +" or on Sunday"); - return true; - } - else{ - outFields.put("authorised", true); - outFields.put("message", "Sale authorised by policy task "+subject.taskName+ - " for time "+df.format(timenow.getTime())); - return true; - } - - /* - This task checks if a sale request is for an item that is an alcoholic drink. - If the local time is between 00:00:00 CET and 13:00:00 CET then the sale is not authorised. - Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised. - In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks :-) - */ - - .. container:: imageblock - - .. container:: content - - |Create a new alternative task MorningBoozeCheckAlt1| - - .. container:: title - - Figure 19. Create a new Task - - .. container:: paragraph - - The task definition is now complete so click the 'Submit' - button to save the task. Now that we have created our - task, we can can add this task to the single pre-existing - state (``BoozeAuthDecide``) in our policy. - - .. container:: paragraph - - To edit the ``BoozeAuthDecide`` state in our policy click - on the 'Policies' tab. In the 'Policies' pane, right - click on our ``MyFirstPolicy`` policy and select 'Edit'. - Navigate to the ``BoozeAuthDecide`` state in the 'states' - section at the bottom of the policy definition pane. - - .. container:: imageblock - - .. container:: content - - |Right click to edit a policy| - - .. container:: title - - Figure 20. Edit a Policy - - .. container:: paragraph - - To add our new task ``MorningBoozeCheckAlt1``, scroll - down to the ``BoozeAuthDecide`` state in the 'States' - section. In the 'State Tasks' section for - ``BoozeAuthDecide`` use the 'Add new task' button. Select - our new ``MorningBoozeCheckAlt1`` task, and use the name - of the task as the 'Local Name' for the task. The - ``MorningBoozeCheckAlt1`` task can reuse the same - ``MorningBoozeCheck_Output_Direct`` 'Direct State Output - Mapping' that we used for the ``MorningBoozeCheck`` task. - (Recall that the role of the 'State Output Mapping' is to - select the output event for the state, and select the - next state to be executed. These both remain the same as - before.) - - .. container:: paragraph - - Since our state has more than one task we must define - some logic to determine which task should be used each - time the state is executed. This *task selection logic* - is defined in the state definition. For our - ``BoozeAuthDecide`` state we want the choice of which - task to use to be based on the ``branch_ID`` from which - the ``SALE_INPUT`` event originated. For simplicity sake - let us assume that branches with ``branch_ID`` between - ``0`` and ``999`` should use the ``MorningBoozeCheck`` - task, and the branches with with ``branch_ID`` between - ``1000`` and ``1999`` should use the - ``MorningBoozeCheckAlt1`` task. - - .. container:: paragraph - - This time, for variety, we will author the task selection - logic using the - ```JavaScript`` `__ - scripting language. Sample task selection logic code - (specified in - ```JavaScript`` `__) - is given below. Paste the script text into the 'Task - Selection Logic' box, and use "JAVASCRIPT" as the 'Task - Selection Logic Type / Flavour'. It is necessary to mark - one of the tasks as the 'Default Task' so that the task - selection logic always has a fallback default option in - cases where a particular task cannot be selected. In this - case the ``MorningBoozeCheck`` task can be the default - task. - - .. container:: listingblock - - .. container:: title - - JavaScript code for the ``BoozeAuthDecide`` task - selection logic - - .. container:: content - - .. code:: - - /* - * ============LICENSE_START======================================================= - * Copyright (C) 2016-2018 Ericsson. All rights reserved. - * ================================================================================ - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - * SPDX-License-Identifier: Apache-2.0 - * ============LICENSE_END========================================================= - */ - - - var returnValueType = Java.type("java.lang.Boolean"); - var returnValue = new returnValueType(true); - - executor.logger.info("Task Selection Execution: '"+executor.subject.id+ - "'. Input Event: '"+executor.inFields+"'"); - - branchid = executor.inFields.get("branch_ID"); - taskorig = executor.subject.getTaskKey("MorningBoozeCheck"); - taskalt = executor.subject.getTaskKey("MorningBoozeCheckAlt1"); - taskdef = executor.subject.getDefaultTaskKey(); - - if(branchid >=0 && branchid <1000){ - taskorig.copyTo(executor.selectedTask); - } - else if (branchid >=1000 && branchid <2000){ - taskalt.copyTo(executor.selectedTask); - } - else{ - taskdef.copyTo(executor.selectedTask); - } - - /* - This task selection logic selects task "MorningBoozeCheck" for branches with - 0<=branch_ID<1000 and selects task "MorningBoozeCheckAlt1" for branches with - 1000<=branch_ID<2000. Otherwise the default task is selected. - In this case the default task is also "MorningBoozeCheck" - */ - - .. container:: imageblock - - .. container:: content - - |State definition with 2 Tasks and Task Selection - Logic| - - .. container:: title - - Figure 21. State definition with 2 Tasks and Task - Selection Logic - - .. container:: paragraph - - When complete don’t forget to click the 'Submit' button - at the bottom of 'Policies' pane for our - ``MyFirstPolicy`` policy after updating the - ``BoozeAuthDecide`` state. - - .. container:: paragraph - - Congratulations, you have now completed the second step - towards your first APEX policy. The policy model - containing our new policy can again be validated and - exported from the editor and saved as shown in Step 1. - - .. container:: paragraph - - The exported policy model is then available in the - directory you selected, as - `MyFirstPolicyModel_0.0.1.json `__. - The exported policy can now be loaded into the APEX - Policy Engine, or can be re-loaded and edited by the APEX - Policy Editor. - -Test Policy Step 2 -################## - - .. container:: paragraph - - To start a new APEX Engine you can use the following - configuration. In a full APEX installation you can find - this configuration in - ``$APEX_HOME/examples/config/MyFirstPolicy/2/MyFirstPolicyConfigStdin2StdoutJsonEvent.json``. - Note, this has changed from the configuration file in - Step 1 to enable the ``JAVASCRIPT`` executor for our new - 'Task Selection Logic'. - - .. container:: listingblock - - .. container:: title - - JSON to load and execute *My First Policy*, read input - JSON events from ``stdin``, and emit output events to - ``stdout`` - - .. container:: content - - .. code:: - - { - "engineServiceParameters" : { - "name" : "MyFirstPolicyApexEngine", - "version" : "0.0.1", - "id" : 102, - "instanceCount" : 4, - "deploymentPort" : 12345, - "policyModelFileName" : "examples/models/MyFirstPolicy/2/MyFirstPolicyModel_0.0.1.json", - "engineParameters" : { - "executorParameters" : { - "MVEL" : { - "parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters" - }, - "JAVASCRIPT" : { - "parameterClassName" : "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters" - } - } - } - }, - "eventOutputParameters": { - "FirstProducer": { - "carrierTechnologyParameters" : { - "carrierTechnology" : "FILE", - "parameters" : { - "standardIO" : true - } - }, - "eventProtocolParameters" : { - "eventProtocol" : "JSON" - } - } - }, - "eventInputParameters": { - "FirstConsumer": { - "carrierTechnologyParameters" : { - "carrierTechnology" : "FILE", - "parameters" : { - "standardIO" : true - } - }, - "eventProtocolParameters" : { - "eventProtocol" : "JSON" - } - } - } - } - - .. container:: paragraph - - To test the policy try paste the following events into - the console as the APEX engine executes. Note, all tests - from Step 1 will still work perfectly since none of those - events originate from a branch with ``branch_ID`` between - ``1000`` and ``2000``. The 'Task Selection Logic' will - therefore pick the ``MorningBoozeCheck`` task as - expected, and will therefore give the same results. - - .. table:: Table 14. Inputs and Outputs when testing *My First Policy* - - +----------------------------------------------+------------------------------------------------------------+---------------------------+ - | Input Event (JSON) | Output Event (JSON) | comment | - +==============================================+============================================================+===========================+ - | .. container:: | .. container:: | Request to buy | - | | | alcohol item | - | .. container:: listingblock | .. container:: listingblock | (``item_ID=1249``) | - | | | | - | | | at *08:41:06 | - | | .. container:: content | GMT* on *Monday, | - | .. container:: content | | 02 January | - | | .. code:: | 2017*. | - | | | | - | | { | Sale is not | - | .. code:: | "nameSpace": "com.hyperm", | authorized. Uses | - | | "name": "SALE_AUTH", | the | - | | "version": "0.0.1", | ``MorningBoozeCheck`` | - | { | "source": "", | | - | "nameSpace": "com.hyperm", | "target": "", | task. | - | "name": "SALE_INPUT", | "amount": 1249, | | - | "version": "0.0.1", | "assistant_ID":12, | Note this test | - | "time": 1483346466000, | "authorised": false, | is copied from | - | "sale_ID": 99999992, | "branch_ID": 2, | Step 1 above, | - | "amount": 1249, | "item_ID": 1012, | and demonstrates | - | "item_ID": 1012, | "message": "Sale not authorised by policy ta | that the | - | "quantity": 1, | sk MorningBoozeCheck for time 08:41:06 GMT.| original | - | "assistant_ID": 12, | Alcohol can not be sold between 00:00:00 | ``MorningBoozeCheck`` | - | "branch_ID": 2 | GMT and 11:30:00 GMT", | | - | } | "notes": null, | task is | - | | "quantity": 1, | executed. | - | | "sale_ID": 99999992, | | - | | "time": 1483346466000 | | - | | } | | - +----------------------------------------------+------------------------------------------------------------+---------------------------+ - | .. container:: | .. container:: | Request to buy | - | | | alcohol | - | .. container:: listingblock | .. container:: listingblock | (``item_ID=1047``) | - | | | | - | | | at *10:14:33* on | - | | .. container:: content | *Thursday, 22 | - | .. container:: content | | December 2016*. | - | | .. code:: | | - | | | Sale is not | - | | { | authorized. Uses | - | .. code:: | "nameSpace" : "com.hyperm", | the | - | | "name" : "SALE_AUTH", | ``MorningBoozeCheckAlt1`` | - | | "version" : "0.0.1", | task. | - | { | "source" : "", | | - | | "target" : "", | | - | "nameSpace": "com.hyperm", | "sale_ID" : 99999981, | | - | "name": "SALE_INPUT", | "amount" : 299, | | - | "version": "0.0.1", | "assistant_ID": 1212, | | - | "time": 1482398073000, | "notes" : null, | | - | "sale_ID": 99999981, | "quantity" : 1, | | - | "amount": 299, | "branch_ID" : 1002, | | - | "item_ID": 1047, | "item_ID" : 1047, | | - | "quantity": 1, | "authorised" : false, | | - | "assistant_ID": 1212, | "time" : 1482398073000, | | - | "branch_ID": 1002 | "message" : "Sale not authorised by policy t | | - | } | ask MorningBoozeCheckAlt1 fortime | | - | | 10:14:33 CET. Alcohol can not be sold | | - | | between 00:00:00 CET and 13:00:00 CET or on | | - | | Sunday" | | - | | } | | - +----------------------------------------------+------------------------------------------------------------+---------------------------+ - | .. container:: | .. container:: | Request to buy | - | | | alcohol | - | .. container:: listingblock | .. container:: listingblock | (``item_ID=1443``) | - | | | | - | | | at *17:19:37* on | - | | .. container:: content | *Sunday, 18 | - | .. container:: content | | December 2016*. | - | | .. code:: | | - | | | Sale is not | - | | { | authorized. Uses | - | .. code:: | "nameSpace" : "com.hyperm", | the | - | | | ``MorningBoozeCheckAlt1`` | - | | "name" : "SALE_AUTH", | task. | - | { | | | - | "nameSpace": "com.hyperm", | "version" : "0.0.1", | | - | "name": "SALE_INPUT", | "source" : "", | | - | "version": "0.0.1", | "target" : "", | | - | "time": 1482077977000, | "sale_ID" : 99999982, | | - | "sale_ID": 99999982, | "amount" : 2199, | | - | "amount": 2199, | "assistant_ID" : 94, | | - | "item_ID": 1443, | "notes" : "Buy 3, get 1 free!!", | | - | "quantity": 12, | "quantity" : 12, | | - | "assistant_ID": 94, | "branch_ID" : 1003, | | - | "branch_ID": 1003, | "item_ID" : 1443, | | - | "notes": "Buy 3, get 1 free!!" | "authorised" : false, | | - | } | "time" : 1482077977000, | | - | | "message" : "Sale not authorised by policy t | | - | | ask MorningBoozeCheckAlt1 for | | - | | time 17:19:37 CET. Alcohol c | | - | | an not be sold between 00:00: | | - | | 00 CET and 13:00:00 CET or on | | - | | Sunday" | | - +----------------------------------------------+------------------------------------------------------------+---------------------------+ - | .. container:: | .. container:: | Request to buy | - | | | non-alcoholic | - | .. container:: listingblock | .. container:: listingblock | item | - | | | (``item_ID=5321``) | - | | | | - | | .. container:: content | at *11:13:09* on | - | .. container:: content | | *Monday, 2 | - | | .. code:: | January 2017*. | - | | | | - | | { | Sale is | - | .. code:: | "nameSpace" : "com.hyperm", | authorized. Uses | - | | "name" : "SALE_AUTH", | the | - | { | "version" : "0.0.1", | ``MorningBoozeCheckAlt1`` | - | "nameSpace": "com.hyperm", | "source" : "", | task. | - | "name": "SALE_INPUT", | "target" : "", | | - | "version": "0.0.1", | "sale_ID" : 99999983, | | - | "time": 1483351989000, | "amount" : 699, | | - | "sale_ID": 99999983, | "assistant_ID" : 2323, | | - | "amount": 699, | "notes" : "", | | - | "item_ID": 5321, | "quantity" : 1, | | - | "quantity": 1, | "branch_ID" : 1001, | | - | "assistant_ID": 2323, | "item_ID" : 5321, | | - | "branch_ID": 1001, | "authorised" : true, | | - | "notes": "" | "time" : 1483351989000, | | - | } | "message" : "Sale authorised by policy task | | - | | MorningBoozeCheckAlt1 for time 11:13:09 CET"| | - | | } | | - +----------------------------------------------+------------------------------------------------------------+---------------------------+ - -Policy 2 in CLI Editor -###################### - - .. container:: paragraph - - An equivalent version of the ``MyFirstPolicyModel`` - policy model can again be generated using the APEX CLI - editor. A sample APEX CLI script is shown below: - - .. container:: listingblock - - .. container:: title - - APEX CLI Editor code for Policy 2 - - .. container:: content - - .. code:: - - #------------------------------------------------------------------------------- - # ============LICENSE_START======================================================= - # Copyright (C) 2016-2018 Ericsson. All rights reserved. - # ================================================================================ - # Licensed under the Apache License, Version 2.0 (the "License"); - # you may not use this file except in compliance with the License. - # You may obtain a copy of the License at - # - # http://www.apache.org/licenses/LICENSE-2.0 - # - # Unless required by applicable law or agreed to in writing, software - # distributed under the License is distributed on an "AS IS" BASIS, - # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - # See the License for the specific language governing permissions and - # limitations under the License. - # - # SPDX-License-Identifier: Apache-2.0 - # ============LICENSE_END========================================================= - #------------------------------------------------------------------------------- - - model create name=MyFirstPolicyModel version=0.0.1 uuid=540226fb-55ee-4f0e-a444-983a0494818e description="This is my first Apex Policy Model." - - schema create name=assistant_ID_type version=0.0.1 uuid=36df4c71-9616-4206-8b53-976a5cd4bd87 description="A type for 'assistant_ID' values" flavour=Java schema=java.lang.Long - - schema create name=authorised_type version=0.0.1 uuid=d48b619e-d00d-4008-b884-02d76ea4350b description="A type for 'authorised' values" flavour=Java schema=java.lang.Boolean - - schema create name=branch_ID_type version=0.0.1 uuid=6468845f-4122-4128-8e49-0f52c26078b5 description="A type for 'branch_ID' values" flavour=Java schema=java.lang.Long - - schema create name=item_ID_type version=0.0.1 uuid=4f227ff1-aee0-453a-b6b6-9a4b2e0da932 description="A type for 'item_ID' values" flavour=Java schema=java.lang.Long - - schema create name=message_type version=0.0.1 uuid=ad1431bb-3155-4e73-b5a3-b89bee498749 description="A type for 'message' values" flavour=Java schema=java.lang.String - - schema create name=notes_type version=0.0.1 uuid=eecfde90-896c-4343-8f9c-2603ced94e2d description="A type for 'notes' values" flavour=Java schema=java.lang.String - - schema create name=price_type version=0.0.1 uuid=52c2fc45-fd8c-463c-bd6f-d91b0554aea7 description="A type for 'amount'/'price' values" flavour=Java schema=java.lang.Long - - schema create name=quantity_type version=0.0.1 uuid=ac3d9842-80af-4a98-951c-bd79a431c613 description="A type for 'quantity' values" flavour=Java schema=java.lang.Integer - - schema create name=sale_ID_type version=0.0.1 uuid=cca47d74-7754-4a61-b163-ca31f66b157b description="A type for 'sale_ID' values" flavour=Java schema=java.lang.Long - - schema create name=timestamp_type version=0.0.1 uuid=fd594e88-411d-4a94-b2be-697b3a0d7adf description="A type for 'time' values" flavour=Java schema=java.lang.Long - - task create name=MorningBoozeCheck version=0.0.1 uuid=3351b0f4-cf06-4fa2-8823-edf67bd30223 description=LS - This task checks if the sales request is for an item that contains alcohol. - If the local time is between 00:00:00 and 11:30:00 then the sale is not authorised. Otherwise the sale is authorised. - In this implementation we assume that all items with item_ID values between 1000 and 2000 contain alcohol :-) - LE - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true - task logic create name=MorningBoozeCheck version=0.0.1 logicFlavour=MVEL logic=LS - /* - * ============LICENSE_START======================================================= - * Copyright (C) 2016-2018 Ericsson. All rights reserved. - * ================================================================================ - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - * SPDX-License-Identifier: Apache-2.0 - * ============LICENSE_END========================================================= - */ - import java.util.Date; - import java.util.Calendar; - import java.util.TimeZone; - import java.text.SimpleDateFormat; - - logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'"); - - outFields.put("amount" , inFields.get("amount")); - outFields.put("assistant_ID", inFields.get("assistant_ID")); - outFields.put("notes" , inFields.get("notes")); - outFields.put("quantity" , inFields.get("quantity")); - outFields.put("branch_ID" , inFields.get("branch_ID")); - outFields.put("item_ID" , inFields.get("item_ID")); - outFields.put("time" , inFields.get("time")); - outFields.put("sale_ID" , inFields.get("sale_ID")); - - item_id = inFields.get("item_ID"); - - //The events used later to test this task use GMT timezone! - gmt = TimeZone.getTimeZone("GMT"); - timenow = Calendar.getInstance(gmt); - df = new SimpleDateFormat("HH:mm:ss z"); - df.setTimeZone(gmt); - timenow.setTimeInMillis(inFields.get("time")); - - midnight = timenow.clone(); - midnight.set( - timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), - timenow.get(Calendar.DATE),0,0,0); - eleven30 = timenow.clone(); - eleven30.set( - timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), - timenow.get(Calendar.DATE),11,30,0); - - itemisalcohol = false; - if(item_id != null && item_id >=1000 && item_id < 2000) - itemisalcohol = true; - - if( itemisalcohol - && timenow.after(midnight) && timenow.before(eleven30)){ - outFields.put("authorised", false); - outFields.put("message", "Sale not authorised by policy task "+subject.taskName+ - " for time "+df.format(timenow.getTime())+ - ". Alcohol can not be sold between "+df.format(midnight.getTime())+ - " and "+df.format(eleven30.getTime())); - return true; - } - else{ - outFields.put("authorised", true); - outFields.put("message", "Sale authorised by policy task "+subject.taskName+ - " for time "+df.format(timenow.getTime())); - return true; - } - - /* - This task checks if a sale request is for an item that is an alcoholic drink. - If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not - authorised. Otherwise the sale is authorised. - In this implementation we assume that items with item_ID value between 1000 and - 2000 are all alcoholic drinks :-) - */ - LE - - task create name=MorningBoozeCheckAlt1 version=0.0.1 uuid=bc6d90c9-c902-4686-afd3-925b30e39990 description=LS - This task checks if a sale request is for an item that is an alcoholic drink. - If the local time is between 00:00:00 CET and 13:00:00 CET then the sale is not authorised. - Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised. - In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks - LE - task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true - task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1 - task inputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true - task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1 - task outputfield create name=MorningBoozeCheckAlt1 version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true - task logic create name=MorningBoozeCheckAlt1 version=0.0.1 logicFlavour=MVEL logic=LS - /* - * ============LICENSE_START======================================================= - * Copyright (C) 2016-2018 Ericsson. All rights reserved. - * ================================================================================ - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - * SPDX-License-Identifier: Apache-2.0 - * ============LICENSE_END========================================================= - */ - import java.util.Date; - import java.util.Calendar; - import java.util.TimeZone; - import java.text.SimpleDateFormat; - - logger.info("Task Execution: '"+subject.id+"'. Input Event: '"+inFields+"'"); - - outFields.put("amount" , inFields.get("amount")); - outFields.put("assistant_ID", inFields.get("assistant_ID")); - outFields.put("notes" , inFields.get("notes")); - outFields.put("quantity" , inFields.get("quantity")); - outFields.put("branch_ID" , inFields.get("branch_ID")); - outFields.put("item_ID" , inFields.get("item_ID")); - outFields.put("time" , inFields.get("time")); - outFields.put("sale_ID" , inFields.get("sale_ID")); - - item_id = inFields.get("item_ID"); - - //The events used later to test this task use CET timezone! - cet = TimeZone.getTimeZone("CET"); - timenow = Calendar.getInstance(cet); - df = new SimpleDateFormat("HH:mm:ss z"); - df.setTimeZone(cet); - timenow.setTimeInMillis(inFields.get("time")); - - midnight = timenow.clone(); - midnight.set( - timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), - timenow.get(Calendar.DATE),0,0,0); - onepm = timenow.clone(); - onepm.set( - timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH), - timenow.get(Calendar.DATE),13,0,0); - - itemisalcohol = false; - if(item_id != null && item_id >=1000 && item_id < 2000) - itemisalcohol = true; - - if( itemisalcohol && - ( (timenow.after(midnight) && timenow.before(onepm)) - || - (timenow.get(Calendar.DAY_OF_WEEK) == Calendar.SUNDAY) - )){ - outFields.put("authorised", false); - outFields.put("message", "Sale not authorised by policy task "+subject.taskName+ - " for time "+df.format(timenow.getTime())+ - ". Alcohol can not be sold between "+df.format(midnight.getTime())+ - " and "+df.format(onepm.getTime()) +" or on Sunday"); - return true; - } - else{ - outFields.put("authorised", true); - outFields.put("message", "Sale authorised by policy task "+subject.taskName+ - " for time "+df.format(timenow.getTime())); - return true; - } - - /* - This task checks if a sale request is for an item that is an alcoholic drink. - If the local time is between 00:00:00 CET and 13:00:00 CET then the sale is not authorised. - Also alcohol sales are not allowed on Sundays. Otherwise the sale is authorised. - In this implementation we assume that items with item_ID between 1000 and 2000 are all alcoholic drinks :-) - */ - LE - - event create name=SALE_AUTH version=0.0.1 uuid=c4500941-3f98-4080-a9cc-5b9753ed050b description="An event emitted by the Policy to indicate whether the sale of an item has been authorised" nameSpace=com.hyperm source="APEX" target="POS" - event parameter create name=SALE_AUTH version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=authorised schemaName=authorised_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=message schemaName=message_type schemaVersion=0.0.1 optional=true - event parameter create name=SALE_AUTH version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true - event parameter create name=SALE_AUTH version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_AUTH version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1 - - event create name=SALE_INPUT version=0.0.1 uuid=4f04aa98-e917-4f4a-882a-c75ba5a99374 description="An event raised by the PoS system each time an item is scanned for purchase" nameSpace=com.hyperm source="POS" target="APEX" - event parameter create name=SALE_INPUT version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true - event parameter create name=SALE_INPUT version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1 - event parameter create name=SALE_INPUT version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1 - - - policy create name=MyFirstPolicy version=0.0.1 uuid=6c5e410f-489a-46ff-964e-982ce6e8b6d0 description="This is my first Apex policy. It checks if a sale should be authorised or not." template=FREEFORM firstState=BoozeAuthDecide - policy state create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide triggerName=SALE_INPUT triggerVersion=0.0.1 defaultTaskName=MorningBoozeCheck defaultTaskVersion=0.0.1 - policy state output create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide outputName=MorningBoozeCheck_Output_Direct eventName=SALE_AUTH eventVersion=0.0.1 nextState=NULL - policy state taskref create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide taskLocalName=MorningBoozeCheckAlt1 taskName=MorningBoozeCheckAlt1 taskVersion=0.0.1 outputType=DIRECT outputName=MorningBoozeCheck_Output_Direct - policy state taskref create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide taskLocalName=MorningBoozeCheck taskName=MorningBoozeCheck taskVersion=0.0.1 outputType=DIRECT outputName=MorningBoozeCheck_Output_Direct - policy state selecttasklogic create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide logicFlavour=JAVASCRIPT logic=LS - /* - * ============LICENSE_START======================================================= - * Copyright (C) 2016-2018 Ericsson. All rights reserved. - * ================================================================================ - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. - * - * SPDX-License-Identifier: Apache-2.0 - * ============LICENSE_END========================================================= - */ - - var returnValueType = Java.type("java.lang.Boolean"); - var returnValue = new returnValueType(true); - - executor.logger.info("Task Selection Execution: '"+executor.subject.id+"'. Input Event: '"+executor.inFields+"'"); - - branchid = executor.inFields.get("branch_ID"); - taskorig = executor.subject.getTaskKey("MorningBoozeCheck"); - taskalt = executor.subject.getTaskKey("MorningBoozeCheckAlt1"); - taskdef = executor.subject.getDefaultTaskKey(); - - if(branchid >=0 && branchid <1000){ - taskorig.copyTo(executor.selectedTask); - } - else if (branchid >=1000 && branchid <2000){ - taskalt.copyTo(executor.selectedTask); - } - else{ - taskdef.copyTo(executor.selectedTask); - } - - /* - This task selection logic selects task "MorningBoozeCheck" for branches with 0<=branch_ID<1000 and selects task "MorningBoozeCheckAlt1" for branches with 1000<=branch_ID<2000. Otherwise the default task is selected. In this case the default task is also "MorningBoozeCheck" - */ - LE - -APEX Logging -^^^^^^^^^^^^ - -Introduction to APEX Logging ----------------------------- - - .. container:: paragraph - - All APEX components make extensive use of logging using the - logging façade `SLF4J `__ with the - backend `Logback `__. Both are used - off-the-shelve, so the standard documentation and - configuration apply to APEX logging. For details on how to - work with logback please see the `logback - manual `__. - - .. container:: paragraph - - The APEX applications is the logback configuration file - ``$APEX_HOME/etc/logback.xml`` (Windows: - ``%APEX_HOME%\etc\logback.xml``). The logging backend is set - to no debug, i.e. logs from the logging framework should be - hidden at runtime. - - .. container:: paragraph - - The configurable log levels work as expected: - - .. container:: ulist - - - *error* (or *ERROR*) is used for serious errors in the - APEX runtime engine - - - *warn* (or *WARN*) is used for warnings, which in general - can be ignored but might indicate some deeper problems - - - *info* (or *INFO*) is used to provide generally - interesting messages for startup and policy execution - - - *debug* (or *DEBUG*) provides more details on startup and - policy execution - - - *trace* (or *TRACE*) gives full details on every aspect - of the APEX engine from start to end - - .. container:: paragraph - - The loggers can also be configured as expected. The standard - configuration (after installing APEX) uses log level *info* - on all APEX classes (components). - - .. container:: paragraph - - The applications and scripts in ``$APEX_HOME/bin`` (Windows: - ``%APEX_HOME\bin``) are configured to use the logback - configuration ``$APEX_HOME/etc/logback.xml`` (Windows: - ``%APEX_HOME\etc\logback.xml``). There are multiple ways to - use different logback configurations, for instance: - - .. container:: ulist - - - Maintain multiple configurations in ``etc``, for instance - a ``logback-debug.xml`` for deep debugging and a - ``logback-production.xml`` for APEX in production mode, - then copy the required configuration file to the used - ``logback.xml`` prior starting APEX - - - Edit the scripts in ``bin`` to use a different logback - configuration file (only recommended if you are familiar - with editing bash scripts or windows batch files) - -Standard Logging Configuration ------------------------------- - - .. container:: paragraph - - The standard logging configuration defines a context *APEX*, - which is used in the standard output pattern. The location - for log files is defined in the property ``logDir`` and set - to ``/var/log/onap/policy/apex-pdp``. The standard status - listener is set to *NOP* and the overall logback - configuration is set to no debug. - - .. container:: listingblock - - .. container:: content - - .. code:: - :number-lines: - - - - - Apex - - - ...appenders - ...loggers - - -.. container:: paragraph - - The first appender defined is called ``STDOUT`` for logs to standard - out. - -.. container:: listingblock - - .. container:: content - - .. code:: - :number-lines: - - - - %d %contextName [%t] %level %logger{36} - %msg%n - - - -.. container:: paragraph - - The root level logger then is set to the level *info* using the - standard out appender. - -.. container:: listingblock - - .. container:: content - - .. code:: - :number-lines: - - - - - -.. container:: paragraph - - The second appender is called ``FILE``. It writes logs to a file - ``apex.log``. - -.. container:: listingblock - - .. container:: content - - .. code:: - :number-lines: - - - ${logDir}/apex.log - - %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full} - - - -.. container:: paragraph - - The third appender is called ``CTXT_FILE``. It writes logs to a file - ``apex_ctxt.log``. - -.. container:: listingblock - - .. container:: content - - .. code:: - :number-lines: - - - ${logDir}/apex_ctxt.log - - %d %-5relative [procId=${processId}] [%thread] %-5level %logger{26} - %msg %n %ex{full} - - - -.. container:: paragraph - - The last definitions are for specific loggers. The first logger - captures all standard APEX classes. It is configured for log level - *info* and uses the standard output and file appenders. The second - logger captures APEX context classes responsible for context - monitoring. It is configured for log level *trace* and uses the - context file appender. - -.. container:: listingblock - - .. container:: content - - .. code:: - :number-lines: - - - - - - - - - - - -Adding Logback Status and Debug -------------------------------- - - .. container:: paragraph - - To activate logback status messages change the status listener - from 'NOP' to for instance console. - - .. container:: listingblock - - .. container:: content - - .. code:: - - - - .. container:: paragraph - - To activate all logback debugging, for instance to debug a new - logback configuration, activate the debug attribute in the - configuration. - - .. container:: listingblock - - .. container:: content - - .. code:: - - - ... - - -Logging External Components ---------------------------- - - .. container:: paragraph - - Logback can also be configured to log any other, external - components APEX is using, if they are using the common logging - framework. - - .. container:: paragraph - - For instance, the context component of APEX is using *Infinispan* - and one can add a logger for this external component. The - following example adds a logger for *Infinispan* using the - standard output appender. - - .. container:: listingblock - - .. container:: content - - .. code:: - - - - - - .. container:: paragraph - - Another example is Apache Zookeeper. The following example adds a - logger for Zookeeper using the standard outout appender. - - .. container:: listingblock - - .. container:: content - - .. code:: - - - - - -Configuring loggers for Policy Logic ------------------------------------- - - .. container:: paragraph - - The logging for the logic inside a policy (task logic, task - selection logic, state finalizer logic) can be configured separate - from standard logging. The logger for policy logic is - ``org.onap.policy.apex.executionlogging``. The following example - defines - - .. container:: ulist - - - a new appender for standard out using a very simple pattern - (simply the actual message) - - - a logger for policy logic to standard out using the new - appender and the already described file appender. - - .. container:: listingblock - - .. container:: content - - .. code:: - - - - policy: %msg\n - - - - - - - - - .. container:: paragraph - - It is also possible to use specific logging for parts of policy - logic. The following example defines a logger for task logic. - - .. container:: listingblock - - .. container:: content - - .. code:: - - - - + + + Rolling File Appenders ---------------------- @@ -8398,22 +5975,5 @@ Send Events .. |REST Editor Start Screen| image:: images/install-guide/rest-start.png .. |REST Editor with loaded SampleDomain Policy Model| image:: images/install-guide/rest-loaded.png .. |APEX Configuration Matrix| image:: images/apex-intro/ApexEngineConfig.png -.. |File > New to create a new Policy Model| image:: images/mfp/MyFirstPolicy_P1_newPolicyModel1.png -.. |Create a new Policy Model| image:: images/mfp/MyFirstPolicy_P1_newPolicyModel2.png -.. |Right click to create a new event| image:: images/mfp/MyFirstPolicy_P1_newEvent1.png -.. |Fill in the necessary information for the 'SALE_INPUT' event and click 'Submit'| image:: images/mfp/MyFirstPolicy_P1_newEvent2.png -.. |Right click to create a new Item Schema| image:: images/mfp/MyFirstPolicy_P1_newItemSchema1.png -.. |Create a new Item Schema| image:: images/mfp/MyFirstPolicy_P1_newItemSchema2.png -.. |Add new event parameters to an event| image:: images/mfp/MyFirstPolicy_P1_newEvent3.png -.. |Right click to create a new task| image:: images/mfp/MyFirstPolicy_P1_newTask1.png -.. |Add input and out fields for the task| image:: images/mfp/MyFirstPolicy_P1_newTask2.png -.. |Add task logic the task| image:: images/mfp/MyFirstPolicy_P1_newTask3.png -.. |Create a new policy| image:: images/mfp/MyFirstPolicy_P1_newPolicy1.png -.. |Create a state| image:: images/mfp/MyFirstPolicy_P1_newState1.png -.. |Add a Task and Output Mapping| image:: images/mfp/MyFirstPolicy_P1_newState2.png -.. |Validate the policy model for error using the 'Model' > 'Validate' menu item| image:: images/mfp/MyFirstPolicy_P1_validatePolicyModel.png -.. |Download the completed policy model using the 'File' > 'Download' menu item| image:: images/mfp/MyFirstPolicy_P1_exportPolicyModel1.png -.. |Create a new alternative task MorningBoozeCheckAlt1| image:: images/mfp/MyFirstPolicy_P2_newTask1.png -.. |Right click to edit a policy| image:: images/mfp/MyFirstPolicy_P2_editPolicy1.png -.. |State definition with 2 Tasks and Task Selection Logic| image:: images/mfp/MyFirstPolicy_P2_editState1.png +