aboutsummaryrefslogtreecommitdiffstats
path: root/docs/apex/APEX-Policy-Guide.rst
blob: a9dad1c661b2577e2750ac119691d7cb93c2d83e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
 .. http://creativecommons.org/licenses/by/4.0

#################
APEX Policy Guide
#################


.. contents::
    :depth: 5

******************
APEX Policy Matrix
******************

.. container:: paragraph

  APEX offers a lot of flexibility for defining, deploying, and executing policies. Based on a theoretic model, it
  supports virtually any policy model and supports translation of legacy policies into the APEX execution format.
  However, the most important aspect for using APEX is to decide what policy is needed, what underlying policy concepts
  should be used, and how the decision logic should be realized. Once these aspects are decided, APEX can be used to
  execute the policies. If the policy evolves, say from a simple decision table to a fully adaptable policy, only the
  policy definition requires change. APEX supports all of that.

.. container:: paragraph

  The figure below shows a (non-exhaustive) matrix, which will help to decide what policy is required to solve your
  problem. Read the matrix from left to right choosing one cell in each column.

.. container:: imageblock

  .. container:: content

    |APEX Policy Matrix|

  .. container:: title

    Figure 1. APEX Policy Matrix

.. container:: paragraph

  The policy can support one of a number of stimuli with an associated purpose/model of the policy, for instance:

.. container:: ulist

  -  Configuration, i.e. what should happen. An example is an event that states an intended network configuration
     and the policy should provide the detailed actions for it. The policy can be realized for instance as an
     obligation policy, a promise or an intent.

  -  Report, i.e. something did happen. An example is an event about an error or fault and the policy needs to
     repair that problem. The policy would usually be an obligation, utility function, or goal policy.

  -  Monitoring, i.e. something does happen. An example is a notification about certain network conditions, to
     which the policy might (or might not) react. The policy will mitigate the monitored events or permit (deny)
     related actions as an obligation or authorization.

  -  Analysis, i.e. why did something happen. An example is an analytic component sends insights of a situation
     requiring a policy to act on it. The policy can solve the problem, escalate it, or delegate it as a refrain or
     delegation policy.

  -  Prediction, i.e. what will happen next. An example are events that a policy uses to predict a future network
     condition. The policy can prevent or enforce the prediction as an adaptive policy, a utility function, or a goal.

  -  Feedback, i.e. why did something happen or not happen. Similar to analysis, but here the feedback will be in
     the input event and the policy needs to something with that information. Feedback can be related to history or
     experience, for instance a previous policy execution. The policy needs to be context-aware or be a meta-policy.

.. container:: paragraph

  Once the purpose of the policy is decided, the next step is to look into what context information the policy will
  require to do its job. This can range from very simple to a lot of different information, for instance:

.. container:: ulist

  -  No context, nothing but a trigger event, e.g. a string or a number, is required

  -  Event context, the incoming event provides all information (more than a string or number) for the policy

  -  Policy context (read only), the policy has access to additional information related to its class but cannot
     change/alter them

  -  Policy context (read and write), the policy has access to additional information related to its class and can
     alter this information (for instance to record historic information)

  -  Global context (read only), the policy has access to additional information of any kind but cannot
     change/alter them

  -  Global context (read and write), the policy the policy has access to additional information of any kind and
     can alter this information (for instance to record historic information)

.. container:: paragraph

  The next step is to decide how the policy should do its job, i.e. what flavor it has, how many states are needed,
  and how many tasks. There are many possible combinations, for instance:

.. container:: ulist

  -  Simple / God: a simple policy with 1 state and 1 task, which is doing everything for the decision-making. This
     is the ideal policy for simple situation, e.g. deciding on configuration parameters or simple access control.

  -  Simple sequence: a simple policy with a number of states each having a single task. This is a very good policy
     for simple decision-making with different steps. For instance, a classic action policy (ECA) would have 3 states
     (E, C, and A) with some logic (1 task) in each state.

  -  Simple selective: a policy with 1 state but more than one task. Here, the appropriate task (and it’s logic)
     will be selected at execution time. This policy is very good for dealing with similar (or the same) situation in
     different contexts. For instance, the tasks can be related to available external software, or to current work load
     on the compute node, or to time of day.

  -  Selective: any number of states having any number of tasks (usually more than 1 task). This is a combination
     of the two policies above, for instance an ECA policy with more than one task in E, C, and A.

  -  Classic directed: a policy with more than one state, each having one task, but a non-sequential execution.
     This means that the sequence of the states is not pre-defined in the policy (as would be for all cases above) but
     calculated at runtime. This can be good to realize decision trees based on contextual information.

  -  Super Adaptive: using the full potential of the APEX policy model, states and tasks and state execution are
     fully flexible and calculated at runtime (per policy execution). This policy is very close to a general
     programming system (with only a few limitations), but can solve very hard problems.

.. container:: paragraph

  The final step is to select a response that the policy creates. Possible responses have been discussed in the
  literature for a very long time. A few examples are:

.. container:: ulist

  -  Obligation (deontic for what should happen)

  -  Authorization (e.g. for rule-based or other access control or security systems)

  -  Intent (instead of providing detailed actions the response is an intent statement and a further system
     processes that)

  -  Delegation (hand the problem over to someone else, possibly with some information or instructions)

  -  Fail / Error (the policy has encountered a problem, and reports it)

  -  Feedback (why did the policy make a certain decision)

*****************
APEX Policy Model
*****************

.. container:: paragraph

  The APEX policy model is shown in UML notation in the figure below. A policy model can be stored in JSON or XML
  format in a file or can be held in a database. The APEX editor creates and modifies APEX policy models. APEX
  deployment deploys policy models, and a policy model is loaded into APEX engines so that the engines can run the
  policies in the policy model.

.. container:: paragraph

  The figure shows four different views of the policy model:

.. container:: ulist

  -  The general model view shows the main parts of a policy: state, state output, event, and task. A task can also
     have parameters. Data types can be defined on a per-model basis using either standard atomic types (such as
     character, string, numbers) or complex types from a policy domain.

  -  The logic model view emphasizes how decision-making logic is injected into a policy. There are essentially
     three different types of logic: task logic (for decision making in a task), task selection logic (to select a task
     if more than one is defined in a state), and state finalizer logic (to compute the final output event of a state
     and select an appropriate next state from the policy model).

  -  The context model view shows how context is injected into a policy. States collect all context from their
     tasks. A task can define what context it requires for the decision making, i.e. what context the task logic will
     process. Context itself is a collection of items (individual context information) with data types. Context can be
     templated.

  -  The event and field model view shows the events in the policy model. Tasks define what information they
     consume (input) and produce (output). This information is modeled as fields, essentially a key/type tuple in the
     model and a key/type/value triple at execution. Events then are collection of fields.

.. container:: imageblock

  .. container:: content

    |APEX Policy Model for Execution|

  .. container:: title

    Figure 2. APEX Policy Model for Execution

Concepts and Keys
=================

.. container:: paragraph

  Each element of the policy model is called a *concept*. Each *concept* is a subclass of the abstract *Concept*
  class, as shown in the next figure. Every concept implements the following abstract methods:

.. container:: imageblock

  .. container:: content

    |Concepts and Keys|

  .. container:: title

    Figure 3. Concepts and Keys

.. container:: ulist

  -  ``getKey()`` - gets the unique key for this concept instance in the system

  -  ``validate()`` - validates the structure of this concept, its sub-concepts and its relationships

  -  ``clean()`` - carries out housekeeping on the concept such as trimming strings, remove any hanging references

  -  ``clone()`` - creates a deep copy of an instance of this concept

  -  ``equals()`` - checks if two instances of this concept are equal

  -  ``toString()`` - returns a string representation of the concept

  -  ``hashCode()`` - returns a hash code for the concept

  -  ``copyTo()`` - carries out a deep copy of one instance of the concept to another instance, overwriting the
     target fields.

.. container:: paragraph

 All concepts must have a *key*, which uniquely identifies a concept instance. The *key* of a subclass of an *Concept*
 must either be an ``ArtifactKey`` or an ``ReferenceKey``. Concepts that have a stand-alone independent existence such
 as *Policy*, *Task*, and *Event* must have an ``ArtifctKey`` key. Concepts that are contained in other concepts, that
 do not exist as stand-alone concepts must have an ``ReferenceKey`` key. Examples of such concepts are *State* and
 *EventParameter*.

