- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- apexApps.sh ws-echo -p 8888
-
-Application: Create Event Templates
------------------------------------
-
- .. container:: paragraph
-
- **Status: Experimental**
-
- .. container:: paragraph
-
- This application takes a policy model (JSON or XML encoded)
- and generates templates for events in JSON format. This can
- help when a policy defines rather complex trigger or action
- events or complex events between states. The application can
- produce events for the types: stimuli (policy trigger
- events), internal (events between policy states), and
- response (action events).
-
- +----------------------------------------------------------------+------------------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +================================================================+==================================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexApps.sh tpl-event-json [args] | > %APEX_HOME%\bin\apexApps.bat tpl-event-json [args] |
- +----------------------------------------------------------------+------------------------------------------------------------------+
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- gen-model2event v{release-version} - generates JSON templates for events generated from a policy model
- usage: gen-model2event
- -h,--help prints this help and usage screen
- -m,--model <MODEL-FILE> set the input policy model file
- -t,--type <TYPE> set the event type for generation, one of:
- stimuli (trigger events), response (action
- events), internal (events between states)
- -v,--version prints the application version
-
- .. container:: paragraph
-
- The created templates are not valid events, instead they use
- some markup for values one will need to change to actual
- values. For instance, running the tool with the *Sample
- Domain* policy model as:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- apexApps.sh tpl-event-json -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json -t stimuli
-
- .. container:: paragraph
-
- will produce the following status messages:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- gen-model2event: starting Event generator
- --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json
- --> type: stimuli
-
- .. container:: paragraph
-
- and then run the generator application producing two event
- templates. The first template is called ``Event0000``.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- {
- "name" : "Event0000",
- "nameSpace" : "org.onap.policy.apex.sample.events",
- "version" : "0.0.1",
- "source" : "Outside",
- "target" : "Match",
- "TestTemperature" : ###double: 0.0###,
- "TestTimestamp" : ###long: 0###,
- "TestMatchCase" : ###integer: 0###,
- "TestSlogan" : "###string###"
- }
-
- .. container:: paragraph
-
- The values for the keys are marked with ``#`` and the
- expected type of the value. To create an actual stimuli
- event, all these markers need to be change to actual values,
- for instance:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- {
- "name" : "Event0000",
- "nameSpace" : "org.onap.policy.apex.sample.events",
- "version" : "0.0.1",
- "source" : "Outside",
- "target" : "Match",
- "TestTemperature" : 25,
- "TestTimestamp" : 123456789123456789,
- "TestMatchCase" : 1,
- "TestSlogan" : "Testing the Match Case with Temperature 25"
- }
-
-Application: Convert a Policy Model to CLI Editor Commands
-----------------------------------------------------------
-
- .. container:: paragraph
-
- **Status: Experimental**
-
- .. container:: paragraph
-
- This application takes a policy model (JSON or XML encoded)
- and generates commands for the APEX CLI Editor. This
- effectively reverses a policy specification realized with
- the CLI Editor.
-
- +-------------------------------------------------------------+---------------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +=============================================================+===============================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexApps.sh model-2-cli [args] | > %APEX_HOME%\bin\apexApps.bat model-2-cli [args] |
- +-------------------------------------------------------------+---------------------------------------------------------------+
-
- .. container:: paragraph
-
- The option ``-h`` provides a help screen.
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- usage: gen-model2cli
- -h,--help prints this help and usage screen
- -m,--model <MODEL-FILE> set the input policy model file
- -sv,--skip-validation switch of validation of the input file
- -v,--version prints the application version
-
- .. container:: paragraph
-
- For instance, running the tool with the *Sample Domain*
- policy model as:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- apexApps.sh model-2-cli -m $APEX_HOME/examples/models/SampleDomain/SamplePolicyModelJAVA.json
-
- .. container:: paragraph
-
- will produce the following status messages:
-
- .. container:: listingblock
-
- .. container:: content
-
- .. code::
-
- gen-model2cli: starting CLI generator
- --> model file: examples/models/SampleDomain/SamplePolicyModelJAVA.json
-
- .. container:: paragraph
-
- and then run the generator application producing all CLI
- Editor commands and printing them to standard out.
-
-Application: Websocket Clients (Echo and Console)
--------------------------------------------------
-
- .. container:: paragraph
-
- **Status: Production**
-
- .. container:: paragraph
-
- The application launcher also provides a Websocket echo
- client and a Websocket console client. The echo client
- connects to APEX and prints all events it receives from
- APEX. The console client connects to APEX, reads input from
- the command line, and sends this input as events to APEX.
-
- +------------------------------------------------------------+--------------------------------------------------------------+
- | Unix, Cygwin | Windows |
- +============================================================+==============================================================+
- | .. container:: | .. container:: |
- | | |
- | .. container:: listingblock | .. container:: listingblock |
- | | |
- | .. container:: content | .. container:: content |
- | | |
- | .. code:: | .. code:: |
- | | |
- | # $APEX_HOME/bin/apexApps.sh ws-echo [args] | > %APEX_HOME%\bin\apexApps.bat ws-echo [args] |
- | # $APEX_HOME/bin/apexApps.sh ws-console [args] | > %APEX_HOME%\bin\apexApps.bat ws-console [args] |
- +------------------------------------------------------------+--------------------------------------------------------------+
-
- .. container:: paragraph
-
- The arguments are the same for both applications:
-
- .. container:: ulist
-
- - ``-p`` defines the Websocket port to connect to (defaults
- to ``8887``)
-
- - ``-s`` defines the host on which a Websocket server is
- running (defaults to ``localhost``)
-
- .. container:: paragraph
-
- A discussion on how to use these two applications to build
- an APEX system is detailed HowTo-Websockets.
-
-My First Policy
-^^^^^^^^^^^^^^^
-
-Introduction
-------------
- .. container:: paragraph
-
- Consider a scenario where a supermarket chain called
- *HyperM* controls how it sells items in a policy-based
- manner. Each time an item is processed by *HyperM*'s
- point-of-sale (PoS) system an event is generated and
- published about that item of stock being sold. This event
- can then be used to update stock levels, etc..
-
- .. container:: paragraph
-
- *HyperM* want to extend this approach to allow some checks
- to be performed before the sale can be completed. This can
- be achieved by requesting a policy-controlled decision as
- each item is processed by for sale by each PoS system. The
- decision process is integrated with *HyperM*'s other IT
- systems that manage stock control, sourcing and purchasing,
- personnel systems, etc.
-
- .. container:: paragraph
-
- In this document we will show how APEX and APEX Policies can
- be used to achieve this, starting with a simple policy,
- building up to more complicated policy that demonstrates the
- features of APEX.
-
-Data Models
------------
-
-Sales Input Event
-#################
-
- .. container:: paragraph
-
- Each time a PoS system processes a sales item an event
- with the following format is emitted:
-
- .. table:: Table 1. Sale Input Event
-
- +----------------------+----------------------+-----------------------+
- | Event | Fields | Description |
- +======================+======================+=======================+
- | SALE_INPUT | time, sale_ID, | Event indicating a |
- | | amount, item_ID, | sale of an item is |
- | | quantity, | occurring |
- | | assistant_ID, | |
- | | branch_ID, notes, … | |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- In each ``SALE_INPUT`` event the ``sale_ID`` field is a
- unique ID generated by the PoS system. A timestamp for
- the event is stored in the ``time`` field. The ``amount``
- field refers to the value of the item(s) to be sold (in
- cents). The ``item_ID`` field is a unique identifier for
- each item type, and can be used to retrieve more
- information about the item from *HyperM*'s stock control
- system. The ``quantity`` field refers to the quantity of
- the item to be sold. The ``assistant_ID`` field is a
- unique identifier for the PoS operator, and can be used
- to retrieve more information about the operator from the
- *HyperM*'s personnel system. Since *HyperM* has many
- branches the ``branch_ID`` identifies the shop. The
- ``notes`` field contains arbitrary notes about the sale.
-
-Sales Decision Event
-####################
-
- .. container:: paragraph
-
- After a ``SALE_INPUT`` event is emitted by the PoS system
- *HyperM*'s policy-based controlled sales checking system
- emits a Sale Authorization Event indicating whether the
- sale is authorized or denied. The PoS system can then
- listen for this event before continuing with the sale.
-
- .. table:: Table 2. Sale Authorisation Event
-
- +----------------------+----------------------+-----------------------+
- | Event | Fields | Description |
- +======================+======================+=======================+
- | SALE_AUTH | sale_ID, time, | Event indicating a |
- | | authorized, amount, | sale of an item is |
- | | item_ID, quantity, | authorized or denied |
- | | assistant_ID, | |
- | | branch_ID, notes, | |
- | | message… | |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- In each ``SALE_AUTH`` event the ``sale_ID`` field is
- copied from the ``SALE_INPUT`` event that trigger the
- decision request. The ``SALE_AUTH`` event is also
- timestamped using the ``time`` field, and a field called
- ``authorised`` is set to ``true`` or ``false`` depending
- on whether the sale is authorized or denied. The
- ``message`` field carries an optional message about why a
- sale was not authorized. The other fields from the
- ``SALE_INPUT`` event are also included for completeness.
-
-Stock Control: Items
-####################
-
- .. container:: paragraph
-
- *HyperM* maintains information about each item for sale
- in a database table called ``ITEMS``.
-
- .. table:: Table 3. Items Database
-
- +----------------------+----------------------+-----------------------+
- | Table | Fields | Description |
- +======================+======================+=======================+
- | ITEMS | item_ID, | Database table |
- | | description, | describing each item |
- | | cost_price, barcode, | for sale |
- | | supplier_ID, | |
- | | category, … | |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- The database table ``ITEMS`` has a row for each items
- that *HyperM* sells. Each item is identified by an
- ``item_ID`` value. The ``description`` field stores a
- description of the item. The cost price of the item is
- given in ``cost_price``. The barcode of the item is
- encoded in ``barcode``, while the item supplier is
- identified by ``supplier_ID``. Items may also be
- classified into categories using the ``category`` field.
- Useful categories might include: ``soft drinks``,
- ``alcoholic drinks``, ``cigarettes``, ``knives``,
- ``confectionery``, ``bakery``, ``fruit&vegetables``,
- ``meat``, etc..
-
-Personnel System: Assistants
-############################
-
- .. table:: Table 4. Assistants Database
-
- +----------------------+----------------------+-----------------------+
- | Table | Fields | Description |
- +======================+======================+=======================+
- | ASSISTANTS | assistant_ID, | Database table |
- | | surname, firstname, | describing each |
- | | middlename, age, | *HyperM* sales |
- | | grade, phone_number, | assistant |
- | | … | |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- The database table ``ASSISTANTS`` has a row for each
- sales assistant employed by *HyperM*. Each assistant is
- identified by an ``assistant_ID`` value, with their name
- given in the ``firstname``, ``middlename`` and
- ``surname`` fields. The assistant’s age in years is given
- in ``age``, while their phone number is contained in the
- ``phone_number`` field. The assistant’s grade is encoded
- in ``grade``. Useful values for ``grade`` might include:
- ``trainee``, ``operator``, ``supervisor``, etc..
-
-Locations: Branches
-####################
-
- .. table:: Table 5. Branches Database
-
- +----------------------+----------------------+-----------------------+
- | Table | Fields | Description |
- +======================+======================+=======================+
- | BRANCHES | branch_ID, | Database table |
- | | branch_Name, | describing each |
- | | category, street, | *HyperM* branch |
- | | city, country, | |
- | | postcode, … | |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- *HyperM* operates a number of branches. Each branch is
- described in the ``BRANCHES`` database table. Each branch
- is identified by a ``branch_ID``, with a branch name
- given in ``branch_Name``. The address for the branch is
- encoded in ``street``, ``city``, ``country`` and
- ``postcode``. The branch category is given in the
- ``category`` field. Useful values for ``category`` might
- include: ``Small``, ``Large``, ``Super``, ``Hyper``,
- etc..
-
-Policy Step 1
--------------
-
-Scenario
-#########
- .. container:: paragraph
-
- For the first version of our policy, let’s start with
- something simple. Let us assume that there exists some
- restriction that alcohol products cannot be sold before
- 11:30am. In this section we will go through the necessary
- steps to define a policy that can enforce this for
- *HyperM*.
-
- .. container:: ulist
-
- - Alcohol cannot be sold before 11:30am.
-
-Create the an new empty Policy Model ``MyFirstPolicyModel``
-###########################################################
-
- .. container:: paragraph
-
- Since an organisation like *HyperM* may have many
- policies covering many different domains, policies should
- be grouped into policy sets. In order to edit or deploy a
- policy, or policy set, the definition of the policy(ies)
- and all required events, tasks, states, etc., are grouped
- together into a 'Policy Model'. An organization might
- define many Policy Models, each containing a different
- set of policies.
-
- .. container:: paragraph
-
- So the first step is to create a new empty Policy Model
- called ``MyFirstPolicyModel``. Using the APEX Policy
- Editor, click on the 'File' menus and select 'New'. Then
- define our new policy model called
- ``MyFirstPolicyModel``. Use the 'Generate UUID' button to
- create a new unique ID for the policy model, and fill in
- a description for the policy model. Press the ``Submit``
- button to save your changes.
-
- .. container:: imageblock
-
- .. container:: content
-
- |File > New to create a new Policy Model|
-
- .. container:: title
-
- Figure 4. Create a new Policy Model 1/2
-
- .. container:: imageblock
-
- .. container:: content
-
- |Create a new Policy Model|
-
- .. container:: title
-
- Figure 5. Create a new Policy Model 2/2
-
-Create the input event ``SALE_INPUT`` and the output event ``SALE_AUTH``
-########################################################################
-
- .. container:: paragraph
-
- Using the APEX Policy Editor, click on the 'Events' tab.
- In the 'Events' pane, right click and select 'New':
-
- .. container:: imageblock
-
- .. container:: content
-
- |Right click to create a new event|
-
- .. container:: title
-
- Figure 6. Create a new Event type
-
- .. container:: paragraph
-
- Create a new event type called ``SALE_INPUT``. Use the
- 'Generate UUID' button to create a new unique ID for the
- event type, and fill in a description for the event. Add
- a namespace, e.g. ``com.hyperm``. We can add hard-coded
- strings for the ``Source`` and ``Target``, e.g. ``POS``
- and ``APEX``. At this stage we will not add any parameter
- fields, we will leave this until later. Use the
- ``Submit`` button to create the event.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Fill in the necessary information for the
- 'SALE_INPUT' event and click 'Submit'|
-
- .. container:: title
-
- Figure 7. Populate the ``SALE_INPUT`` event
-
- .. container:: paragraph
-
- Repeat the same steps for a new event type called
- ``SALE_AUTH``. Just use ``APEX`` as source and ``POS`` as
- target, since this is the output event coming from APEX
- going to the sales point.
-
- .. container:: paragraph
-
- Before we can add parameter fields to an event we must
- first define APEX Context Item Schemas that can be used
- by those fields.
-
- .. container:: paragraph
-
- To create new item schemas, click on the 'Context Item
- Schemas' tab. In that 'Context Item Schemas' pane, right
- click and select 'Create new ContextSchema'.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Right click to create a new Item Schema|
-
- .. container:: title
-
- Figure 8. Create new Data Types
-
- .. container:: paragraph
-
- Create item schemas with the following characteristics,
- each with its own unique UUID:
-
- .. table:: Table 6. Item Schemas
-
- +-------------------+-----------------+-----------------+----------------------+
- | Name | Schema Flavour | Schema | Description |
- | | | Definition | |
- +===================+=================+=================+======================+
- | timestamp_type | Java | java.lang.Long | A type for |
- | | | | ``time`` values |
- +-------------------+-----------------+-----------------+----------------------+
- | sale_ID_type | Java | java.lang.Long | A type for |
- | | | | ``sale_ID`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | price_type | Java | java.lang.Long | A type for |
- | | | | ``amount``/``price`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | item_ID_type | Java | java.lang.Long | A type for |
- | | | | ``item_ID`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | assistant_ID_type | Java | java.lang.Long | A type for |
- | | | | ``assistant_ID`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | quantity_type | Java | java.lang.Integ | A type for |
- | | | er | ``quantity`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | branch_ID_type | Java | java.lang.Long | A type for |
- | | | | ``branch_ID`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | notes_type | Java | java.lang.Strin | A type for |
- | | | g | ``notes`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | authorised_type | Java | java.lang.Boole | A type for |
- | | | an | ``authorised`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
- | message_type | Java | java.lang.Strin | A type for |
- | | | g | ``message`` |
- | | | | values |
- +-------------------+-----------------+-----------------+----------------------+
-
- .. container:: imageblock
-
- .. container:: content
-
- |Create a new Item Schema|
-
- .. container:: title
-
- Figure 9. Create new Item Schemas
-
- .. container:: paragraph
-
- The item schemas can now be seen on the 'Context Item
- Schemas' tab, and can be updated at any time by
- right-clicking on the item schemas on the 'Context Item
- Schemas' tab. Now we can go back to the event definitions
- for ``SALE_INPUT`` and ``SALE_AUTH`` and add some
- parameter fields.
-
- .. tip
-
- .. container:: title
-
- Field Schema types
-
- .. container:: paragraph
-
- APEX natively supports schema definitions in ``Java`` and ``Avro``.
-
- .. container:: paragraph
-
- ``Java`` schema definitions are simply the name of a Java Class. There are some restrictions:
-
- .. container:: ulist
-
- - the class must be instantiatable, i.e. not an Java interface or abstract class
-
- - primitive types are not supported, i.e. use ``java.lang.Integer`` instead of ``int``, etc.
-
- - it must be possible to find the class, i.e. the class must be contained in the Java classpath.
-
- .. container:: paragraph
-
- ``Avro`` schema definitions can be any valid `Avro <https://avro.apache.org/docs/current/spec.html>`__
- schema. For events using fields defined with ``Avro`` schemas, any incoming event containing that field must
- contain a value that conforms to the Avro schema.
-
- .. container:: paragraph
-
- Click on the 'Events' tab, then right click the
- ``SALE_INPUT`` row and select 'Edit Event
- :literal:`SALE_INPUT’. To add a new event parameter use the 'Add Event Parameter' button at the bottom of the screen. For the `SALE_INPUT`
- event add the following event parameters:
-
- .. table:: Table 7. Event Parameter Fields for the ``SALE_INPUT`` Event
-
- +----------------------+----------------------+-----------------------+
- | Parameter Name | Parameter Type | Optional |
- +======================+======================+=======================+
- | time | timestamp_type | no |
- +----------------------+----------------------+-----------------------+
- | sale_ID | sale_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | amount | price_type | no |
- +----------------------+----------------------+-----------------------+
- | item_ID | item_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | quantity | quantity_type | no |
- +----------------------+----------------------+-----------------------+
- | assistant_ID | assistant_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | branch_ID | branch_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | notes | notes_type | *yes* |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- Remember to click the 'Submit' button at the bottom of
- the event definition pane.
-
- .. tip::
- Optional Fields in APEX Events
- Parameter fields can be *optional* in events. If a parameter is not marked as *optional* then by default it
- is *mandatory*, so it must appear in any input event passed to APEX. If an *optional* field is not set
- for an output event then value will be set to ``null``.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Add new event parameters to an event|
-
- .. container:: title
-
- Figure 10. Add typed parameter fields to an event
-
- .. container:: paragraph
-
- Select the ``SALE_AUTH`` event and add the following
- event parameters:
-
- .. table:: Table 8. Event Parameter Fields for the ``SALE_AUTH`` Event
-
- +----------------------+----------------------+-----------------------+
- | Parameter Name | Parameter Type | no |
- +======================+======================+=======================+
- | sale_ID | sale_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | time | timestamp_type | no |
- +----------------------+----------------------+-----------------------+
- | authorised | authorised_type | no |
- +----------------------+----------------------+-----------------------+
- | message | message_type | *yes* |
- +----------------------+----------------------+-----------------------+
- | amount | price_type | no |
- +----------------------+----------------------+-----------------------+
- | item_ID | item_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | assistant_ID | assistant_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | quantity | quantity_type | no |
- +----------------------+----------------------+-----------------------+
- | branch_ID | branch_ID_type | no |
- +----------------------+----------------------+-----------------------+
- | notes | notes_type | *yes* |
- +----------------------+----------------------+-----------------------+
-
- .. container:: paragraph
-
- Remember to click the 'Submit' button at the bottom of
- the event definition pane.
-
- .. container:: paragraph
-
- The events for our policy are now defined.
-
-Create a new Policy and add the *"No Booze before 11:30"* check
-###############################################################
-
- .. container:: paragraph
-
- APEX policies are defined using a state-machine model.
- Each policy comprises one or more *states* that can be
- individually executed. Where there is more than one
- *state* the states are chained together to form a
- `Directed Acyclic Graph
- (DAG) <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__
- of states. A *state* is triggered by passing it a single
- input (or 'trigger') event and once executed each state
- then emits an output event. For each *state* the logic
- for the *state* is embedded in one or more *tasks*. Each
- *task* contains specific *task logic* that is executed by
- the APEX execution environment each time the *task* is
- invoked. Where there is more than one *task* in a *state*
- then the *state* also defines some *task selection logic*
- to select an appropriate task each time the *state* is
- executed.
-
- .. container:: paragraph
-
- Therefore, to create a new policy we must first define
- one or more tasks.
-
- .. container:: paragraph
-
- To create a new Task click on the 'Tasks' tab. In the
- 'Tasks' pane, right click and select 'Create new Task'.
- Create a new Task called ``MorningBoozeCheck``. Use the
- 'Generate UUID' button to create a new unique ID for the
- task, and fill in a description for the task.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Right click to create a new task|
-
- .. container:: title
-
- Figure 11. Create a new Task
-
- .. container:: paragraph
-
- Tasks are configured with a set of *input fields* and a
- set of *output fields*. To add new input/output fields
- for a task use the 'Add Task Input Field' and 'Add Task
- Output Field' button. The list of input and out fields to
- add for the ``MorningBoozeCheck`` task are given below.
- The input fields are drawn from the parameters in the
- state’s input event, and the task’s output fields are
- used to populate the state’s output event. The task’s
- input and output fields must be a subset of the event
- parameters defined for the input and output events for
- any state that uses that task. (You may have noticed that
- the input and output fields for the ``MorningBoozeCheck``
- task have the exact same names and reuse the item schemas
- that we used for the parameters in the ``SALE_INPUT`` and
- ``SALE_AUTH`` events respectively).
-
- .. table:: Table 9. Input fields for ``MorningBoozeCheck`` task
-
- +-----------------------------------+-----------------------------------+
- | Parameter Name | Parameter Type |
- +===================================+===================================+
- | time | timestamp_type |
- +-----------------------------------+-----------------------------------+
- | sale_ID | sale_ID_type |
- +-----------------------------------+-----------------------------------+
- | amount | price_type |
- +-----------------------------------+-----------------------------------+
- | item_ID | item_ID_type |
- +-----------------------------------+-----------------------------------+
- | quantity | quantity_type |
- +-----------------------------------+-----------------------------------+
- | assistant_ID | assistant_ID_type |
- +-----------------------------------+-----------------------------------+
- | branch_ID | branch_ID_type |
- +-----------------------------------+-----------------------------------+
- | notes | notes_type |
- +-----------------------------------+-----------------------------------+
-
- .. table:: Table 10. Output fields for ``MorningBoozeCheck`` task
-
- +-----------------------------------+-----------------------------------+
- | Parameter Name | Parameter Type |
- +===================================+===================================+
- | sale_ID | sale_ID_type |
- +-----------------------------------+-----------------------------------+
- | time | timestamp_type |
- +-----------------------------------+-----------------------------------+
- | authorised | authorised_type |
- +-----------------------------------+-----------------------------------+
- | message | message_type |
- +-----------------------------------+-----------------------------------+
- | amount | price_type |
- +-----------------------------------+-----------------------------------+
- | item_ID | item_ID_type |
- +-----------------------------------+-----------------------------------+
- | assistant_ID | assistant_ID_type |
- +-----------------------------------+-----------------------------------+
- | quantity | quantity_type |
- +-----------------------------------+-----------------------------------+
- | branch_ID | branch_ID_type |
- +-----------------------------------+-----------------------------------+
- | notes | notes_type |
- +-----------------------------------+-----------------------------------+
-
- .. container:: imageblock
-
- .. container:: content
-
- |Add input and out fields for the task|
-
- .. container:: title
-
- Figure 12. Add input and out fields for the Task
-
- .. container:: paragraph
-
- Each task must include some 'Task Logic' that implements
- the behaviour for the task. Task logic can be defined in
- a number of different ways using a choice of languages.
- For this task we will author the logic using the
- Java-like scripting language called
- ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__.
-
- .. container:: paragraph
-
- For simplicity use the following code for the task logic.
- Paste the script text into the 'Task Logic' box, and use
- "MVEL" as the 'Task Logic Type / Flavour'.
-
- .. container:: paragraph
-
- This logic assumes that all items with ``item_ID``
- between 1000 and 2000 contain alcohol, which is not very
- realistic, but we will see a better approach for this
- later. It also uses the standard ``Java`` time utilities
- to check if the current time is between ``00:00:00 GMT``
- and ``11:30:00 GMT``. For a detailed guide to how to
- write your own logic in
- ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__,
- ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__ or one
- of the other supported languages please refer to APEX
- Programmers Guide.
-
- .. container:: listingblock
-
- .. container:: title
-
- MVEL code for the ``MorningBoozeCheck`` task
-
- .. container:: content
-
- .. code::
-
- /*
- * ============LICENSE_START=======================================================
- * Copyright (C) 2016-2018 Ericsson. All rights reserved.
- * ================================================================================
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * SPDX-License-Identifier: Apache-2.0
- * ============LICENSE_END=========================================================
- */
- import java.util.Date;
- import java.util.Calendar;
- import java.util.TimeZone;
- import java.text.SimpleDateFormat;
-
- logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'");
-
- outFields.put("amount" , inFields.get("amount"));
- outFields.put("assistant_ID", inFields.get("assistant_ID"));
- outFields.put("notes" , inFields.get("notes"));
- outFields.put("quantity" , inFields.get("quantity"));
- outFields.put("branch_ID" , inFields.get("branch_ID"));
- outFields.put("item_ID" , inFields.get("item_ID"));
- outFields.put("time" , inFields.get("time"));
- outFields.put("sale_ID" , inFields.get("sale_ID"));
-
- item_id = inFields.get("item_ID");
-
- //The events used later to test this task use GMT timezone!
- gmt = TimeZone.getTimeZone("GMT");
- timenow = Calendar.getInstance(gmt);
- df = new SimpleDateFormat("HH:mm:ss z");
- df.setTimeZone(gmt);
- timenow.setTimeInMillis(inFields.get("time"));
-
- midnight = timenow.clone();
- midnight.set(
- timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
- timenow.get(Calendar.DATE),0,0,0);
- eleven30 = timenow.clone();
- eleven30.set(
- timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
- timenow.get(Calendar.DATE),11,30,0);
-
- itemisalcohol = false;
- if(item_id != null && item_id >=1000 && item_id < 2000)
- itemisalcohol = true;
-
- if( itemisalcohol
- && timenow.after(midnight) && timenow.before(eleven30)){
- outFields.put("authorised", false);
- outFields.put("message", "Sale not authorised by policy task "+subject.taskName+
- " for time "+df.format(timenow.getTime())+
- ". Alcohol can not be sold between "+df.format(midnight.getTime())+
- " and "+df.format(eleven30.getTime()));
- return true;
- }
- else{
- outFields.put("authorised", true);
- outFields.put("message", "Sale authorised by policy task "+subject.taskName+
- " for time "+df.format(timenow.getTime()));
- return true;
- }
-
- /*
- This task checks if a sale request is for an item that is an alcoholic drink.
- If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not
- authorised. Otherwise the sale is authorised.
- In this implementation we assume that items with item_ID value between 1000 and
- 2000 are all alcoholic drinks :-)
- */
-
- .. container:: imageblock
-
- .. container:: content
-
- |Add task logic the task|
-
- .. container:: title
-
- Figure 13. Add Task Logic the Task
-
- .. container:: paragraph
-
- An alternative version of the same logic is available in
- JavaScript. Just use "JAVASCRIPT" as the 'Task Logic Type
- / Flavour' instead.
-
- .. container:: listingblock
-
- .. container:: title
-
- Javascript alternative for the ``MorningBoozeCheck``
- task
-
- .. container:: content
-
- .. code::
-
- /*
- * ============LICENSE_START=======================================================
- * Copyright (C) 2016-2018 Ericsson. All rights reserved.
- * ================================================================================
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * SPDX-License-Identifier: Apache-2.0
- * ============LICENSE_END=========================================================
- */
-
- var returnValueType = Java.type("java.lang.Boolean");
- var returnValue = new returnValueType(true);
-
- // Load compatibility script for imports etc
- load("nashorn:mozilla_compat.js");
- importPackage(java.text);
- importClass(java.text.SimpleDateFormat);
-
- executor.logger.info("Task Execution: '"+executor.subject.id+"'. Input Fields: '"+executor.inFields+"'");
-
- executor.outFields.put("amount" , executor.inFields.get("amount"));
- executor.outFields.put("assistant_ID", executor.inFields.get("assistant_ID"));
- executor.outFields.put("notes" , executor.inFields.get("notes"));
- executor.outFields.put("quantity" , executor.inFields.get("quantity"));
- executor.outFields.put("branch_ID" , executor.inFields.get("branch_ID"));
- executor.outFields.put("item_ID" , executor.inFields.get("item_ID"));
- executor.outFields.put("time" , executor.inFields.get("time"));
- executor.outFields.put("sale_ID" , executor.inFields.get("sale_ID"));
-
- item_id = executor.inFields.get("item_ID");
-
- //All times in this script are in GMT/UTC since the policy and events assume time is in GMT.
- var timenow_gmt = new Date(Number(executor.inFields.get("time")));
-
- var midnight_gmt = new Date(Number(executor.inFields.get("time")));
- midnight_gmt.setUTCHours(0,0,0,0);
-
- var eleven30_gmt = new Date(Number(executor.inFields.get("time")));
- eleven30_gmt.setUTCHours(11,30,0,0);
-
- var timeformatter = new java.text.SimpleDateFormat("HH:mm:ss z");
-
- var itemisalcohol = false;
- if(item_id != null && item_id >=1000 && item_id < 2000)
- itemisalcohol = true;
-
- if( itemisalcohol
- && timenow_gmt.getTime() >= midnight_gmt.getTime()
- && timenow_gmt.getTime() < eleven30_gmt.getTime()) {
-
- executor.outFields.put("authorised", false);
- executor.outFields.put("message", "Sale not authorised by policy task " +
- executor.subject.taskName+ " for time " + timeformatter.format(timenow_gmt.getTime()) +
- ". Alcohol can not be sold between " + timeformatter.format(midnight_gmt.getTime()) +
- " and " + timeformatter.format(eleven30_gmt.getTime()));
- }
- else{
- executor.outFields.put("authorised", true);
- executor.outFields.put("message", "Sale authorised by policy task " +
- executor.subject.taskName + " for time "+timeformatter.format(timenow_gmt.getTime()));
- }
-
- /*
- This task checks if a sale request is for an item that is an alcoholic drink.
- If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not
- authorised. Otherwise the sale is authorised.
- In this implementation we assume that items with item_ID value between 1000 and
- 2000 are all alcoholic drinks :-)
- */
-
- .. container:: paragraph
-
- The task definition is now complete so click the 'Submit'
- button to save the task. The task can now be seen on the
- 'Tasks' tab, and can be updated at any time by
- right-clicking on the task on the 'Task' tab. Now that we
- have created our task, we can can create a policy that
- uses that task.
-
- .. container:: paragraph
-
- To create a new Policy click on the 'Policies' tab. In
- the 'Policies' pane, right click and select 'Create new
- Policy':
-
- .. container:: paragraph
-
- Create a new Policy called ``MyFirstPolicy``. Use the
- 'Generate UUID' button to create a new unique ID for the
- policy, and fill in a description for the policy. Use
- 'FREEFORM' as the 'Policy Flavour'.
-
- .. container:: paragraph
-
- Each policy must have at least one state. Since this is
- 'freeform' policy we can add as many states as we wish.
- Let’s start with one state. Add a new state called
- ``BoozeAuthDecide`` to this ``MyFirstPolicy`` policy
- using the 'Add new State' button after filling in the
- name of our new state.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Create a new policy|
-
- .. container:: title
-
- Figure 14. Create a new Policy
-
- .. container:: paragraph
-
- Each state must uses one input event type. For this new
- state select the ``SALE_INPUT`` event as the input event.
-
- .. container:: paragraph
-
- Each policy must define a 'First State' and a 'Policy
- Trigger Event'. The 'Policy Trigger Event' is the input
- event for the policy as a whole. This event is then
- passed to the first state in the chain of states in the
- policy, therefore the 'Policy Trigger Event' will be the
- input event for the first state. Each policy can only
- have one 'First State'. For our ``MyFirstPolicy`` policy,
- select ``BoozeAuthDecide`` as the 'First State'. This
- will automatically select ``SALE_INPUT`` as the 'Policy
- Trigger Event' for our policy.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Create a state|
-
- .. container:: title
-
- Figure 15. Create a new State
-
- .. container:: paragraph
-
- In this case we will create a reference the pre-existing
- ``MorningBoozeCheck`` task that we defined above using
- the 'Add New Task' button. Select the
- ``MorningBoozeCheck`` task, and use the name of the task
- as the 'Local Name' for the task.
-
- .. container:: paragraph
-
- in the case where a state references more than one task,
- a 'Default Task' must be selected for the state and some
- logic ('Task Selection Logic') must be specified to
- select the appropriate task at execution time. Since our
- new state ``BoozeAuthDecide`` only has one task the
- default task is automatically selected and no 'Task
- Selection Logic' is required.
-
- .. note::
- .. container:: title
-
- State Output Mappings
-
- .. container:: paragraph
-
- In a 'Policy' 'State' a 'State Output Mapping' has 3 roles:
- 1) Select which 'State' should be executed next, 2) Select
- the type of the state’s 'Outgoing Event', and 3)
- Populate the state’s 'Outgoing Event'. This is how states are
- chained together to form a (`Directed Acyclic Graph
- (DAG) <https://en.wikipedia.org/wiki/Directed_acyclic_graph>`__ )
- of states. The final state(s) of a policy are those that do
- not select any 'next' state. Since a 'State' can only
- accept a single type of event, the type of the event emitted
- by a previous 'State' must be match the incoming event type
- of the next 'State'. This is also how the last state(s) in
- a policy can emit events of different types. The 'State
- Output Mapping' is also responsible for taking the
- fields that are output by the task executed in the state and
- populating the state’s output event before it is emitted.
-
- .. container:: paragraph
-
- Each 'Task' referenced in 'State' must have a defined
- 'Output Mapping' to take the output of the task, select an
- 'Outgoing Event' type for the state, populate the state’s
- outgoing event, and then select the next state to be
- executed (if any).
-
- .. container:: paragraph
-
- There are 2 basic types of output mappings:
-
- .. container:: olist arabic
-
- #. **Direct Output Mappings** have a single value for
- 'Next State' and a single value for 'State Output
- Event'. The outgoing event for the state is
- automatically created, any outgoing event parameters
- that were present in the incoming event are copied
- into the outgoing event, then any task output fields
- that have the same name and type as parameters in the
- outgoing event are automatically copied into
- the outgoing event.
-
- #. **Logic-based State Output Mappings / Finalizers**
- have some logic defined that dynamically selects
- and creates the 'State Outgoing Event', manages
- the population of the outgoing event parameters
- (perhaps changing or adding to the outputs from the
- task), and then dynamically selects the next state to
- be executed (if any).
-
- .. container:: paragraph
-
- Each task reference must also have an associated 'Output
- State Mapping' so we need an 'Output State Mapping' for
- the ``BoozeAuthDecide`` state to use when the
- ``MorningBoozeCheck`` task is executed. The simplest type
- of output mapping is a 'Direct Output Mapping'.
-
- .. container:: paragraph
-
- Create a new 'Direct Output Mapping' for the state called
- ``MorningBoozeCheck_Output_Direct`` using the 'Add New
- Direct State Output Mapping' button. Select ``SALE_AUTH``
- as the output event and select ``None`` for the next
- state value. We can then select this output mapping for
- use when the the ``MorningBoozeCheck`` task is executed.
- Since there is only state, and only one task for that
- state, this output mapping ensures that the
- ``BoozeAuthDecide`` state is the only state executed and
- the state (and the policy) can only emit events of type
- ``SALE_AUTH``. (You may remember that the output fields
- for the ``MorningBoozeCheck`` task have the exact same
- names and reuse the item schemas that we used for the
- parameters in ``SALE_AUTH`` event. The
- ``MorningBoozeCheck_Output_Direct`` direct output mapping
- can now automatically copy the values from the
- ``MorningBoozeCheck`` task directly into outgoing
- ``SALE_AUTH`` events.)
-
- .. container:: imageblock
-
- .. container:: content
-
- |Add a Task and Output Mapping|
-
- .. container:: title
-
- Figure 16. Add a Task and Output Mapping
-
- .. container:: paragraph
-
- Click the 'Submit' button to complete the definition of
- our ``MyFirstPolicy`` policy. The policy
- ``MyFirstPolicy`` can now be seen in the list of policies
- on the 'Policies' tab, and can be updated at any time by
- right-clicking on the policy on the 'Policies' tab.
-
- .. container:: paragraph
-
- The ``MyFirstPolicyModel``, including our
- ``MyFirstPolicy`` policy can now be checked for errors.
- Click on the 'Model' menu and select 'Validate'. The
- model should validate without any 'Warning' or 'Error'
- messages. If you see any 'Error' or 'Warning' messages,
- carefully read the message as a hint to find where you
- might have made a mistake when defining some aspect of
- your policy model.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Validate the policy model for error using the 'Model'
- > 'Validate' menu item|
-
- .. container:: title
-
- Figure 17. Validate a Policy Model
-
- .. container:: paragraph
-
- Congratulations, you have now completed your first APEX
- policy. The policy model containing our new policy can
- now be exported from the editor and saved. Click on the
- 'File' menu and select 'Download' to save the policy
- model in JSON format. The exported policy model is then
- available in the directory you selected, for instance
- ``$APEX_HOME/examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json``.
- The exported policy can now be loaded into the APEX
- Policy Engine, or can be re-loaded and edited by the APEX
- Policy Editor.
-
- .. container:: imageblock
-
- .. container:: content
-
- |Download the completed policy model using the 'File'
- > 'Download' menu item|
-
- .. container:: title
-
- Figure 18. Export a Policy Model
-
-Test Policy Step 1
-##################
-
- .. container:: paragraph
-
- To start a new APEX Engine you can use the following
- configuration. In a full APEX installation you can find
- this configuration in
- ``$APEX_HOME/examples/config/MyFirstPolicy/1/MyFirstPolicyConfigStdin2StdoutJsonEvent.json``.
- This configuration expects incoming events to be in
- ``JSON`` format and to be passed into the APEX Engine
- from ``stdin``, and result events will be printed in
- ``JSON`` format to ``stdout``. This configuration loads
- the policy model stored in the file
- 'MyFirstPolicyModel_0.0.1.json' as exported from the APEX
- Editor. Note, you may need to edit this file to provide
- the full path to wherever you stored the exported policy
- model file.
-
- .. container:: listingblock
-
- .. container:: title
-
- JSON to load and execute *My First Policy*, read input
- JSON events from ``stdin``, and emit output events to
- ``stdout``
-
- .. container:: content
-
- .. code::
-
- {
- "engineServiceParameters" : {
- "name" : "MyFirstPolicyApexEngine",
- "version" : "0.0.1",
- "id" : 101,
- "instanceCount" : 4,
- "deploymentPort" : 12345,
- "policyModelFileName" : "examples/models/MyFirstPolicy/1/MyFirstPolicyModel_0.0.1.json",
- "engineParameters" : {
- "executorParameters" : {
- "MVEL" : {
- "parameterClassName" : "org.onap.policy.apex.plugins.executor.mvel.MVELExecutorParameters"
- },
- "JAVASCRIPT" : {
- "parameterClassName" : "org.onap.policy.apex.plugins.executor.javascript.JavascriptExecutorParameters"
- }
- }
- }
- },
- "eventOutputParameters": {
- "FirstProducer": {
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "FILE",
- "parameters" : {
- "standardIO" : true
- }
- },
- "eventProtocolParameters" : {
- "eventProtocol" : "JSON"
- }
- }
- },
- "eventInputParameters": {
- "FirstConsumer": {
- "carrierTechnologyParameters" : {
- "carrierTechnology" : "FILE",
- "parameters" : {
- "standardIO" : true
- }
- },
- "eventProtocolParameters" : {
- "eventProtocol" : "JSON"
- }
- }
- }
- }
-
- .. container:: paragraph
-
- To test the policy try paste the following events into
- the console as the APEX engine executes:
-
- .. table:: Table 11. Inputs and Outputs when testing *My First Policy*
-
- +------------------------------------------+-------------------------------------------+-----------+
- | Input Event (JSON) | Output Event (JSON) | comment |
- +==========================================+===========================================+===========+
- | .. container:: | .. container:: | Request |
- | | | to buy a |
- | .. container:: listingblock | .. container:: listingblock | non-alcoh |
- | | | olic |
- | | .. container:: content | item |
- | .. container:: content | | (``item_I |
- | | .. code:: | D=5123``) |
- | | | at |
- | .. code:: | { | *10:13:09 |
- | | "name": "SALE_AUTH", | * |
- | | | on |
- | { | "version": "0.0.1", | *Tuesday, |
- | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | 10 |
- | "name" : "SALE_INPUT", | "source": "", | January |
- | "version": "0.0.1", | "target": "", | 2017*. |
- | "time" : 1483351989000, | "amount": 299, | Sale is |
- | "sale_ID": 99999991, | "assistant_ID": 23, | authorize |
- | "amount": 299, | "authorised": true, | d. |
- | "item_ID": 5123, | "branch_ID": 1, | |
- | "quantity": 1, | "item_ID": 5123, | |
- | "assistant_ID": 23, | "message": "Sale authorised | |
- | "branch_ID": 1, | by policy task MorningBo | |
- | "notes": "Special Offer!!" | ozeCheck for time 10:13:09 | |
- | } | GMT", | |
- | | "notes": "Special Offer!!", | |
- | | "quantity": 1, | |
- | | "sale_ID": 99999991, | |
- | | "time": 1483351989000 | |
- | | } | |
- | | | |
- | | | |
- | | | |
- +------------------------------------------+-------------------------------------------+-----------+
- | .. container:: | .. container:: | Request |
- | | | to buy |
- | .. container:: listingblock | .. container:: listingblock | alcohol |
- | | | item |
- | .. container:: content | .. container:: content | (``item_I |
- | | | D=1249``) |
- | .. code:: | .. code:: | at |
- | | | *08:41:06 |
- | { | { | * |
- | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | on |
- | "name": "SALE_INPUT", | "name": "SALE_AUTH", | *Monday, |
- | "version": "0.0.1", | "source": "", | 02 |
- | "time": 1483346466000, | "target": "", | January |
- | "sale_ID": 99999992, | "amount": 1249, | 2017*. |
- | "version": "0.0.1", | "assistant_ID": 12, | |
- | "amount": 1249, | "authorised": false, | Sale is |
- | "item_ID": 1012, | "branch_ID": 2, | not |
- | "quantity": 1, | "item_ID": 1012, | authorize |
- | "assistant_ID": 12, | "message": "Sale not | d. |
- | "branch_ID": 2 | authorised by policy task | |
- | } | MorningBoozeCheck for time | |
- | | 08:41:06 GMT. Alcohol can | |
- | | not be sold between | |
- | | 00:00:00 GMT and 11:30:00 | |
- | | GMT", | |
- | | "notes": null, | |
- | | "quantity": 1, | |
- | | "sale_ID": 99999992, | |
- | | "time": 1483346466000 | |
- | | } | |
- +------------------------------------------+-------------------------------------------+-----------+
- | .. container:: | .. container:: | Request |
- | | | to buy |
- | .. container:: listingblock | .. container:: listingblock | alcohol |
- | | | (``item_I |
- | | .. container:: content | D=1943``) |
- | .. container:: content | | at |
- | | .. code:: | *20:17:13 |
- | | | * |
- | .. code:: | { | on |
- | | "name": "SALE_AUTH", | *Tuesday, |
- | { | "version": "0.0.1", | 20 |
- | "nameSpace": "com.hyperm", | "nameSpace": "com.hyperm", | December |
- | "name" : "SALE_INPUT", | "source": "", | 2016*. |
- | "version": "0.0.1", | "target": "", | |
- | "time" : 1482265033000, | "amount": 4799, | Sale is |
- | "sale_ID": 99999993, | "assistant_ID": 9, | authorize |
- | "amount": 4799, | "authorised": true, | d. |
- | "item_ID": 1943, | "branch_ID": 3, | |
- | "quantity": 2, | "item_ID": 1943, | |
- | "assistant_ID": 9, | "message": "Sale authorised | |
- | "branch_ID": 3 | by policy task MorningBo | |
- | } | ozeCheck for time 20:17:13 | |
- | | GMT", | |
- | | "notes": null, | |
- | | "quantity": 2, | |
- | | "sale_ID": 99999993, | |
- | | "time": 1482265033000 | |
- | | } | |
- +------------------------------------------+-------------------------------------------+-----------+
-
-4.3.6. Policy 1 in CLI Editor
-#############################
-
- .. container:: paragraph
-
- An equivalent version of the ``MyFirstPolicyModel``
- policy model can again be generated using the APEX CLI
- editor. A sample APEX CLI script is shown below:
-
- .. container:: listingblock
-
- .. container:: title
-
- APEX CLI Editor code for Policy 1
-
- .. container:: content
-
- .. code::
-
- #-------------------------------------------------------------------------------
- # ============LICENSE_START=======================================================
- # Copyright (C) 2016-2018 Ericsson. All rights reserved.
- # ================================================================================
- # Licensed under the Apache License, Version 2.0 (the "License");
- # you may not use this file except in compliance with the License.
- # You may obtain a copy of the License at
- #
- # http://www.apache.org/licenses/LICENSE-2.0
- #
- # Unless required by applicable law or agreed to in writing, software
- # distributed under the License is distributed on an "AS IS" BASIS,
- # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- # See the License for the specific language governing permissions and
- # limitations under the License.
- #
- # SPDX-License-Identifier: Apache-2.0
- # ============LICENSE_END=========================================================
- #-------------------------------------------------------------------------------
-
- model create name=MyFirstPolicyModel version=0.0.1 uuid=540226fb-55ee-4f0e-a444-983a0494818e description="This is my first Apex Policy Model."
-
- schema create name=assistant_ID_type version=0.0.1 uuid=36df4c71-9616-4206-8b53-976a5cd4bd87 description="A type for 'assistant_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=authorised_type version=0.0.1 uuid=d48b619e-d00d-4008-b884-02d76ea4350b description="A type for 'authorised' values" flavour=Java schema=java.lang.Boolean
-
- schema create name=branch_ID_type version=0.0.1 uuid=6468845f-4122-4128-8e49-0f52c26078b5 description="A type for 'branch_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=item_ID_type version=0.0.1 uuid=4f227ff1-aee0-453a-b6b6-9a4b2e0da932 description="A type for 'item_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=message_type version=0.0.1 uuid=ad1431bb-3155-4e73-b5a3-b89bee498749 description="A type for 'message' values" flavour=Java schema=java.lang.String
-
- schema create name=notes_type version=0.0.1 uuid=eecfde90-896c-4343-8f9c-2603ced94e2d description="A type for 'notes' values" flavour=Java schema=java.lang.String
-
- schema create name=price_type version=0.0.1 uuid=52c2fc45-fd8c-463c-bd6f-d91b0554aea7 description="A type for 'amount'/'price' values" flavour=Java schema=java.lang.Long
-
- schema create name=quantity_type version=0.0.1 uuid=ac3d9842-80af-4a98-951c-bd79a431c613 description="A type for 'quantity' values" flavour=Java schema=java.lang.Integer
-
- schema create name=sale_ID_type version=0.0.1 uuid=cca47d74-7754-4a61-b163-ca31f66b157b description="A type for 'sale_ID' values" flavour=Java schema=java.lang.Long
-
- schema create name=timestamp_type version=0.0.1 uuid=fd594e88-411d-4a94-b2be-697b3a0d7adf description="A type for 'time' values" flavour=Java schema=java.lang.Long
-
- task create name=MorningBoozeCheck version=0.0.1 uuid=3351b0f4-cf06-4fa2-8823-edf67bd30223 description=LS
- This task checks if the sales request is for an item that contains alcohol.
- If the local time is between 00:00:00 and 11:30:00 then the sale is not authorised. Otherwise the sale is authorised.
- In this implementation we assume that all items with item_ID values between 1000 and 2000 contain alcohol :-)
- LE
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- task inputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=amount schemaName=price_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=quantity schemaName=quantity_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=authorised schemaName=authorised_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=time schemaName=timestamp_type schemaVersion=0.0.1
- task outputfield create name=MorningBoozeCheck version=0.0.1 fieldName=message schemaName=message_type schemaVersion=0.0.1 optional=true
- task logic create name=MorningBoozeCheck version=0.0.1 logicFlavour=MVEL logic=LS
- /*
- * ============LICENSE_START=======================================================
- * Copyright (C) 2016-2018 Ericsson. All rights reserved.
- * ================================================================================
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- *
- * SPDX-License-Identifier: Apache-2.0
- * ============LICENSE_END=========================================================
- */
- import java.util.Date;
- import java.util.Calendar;
- import java.util.TimeZone;
- import java.text.SimpleDateFormat;
-
- logger.info("Task Execution: '"+subject.id+"'. Input Fields: '"+inFields+"'");
-
- outFields.put("amount" , inFields.get("amount"));
- outFields.put("assistant_ID", inFields.get("assistant_ID"));
- outFields.put("notes" , inFields.get("notes"));
- outFields.put("quantity" , inFields.get("quantity"));
- outFields.put("branch_ID" , inFields.get("branch_ID"));
- outFields.put("item_ID" , inFields.get("item_ID"));
- outFields.put("time" , inFields.get("time"));
- outFields.put("sale_ID" , inFields.get("sale_ID"));
-
- item_id = inFields.get("item_ID");
-
- //The events used later to test this task use GMT timezone!
- gmt = TimeZone.getTimeZone("GMT");
- timenow = Calendar.getInstance(gmt);
- df = new SimpleDateFormat("HH:mm:ss z");
- df.setTimeZone(gmt);
- timenow.setTimeInMillis(inFields.get("time"));
-
- midnight = timenow.clone();
- midnight.set(
- timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
- timenow.get(Calendar.DATE),0,0,0);
- eleven30 = timenow.clone();
- eleven30.set(
- timenow.get(Calendar.YEAR),timenow.get(Calendar.MONTH),
- timenow.get(Calendar.DATE),11,30,0);
-
- itemisalcohol = false;
- if(item_id != null && item_id >=1000 && item_id < 2000)
- itemisalcohol = true;
-
- if( itemisalcohol
- && timenow.after(midnight) && timenow.before(eleven30)){
- outFields.put("authorised", false);
- outFields.put("message", "Sale not authorised by policy task "+subject.taskName+
- " for time "+df.format(timenow.getTime())+
- ". Alcohol can not be sold between "+df.format(midnight.getTime())+
- " and "+df.format(eleven30.getTime()));
- return true;
- }
- else{
- outFields.put("authorised", true);
- outFields.put("message", "Sale authorised by policy task "+subject.taskName+
- " for time "+df.format(timenow.getTime()));
- return true;
- }
-
- /*
- This task checks if a sale request is for an item that is an alcoholic drink.
- If the local time is between 00:00:00 GMT and 11:30:00 GMT then the sale is not
- authorised. Otherwise the sale is authorised.
- In this implementation we assume that items with item_ID value between 1000 and
- 2000 are all alcoholic drinks :-)
- */
- LE
-
- event create name=SALE_AUTH version=0.0.1 uuid=c4500941-3f98-4080-a9cc-5b9753ed050b description="An event emitted by the Policy to indicate whether the sale of an item has been authorised" nameSpace=com.hyperm source="APEX" target="POS"
- event parameter create name=SALE_AUTH version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=authorised schemaName=authorised_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=message schemaName=message_type schemaVersion=0.0.1 optional=true
- event parameter create name=SALE_AUTH version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- event parameter create name=SALE_AUTH version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_AUTH version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1
-
- event create name=SALE_INPUT version=0.0.1 uuid=4f04aa98-e917-4f4a-882a-c75ba5a99374 description="An event raised by the PoS system each time an item is scanned for purchase" nameSpace=com.hyperm source="POS" target="APEX"
- event parameter create name=SALE_INPUT version=0.0.1 parName=amount schemaName=price_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=assistant_ID schemaName=assistant_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=branch_ID schemaName=branch_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=item_ID schemaName=item_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=notes schemaName=notes_type schemaVersion=0.0.1 optional=true
- event parameter create name=SALE_INPUT version=0.0.1 parName=quantity schemaName=quantity_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=sale_ID schemaName=sale_ID_type schemaVersion=0.0.1
- event parameter create name=SALE_INPUT version=0.0.1 parName=time schemaName=timestamp_type schemaVersion=0.0.1
-
-
- policy create name=MyFirstPolicy version=0.0.1 uuid=6c5e410f-489a-46ff-964e-982ce6e8b6d0 description="This is my first Apex policy. It checks if a sale should be authorised or not." template=FREEFORM firstState=BoozeAuthDecide
- policy state create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide triggerName=SALE_INPUT triggerVersion=0.0.1 defaultTaskName=MorningBoozeCheck defaultTaskVersion=0.0.1
- policy state output create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide outputName=MorningBoozeCheck_Output_Direct eventName=SALE_AUTH eventVersion=0.0.1 nextState=NULL
- policy state taskref create name=MyFirstPolicy version=0.0.1 stateName=BoozeAuthDecide taskLocalName=MorningBoozeCheck taskName=MorningBoozeCheck taskVersion=0.0.1 outputType=DIRECT outputName=MorningBoozeCheck_Output_Direct
-
-Policy Step 2
--------------
-
-Scenario
-#########
- .. container:: paragraph
-
- *HyperM* have just opened a new branch in a different
- country, but that country has different rules about when
- alcohol can be sold! In this section we will go through
- the necessary steps to extend our policy to enforce this
- for *HyperM*.
-
- .. container:: ulist
-
- - In some branches alcohol cannot be sold before 1pm,
- and not at all on Sundays.
-
- .. container:: paragraph
-
- Although there are a number of ways to accomplish this
- the easiest approach for us is to define another task and
- then select which task is appropriate at runtime
- depending on the branch identifier in the incoming event.
-
-Extend the Policy with the new Scenario
-#######################################
-
- .. container:: paragraph
-
- To create a new Task click on the 'Tasks' tab. In the
- 'Tasks' pane, right click and select 'Create new Task':
-
- .. container:: paragraph
-
- Create a new Task called ``MorningBoozeCheckAlt1``. Use
- the 'Generate UUID' button to create a new unique ID for
- the task, and fill in a description for the task. Select
- the same input and output fields that we used earlier
- when we defined the ``MorningBoozeCheck`` task earlier.
-
- .. table:: Table 12. Input fields for ``MorningBoozeCheckAlt1`` task
-
- +-----------------------------------+-----------------------------------+
- | Parameter Name | Parameter Type |
- +===================================+===================================+
- | time | timestamp_type |
- +-----------------------------------+-----------------------------------+
- | sale_ID | sale_ID_type |
- +-----------------------------------+-----------------------------------+
- | amount | price_type |
- +-----------------------------------+-----------------------------------+
- | item_ID | item_ID_type |
- +-----------------------------------+-----------------------------------+
- | quantity | quantity_type |
- +-----------------------------------+-----------------------------------+
- | assistant_ID | assistant_ID_type |
- +-----------------------------------+-----------------------------------+
- | branch_ID | branch_ID_type |
- +-----------------------------------+-----------------------------------+
- | notes | notes_type |
- +-----------------------------------+-----------------------------------+