.. container:: paragraph

 An ``ArticactKey`` has two fields; the *Name* of the concept it is the key for and the concept’s *Version*. A
 concept’s name must be unique in a given PolicyModel. A concept version is represented using the well known
 *major.minor.path* scheme as used in semantic versioning.

.. container:: paragraph

  A ``ReferenceKey`` has three fields. The *UserKeyName* and *UserKeyVersion* fields identify the ``ArtifactKey`` of
  the concept in which the concept keyed by the ``ReferenceKey`` is contained. The *LocalName* field identifies the
  contained concept instance. The *LocalName* must be unique in the concepts of a given type contained by a parent.

.. container:: paragraph

  For example, a policy called ``SalesPolicy`` with a Version of ``1.12.4`` has a state called ``Decide``. The
  ``Decide`` state is linked to the ``SalesPolicy`` with a ``ReferenceKey`` with fields *UserKeyName* of
  ``SalesPolicy``, *UserKeyVersion* of ``1.12.4``, and *LocalName* of ``Decide``. There must not be another state
  called ``Decide`` in the policy ``SalesPolicy``. However, there may well be a state called ``Decide`` in some other
  policy called ``PurchasingPolicy``.

.. container:: paragraph

  Each concept in the model is also a JPA
  (`Java Persistence API <https://en.wikipedia.org/wiki/Java_Persistence_API>`__) Entity. This means that every concept
  can be individually persisted or the entire model can be persisted en-bloc to any persistence mechanism using an JPA
  framework such as `Hibernate <http://hibernate.org/>`__ or `EclipseLink <http://www.eclipse.org/eclipselink/>`__.

Concept: PolicyModel
====================

.. container:: paragraph

  The *PolicyModel* concept is a container that holds the definition of a set of policies and their associated events,
  context maps, and tasks. A *PolicyModel* is implemented as four maps for policies, events, context maps, and tasks.
  Each map is indexed by the key of the policy, event, context map, or task. Any non-empty policy model must have at
  least one entry in its policy, event, and task map because all policies must have at least one input and output event
  and must execute at least one task.

.. container:: paragraph

  A *PolicyModel* concept is keyed with an ``ArtifactKey key``. Because a *PolicyModel* is an ``AxConcept``, calling
  the ``validate()`` method on a policy model validates the concepts, structure, and relationships of the entire policy
  model.

Concept: DataType
=================

.. container:: paragraph

  Data types are tightly controlled in APEX in order to provide a very high degree of consistency in policies and to
  facilitate tracking of changes to context as policies execute. All context is modeled as a *DataType* concept. Each
  DataType concept instance is keyed with an ``ArtifactKey`` key. The DataType field identifies the Java class of
  objects that is used to represent concept instances that use this data type. All context has a *DataType*; incoming
  and outgoing context is represented by *EventField* concepts and all other context is represented by *ContextItem*
  concepts.

Concept: Event
==============

.. container:: paragraph

  An *Event* defines the structure of a message that passes into or out of an APEX engine or that passes between two
  states in an APEX engine. APEX supports message reception and sending in many formats and all messages are translated
  into an *Event* prior to processing by an APEX engine. Event concepts are keyed with an ``ArtifactKey`` key. The
  parameters of an event are held as a map of *EventField* concept instances with each parameter indexed by the
  *LocalName* of its ``ReferenceKey``. An *Event* has three fields:

.. container:: ulist

  -  The *NameSpace* identifies the domain of application of the event

  -  The *Source* of the event identifies the system that emitted the event

  -  The *Target* of the event identifies the system that the event was sent to

.. container:: paragraph

  A *PolicyModel* contains a map of all the events known to a given policy model. Although an empty model may have no
  events in its event map, any sane policy model must have at least one *Event* defined.

Concept: EventField
===================

.. container:: paragraph

  The incoming context and outgoing context of an event are the fields of the event. Each field representing a single
  piece of incoming or outgoing context. Each field of an *Event* is represented by an instance of the *EventField*
  concept. Each *EventField* concept instance in an event is keyed with a ``ReferenceKey`` key, which references the
  event. The *LocalName* field of the ``ReferenceKey`` holds the name of the field A reference to a *DataType* concept
  defines the data type that values of this parameter have at run time.

Concept: ContextMap
===================

.. container:: paragraph

  The set of context that is available for use by the policies of a *PolicyModel* is defined as *ContextMap* concept
  instances. The *PolicyModel* holds a map of all the *ContextMap* definitions. A *ContextMap* is itself a container
  for a group of related context items, each of which is represented by a *ContextItem* concept instance. *ContextMap*
  concepts are keyed with an ``ArtifactKey`` key. A developer can use the APEX Policy Editor to create context maps for
  their application domain.

.. container:: paragraph

  A *ContextMap* uses a map to hold the context items. The ContextItem concept instances in the map are indexed by the
  *LocalName* of their ``ReferenceKey``.

.. container:: paragraph

  The *ContextMapType* field of a *ContextMap* defines the type of a context map. The type can have either of two
  values:

.. container:: ulist

 -  A *BAG* context map is a context map with fixed content. Each possible context item in the context map is
    defined at design time and is held in the *ContextMap* context instance as *ContextItem* concept definitions and
    only the values of the context items in the context map can be changed at run time. The context items in a *BAG*
    context map have mixed types and distinct *ContextItem* concept instances of the same type can be defined. A *BAG*
    context map is convenient for defining a group of context items that are diverse but are related by domain, such as
    the characteristics of a device. A fully defined *BAG* context map has a fully populated *ContextItem* map but its
    *ContextItemTemplate* reference is not defined.

  -  A *SAMETYPE* context map is used to represent a group of *ContextItem* instances of the same type. Unlike a
     *BAG* context map, the *ContextItem* concept instances of a *SAMETYPE* context map can be added, modified, and
     deleted at runtime. All *ContextItem* concept instances in a *SAMETYPE* context map must be of the same type, and
     that context item is defined as a single *ContextItemTemplate* concept instances at design time. At run time, the
     *ContextItemTemplate* definition is used to create new *ContextItem* concept instances for the context map on
     demand. A fully defined *SAMETYPE context map has an empty ContextItem map and its ContextItemTemplate\_*
     reference is defined.

.. container:: paragraph

  The *Scope* of a *ContextMap* defines the range of applicability of a context map in APEX. The following scopes of
  applicability are defined:

.. container:: ulist

  -  *EPHEMERAL* scope means that the context map is owned, used, and modified by a single application but the
     context map only exists while that application is running

  -  *APPLICATION* scope specifies that the context map is owned, used, and modified by a single application, the
     context map is persistent

  -  *GLOBAL* scope specifies that the context map is globally owned and is used and modified by any application,
     the context map is persistent

  -  *EXTERNAL* scope specifies that the context map is owned by an external system and may be used in a read-only
     manner by any application, the context map is persistent

.. container:: paragraph

  A much more sophisticated scoping mechanism for context maps is envisaged for Apex in future work. In such a
  mechanism, the scope of a context map would work somewhat like the way roles work in security authentication systems.

Concept: ContextItem
====================

.. container:: paragraph

  Each piece of context in a *ContextMap* is represented by an instance of the *ContextItem* concept. Each
  *ContextItem* concept instance in a context map keyed with a ``ReferenceKey`` key, which references the context map
  of the context item. The *LocalName* field of the ``ReferenceKey`` holds the name of the context item in the context
  map A reference to a *DataType* concept defines the data type that values of this context item have at run time. The
  *WritableFlag* indicates if the context item is read only or read-write at run time.

Concept: ContextItemTemplate
============================

.. container:: paragraph

  In a *SAMETYPE* *ContextMap*, the *ContextItemTemplate* definition provides a template for the *ContextItem*
  instances that will be created on the context map at run time. Each *ContextItem* concept instance in the context map
  is created using the *ContextItemTemplate* template. It is keyed with a ``ReferenceKey`` key, which references the
  context map of the context item. The *LocalName* field of the ``ReferenceKey``, supplied by the creator of the
  context item at run time, holds the name of the context item in the context map. A reference to a *DataType* concept
  defines the data type that values of this context item have at run time. The *WritableFlag* indicates if the context
  item is read only or read-write at run time.

Concept: Task
=============

.. container:: paragraph

  The smallest unit of logic in a policy is a *Task*. A task encapsulates a single atomic unit of logic, and is
  designed to be a single indivisible unit of execution. A task may be invoked by a single policy or by many policies.
  A task has a single trigger event, which is sent to the task when it is invoked. Tasks emit one or more outgoing
  events, which carry the result of the task execution. Tasks may use or modify context as they execute.

.. container:: paragraph

  The Task concept definition captures the definition of an APEX task. Task concepts are keyed with an ``ArtifactKey``
  key. The Trigger of the task is a reference to the *Event* concept that triggers the task. The *OutgoingEvents* of a
  task are a set of references to *Event* concepts that may be emitted by the task.

.. container:: paragraph

  All tasks have logic, some code that is programmed to execute the work of the task. The *Logic* concept of the task
  holds the definition of that logic.

.. container:: paragraph

  The *Task* definition holds a set of *ContextItem* and *ContextItemTemplate* context items that the task is allow to
  access, as defined by the task developer at design time. The type of access (read-only or read write) that a task has
  is determined by the *WritableFlag* flag on the individual context item definitions. At run time, a task may only
  access the context items specified in its context item set, the APEX engine makes only the context items in the task
  context item set is available to the task.

.. container:: paragraph

  A task can be configured with startup parameters. The set of parameters that can be configured on a task are defined
  as a set of *TaskParameter* concept definitions.

Concept: TaskParameter
======================

.. container:: paragraph

  Each configuration parameter of a task are represented as a *Taskparameter* concept keyed with a ``ReferenceKey``
  key, which references the task. The *LocalName* field of the ``ReferenceKey`` holds the name of the parameter. The
  *DefaultValue* field defines the default value that the task parameter is set to. The value of *TaskParameter*
  instances can be overridden at deployment time by specifying their values in the configuration information passed to
  APEX engines.

.. container:: paragraph

  The *taskParameters* field is specified under *engineParameters* in the ApexConfig. It can contain one or more task
  parameters, where each item can contain the parameter key, value as well as the taskId to which it is associated. If
  the taskId is not specified, then the parameters are added to all tasks.

Concept: Logic
==============

.. container:: paragraph

  The *Logic* concept instance holds the actual programmed task logic for a task defined in a *Task* concept or the
  programmed task selection logic for a state defined in a *State* concept. It is keyed with a ``ReferenceKey`` key,
  which references the task or state that owns the logic. The *LocalName* field of the Logic concept is the name of the
  logic.

.. container:: paragraph

  The *LogicCode* field of a Logic concept definition is a string that holds the program code that is to be executed
  at run time. The *LogicType* field defines the language of the code. The standard values are the logic languages
  supported by APEX: `JAVASCRIPT <https://en.wikipedia.org/wiki/JavaScript>`__,
  `JAVA <https://www.oracle.com/java/>`__,
  `JYTHON <http://www.jython.org/>`__, `JRUBY <http://jruby.org/>`__, or
  `MVEL <https://en.wikibooks.org/wiki/Transwiki:MVEL_Language_Guide>`__.

.. container:: paragraph

  The APEX engine uses the *LogicType* field value to decide which language interpreter to use for a task and then
  sends the logic defined in the *LogicCode* field to that interpreter.

Concept: Policy
===============

.. container:: paragraph

  The *Policy* concept defines a policy in APEX. The definition is rather straightforward. A policy is made up of a
  set of states with the flavor of the policy determining the structure of the policy states and the first state
  defining what state in the policy executes first. *Policy* concepts are keyed with an ``ArtifactKey`` key.

.. container:: paragraph

  The *PolicyFlavour* of a *Policy* concept specifies the structure that will be used for the states in the policy. A
  number of commonly used policy patterns are supported as APEX policy flavors. The standard policy flavors are:

.. container:: ulist

  -  The *MEDA* flavor supports policies written to the
     `MEDA policy pattern https://ieeexplore.ieee.org/document/7367357`
     and require a sequence of four states: namely *Match*, *Establish*, *Decide* and *Act*.

  -  The *OODA* flavor supports policies written to the
     `OODA loop pattern <https://en.wikipedia.org/wiki/OODA_loop>`__ and require a sequence of four states: namely
     *Observe*, *Orient*, *Decide* and *Act*.

  -  The *ECA* flavor supports policies written to the
     `ECA active rule pattern <https://en.wikipedia.org/wiki/Event_condition_action>`__ and require a sequence of three
     states: namely *Event*, *Condition* and *Action*

  -  The *XACML* flavor supports policies written in `XACML <https://en.wikipedia.org/wiki/XACML>`__ and require a
     single state: namely *XACML*

  -  The *FREEFORM* flavor supports policies written in an arbitrary style. A user can define a *FREEFORM* policy
     as an arbitrarily long chain of states.

.. container:: paragraph

  The *FirstState* field of a *Policy* definition is the starting point for execution of a policy. Therefore, the
  trigger event of the state referenced in the *FirstState* field is also the trigger event for the entire policy.

Concept: State
==============

.. container:: paragraph

  The *State* concept represents a phase or a stage in a policy, with a policy being composed of a series of states.
  Each state has at least one but may have many tasks and, on each run of execution, a state executes one and only one
  of its tasks. If a state has more than one task, then its task selection logic is used to select which task to
  execute. Task selection logic is programmable logic provided by the state designer. That logic can use incoming,
  policy, global, and external context to select which task best accomplishes the purpose of the state in a give
  situation if more than one task has been specified on a state. A state calls one and only one task when it is
  executed.

.. container:: paragraph

  Each state is triggered by an event, which means that all tasks of a state must also be triggered by that same
  event. The set of output events for a state is the union of all output events from all tasks for that task. In
  practice at the moment, because a state can only have a single input event, a state that is not the final state of a
  policy may only output a single event and all tasks of that state may also only output that single event. In future
  work, the concept of having a less restrictive trigger pattern will be examined.

.. container:: paragraph

  A state that is the final state of a policy may output multiple events, and the task associated with the final state
  outputs those events.

.. container:: paragraph

  A *State* concept is keyed with a ``ReferenceKey`` key, which references the *Policy* concept that owns the state.
  The *LocalName* field of the ``ReferenceKey`` holds the name of the state. As a state is part of a chain of states,
  the *NextState* field of a state holds the ``ReferenceKey`` key of the state in the policy to execute after this
  state.

.. container:: paragraph

  The *Trigger* field of a state holds the ``ArtifactKey`` of the event that triggers this state. The *OutgoingEvents*
  field holds the ``ArtifactKey`` references of all possible events that may be output from the state. This is a set
  that is the union of all output events of all tasks of the state.

.. container:: paragraph

  The *Task* concepts that hold the definitions of the task for the state are held as a set of ``ArtifactKey``
  references in the state. The *DefaultTask* field holds a reference to the default task for the state, a task that is
  executed if no task selection logic is specified. If the state has only one task, that task is the default task.

.. container:: paragraph

  The *Logic* concept referenced by a state holds the task selection logic for a state. The task selection logic uses
  the incoming context (parameters of the incoming event) and other context to determine the best task to use to
  execute its goals. The state holds a set of references to *ContextItem* and *ContextItemTemplate* definitions for the
  context used by its task selection logic.

*************
Writing Logic
*************

Writing APEX Task Logic
=======================

.. container:: paragraph

  Task logic specifies the behavior of an Apex Task. This logic can be specified in a number of ways, exploiting
  Apex’s plug-in architecture to support a range of logic executors. In Apex scripted Task Logic can be written in any
  of these languages:

.. container:: ulist

  -  ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__,

  -  ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__,

  -  ```JRuby`` <https://en.wikipedia.org/wiki/JRuby>`__ or

  -  ```Jython`` <https://en.wikipedia.org/wiki/Jython>`__.

.. container:: paragraph

  These languages were chosen because the scripts can be compiled into Java bytecode at runtime and then efficiently
  executed natively in the JVM. Task Logic an also be written directly in Java but needs to be compiled, with the
  resulting classes added to the classpath. There are also a number of other Task Logic types (e.g. Fuzzy Logic), but
  these are not supported as yet. This guide will focus on the scripted Task Logic approaches, with MVEL and JavaScript
  being our favorite languages. In particular this guide will focus on the Apex aspects of the scripts. However, this
  guide does not attempt to teach you about the scripting languages themselves …​ that is up to you!

.. tip::
  JVM-based scripting languages For more more information on scripting for the Java platform see:
  https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/index.html

.. note::
  What do Tasks do? The function of an Apex Task is to provide the logic that can be executed for an Apex State as one
  of the steps in an Apex Policy. Each task receives some *incoming fields*, executes some logic (e.g: make a decision
  based on *shared state* or *context*, *incoming fields*, *external context*, etc.), perhaps set some *shared state*
  or *context* and then emits *outgoing fields* (in case of a single outgoing event), or a set of *outgoing fields*
  (in case of multiple outgoing events). The state that uses the task is responsible for extracting the
  *incoming fields* from the state input event. The state also has an *output mapper* associated with the task, and
  this *output mapper* is responsible for mapping the *outgoing fields* from the task into an appropriate output event
  for the state.

.. container:: paragraph

  First lets start with a sample task, drawn from the "My First Apex Policy" example: The task "MorningBoozeCheck"
  from the "My First Apex Policy" example is available in both MVEL and JavaScript:

.. container:: listingblock

  .. container:: title

    Javascript code for the ``MorningBoozeCheck`` task

  .. container:: content

    .. code:: javascript
      :number-lines:

      /*
       * ============LICENSE_START=======================================================
       *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
       *  Modifications Copyright (C) 2020 Nordix Foundation.
       * ================================================================================
       * 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=========================================================
       */

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

      true;

.. container:: listingblock

  .. container:: title

    MVEL code for the ``MorningBoozeCheck`` task

  .. container:: content

    .. code:: javascript
      :number-lines:

      /*
       * ============LICENSE_START=======================================================
       *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
       *  Modifications Copyright (C) 2020 Nordix Foundation.
       * ================================================================================
       * 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:: paragraph

  The role of the task in this simple example is to copy the values in the incoming fields into the outgoing
  fields, then examine the values in some incoming fields (``item_id`` and ``time``), then set the values in some
  other outgoing fields (``authorised`` and ``message``).

.. container:: paragraph

  Both MVEL and JavaScript like most JVM-based scripting languages can use standard Java libraries to perform
  complex tasks. Towards the top of the scripts you will see how to import Java classes and packages to be used
  directly in the logic. Another thing to notice is that Task Logic should return a ``java.lang.Boolean`` value
  ``true`` if the logic executed correctly. If the logic fails for some reason then ``false`` can be returned, but
  this will cause the policy invoking this task will fail and exit.

.. note::
  How to return a value from task logic
  Some languages explicitly support returning values from the script (e.g. MVEL and JRuby) using an explicit
  return statement (e.g. ``return true``), other languages do not (e.g. Jython). For
  languages that do not support the ``return`` statement, a special field called ``returnValue`` must be
  created to hold the result of the task logic operation (i.e. assign a ``java.lang.Boolean``
  value to the ``returnValue`` field before completing the task).
  Also, in MVEL if there is no explicit return statement then the return value of the last executed statement will
  return (e.g. the statement a=(1+2) will return the value 3).

  For Javascript, the last statement of a script must be a statement that evaluates to *true* or *false*, indicating
  whether the script executed correctly or not. In the case where the script always executes to compeletion
  sucessfully, simply add a last line with the statement *true'*. In cases where success or failure is assessed in the
  script, create a boolean
  local variable with a name such as ``returnvalue``. In the execution of the script, set ``returnValue`` to be ``true``
  or ``false`` as appropriate. The last line of the scritp tehn should simply be ``returnValue;``, which returns the
  value of ``returnValue``.

.. container:: paragraph

  Besides these imported classes and normal language features Apex provides some natively available parameters
  and functions that can be used directly. At run-time these parameters are populated by the Apex execution
  environment and made natively available to logic scripts each time the logic script is invoked. (These can be
  accessed using the ``executor`` keyword for most languages, or can be accessed directly without the
  ``executor`` keyword in MVEL):

Table 1. The ``executor`` Fields / Methods

  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | Name                                                | Type                                                                     | Java type                     | Description                                                                      |
  +=====================================================+==========================================================================+===============================+==================================================================================+
  | inFields                                            | Fields                                                                   | java.util.Map <String,Object> |The incoming task fields, implemented as a standard Java (unmodifiable) Map       |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |**Example:**                                                                      |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |.. code:: javascript                                                              |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  executor.logger.debug("Incoming fields: " +executor.inFields.entrySet());       |
  |                                                     |                                                                          |                               |  var item_id = executor.incomingFields["item_ID"];                               |
  |                                                     |                                                                          |                               |  if (item_id >=1000) { ... }                                                     |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | outFields                                           | Fields                                                                   | java.util.Map <String,Object> |The outgoing task fields. This is implemented as a standard initially empty Java  |
  |                                                     |                                                                          |                               |(modifiable) Map. To create a new schema-compliant instance of a field object     |
  |                                                     |                                                                          |                               |see the utility method subject.getOutFieldSchemaHelper() below that takes the     |
  |                                                     |                                                                          |                               |fieldName as an argument.                                                         |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |**Example:**                                                                      |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |.. code:: javascript                                                              |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  executor.outFields["authorised"] = false;                                       |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | outFieldsList                                       | Fields                                                                   | java.util.Collection          |The collection of outgoing task fields when there are multiple outputs from the   |
  |                                                     |                                                                          |   <Map<String, Object>>       |final state. To create a new schema-compliant instance of a field, see the        |
  |                                                     |                                                                          |                               |utility method subject.getOutFieldSchemaHelper() below that takes eventName and   |
  |                                                     |                                                                          |                               |fieldName as arguments.                                                           |
  |                                                     |                                                                          |                               |To add the set of output fields to the outFieldsList, the utility method          |
  |                                                     |                                                                          |                               |executor.addFieldsToOutput can be used as shown below.                            |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | void addFieldsToOutput(Map<String, Object> fields)  |A utility method to add fields to outgoing fields.                        |                               |                                                                                  |
  |                                                     |When there are multiple output events emitted from the task associated    |                               |                                                                                  |
  |                                                     |with a final state, this utility method can be used to add the            |                               |                                                                                  |
  |                                                     |corresponding fields to the outFieldsList.                                |                               |                                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |**Example:**                                                              |                               |                                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |.. code:: javascript                                                      |                               |                                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |  var cdsRequestEventFields = java.util.HashMap();                        |                               |                                                                                  |
  |                                                     |  var actionIdentifiers = executor.subject.getOutFieldSchemaHelper        |                               |                                                                                  |
  |                                                     |  ("CDSRequestEvent","actionIdentifiers").createNewInstance();            |                               |                                                                                  |
  |                                                     |  cdsRequestEventFields.put("actionIdentifiers", actionIdentifiers);      |                               |                                                                                  |
  |                                                     |  executor.addFieldsToOutput(cdsRequestEventFields);                      |                               |                                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |  var logEventFields = java.util.HashMap();                               |                               |                                                                                  |
  |                                                     |  logEventFields.put("status", "FINAL_SUCCESS");                          |                               |                                                                                  |
  |                                                     |  executor.addFieldsToOutput(logEventFields);                             |                               |                                                                                  |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | logger                                              | Logger                                                                   | org.slf4j.ext.XLogger         |A helpful logger                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |**Example:**                                                                      |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |.. code:: javascript                                                              |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  executor.logger.info("Executing task: " +executor.subject.id);                  |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | TRUE/FALSE                                          | boolean                                                                  | java.lang.Boolean             |2 helpful constants. These are useful to retrieve correct return  values for the  |
  |                                                     |                                                                          |                               |task logic                                                                        |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |**Example:**                                                                      |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |.. code:: javascript                                                              |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  var returnValue = executor.isTrue;                                              |
  |                                                     |                                                                          |                               |  var returnValueType = Java.type("java.lang.Boolean");                           |
  |                                                     |                                                                          |                               |  var returnValue = new returnValueType(true);                                    |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | subject                                             | Task                                                                     | TaskFacade                    |This provides some useful information about the task that contains this task      |
  |                                                     |                                                                          |                               |logic. This object has some useful fields and methods :                           |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |.. container:: ulist                                                              |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  - **AxTask task** to get access to the full task definition of the host task    |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  - **String getTaskName()** to get the name of the host task                     |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  - **String getId()** to get the ID of the host task                             |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  - **SchemaHelper getInFieldSchemaHelper( String fieldName )** to                |
  |                                                     |                                                                          |                               |    get a ``SchemaHelper`` helper object to manipulate incoming                   |
  |                                                     |                                                                          |                               |    task fields in a schema-aware manner                                          |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  - **SchemaHelper getOutFieldSchemaHelper( String fieldName )** to               |
  |                                                     |                                                                          |                               |    get a ``SchemaHelper`` helper object to manipulate outgoing                   |
  |                                                     |                                                                          |                               |    task fields in a schema-aware manner, e.g. to instantiate new                 |
  |                                                     |                                                                          |                               |    schema-compliant field objects to populate the                                |
  |                                                     |                                                                          |                               |    ``executor.outFields`` outgoing fields map. This can be used only when there  |
  |                                                     |                                                                          |                               |    is a single outgoing event from a task.                                       |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  - **SchemaHelper getOutFieldSchemaHelper( String eventname, String fieldName )**|
  |                                                     |                                                                          |                               |    to get a ``SchemaHelper`` helper object to manipulate outgoing                |
  |                                                     |                                                                          |                               |    task fields in a schema-aware manner, e.g. to instantiate new                 |
  |                                                     |                                                                          |                               |    schema-compliant field objects to populate the                                |
  |                                                     |                                                                          |                               |    ``executor.outFieldsList`` collection of outgoing fields map. This must be    |
  |                                                     |                                                                          |                               |    used in case of multiple outgoing events from a task, as the intention is to  |
  |                                                     |                                                                          |                               |    fetch the schema of a field associated to one of the expected events.         |
  |                                                     |                                                                          |                               |    This method works fine in case of single outgoing event too, but the previous |
  |                                                     |                                                                          |                               |    method is enough as the field anyway belongs to the single event.             |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |**Example:**                                                                      |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |.. code:: javascript                                                              |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  executor.logger.info("Task name: " + executor.subject.getTaskName());           |
  |                                                     |                                                                          |                               |  executor.logger.info("Task id: " + executor.subject.getId());                   |
  |                                                     |                                                                          |                               |  executor.outFields["authorised"] = executor.subject                             |
  |                                                     |                                                                          |                               |    .getOutFieldSchemaHelper("authorised").createNewInstance("false");            |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |  var actionIdentifiers = executor.subject.getOutFieldSchemaHelper                |
  |                                                     |                                                                          |                               |    ("CDSRequestEvent","actionIdentifiers").createNewInstance();                  |
  |                                                     |                                                                          |                               |  actionIdentifiers.put("blueprintName", "sample-bp");                            |
  |                                                     |                                                                          |                               |  var cdsRequestEventFields = java.util.HashMap();                                |
  |                                                     |                                                                          |                               |  cdsRequestEventFields.put("actionIdentifiers", actionIdentifiers);              |
  |                                                     |                                                                          |                               |  executor.addFieldsToOutput(cdsRequestEventFields);                              |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | ContextAlbum getContextAlbum(String ctxtAlbumName ) |A utility method to retrieve a ``ContextAlbum`` for use in the task.      |                               |                                                                                  |
  |                                                     |This is how you access the context used by the task. The returned         |                               |                                                                                  |
  |                                                     |``ContextAlbum`` implements the ``java.util.Map <String,Object>``         |                               |                                                                                  |
  |                                                     |interface to get and set context as appropriate. The returned             |                               |                                                                                  |
  |                                                     |``ContextAlbum`` also has methods to lock context albums, get             |                               |                                                                                  |
  |                                                     |information about the schema of the items to be stored in a context       |                               |                                                                                  |
  |                                                     |album, and get a ``SchemaHelper`` to manipulate context album items. How  |                               |                                                                                  |
  |                                                     |to define and use context in a task is described in the Apex              |                               |                                                                                  |
  |                                                     |Programmer’s Guide and in the My First Apex Policy guide.                 |                               |                                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |**Example:**                                                              |                               |                                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |.. code:: javascript                                                      |                               |                                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |  var bkey = executor.inFields.get("branch_ID");                          |                               |                                                                                  |
  |                                                     |  var cnts = executor.getContextMap("BranchCounts");                      |                               |                                                                                  |
  |                                                     |  cnts.lockForWriting(bkey);                                              |                               |                                                                                  |
  |                                                     |  cnts.put(bkey, cnts.get(bkey) + 1);                                     |                               |                                                                                  |
  |                                                     |  cnts.unlockForWriting(bkey);                                            |                               |                                                                                  |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+

Writing APEX Task Selection Logic
=================================

.. container:: paragraph

  The function of Task Selection Logic is to choose which task should be executed for an Apex State as one of
  the steps in an Apex Policy. Since each state must define a default task there is no need for Task Selection
  Logic unless the state uses more than one task. This logic can be specified in a number of ways, exploiting
  Apex’s plug-in architecture to support a range of logic executors. In Apex scripted Task Selection Logic can be
  written in any of these languages:

.. container:: ulist

  -  ```MVEL`` <https://en.wikipedia.org/wiki/MVEL>`__,

  -  ```JavaScript`` <https://en.wikipedia.org/wiki/JavaScript>`__,

  -  ```JRuby`` <https://en.wikipedia.org/wiki/JRuby>`__ or

  -  ```Jython`` <https://en.wikipedia.org/wiki/Jython>`__.

.. container:: paragraph

  These languages were chosen because the scripts can be compiled into Java bytecode at runtime and then
  efficiently executed natively in the JVM. Task Selection Logic an also be written directly in Java but needs to
  be compiled, with the resulting classes added to the classpath. There are also a number of other Task Selection
  Logic types but these are not supported as yet. This guide will focus on the scripted Task Selection Logic
  approaches, with MVEL and JavaScript being our favorite languages. In particular this guide will focus on the
  Apex aspects of the scripts. However, this guide does not attempt to teach you about the scripting languages
  themselves …​ that is up to you!

.. tip::
  JVM-based scripting languages
  For more more information on Scripting for the Java platform see:
  https://docs.oracle.com/javase/8/docs/technotes/guides/scripting/prog_guide/index.html

.. note::
  What does Task Selection Logic do?
  When an Apex state references multiple tasks, there must be a way to dynamically decide
  which task should be chosen and executed. This can depend on the many factors, e.g. the
  *incoming event for the state*, *shared state* or *context*, *external context*,
  etc.. This is the function of a state’s Task Selection Logic. Obviously, if there is
  only one task then Task only one task then Task Selection Logic is not needed.
  Each state must also select one of the tasks a the *default state*. If the Task
  Selection Logic is unable to select an appropriate task, then it should select the
  *default task*. Once the task has been selected the Apex Engine will then execute that task.

.. container:: paragraph

  First lets start with some simple Task Selection Logic, drawn from the "My First Apex Policy" example: The Task
  Selection Logic from the "My First Apex Policy" example is specified in JavaScript here:

.. container:: listingblock

  .. container:: title

    Javascript code for the "My First Policy" Task Selection Logic

  .. container:: content

    .. code:: javascript

      /*
       * ============LICENSE_START=======================================================
       *  Copyright (C) 2016-2018 Ericsson. All rights reserved.
       *  Modifications Copyright (C) 2020 Nordix Foundation.
       * ================================================================================
       * 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=========================================================
       */

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

      true;

.. container:: paragraph

  The role of the Task Selection Logic in this simple example is to examine the value in one incoming field
  (``branchid``), then depending on that field’s value set the value for the selected task to the appropriate task
  (``MorningBoozeCheck``, ``MorningBoozeCheckAlt1``, or the default task).

.. container:: paragraph

  Another thing to notice is that Task Selection Logic should return a ``java.lang.Boolean`` value ``true`` if
  the logic executed correctly. If the logic fails for some reason then ``false`` can be returned, but this will
  cause the policy invoking this task will fail and exit.

.. note::
  How to return a value from Task Selection Logic
  Some languages explicitly support returning values from the script (e.g. MVEL and
  JRuby) using an explicit return statement (e.g. ``return true``), other languages do not (e.g.
  JavaScript and Jython). For languages that do not support the ``return`` statement, a special field called
  ``returnValue`` must be created to hold the result of the task logic operation (i.e. assign a ``java.lang.Boolean``
  value to the ``returnValue`` field before completing the task).
  Also, in MVEL if there is not explicit return statement then the return value of the last executed statement will
  return (e.g. the statement a=(1+2) will return the value 3).

.. container:: paragraph

  Each of the scripting languages used in Apex can import and use standard Java libraries to perform complex tasks.
  Besides imported classes and normal language features Apex provides some natively available parameters and functions
  that can be used directly. At run-time these parameters are populated by the Apex execution environment and made
  natively available to logic scripts each time the logic script is invoked. (These can be accessed using the
  ``executor`` keyword for most languages, or can be accessed directly without the ``executor`` keyword in MVEL):

Table 2. The ``executor`` Fields / Methods
  +-----------------------------------+------------------------------------+
  | Unix, Cygwin                      | Windows                            |
  +===================================+====================================+
  |.. container:: content             |.. container:: content              |
  |                                   |                                    |
  |  .. code:: bash                   |  .. code:: bash                    |
  |    :number-lines:                 |    :number-lines:                  |
  |                                   |                                    |
  |    >c:                            |    # cd /usr/local/src/apex-pdp    |
  |    >cd \dev\apex                  |    # mvn clean install -DskipTests |
  |    >mvn clean install -DskipTests |                                    |
  +-----------------------------------+------------------------------------+

  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | Name                                                | Type                                                                     | Java type                     | Description                                                                      |
  +=====================================================+==========================================================================+===============================+==================================================================================+
  | inFields                                            | Fields                                                                   | java.util.Map <String,Object> | All fields in the state’s incoming event. This is implemented as a standard Java |
  |                                                     |                                                                          |                               | Java (unmodifiable) Map                                                          |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | **Example:**                                                                     |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | .. code:: javascript                                                             |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   executor.logger.debug("Incoming fields: " + executor.inFields.entrySet());     |
  |                                                     |                                                                          |                               |   var item_id = executor.incomingFields["item_ID"];                              |
  |                                                     |                                                                          |                               |   if (item_id >=1000) { ... }                                                    |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | outFields                                           | Fields                                                                   | java.util.Map <String,Object> | The outgoing task fields. This is implemented as a standard initially empty Java |
  |                                                     |                                                                          |                               | (modifiable) Map. To create a new schema-compliant instance of a field object    |
  |                                                     |                                                                          |                               | see the utility method subject.getOutFieldSchemaHelper() below                   |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | **Example:**                                                                     |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | .. code:: javascript                                                             |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   executor.outFields["authorised"] = false;                                      |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | logger                                              | Logger                                                                   | org.slf4j.ext.XLogger         | A helpful logger                                                                 |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | **Example:**                                                                     |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | .. code:: javascript                                                             |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   executor.logger.info("Executing task: "                                        |
  |                                                     |                                                                          |                               |   +executor.subject.id);                                                         |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | TRUE/FALSE                                          | boolean                                                                  | java.lang.Boolean             | 2 helpful constants. These are useful to retrieve correct return  values for the |
  |                                                     |                                                                          |                               | task logic                                                                       |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | **Example:**                                                                     |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | .. code:: javascript                                                             |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   var returnValue = executor.isTrue;                                             |
  |                                                     |                                                                          |                               |   var returnValueType = Java.type("java.lang.Boolean");                          |
  |                                                     |                                                                          |                               |   var returnValue = new returnValueType(true);                                   |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | subject                                             | Task                                                                     | TaskFacade                    | This provides some useful information about the task that contains this task     |
  |                                                     |                                                                          |                               | logic. This object has some useful fields and methods :                          |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | .. container:: ulist                                                             |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   - **AxTask task** to get access to the full task definition of the host task   |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   - **String getTaskName()** to get the name of the host task                    |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   - **String getId()** to get the ID of the host task                            |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   - **SchemaHelper getInFieldSchemaHelper( String fieldName )** to               |
  |                                                     |                                                                          |                               |     get a ``SchemaHelper`` helper object to manipulate incoming                  |
  |                                                     |                                                                          |                               |     task fields in a schema-aware manner                                         |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   - **SchemaHelper getOutFieldSchemaHelper( String fieldName )** to              |
  |                                                     |                                                                          |                               |     get a ``SchemaHelper`` helper object to manipulate outgoing                  |
  |                                                     |                                                                          |                               |     task fields in a schema-aware manner, e.g. to instantiate new                |
  |                                                     |                                                                          |                               |     schema-compliant field objects to populate the                               |
  |                                                     |                                                                          |                               |     ``executor.outFields`` outgoing fields map                                   |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | **Example:**                                                                     |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | .. code:: javascript                                                             |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   executor.logger.info("Task name: " + executor.subject.getTaskName());          |
  |                                                     |                                                                          |                               |   executor.logger.info("Task id: " + executor.subject.getId());                  |
  |                                                     |                                                                          |                               |   executor.outFields["authorised"] = executor.subject                            |
  |                                                     |                                                                          |                               |     .getOutFieldSchemaHelper("authorised")                                       |
  |                                                     |                                                                          |                               |     .createNewInstance("false");                                                 |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | parameters                                          | Fields                                                                   | java.util.Map <String,String> | All parameters in the current task. This is implemented as a standard Java Map.  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | **Example:**                                                                     |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               | .. code:: javascript                                                             |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |                                                                          |                               |   executor.parameters.get("ParameterKey1"))                                      |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+
  | ContextAlbum getContextAlbum(String ctxtAlbumName ) | A utility method to retrieve a ``ContextAlbum`` for use in the task.     |                               |                                                                                  |
  |                                                     | This is how you access the context used by the task. The returned        |                               |                                                                                  |
  |                                                     | ``ContextAlbum`` implements the ``java.util.Map <String,Object>``        |                               |                                                                                  |
  |                                                     | interface to get and set context as appropriate. The returned            |                               |                                                                                  |
  |                                                     | ``ContextAlbum`` also has methods to lock context albums, get            |                               |                                                                                  |
  |                                                     | information about the schema of the items to be stored in a context      |                               |                                                                                  |
  |                                                     | album, and get a ``SchemaHelper`` to manipulate context album items. How |                               |                                                                                  |
  |                                                     | to define and use context in a task is described in the Apex             |                               |                                                                                  |
  |                                                     | Programmer’s Guide and in the My First Apex Policy guide.                |                               |                                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     | **Example:**                                                             |                               |                                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     | .. code:: javascript                                                     |                               |                                                                                  |
  |                                                     |                                                                          |                               |                                                                                  |
  |                                                     |   var bkey = executor.inFields.get("branch_ID");                         |                               |                                                                                  |
  |                                                     |   var cnts = executor.getContextMap("BranchCounts");                     |                               |                                                                                  |
  |                                                     |   cnts.lockForWriting(bkey);                                             |                               |                                                                                  |
  |                                                     |   cnts.put(bkey, cnts.get(bkey) + 1);                                    |                               |                                                                                  |
  |                                                     |   cnts.unlockForWriting(bkey);                                           |                               |                                                                                  |
  +-----------------------------------------------------+--------------------------------------------------------------------------+-------------------------------+----------------------------------------------------------------------------------+

Logic Cheat Sheet
=================

.. container:: paragraph

  Examples given here use Javascript (if not stated otherwise), other execution environments will be similar.

Finish Logic with Success or Error
----------------------------------

.. container:: paragraph

  To finish logic, i.e. return to APEX, with success use the following line close to the end of the logic.

.. container:: listingblock

  .. container:: title

    JS Success

  .. container:: content

    .. code:: javascript

      true;

.. container:: paragraph

  To notify a problem, finish with an error.

  .. container:: listingblock

    .. container:: title

      JS Fail

    .. container:: content

      .. code:: javascript

        false;

Logic Logging
-------------

.. container:: paragraph

  Logging can be made easy using a local variable for the logger. Line 1 below does that. Then we start
  with a trace log with the task (or task logic) identifier followed by the infields.

.. container:: listingblock

  .. container:: title

    JS Logging

  .. container:: content

    .. code:: javascript

      var logger = executor.logger;
      logger.trace("start: " + executor.subject.id);
      logger.trace("-- infields: " + executor.inFields);

.. container:: paragraph

  For larger logging blocks you can use the standard logging API to detect log levels, for instance:

  .. container:: listingblock

    .. container:: title

      JS Logging Blocks

    .. container:: content

      .. code:: javascript

        if(logger.isTraceEnabled()){
          // trace logging block here
        }

.. container:: paragraph

  Note: the shown logger here logs to ``org.onap.policy.apex.executionlogging``. The behavior of the actual logging can
  be specified in the ``$APEX_HOME/etc/logback.xml``.

.. container:: paragraph

  If you want to log into the APEX root logger (which is sometimes necessary to report serious logic errors to the top),
  then import the required class and use this logger.

.. container:: listingblock

  .. container:: title

    JS Root Logger

  .. container:: content

    .. code:: javascript

      var rootLogger = LoggerFactory.getLogger(logger.ROOT_LOGGER_NAME);
      rootLogger.error("Serious error in logic detected: " + executor.subject.id);

Accessing TaskParameters
------------------------

.. container:: paragraph

  TaskParameters available in a Task can be accessed in the logic. The parameters in each task are made
  available at the executor level. This example assumes a parameter with key ``ParameterKey1``.

  .. container:: listingblock

    .. container:: title

      JS TaskParameter value

    .. container:: content

      .. code:: javascript

        executor.parameters.get("ParameterKey1"))

.. container:: paragraph

  Alternatively, the task parameters can also be accessed from the task object.

  .. container:: listingblock

    .. container:: title

      JS TaskParameter value using task object

    .. container:: content

      .. code:: javascript

        executor.subject.task.getTaskParameters.get("ParameterKey1").getTaskParameterValue()

Local Variable for Infields
---------------------------

.. container:: paragraph

  It is a good idea to use local variables for ``infields``. This avoids long code lines and policy
  evolution. The following example assumes infields named ``nodeName`` and ``nodeAlias``.

 .. container:: listingblock

   .. container:: title

     JS Infields Local Var

  .. container:: content

    .. code:: javascript

      var ifNodeName = executor.inFields["nodeName"];
      var ifNodeAlias = executor.inFields["nodeAlias"];

Local Variable for Context Albums
---------------------------------

.. container:: paragraph

  Similar to the ``infields`` it is good practice to use local variables for context albums as well. The
  following example assumes that a task can access a context album ``albumTopoNodes``. The second line gets a
  particular node from this context album.

.. container:: listingblock

  .. container:: title

    JS Infields Local Var

  .. container:: content

    .. code:: javascript

      var albumTopoNodes = executor.getContextAlbum("albumTopoNodes");
      var ctxtNode = albumTopoNodes.get(ifNodeName);

Set Outfields in Logic
----------------------

.. container:: paragraph

  The task logic needs to set outfields with content generated. The exception are outfields that are a
  direct copy from an infield of the same name, APEX does that autmatically.

.. container:: listingblock

  .. container:: title

    JS Set Outfields

  .. container:: content

    .. code:: javascript

      executor.outFields["report"] = "node ctxt :: added node " + ifNodeName;

Create a instance of an Outfield using Schemas
----------------------------------------------

.. container:: paragraph

  If an outfield is not an atomic type (string, integer, etc.) but uses a complex schema (with a Java or
  Avro backend), APEX can help to create new instances. The ``executor`` provides a field called ``subject``,
  which provides a schem helper with an API for this.

.. container:: paragraph

  If the backend is Java, then the Java class implementing the schema needs to be imported.

*Single outgoing event*

.. container:: paragraph

  When there is a single outgoing event associated with a task, the fieldName alone is enough to fetch its schema.
  The following example assumes an outfield ``situation``. The ``subject`` method ``getOutFieldSchemaHelper()`` is used
  to create a new instance.

.. container:: listingblock

  .. container:: title

    JS Outfield Instance with Schema

  .. container:: content

    .. code:: javascript

      var situation = executor.subject.getOutFieldSchemaHelper("situation").createNewInstance();

.. container:: paragraph

  If the schema backend is Java, the new instance will be as implemented in the Java class. If the schema backend is
  Avro, the new instance will have all fields from the Avro schema specification, but set to ``null``. So any entry here
  needs to be done separately. For instance, the ``situation`` schema has a field ``problemID`` which we set.

.. container:: listingblock

  .. container:: title

    JS Outfield Instance with Schema, set

  .. container:: content

    .. code:: javascript

      situation.put("problemID", "my-problem");

*Multiple outgoing events*

.. container:: paragraph

  When there are multiple outgoing events associated with a task, the fieldName along with the eventName it belongs to
  are needed to fetch its schema.
  The following example assumes an outfield ``actionIdentifiers`` which belongs to ``CDSRequestEvent``.
  The ``subject`` method ``getOutFieldSchemaHelper()`` is used to create a new instance.

.. container:: listingblock

  .. container:: content

    .. code:: javascript

      var actionIdentifiers = executor.subject.getOutFieldSchemaHelper("CDSRequestEvent", "actionIdentifiers").createNewInstance();

Create a instance of an Context Album entry using Schemas
---------------------------------------------------------

.. container:: paragraph

  Context album instances can be created using very similar to the outfields. Here, the schema helper
  comes from the context album directly. The API of the schema helper is the same as for outfields.

.. container:: paragraph

  If the backend is Java, then the Java class implementing the schema needs to be imported.

.. container:: paragraph

  The following example creates a new instance of a context album instance named ``albumProblemMap``.

.. container:: listingblock

  .. container:: title

    JS Outfield Instance with Schema

  .. container:: content

    .. code:: javascript

      var albumProblemMap = executor.getContextAlbum("albumProblemMap");
      var linkProblem = albumProblemMap.getSchemaHelper().createNewInstance();

.. container:: paragraph

  This can of course be also done in a single call without the local variable for the context album.

.. container:: listingblock

  .. container:: title

    JS Outfield Instance with Schema, one line

  .. container:: content

    .. code:: javascript

      var linkProblem = executor.getContextAlbum("albumProblemMap").getSchemaHelper().createNewInstance();

.. container:: paragraph

  If the schema backend is Java, the new instance will be as implemented in the Java class. If the schema backend is
  Avro, the new instance will have all fields from the Avro schema specification, but set to ``null``. So any entry here
  needs to be done separately (see above in outfields for an example).

Enumerates
----------

.. container:: paragraph

  When dealing with enumerates (Avro or Java defined), it is sometimes and in some execution
  environments necessary to convert them to a string. For example, assume an Avro enumerate schema as:

.. container:: listingblock

  .. container:: title

    Avro Enumerate Schema

  .. container:: content

    .. code:: javascript

      {
        "type": "enum", "name": "Status", "symbols" : [
          "UP", "DOWN"
        ]
      }

.. container:: paragraph

  Using a switch over a field initialized with this enumerate in Javascript will fail. Instead, use the ``toString`` method, for example:

.. container:: listingblock

  .. container:: title

    JS Outfield Instance with Schema, one line

  .. container:: content

    .. code:: javascript

      var switchTest = executor.inFields["status"]; switch(switchTest.toString()){
        case "UP": ...; break; case "DOWN": ...; break; default: ...;
      }

MVEL Initialize Outfields First!
--------------------------------

.. container:: paragraph

  In MVEL, we observed a problem when accessing (setting) outfields without a prior access to them. So
  in any MVEL task logic, before setting any outfield, simply do a get (with any string), to load the outfields
  into the MVEL cache.

.. container:: listingblock

  .. container:: title

    MVEL Outfield Initialization

  .. container:: content

    .. code:: javascript

      outFields.get("initialize outfields");

Using Java in Scripting Logic
-----------------------------

.. container:: paragraph

  Since APEX executes the logic inside a JVM, most scripting languages provide access to all standard
  Java classes. Simply add an import for the required class and then use it as in actual Java.

.. container:: paragraph

  The following example imports ``java.util.arraylist`` into a Javascript logic, and then creates a new
  list.

.. container:: listingblock

  .. container:: title

    JS Import ArrayList

  .. container:: content

    .. code:: javascript

      var myList = new ArrayList();

Converting Javascript scripts from Nashorn to Rhino dialects
------------------------------------------------------------

The Nashorn Javascript engine was removed from Java in the Java 11 release. Java 11 was introduced into
the Policy Framework in the Frankfurt release, so from Frankfurt on, APEX Javascript scripts use the Rhino
Javascript engine and scripts must be in the Rhino dialect.

There are some minor but important differences between the dialects that users should be aware of so
that they can convert their scripts into the Rhino dialect.

Return Values
^^^^^^^^^^^^^

APEX scripts must always return a value of ``true`` indicating that the script executed correctly or ``false``
indicating that there was an error in script execution.

*Pre Frankfurt*

In Nashorn dialect scripts, the user had to create a special variable called ``returnValue`` and set the value of
that variable to be the return value for the script.

*Frankfurt and Later*

In Rhino dialect scripts, the return value of the script is the logical result of the last statement. Therefore the
last line of the script must evaluate to either ``true`` or ``false``.

.. container:: listingblock

  .. container:: title

    JS Rhino script last executed line examples

  .. container:: content

    .. code:: javascript

      true;

      returnValue; // Where returnValue is assigned earlier in the script

      someValue == 1; // Where the value of someValue is assigned earlier in the script

return statement
^^^^^^^^^^^^^^^^

The ``return`` statement is not supported from the main script called in the Rhino interpreter.

*Pre Frankfurt*

In Nashorn dialect scripts, the user could return a value of ``true`` or ``false`` at any point in their script.

.. container:: listingblock

  .. container:: title

    JS Nashorn main script returning ``true`` and ``false``

  .. container:: content

    .. code:: javascript

      var n;

      // some code assigns n a value

      if (n < 2) {
        return false;
      } else {
        return true;
      }

*Frankfurt and Later*

In Rhino dialect scripts, the ``return`` statement cannot be used in the main method, but it can still be used in
functions. If you want to have a ``return`` statement in your code prior to the last statement, encapsulate your code
in a function.

.. container:: listingblock

  .. container:: title

    JS Rhino script with ``return`` statements in a function

  .. container:: content

    .. code:: javascript

      someFunction();

      function someFunction() {
        var n;

        // some code assigns n a value

        if (n < 2) {
            return false;
        } else {
            return true;
        }
      }

Compatibility Script
^^^^^^^^^^^^^^^^^^^^

For Nashorn, the user had to call a compatibility script at the beginning of their Javascript script. This is not
required in Rhino.

*Pre Frankfurt*

In Nashorn dialect scripts, the compatibility script must be loaded.

.. container:: listingblock

  .. container:: title

    Nashorn compatability script loading

  .. container:: content

    .. code:: javascript

      load("nashorn:mozilla_compat.js");

*Frankfurt and Later*

Not required.

Import of Java classes
^^^^^^^^^^^^^^^^^^^^^^

For Nashorn, the user had explicitly import all the Java packages and classes they wished to use in their Javascript
script. In Rhino, all Java classes on the classpath are available for use.

*Pre Frankfurt*

In Nashorn dialect scripts, Java classes must be imported.

.. container:: listingblock

  .. container:: title

    Importation of Java packages and classes

  .. container:: content

    .. code:: javascript

      importPackage(java.text);
      importClass(java.text.SimpleDateFormat);

*Frankfurt and Later*

Not required.

Using Java Classes and Objects as Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Setting a Javascript variable to hold a Java class or a Java object is more straightforward in Rhino than it is in
Nashorn. The examples below show how to instantiate a Javascript variable as a Java class and how to use that variable
to create an instance of the Java class in another Javascript variable in both dialects.


*Pre Frankfurt*

.. container:: listingblock

  .. container:: title

    Create Javascript variables to hold a Java class and instance

  .. container:: content

    .. code:: javascript

      var webClientClass = Java.type("org.onap.policy.apex.examples.bbs.WebClient");
      var webClientObject = new webClientClass();

*Frankfurt and Later*

.. container:: listingblock

  .. container:: title

    Create Javascript variables to hold a Java class and instance

  .. container:: content

    .. code:: javascript

      var webClientClass = org.onap.policy.apex.examples.bbs.WebClient;
      var webClientObject = new webClientClass();

Equal Value and Equal Type operator ``===``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The *Equal Value and Equal Type* operator ``===`` is not supported in Rhino. Developers must use the Equal To
operator ``==`` instead. To check types, they may need to explicitly find and check the type of the variables
they are using.

*************************************************
Writing Multiple Output Events from a Final State
*************************************************

.. container:: paragraph

  APEX-PDP now supports sending multiple events from a final state in a Policy. The task assocaiated with the final
  state can populate the fields of multiple events, and then they can be passed over as the output events from the final
  state of a policy.

.. note::
  inputfields and outputfields are not needed as part of the task definition anymore. Fields of an event are already
  defined as part of the event definition. Input event (single trigger event) and output event/events can be populated
  to a task as part of the policy/state definition because the event tagging is done there anyway.

.. container:: paragraph

  Consider a simple example where a policy *CDSActionPolicy* has a state *MakeCDSRequestState* which is also a final
  state. The state is triggered by an event *AAIEvent*. A task called *HandleCDSActionTask* is associated with
  *MakeCDSRequestState*.There are two output events expected from *MakeCDSRequestState* which are *CDSRequestEvent*
  (request event sent to CDS) and *LogEvent* (log event sent to DMaaP).
  Writing an APEX policy with this example will involve the below changes.

*Command File:*

.. container:: listingblock

  .. container:: title

    Define all the concepts in the Policy. Only relevant parts for the multiple output support are shown.

  .. container:: content

    .. code::

      ## Define Events
      event create name=AAIEvent version=0.0.1 nameSpace=org.onap.policy.apex.test source=AAI target=APEX
      ..
      event create name=CDSRequestEvent version=0.0.1 nameSpace=org.onap.policy.apex.test source=APEX target=CDS
      event parameter create name=CDSRequestEvent parName=actionIdentifiers schemaName=CDSActionIdentifiersType
      ..
      event create name=LogEvent version=0.0.1 nameSpace=org.onap.policy.apex.test source=APEX target=DMaaP
      event parameter create name=LogEvent  parName=status schemaName=SimpleStringType
      ..

      ## Define Tasks
      task create name=HandleCDSActionTask
      task contextref create name=HandleCDSActionTask albumName=EventDetailsAlbum
      task logic create name=HandleCDSActionTask logicFlavour=JAVASCRIPT logic=LS
      #MACROFILE:"src/main/resources/logic/HandleCDSActionTask.js"
      LE
      ..

      ## Define Policies and States
      policy create name=CDSActionPolicy template=Freestyle firstState=MakeCDSRequestState
      policy state create name=CDSActionPolicy stateName=MakeCDSRequestState triggerName=AAIEvent defaultTaskName=HandleCDSActionTask
      # Specify CDSRequestEvent as output
      policy state output create name=CDSActionPolicy stateName=MakeCDSRequestState outputName=CDSActionStateOutput eventName=CDSRequestEvent
      # Specify LogEvent as output
      policy state output create name=CDSActionPolicy stateName=MakeCDSRequestState outputName=CDSActionStateOutput eventName=LogEvent
      policy state taskref create name=CDSActionPolicy stateName=MakeCDSRequestState taskName=HandleCDSActionTask outputType=DIRECT outputName=CDSActionStateOutput

*Task Logic File:*

.. container:: listingblock

  .. container:: title

    Create outfields' instance if required, populate and add them the output events

  .. container:: content

    .. code:: javascript

      ..
      var cdsRequestEventFields = java.util.HashMap();
      var actionIdentifiers = executor.subject.getOutFieldSchemaHelper("CDSRequestEvent","actionIdentifiers").createNewInstance();
      actionIdentifiers.put("blueprintName", "sample-bp");
      cdsRequestEventFields.put("actionIdentifiers", actionIdentifiers);
      executor.addFieldsToOutput(cdsRequestEventFields);

      var logEventFields = java.util.HashMap();
      logEventFields.put("status", "FINAL_SUCCESS");
      executor.addFieldsToOutput(logEventFields);

.. container:: paragraph

  With the above changes, the task populates the fields for both the expected events, and the corresponding state which
  is *MakeCDSRequestState* outputs both *CDSRequestEvent* and *LogEvent*

.. |APEX Policy Matrix| image:: images/apex-intro/ApexPolicyMatrix.png
.. |APEX Policy Model for Execution| image:: images/apex-policy-model/UmlPolicyModels.png
.. |Concepts and Keys| image:: images/apex-policy-model/ConceptsKeys.png