language.adoc 55.8 KB
Newer Older
Raj Shah's avatar
Raj Shah committed
1
= IND^2^UCE Policy Language Documentation - Version 3.2.46
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Fraunhofer IESE
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 4
:sectlinks:
:stylesdir: ./css
:stylesheet: ind2uce.css
:linkcss:

[[introduction]]
= Introduction

Raj Shah's avatar
Raj Shah committed
16
This documentation is about the definition of *privacy policies* regulating security-relevant system events.
17
18
19

Currently, our policy language supports the declaration of the following features:

Raj Shah's avatar
Raj Shah committed
20
21
22
23
* Inhibition of system events
* Modification of system events
* Execution of compensating actions
* Time interval based executions of mechanisms (cron jobs)
24

Raj Shah's avatar
Raj Shah committed
25
Policies are based on Boolean logic and can make use of:
26

Raj Shah's avatar
Raj Shah committed
27
28
29
* Data contained in the monitored event
* External data sources (e.g. LDAP)
* The history of events
30

Raj Shah's avatar
Raj Shah committed
31
32
33
34
A *policy* consists of one or more *mechanisms*.
Mechanisms are based on the *Event-Condition-Action* (ECA) schema:
If a system *event E* (<<<mechanism>>>) is fetched and *condition C* (<<if_elseif,<if> , <elseif>>>) is satisfied, then *action A* (<<then_else, <then>, <else>>>) is performed. The IND^2^UCE framework follows a blacklisting approach.
Events that are not covered by policies are allowed by default.
35

Raj Shah's avatar
Raj Shah committed
36
.Example IND^2^UCE security policy: The following policy translates to "Inhibit event getTransactions if the external information source getCurrentHour returns a value below or equal to 15"
37
38
[source,xml]
----
Raj Shah's avatar
Raj Shah committed
39
40
41
42
43
44
45
46
47
48
49
50
<policy id='urn:policy:banking-demo:getTransactions'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <lessEqual>
        <constant:number value='15'/>
        <pip:number method='urn:info:banking-demo:getCurrentHour' default='0'/>
      </lessEqual>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
51
52
53
54
55
56
</policy>
----

[[language-elements]]
= Language Elements

Raj Shah's avatar
Raj Shah committed
57
58
[[policy]]
== policy
59

Raj Shah's avatar
Raj Shah committed
60
The *<policy>* tag is the root element of an IND²UCE security policy. It has the following attributes:
61
62
63

[options='header']
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
64
65
66
67
|Attribute    |Type      |Required |Meaning
|id           |URN       |yes      |The id of the policy, which must be unique. The id syntax is urn:policy:<scope>:<identifier>. The <scope> matches your solution ID and defines the range of effect. The <identifier> uniquely identifies the policy within the scope.
|name         |String    |no       |A short name for the policy.
|description  |String    |no       |A natural language description of the security policy.
68
69
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
70
The *<policy>* tag must have at least one <<mechanism,<mechanism>>> child and can optionally contain <<variableDeclaration-group,variableDeclaration>> children.
71

Raj Shah's avatar
Raj Shah committed
72
.Example: The following policy describes the basic policy structure
73
74
[source,xml]
----
Raj Shah's avatar
Raj Shah committed
75
76
77
78
79
80
81
82
83
84
<policy id='urn:policy:banking-demo:notifyUser'>
  <!-- optional -->
  <variableDeclaration:string name='variableExample'>
    ...
  </variableDeclaration:string>

  <!-- at least one -->
  <mechanism event='urn:action:banking-demo:notify-user'>
    ...
  </mechanism>
85
86
87
</policy>
----

Raj Shah's avatar
Raj Shah committed
88
89
[[mechanism]]
== mechanism
90

Raj Shah's avatar
Raj Shah committed
91
92
93
94
95
96
97
The *<mechanism>* describes a rule of a policy based on a monitored or intercepted event.
Depending on the policy specification and evaluation, the intercepted event can be allowed (event is released and executed normally),
modified (the event is changed according to the modifiers specified in the mechanism before it is executed) or
inhibited (the event is dropped and will not be executed).
If an event that is matching the event declaration is intercepted by a PEP, the event is sent to the PDP. The PDP checks whether the condition is satisfied.
If it is satisfied, the specified action is the decision of the PDP and will be enforced by the corresponding PEP.
An action of a non-satisfied condition will never be executed.
98

Raj Shah's avatar
Raj Shah committed
99
The *<mechanism>* element has the following attributes:
100
101
102

[options='header']
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
103
104
105
106
|Attribute    |Type      |Required |Meaning
|event        |PepEvent  |Yes      |Specifies the event by which the mechanism is triggered and for which the mechanism provides a security rule. The event id follows this pattern: urn:action:<scope>:<identifier>
|id           |String    |no       |A unique id for the mechanism, used for logging purposes only.
|description  |String    |no       |A natural language description of the mechanism.
107
108
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
109
A *<mechanism>* can have the following child elements:
110

Raj Shah's avatar
Raj Shah committed
111
112
113
114
115
116
117
118
119
120
121
122
* <<if_elseif,<if>>>: A condition that leads to an authorization decision if it matches
* <<if_elseif,<elseif>>>: A condition that leads to an authorization decision if it matches and the previous if's did not match
* <<then_else,<else>>>: A condition that leads to an authorization decision if none of the previous if's matched
* <<execute,<execute>>>: The unconditional execution of an action

.Policy Specification Rules
[CAUTION]
===============================
* The child element <<if,<if>>> is mandatory and only allowed to be used once within a <<mechanism,<mechanism>>>.
* The child element <<else,<else>>> is optional but only allowed to be used once within a <<mechanism,<mechanism>>> also.
* The child elements <<elseif,<elseif>>> and <<execute,<execute>>> may be used multiple times.
===============================
123
124
125
126

.Policy Evaluation Rules
[IMPORTANT]
===============================
Raj Shah's avatar
Raj Shah committed
127
* A specified <<execute,<execute>>> inside the <<mechanism,<mechanism>>> tag is triggered by the event, independently from the satisfaction of a condition.
128
129
===============================

Raj Shah's avatar
Raj Shah committed
130
.Example: The following policy inhibits access to accounts and loggs the action
131
132
[source,xml]
----
Raj Shah's avatar
Raj Shah committed
133
134
135
136
137
138
139
140
141
142
143
144
<policy id='urn:policy:banking-demo:getAccounts' description='Inhibits access to accounts and loggs the action'>
  <mechanism event='urn:action:banking-demo:get-accounts'>
    <if>
      <constant:true/>
      <then>
        <inhibit/>
      </then>
    </if>
    <execute action='urn:action:banking-demo:logNotification'>
       <parameter:string name='message' value='Access attempt to account data'/>
    </execute>
  </mechanism>
145
146
147
</policy>
----

Raj Shah's avatar
Raj Shah committed
148
149
[[if_elseif]]
== if, elseif
150

Raj Shah's avatar
Raj Shah committed
151
The *<if>* and the *<elseif>* elements declare the condition that is evaluated each time the mechanism fires.
152

Raj Shah's avatar
Raj Shah committed
153
A condition can have the following child elements:
154

Raj Shah's avatar
Raj Shah committed
155
156
* A boolean-function (e.g. <<constant:true,<constant:true>>>, <<pip:boolean,<pip:boolean>>>)
* <<then,<then>>>: An authorization decision that the mechanism evaluates to if the condition matches
157
158
159


.Policy Specification Rules
Raj Shah's avatar
Raj Shah committed
160
[CAUTION]
161
===============================
Raj Shah's avatar
Raj Shah committed
162
* The <if> and the <elseif> must have exactly two child elements. One of these is the <<then,<then>>>. For more complex conditions, the Boolean operators (<<and,<and>>>, <<or,<or>>>, etc.) need to be used.
163
164
165
166
167
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
Raj Shah's avatar
Raj Shah committed
168
169
170
171
* If the <if> condition is not satisfied, then the first <elseif> condition will be evaluated.
* Only the one action specified in the <then> element of the *first* satisfied <if> or <elseif> condition will be executed.
* If no condition is satisfied, then the action defined in the <else> element will be executed.
* If no condition is satisfied and no <else> element is specified, then the default action will be executed, which is <allow>.
172
173
===============================

Raj Shah's avatar
Raj Shah committed
174
.Example: Prohibits access to transactions after 3pm and loggs access to transactions between 2pm and 3pm
175
176
[source,xml]
----
Raj Shah's avatar
Raj Shah committed
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
<policy id='urn:policy:banking-demo:getTransactions'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <lessEqual>
        <constant:number value='15'/>
        <pip:number method='urn:info:banking-demo:getCurrentHour' default='0'/>
      </lessEqual>
      <then>
        <inhibit/>
      </then>
    </if>
    <elseif>
      <and>
         <greaterEqual>
           <pip:number method='urn:banking-demo:getCurrentHour' default='0'/>
           <constant:number value='14'/>
         </greaterEqual>
         <less>
           <pip:number method='urn:info:banking-demo:getCurrentHour' default='0'/>
           <constant:number value='15'/>
         </less>
      </and>
      <then>
        <execute action='urn:action:banking-demo:logNotification'>
          <parameter:string name='message' value='Access attempt to account data between 2 and 3pm'/>
        </execute>
      </then>
    </elseif>
    <else>
      <constant:true/>
      <then>
        <allow/>
        <execute action='urn:action:banking-demo:logNotification'>
          <parameter:string name='message' value='Someone accessed the transactions'/>
        </execute>
      </then>
    </else>
  </mechanism>
</policy>
----

[[then_else]]
== then, else

If the condition (<if> or <elseif>) is satisfied, the authorization decision has to be defined.
Therefore you can use the <<then,<then>>> element.

The two elements can have the following child elements:

* <<allow,<allow>>>: The event will be allowed and executed
* <<inhibit,<inhibit>>>: The event will be inhibited and not executed
* <<modify,<modify>>>: The event is modified before execution
* <<execute,<execute>>>: Independent of the event allowance, additional actions are executed
230
231

.Policy Specification Rules
Raj Shah's avatar
Raj Shah committed
232
[CAUTION]
233
===============================
Raj Shah's avatar
Raj Shah committed
234
235
236
* The <then> and the <else> elements must have at least one child element.
* Only one from the elements <allow>, <inhibit> and <modify> must be chosen.
* If none of the elements  <allow>, <inhibit> and <modify> is specified, an implicit <allow> is executed.
237
238
===============================

Raj Shah's avatar
Raj Shah committed
239
.Example: If role is banker *then* allow the event "get transactions" *else* inhibit
240
241
[source,xml]
----
Raj Shah's avatar
Raj Shah committed
242
243
244
245
246
247
248
249
250
251
252
253
<policy id='urn:policy:banking-demo:checkRole>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <equals>
        <pip:string method='urn:info:banking-demo:checkRole' default=''/>
        <constant:string value='Banker'/>
      </equals>
      <then>
        <allow/>
      </then>
    </if>
    <else>
254
      <inhibit/>
Raj Shah's avatar
Raj Shah committed
255
256
    </else>
  </mechanism>
257
258
259
</policy>
----

Raj Shah's avatar
Raj Shah committed
260
261
262
263
264
265
266
267
268
269
[[allow, inhibit]]
=== allow, inhibit
The *<allow>* tag is part of a positive authorization decision. It informs the PEP that the intercepted event can be released for reaching its destination.
The *<inhibit>* tag is part of a negative authorization decision. It informs the PEP that the intercepted event must be dropped so that it never reaches its destination.
A reason can be added to both elements:
[options='header']
|======================================================================================================================================
|Attribute    |Type      |Required  |Meaning
|reason       |String    |no        |The description of the authorisation reason.
|======================================================================================================================================
270

Raj Shah's avatar
Raj Shah committed
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
.Example: If role is banker then *allow* the event "get transactions" else *inhibit*
[source,xml]
----
<policy id='urn:policy:banking-demo:checkRoleExample'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <equals>
        <pip:string method='urn:info:banking-demo:checkRole' default=''/>
        <constant:string value='Banker'/>
      </equals>
      <then>
        <allow reason='Banker is authorized to get transactions'/>
      </then>
    </if>
    <else>
      <inhibit reason='User is not authorized'/>
    </else>
  </mechanism>
</policy>
----
291

Raj Shah's avatar
Raj Shah committed
292
293
[[modify]]
=== modify
294

Raj Shah's avatar
Raj Shah committed
295
296
297
The *<modify>* element is used to specify event modifications that the PEP must enforce before releasing the intercepted event.
It has the following attributes:
[options='header']
298
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
299
300
301
302
303
|Attribute      |Type       |Required   |Meaning
|eventParameter |String     |yes        |The name of the parameter that should be modified.
|method         |String     |yes        |The name of the modification that should be applied (e.g., delete, anonymize). This depends on the capabilities of the PEP. Available modifier methods can be checked in your component overview and proposed by the policy editor.
|jsonPathQuery  |String     |no         |If the parameter contains a complex object, modifications can be applied to specific parts of the data structure. For example a query "$firstName" of a parameter "user" will result in the modification of the first name of the user object only. Please refer to http://goessner.net/articles/JsonPath/ for more information about JsonPath.
|reason         |String     |no         |The description why the event is modified.
304
305
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
306
Child elements can be all elements of the <<parameter-group,parameter-group>>. The mandatory and optional parameters depend on the selected modifier method.
307

Raj Shah's avatar
Raj Shah committed
308
.Example: Replace the bank code number before showing it
309
310
[source,xml]
----
Raj Shah's avatar
Raj Shah committed
311
312
313
314
315
316
317
318
319
320
321
<policy id='urn:policy:banking-demo:getAccounts'>
  <mechanism event='urn:action:banking-demo:get-accounts'>
    <if>
      <constant:true/>
      <then>
        <modify eventParameter='accounts' method='replace' jsonPathQuery='$.accounts.bankCodeNumber'>
          <parameter:object name='replaceWith' value='XXXXX'/>
        </modify>
      </then>
    </if>
  </mechanism>
322
323
324
</policy>
----

Raj Shah's avatar
Raj Shah committed
325
326
327
328
329
330
.JSONPath
[TIP]
===============================
* JSONPath is an instrument to query JSON structures. JSONPath uses special notation to represent nodes and their connections to adjacent nodes in a JsonPath path.
* Notation to get the value of a transaction: $.transactions.amount.value
===============================
331

Raj Shah's avatar
Raj Shah committed
332
333
[[execute]]
== execute
334

Raj Shah's avatar
Raj Shah committed
335
336
Execute Actions are compensating actions that security policies can trigger in the system.
They are specified using the *<execute>* tag. Execute actions return a Boolean value indicating the execution success.
337
338
339

[options='header']
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
340
341
|Attribute    |Type      |Required |Meaning
|action        |String   |yes    | The action to be executed.
342
343
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
344
Child elements can be all elements of the <<parameter-group,parameter-group>>. They serve as input parameters for the corresponding execution function. The mandatory and optional parameters depend on the selected execute action.
345

Raj Shah's avatar
Raj Shah committed
346
.Example: Replace the account information before showing it and log the event
347
348
[source,xml]
----
Raj Shah's avatar
Raj Shah committed
349
350
351
352
353
354
355
<policy id='urn:policy:banking-demo:log_Message'>
  <mechanism event='urn:action:banking-demo:get-accounts'>
    <if>
      <constant:true/>
      <then>
        <modify eventParameter='customerId' method='replace'>
          <parameter:object name='replaceWith' value='XX'/>
356
        </modify>
Raj Shah's avatar
Raj Shah committed
357
358
359
360
361
362
        <execute action='urn:action:banking-demo:logNotification'>
          <parameter:string name='message' value='Log Message'/>
        </execute>
      </then>
    </if>
  </mechanism>
363
364
365
</policy>
----

Raj Shah's avatar
Raj Shah committed
366
367
368
369
370
371
372
373
374
375
376
377
378
379
[[number-functions]]
== number functions
The following elements process numbers:

* <plus>
* <minus>
* <multiply>
* <divide>
* <size>
// * <count>

The functions *<plus>, <minus>, <multiply>* and *<divide>* are used to perform the arithmetical operations (addition, subtraction, multiplication, division).
These four functions don't have any attributes.
Every element which has a number as return value or is a number function can be used as a child element (e.g. <constant:number>, <pip:number>, <size>).
380

Raj Shah's avatar
Raj Shah committed
381
382
383
384
385
.Policy Specification Rules
[CAUTION]
===============================
* <plus>, <minus>, <multiply> and <divide> must have at least two child elements.
===============================
386

Raj Shah's avatar
Raj Shah committed
387
388
389
The *<size>* function is used to count the number of elements in a list or the number of characters in a string.
It doesn't have any attributes, either. You can assign all child elements with
a list return value or a <<pip:string,<pip:string>>> or <<concat,<concat>>> element.
390

Raj Shah's avatar
Raj Shah committed
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
.Policy Specification Rules
[CAUTION]
===============================
* <size> must have at least one child element.
===============================
////
The *<count>* function is used to count the number of event occurrences in a certain time or time range. A detailed description is written under the section <<time-elements,time elements>>.

.Example: Inhibits access to transactions if the event get-transactions and get-money was fired more than 20 times today
----
<policy id='urn:policy:banking-demo:getTransactions'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <greaterEqual>
        <plus>
          <count>
            <eventOccurrence event='urn:action:banking-demo:get-transactions'/>
            <today/>
          </count>
          <count>
            <eventOccurrence event='urn:action:banking-demo:get-money'/>
            <today/>
          </count>
        </plus>
        <constant:number value='20'/>
      </greaterEqual>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
</policy>
----
////
[[boolean-functions]]
== boolean functions

The boolean functions are needed to process boolean values or compare and evaluate other values. The functions can be divided into three different groups:

The following elements are used to compare numbers, strings, objects, lists and boolean:

* <equals> (number, string, object, list, boolean)
* <less> (number)
* <lessEqual> (number)
* <greater> (number)
* <greaterEqual> (number)

These elements are used to aggregate boolean expressions:

* <and>
* <or>
* <xor>
* <not>
* <implies>

Further boolean functions are:

// * <valueChanged>: evaluates if a value has changed to true or false
// * <valueUnchanged>: return true if value is unchanged
* <regex>: evaluates whether the value of the child elements match a given regular expression
* <contains>: evaluates whether the declared values are contained in e.g a list
* <eventHasParameter>: evaluates whether the event contains a specified parameter
* <execute>: triggers an action in the system and returns a boolean value indicating the execution success
// * <continuousOccurrence>: evaluates if an event occurs more than one time in a certain time frame

=== less, lessEqual, greater, greaterEqual, equals
The functions *<less>, <lessEqual>, <greater>* and *<greaterEqual>* are used to compare different numbers. For instance if you want to compare the current time with a constant number.
These functions don't have attributes and child elements can be elements with a number return value (like <<pip:number, <pip:number>>>)
 and the <<number-functions, number-functions>>.

The function *<equals>* is different, because besides numbers other values can be compared with each other. For example, it is possible to compare strings like a constant string and a user name.
 *<equals>* doesn't have an attribute, either.
 And besides child elements with a number return value, also elements with string, object, list and boolean return value as well as boolean-functions can be added to <equals>.
464

Raj Shah's avatar
Raj Shah committed
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
.Policy Specification Rules
[CAUTION]
===============================
* The elements <less>, <lessEqual>, <greater>, <greaterEqual> and <equals> must have at least two child elements.
* The order is essential, e.g. for the child elements values A, B and C specified in this order, the *<less>* element evaluates A < B < C.
* In <equals> all child values have to be the same. (It is only possible to compare number with number, string with string,...).
===============================
////
.Example: Inhibit the event "get transactions" if the event already occurred more than 10 times today
----
<policy id='urn:policy:banking-demo:getTransactionsGreaterEqualExample' xmlns='http://www.iese.fraunhofer.de/ind2uce/3.2.46/ind2uceLanguage' xmlns:tns='http://www.iese.fraunhofer.de/ind2uce/3.2.46/ind2uceLanguage' xmlns:parameter='http://www.iese.fraunhofer.de/ind2uce/3.2.46/parameter' xmlns:pip='http://www.iese.fraunhofer.de/ind2uce/3.2.46/pip' xmlns:function='http://www.iese.fraunhofer.de/ind2uce/3.2.46/function' xmlns:event='http://www.iese.fraunhofer.de/ind2uce/3.2.46/event' xmlns:constant='http://www.iese.fraunhofer.de/ind2uce/3.2.46/constant' xmlns:variable='http://www.iese.fraunhofer.de/ind2uce/3.2.46/variable' xmlns:variableDeclaration='http://www.iese.fraunhofer.de/ind2uce/3.2.46/variableDeclaration' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <greaterEqual>
        <count>
          <eventOccurrence event='urn:action:banking-demo:get-transactions'/>
          <today/>
        </count>
        <constant:number value='10'/>
      </greaterEqual>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
</policy>
----
////
=== and, or, xor, implies, not
The elements *<and>, <or>, <not>, <xor>* and *<implies>* aggregate the values of the child elements according to Boolean logic.
The following attribute can be added, if it's not added the evaluation is only done, when it's necessary.
496
497
498
[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
Raj Shah's avatar
Raj Shah committed
499
|mode        |String      |LAZY          |no    | It is possible to choose the mode lazy or eager. Lazy means that an evaluation is executed if it is needed. Eager means that the evaluation is executed also if it isn't needed.
500
501
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
502
Child elements can be all elements with boolean return value (e.g. <constant:true>, <event:boolean>) or elements of the <<boolean-functions>,boolean-functions>>.
503

Raj Shah's avatar
Raj Shah committed
504
.Policy Specification Rules
505
506
[CAUTION]
===============================
Raj Shah's avatar
Raj Shah committed
507
508
* The *<and>, <or>, <xor>* and *<implies>* elements must have at least one child element.
* The *<not>* element must have exactly one child element.
509
510
===============================

Raj Shah's avatar
Raj Shah committed
511
.Example: Inhibit transaction if user has id 1 *and* the transaction amount value is greater than 10.000
512
----
Raj Shah's avatar
Raj Shah committed
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
<policy id='urn:policy:banking-demo:InhibitUser1Transaction'>
  <mechanism event='urn:action:banking-demo:get-money'>
    <if>
      <and>
        <equals>
          <event:string eventParameter='sts' default='' jsonPathQuery='$.simpleusers.id'/>
          <constant:string value='1'/>
        </equals>
        <greater>
          <event:number eventParameter='sts' default='0' jsonPathQuery='$.transactions.amount.value'/>
          <constant:number value='10000'/>
        </greater>
      </and>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
</policy>
----
////
=== valueChanged, valueUnchanged
When using the *<valueChanged>* and *<valueUnchanged>* function, the system checks if the return value of the child has changed between the last evaluation cycle and this evaluation cycle to the value defined in the attribute.
The *<valueChanged>* element only returns true if the value is changed. However, the *<valueUnchanged>* element only returns true if the value didn't change between the last evaluation cycle and the current cycle.
The *valueChanged* and *valueUnchanged*'s child element can be <<boolean-functions,boolean-functions>> and elements with boolean return value.
 *<valueUnchanged>* doesn't have an attribute, because it's expected that the value didn't change to another value. However, *<valueChanged>* has the following required attribute:
[options='header']
|======================================================================================================================================
|Attribute    |Type      |Required |Meaning
|to        |Boolean      |yes    | Defines if the value of the child element changed to true or false.
|======================================================================================================================================
544

Raj Shah's avatar
Raj Shah committed
545
Child elements can be all elements with boolean return value (e.g. <constant:true>, <event:boolean>) or elements of the <<boolean-functions>,boolean-functions>>.
546

Raj Shah's avatar
Raj Shah committed
547
548
549
550
551
.Policy Specification Rules
[CAUTION]
===============================
* The <valueChanged> and <valueUnchanged> element must have exactly one child.
===============================
552

Raj Shah's avatar
Raj Shah committed
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
.Example: As soon as the event don't have the parameter simpleusers (the value changed to false) inhibit the event
----
<policy id='urn:policy:banking-demo:valueChangedExample'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <valueChanged to='false'>
         <eventHasParameter>
          <event:string eventParameter='transactions' default='' jsonPathQuery='$.simpleusers'/>
      </valueChanged>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
</policy>
----
////
=== regex
A regular expression (regex) is a formal language to describe a certain pattern or a sequence of characters.
If the regex pattern matches to the child-elements value the <regex> element returns true otherwise it would return false.
The *<regex>* element has the following attributes:
574
575
576
577

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
Raj Shah's avatar
Raj Shah committed
578
579
|regex        |String    |-             |yes      |The String defines the regex that is applied for matching the values of child elements.
|mode         |enum      |ALL           |no       |The mode declares how many child element must match. Possible modes are ALL, EXACTLY_ONE, AT_LEAST_ONE, NONE.
580
581
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
582
A *<regex>* can have the child elements with string return value and elements from the <<string-functions, string-functions>>.
583

Raj Shah's avatar
Raj Shah committed
584
585
586
587
588
.Policy Specification Rules
[CAUTION]
===============================
* The <regex> element must have at least one child.
===============================
589
590

.Policy Evaluation Rules
Raj Shah's avatar
Raj Shah committed
591
[IMPORTANT]
592
===============================
Raj Shah's avatar
Raj Shah committed
593
594
595
596
597
* The *<regex>* element has four evaluation modes:
** ALL: Regex must match all of the child element values.
** EXACTLY_ONE: Regex must match exactly one of the child element values, but not more than one.
** AT_LEAST_ONE: Regex must at least match one of the child element values.
** NONE: Regex must not match any of the child element values.
598
599
===============================

Raj Shah's avatar
Raj Shah committed
600
.Example: If the transaction prupose matches to "Gehalt", "Lohn", "salary" or "pay" than replace the amount
601
----
Raj Shah's avatar
Raj Shah committed
602
603
604
605
606
607
608
609
610
611
612
613
614
<policy id='urn:policy:banking-demo:regexExample'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <regex regex='(Lohn)|(Gehalt)|(salary)|(pay)'>
        <event:string eventParameter='transactions' default='' jsonPathQuery='$.transactions.purpose'/>
      </regex>
      <then>
        <modify eventParameter='transactions' method='replace' jsonPathQuery='$.transactions.amount.value'>
          <parameter:object name='replaceWith' value='XXXX'/>
        </modify>
      </then>
    </if>
  </mechanism>
615
616
617
</policy>
----

Raj Shah's avatar
Raj Shah committed
618
=== contains
619

Raj Shah's avatar
Raj Shah committed
620
621
The <contains> element can be used to verify if one or several element values contain another value.
For instance, to verify if the string "Policy Language" contains the string "Policy".
622

Raj Shah's avatar
Raj Shah committed
623
A <contains> element has the following attribute:
624
625
626
627

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
Raj Shah's avatar
Raj Shah committed
628
|mode         |enum      |ALL           |no       |The mode declares how many child element must match. Possible modes are ALL, EXACTLY_ONE, AT_LEAST_ONE, NONE.
629
630
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
631
632
Because *<contains>* evaluates strings, numbers, lists, objects and booleans every element which returns these values can be added as child elements.
Additionally all elements of <<boolean-functions,boolean-functions>>, <<number-functions,number-functions>> and <<string-functions,string-functions>> can be added.
633
634


Raj Shah's avatar
Raj Shah committed
635
.Policy Specification Rules
636
637
[CAUTION]
===============================
Raj Shah's avatar
Raj Shah committed
638
639
640
* The *<contains>* element must have at least two child elements
* The order is essential, e.g. for the child elements values A, B and C specified in this order, the *<contains>* element evaluates if A contains B and C.
* In <contains> all child values have to be the same. (It is only possible to compare number with number, string with string,...).
641
642
===============================

Raj Shah's avatar
Raj Shah committed
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
.Policy Evaluation Rules
[IMPORTANT]
===============================
* The *<contains>* element has four evaluation modes:
** ALL: The first value must match all of the following element values.
** EXACTLY_ONE: The first value must match exactly one of the following element values, but not more than one.
** AT_LEAST_ONE: The first value must at least match one of the following element values.
** NONE: The first value must not match any of the following element values.
===============================

.Example: If the iban contains a "GB" or "FR" (iban from France or Great Britain) than replace the account owner
----
<policy id='urn:policy:banking-demo:containsExample'>
  <mechanism event='urn:action:banking-demo:get-accounts'>
    <if>
      <contains mode='EXACTLY_ONE'>
        <event:number eventParameter='accounts' default='0' jsonPathQuery='$.accounts.iban'/>
        <constant:string value='GB'/>
        <constant:string value='FR'/>
      </contains>
      <then>
        <modify eventParameter='accounts' method='replace' jsonPathQuery='$.accounts.owner'>
          <parameter:object name='replaceWith' value='xxxxxx'/>
        </modify>
      </then>
    </if>
  </mechanism>
670
671
672
</policy>
----

Raj Shah's avatar
Raj Shah committed
673
=== eventHasParameter
674

Raj Shah's avatar
Raj Shah committed
675
676
To check if an event has a certain parameter the *<eventHasParameter>* element can be used.
Like the <regex> and the <contains> element the <eventHasParameter> has the following mode attribute:
677

Raj Shah's avatar
Raj Shah committed
678
options='header']
679
680
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
Raj Shah's avatar
Raj Shah committed
681
|mode         |enum      |ALL           |no       |The mode declares how many child element must match. Possible modes are ALL, EXACTLY_ONE, AT_LEAST_ONE, NONE.
682
683
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
684
Because <eventHasParameter> only evaluates strings it can only have child elements which return string values.
685

Raj Shah's avatar
Raj Shah committed
686
687
688
689
690
.Policy Specification Rules
[CAUTION]
===============================
* The *<eventHasParameter>* element must have at least one child element
===============================
691
692

.Policy Evaluation Rules
Raj Shah's avatar
Raj Shah committed
693
[IMPORTANT]
694
===============================
Raj Shah's avatar
Raj Shah committed
695
696
697
698
699
* The *<eventHasParameter>* element has four evaluation modes:
** ALL: All child element values have to be an event parameter.
** EXACTLY_ONE: Exactly one child element value has to be an event parameter, but not more than one.
** AT_LEAST_ONE: At least one child element value has to be an event parameter.
** NONE: No child element value has to be a event parameter.
700
701
===============================

Raj Shah's avatar
Raj Shah committed
702
.Example: Log event if user id is empty (event has no parameter $.id)
703
----
Raj Shah's avatar
Raj Shah committed
704
705
706
707
708
709
710
711
712
713
714
715
716
<policy id='urn:policy:banking-demo:eventHasParameterExample'>
  <mechanism event='urn:action:banking-demo:get-userForStats'>
    <if>
      <eventHasParameter mode='NONE'>
        <event:string eventParameter='user' default='' jsonPathQuery='$.id'/>
      </eventHasParameter>
      <then>
        <execute action='urn:action:banking-demo:logNotification'>
          <parameter:string name='message' value='user id is empty'/>
        </execute>
      </then>
    </if>
  </mechanism>
717
718
</policy>
----
Raj Shah's avatar
Raj Shah committed
719
720
////
=== continuousOccurrence
721

Raj Shah's avatar
Raj Shah committed
722
723
724
725
726
727
With the *<continuousOccurrence>* element it is possible to evaluate if an event occurred during a certain time interval or since a certain time for example.
Because the return value is a boolean value it is assigned to the boolean-functions.
However, a detailed documentation about <continuousOccurrence> can be found under the <<time-elements,time-elements>>.
////
[[string-functions]]
== string functions
728

Raj Shah's avatar
Raj Shah committed
729
The following element processes strings:
730

Raj Shah's avatar
Raj Shah committed
731
* <concat>
732

Raj Shah's avatar
Raj Shah committed
733
734
735
*<concat>* concatenates all values of child elements to a string.
The concat-function doesn't have an attribute.
It is possible to add all child elements which return a string, number, object, list or boolean or belong to the <<number-functions, number-functions>>, <<boolean-functions,boolean-functions>> or <<string-functions, string-functions>>.
736

Raj Shah's avatar
Raj Shah committed
737
.Policy Specification Rules
738
739
[CAUTION]
===============================
Raj Shah's avatar
Raj Shah committed
740
* The *<concat>* element must have at least one child element
741
742
===============================

Raj Shah's avatar
Raj Shah committed
743
.Example: This policy prevents showing data if complete employee name is not on the list of priviledged employees
744
----
Raj Shah's avatar
Raj Shah committed
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
<policy id='urn:policy:cs4:showEmployees'>
  <mechanism event='urn:action:cs4:showEmployees'>
    <if>
      <not>
        <contains>
          <pip:list method='urn:info:cs4:getAllPriviledgedEmployees' default='[]'/>
          <concat>
            <event:string eventParameter='user' default='' jsonPathQuery='$.firstName'/>
            <constant:string value=''/>
            <event:string eventParameter='user' default='' jsonPathQuery='$.lastName'/>
          </concat>
        </contains>
      </not>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
763
764
</policy>
----
Raj Shah's avatar
Raj Shah committed
765
766
767
////
[[time-elements]]
== time-elements
768

Raj Shah's avatar
Raj Shah committed
769
770
771
For the evaluation of system events in a certain time interval, it is necessary to be able to express different time specifications.
The time-elements are used to express these time specifications.
The elements *<continuousOccurrence>, <eventOccurrence>* and *<count>*, on the other hand, are used to evaluate these times.
772

Raj Shah's avatar
Raj Shah committed
773
The following elements are used to express times (specific times):
774

Raj Shah's avatar
Raj Shah committed
775
776
777
778
779
780
781
782
783
784
785
786
787
788
* thisMinute
* lastMinute
* thisHour
* lastHour
* today
* yesterday
* thisWeek (this week from Monday to Sunday)
* lastWeek (last week from Monday to Sunday)
* thisSunWeek (this week from Sunday to Saturday)
* lastSunWeek (last week from Sunday to Saturday)
* thisMonth
* lastMonth
* thisYear
* lastYear
789

Raj Shah's avatar
Raj Shah committed
790
Special cases are:
791

Raj Shah's avatar
Raj Shah committed
792
793
* start
* end
794

Raj Shah's avatar
Raj Shah committed
795
=== specific times
796

Raj Shah's avatar
Raj Shah committed
797
798
799
800
For evaluations for specific period of time the time-elements can be used.
For example if you want to evaluate the amount of fired events within the last hour, the <lastHour> element can be used.

.Policy Specification Rules
801
802
[CAUTION]
===============================
Raj Shah's avatar
Raj Shah committed
803
* The time-elements doesn't have child elements nor attributes (except for the <start> and <end>).
804
805
===============================

Raj Shah's avatar
Raj Shah committed
806
.Example: Inhibit action if event get-money was already fired more than 15 times in this minute
807
----
Raj Shah's avatar
Raj Shah committed
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
<policy id='urn:policy:banking-demo:ExamplePolicy'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <greaterEqual>
        <count>
          <eventOccurrence event='urn:action:banking-demo:get-money'/>
          <thisMinute/>
        </count>
        <constant:number value='15'/>
      </greaterEqual>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
823
824
825
</policy>
----

Raj Shah's avatar
Raj Shah committed
826
827
828
=== start and end
To execute an evaluation which only considers events which were fired starting at or before a certain point of time the *<start>* and *<end>* can be used.
The <start> and <end> elements have the following attribute:
829
830
831

[options='header']
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
832
833
|Attribute    |Type       |Required |Meaning
|time         |cron       |yes      |Declares the point in time for start or end.
834
835
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
836
837
<start> and <end> doesn't need to have a child element, although it is possible to add one <<eventOccurrence,<eventOccurrence>>> element.
If <start> or <end> has a <eventOccurrence> child element it means that the system evaluates the time interval since the first or the last event occurrence.
838

Raj Shah's avatar
Raj Shah committed
839
.Policy Specification Rules
840
841
[CAUTION]
===============================
Raj Shah's avatar
Raj Shah committed
842
* The <start> and <end> elements can have at maximum one <eventOccurrence> child element.
843
844
===============================

Raj Shah's avatar
Raj Shah committed
845
.Example: Inhibit action if event get-money was already fired more than 15 times since 01.01.2018
846
----
Raj Shah's avatar
Raj Shah committed
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
<policy id='urn:policy:banking-demo:getTransactionsExample'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <greaterEqual>
        <count>
          <eventOccurrence event='urn:action:banking-demo:get-money'/>
          <start time='1.1.2018 *:*:*'/>
        </count>
        <constant:number value='15'/>
      </greaterEqual>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
862
863
864
</policy>
----

Raj Shah's avatar
Raj Shah committed
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
== count
The *<count>* function is used to count the number of event Occurrences in a certain time or time interval.
With <count> it is possible to express the cardinal and temporal aspects of the policy language.
For instance, if you need to count the number of eventOccurrences within the last minute you can use the element <count>.
Therefore, it is necessary to specify the event with the eventOccurrence child element and the time with one of the <<time-elements,time-elements>>.

.Policy Specification Rules
[CAUTION]
===============================
* The <count> elements must have exactly one eventOccurrence and one of the <<time-elements,time-elements>> (or two if they are <start> and <end>) as child elements.
===============================

.Example: Inhibit action if event get-money was already fired more than 15 times since 01.01.2018
----
<policy id='urn:policy:banking-demo:getTransactionsExample'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <greaterEqual>
        <count>
          <eventOccurrence event='urn:action:banking-demo:get-money'/>
          <start time='1.1.2018 *:*:*'/>
        </count>
        <constant:number value='15'/>
      </greaterEqual>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
</policy>
----
896

Raj Shah's avatar
Raj Shah committed
897
== continuousOccurrence
898

Raj Shah's avatar
Raj Shah committed
899
900
901
902
903
With the *<continuousOccurrence>* element it is possible to evaluate, if an event occurred during a certain time interval or since a certain time for example.
As well as <count> it covers the cardinal and temporal aspects of the policy language.
But unlike <count> it checks if the event occurred continuously (once or more than once) and returns a boolean.
<continuousOccurrence> is needed to express 'during', 'always' or 'since' for example.
These are the attributes:
904

Raj Shah's avatar
Raj Shah committed
905
options='header']
906
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
907
908
909
910
|Attribute      |Type         |Required |Meaning
|interval       |String       |yes      |The interval declares the time interval in which an event has to occur to fulfill the condition.
|minOccurrences |number       |no       |Declares the minimum number of occurrences until the condition is fulfilled.
|maxOccurrences |number       |no       |Declares the maximum number of Occurrences that the condition is fulfilled.
911
912
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
913
914
Child elements can be all elements of the <<time-elements,time-elements>> and the <eventOccurrence> element.
With the child <eventOccurrence> the evaluated event is determined.
915

Raj Shah's avatar
Raj Shah committed
916
.Policy Specification Rules
917
918
[CAUTION]
===============================
Raj Shah's avatar
Raj Shah committed
919
* The <continuousOccurrence> elements must have exactly one eventOccurrence and one of the <<time-elements,time-elements>> (or two if they are <start> and <end>) as child elements.
920
921
===============================

Raj Shah's avatar
Raj Shah committed
922
.Example: If the user was not notified at least one time every day since thisWeek the event has to be inhibited
923
----
Raj Shah's avatar
Raj Shah committed
924
925
926
927
928
929
930
931
932
933
934
935
<policy id='urn:policy:banking-demo:continuousOccurrenceExample'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <continuousOccurrence interval='1d' minOccurrences='1'>
        <eventOccurrence event='urn:action:banking-demo:notify-user'/>
        <thisWeek/>
      </continuousOccurrence>
      <then>
        <allow/>
      </then>
    </if>
    <else>
936
      <inhibit/>
Raj Shah's avatar
Raj Shah committed
937
938
    </else>
  </mechanism>
939
940
941
</policy>
----

Raj Shah's avatar
Raj Shah committed
942
943
[[eventOccurrence]]
== eventOccurrence
944

Raj Shah's avatar
Raj Shah committed
945
946
947
The <eventOccurrence> element is used to evaluate how many times a event was fired. <eventOccurrence> is needed to specify the event.
For example <eventOccurrence> is needed if a system event should be inhibited if an event already occurred several times this week.
The element has the following attributes:
948
949
950

[options='header']
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
951
952
953
|Attribute      |Type      |Required    |Meaning
|event          |String    |yes         |Declares the event. The event id follows this pattern: urn:action:_scope_:_identifier_
|mode           |String    |no          |Possible values are "FIRST" or "LAST", to get the first or last eventOccurrence.
954
955
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
956
957
958
The <eventOccurrence> can have the elements from the <<parameter-group,parameter-group>>.

.Example: If the event occured more than 100 times this month than the event has to be inhibited
959
----
Raj Shah's avatar
Raj Shah committed
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
<policy id='urn:policy:banking-demo:containsExample'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <greater>
        <count>
          <eventOccurrence event='urn:action:banking-demo:get-transactions'/>
          <thisMonth/>
        </count>
        <constant:number value='100'/>
      </greater>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
975
976
</policy>
----
Raj Shah's avatar
Raj Shah committed
977
978
979
////
[[parameter-group]]
== parameter-group
980

Raj Shah's avatar
Raj Shah committed
981
982
The parameter elements are used for parameterizing PIP's of type string, number, object, list or boolean and for modifying and executing actions. Each element returns its value.
The following parameter-elements are available:
983

Raj Shah's avatar
Raj Shah committed
984
985
986
987
988
* <parameter:string>
* <parameter:number>
* <parameter:object>
* <parameter:list>
* <parameter:boolean>
989

Raj Shah's avatar
Raj Shah committed
990
The elements have the following attributes:
991
992
993

[options='header']
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
994
995
996
|Attribute    |Type      |Required |Meaning
|name         |String    |yes      |The name of the parameter.
|value        |String    |no, unless the parameter element doesn't have a child element      |The value of the parameter.
997
998
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
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

Depending on the return value there can be added diverse child elements.
For *<parameter:string>* and *<parameter:object>* you can add the following elements:

* all elements of <<pip-group,pip-group>>
* all elements of <<event-group,event-group>>
* all elements of <<variable-group,variable-group>>
* all elements of <<boolean-functions,boolean-functions>>
* all elements of <<number-functions,number-functions>>

For *<parameter:number>* you can add the following elements:

* all elements with number return value (<pip:number>, <variable:number>, <event:number>)
* all elements of <<number-functions,number-functions>>

For *<parameter:list>* you can add the following elements:

* all elements with list return value ( <pip:list>, <variable:list>, <event:list>)

For *<parameter:boolean>* you can add the following elements:

* all elements with boolean return value (e.g. <pip:boolean>,<variable:boolean>,<event:boolean>)
* all elements of <<boolean-functions,boolean-functions>>

.Example: When Role of User is Manager, then allow event
1024
----
Raj Shah's avatar
Raj Shah committed
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
<policy id='urn:policy:cs4:showUser'>
  <mechanism event='urn:action:cs4:show-project'>
    <if>
      <equals>
        <pip:string method='urn:info:cs4:getRoleByUsername' default=''>
          <parameter:string name='userId' value='1'/>
        </pip:string>
        <constant:string value='Manager'/>
      </equals>
      <then>
        <allow/>
      </then>
    </if>
  </mechanism>
1039
1040
1041
1042
</policy>
----


Raj Shah's avatar
Raj Shah committed
1043
1044
[[pip-group]]
== pip-group
1045

Raj Shah's avatar
Raj Shah committed
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
The pip elements are used to request information from a PIP. Each element returns their value (String, number, object, list, boolean). The parameters that can be added as child elements are sent to the PIP as request parameters.

The following pip elements are available:

* <pip:string>
* <pip:number>
* <pip:object>
* <pip:list>
* <pip:boolean>

The elements have the following attributes:
1057
1058
1059
1060

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
Raj Shah's avatar
Raj Shah committed
1061
1062
1063
|method         |String    |-             |yes      |The name of a PIP method.
|default        |depends on pip type (string, number, boolean)   |-             |yes       |The value that is returned if the PIP is not reachable.
|ttl            |time interval notation    |-            |no         |The "time to live" value sets the time interval that the response value of the PIP is cached. The ttl has a special notation, for example if the pip value should be cached for 1 week, 4 days and 2 hours it would look like "1w4d2h".
1064
1065
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
All elements of the <<parameter-group,parameter-group>> can be child elements.

.Policy Evaluation Rules
[CAUTION]
===============================
* During the "time to live" caching time interval, the pip-elements only returns the cached value. When the time to live has elapsed, the cache is refreshed by the current value retrieved by the PIP for the next interval.
* If the "time to live" caching time interval is not set, then the PIP is requested on each PIP element evaluation.
===============================

.Example: If logged User has Role Banker then replace transactions with XXX
1076
----
Raj Shah's avatar
Raj Shah committed
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
<policy id='urn:policy:banking-demo:getTransactions'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <and>
        <equals>
          <constant:string value='Banker'/>
          <pip:string method='urn:info:banking-demo:checkRole' default=''>
            <parameter:number name='loggedUser'/>
          </pip:string>
        </equals>
        <constant:true/>
      </and>
      <then>
        <modify eventParameter='transactions' method='replace'>
          <parameter:object name='replaceWith' value='XXX'/>
        </modify>
      </then>
    </if>
  </mechanism>
1096
1097
1098
</policy>
----

Raj Shah's avatar
Raj Shah committed
1099
1100
1101
1102
[[event-group]]
== event-group

The event elements are used to get parameter values from the event.
1103

Raj Shah's avatar
Raj Shah committed
1104
The following event elements are available:
1105

Raj Shah's avatar
Raj Shah committed
1106
1107
1108
1109
1110
1111
1112
* <event:string>
* <event:number>
* <event:object>
* <event: list>
* <event:boolean>

The elements have the following attributes:
1113
1114
1115

[options='header']
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
1116
1117
1118
1119
|Attribute              |Type                                           |Required |Meaning
|eventParameter         |String                                         |yes      |The name of an event parameter.
|default                |depends on pip type (string, number, boolean)  |yes      |The value that is returned if the event is not reachable.
|jsonPathQuery          |String                                         |no       |The JSONPath expression to be executed on the parameter value, if the value is a complex object. Please refer to http://goessner.net/articles/JsonPath/ for more information about JsonPath.
1120
1121
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
1122
.Example: If customerId is 1 then replace transactions with XXX
1123
----
Raj Shah's avatar
Raj Shah committed
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
<policy id='urn:policy:banking-demo:getTransactions'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <equals>
        <event:number eventParameter='customerId' default='1'/>
        <constant:number value='1'/>
      </equals>
      <then>
        <modify eventParameter='transactions' method='replace'>
          <parameter:object name='replaceWith' value='XXX'/>
        </modify>
      </then>
    </if>
  </mechanism>
1138
1139
1140
</policy>
----

Raj Shah's avatar
Raj Shah committed
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
.JSONPath
[TIP]
===============================
* JSONPath is an instrument to query JSON structures. JSONPath uses special notation to represent nodes and their connections to adjacent nodes in a JsonPath path.
* Notation to get the value of a transaction: $.transactions.amount.value
===============================

[[constant-group]]
== constant-group

The constant elements are used for defining a string, number, object, list or boolean constant that returns the specified value.
1152

Raj Shah's avatar
Raj Shah committed
1153
The following constant elements are available:
1154

Raj Shah's avatar
Raj Shah committed
1155
1156
1157
1158
1159
1160
1161
1162
1163
* <constant:string>
* <constant:number>
* <constant:object>
* <constant:list>
* <constant:boolean>
* <constant:true>
* <constant:false>

The constant elements (except true and false) have the following attributes:
1164
1165
1166

[options='header']
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
1167
1168
|Attribute    |Type                                                 |Required |Meaning
|value        |depends on constant type (string, number, boolean)   |yes      |The value of the constant.
1169
1170
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
1171
.Example: If Role is Banker, then inhibit action
1172
----
Raj Shah's avatar
Raj Shah committed
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
<policy id='urn:policy:banking-demo:getTransactions'>
  <mechanism event='urn:action:banking-demo:get-transactions'>
    <if>
      <equals>
        <pip:string method='urn:info:banking-demo:checkRole' default=''/>
        <constant:string value='Banker'/>
      </equals>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
1185
1186
1187
</policy>
----

Raj Shah's avatar
Raj Shah committed
1188
1189
[[variableDeclaration-group]]
== variableDeclaration-group
1190

Raj Shah's avatar
Raj Shah committed
1191
1192
1193
A <policy> element can have an unlimited number of variableDeclaration elements.
 These tags define a variable, which might be used several times in a policy.
 The following variableDeclaration-elements can be used:
1194

Raj Shah's avatar
Raj Shah committed
1195
1196
1197
1198
1199
1200
1201
1202
* <variableDeclaration:string>
* <variableDeclaration:number>
* <variableDeclaration:object>
* <variableDeclaration:list>
* <variableDeclaration:boolean>

Every element returns the specific value (e.g. string, number).
The declaration elements have the following attributes:
1203
1204
1205

[options='header']
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
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
|Attribute   |Type     |Required |Meaning
|name        |String   |yes      |The reference name to use the declaration.
|======================================================================================================================================

The following child elements can be added for *<variableDeclaration:string>*:

* all elements from <<pip-group,pip-group>>
* all elements from <<variable-group,variable-group>>
* all elements from <<constant-group,constant-group>>>
* all elements from <<event-group,event-group>>
* all elements from <<boolean-functions, boolean-functions>>
* all elements from <<number-functions, number-functions>>
* all elements from <<string-functions, string-functions>>

The following child elements can be added for *<variableDeclaration:number>*:

* all elements with number return value (eg. <pip:number>, <event:number>)
* all elements from <<number-functions, number-functions>>

The following child elements can be added for *<variableDeclaration:boolean>*:

* all elements with boolean return value (eg. <pip:boolean>, <event:boolean>, <constant:true>)
* all elements from <<boolean-functions, boolean-functions>>

The following child elements can be added for *<variableDeclaration:object>*:

* all elements with object return value (eg. <pip:object>, <event:object>)

The following child elements can be added for *<variableDeclaration:list>*:

* all elements with list return value (eg. <pip:list>, <event:list>)

.Example: If event 'get-bankusers' is fired and logeed user is a customer then inhibit action, if event 'getTransactions' is fired and logged user is a banker then modify the values
----
<policy id='urn:policy:banking-demo:getTransactionsExample'>
  <variableDeclaration:string name='RoleLoggedUser'>
    <pip:string method='urn:info:banking-demo:checkRole' default=''>
      <parameter:number name='loggedUser' value='1'/>
    </pip:string>
  </variableDeclaration:string>
  <mechanism event='urn:action:banking-demo:get-bankusers'>
    <if>
      <equals>
        <variable:string reference='RoleLoggedUser'/>
        <constant:string value='Customer'/>
      </equals>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
  <mechanism event='urn:action:banking-demo:getTransactions'>
    <if>
      <equals>
        <variable:string reference='RoleLoggedUser'/>
        <constant:string value='Banker'/>
      </equals>
      <then>
        <modify eventParameter='transactions' method='replace'>
          <parameter:object name='replaceWith' value='XXX'/>
        </modify>
      </then>
    </if>
  </mechanism>
1270
1271
1272
</policy>
----

Raj Shah's avatar
Raj Shah committed
1273
1274
[[variable-group]]
== variable-group
1275

Raj Shah's avatar
Raj Shah committed
1276
1277
The variable elements are used as references to the variableDeclaration elements.
 They return their specific value:
1278

Raj Shah's avatar
Raj Shah committed
1279
1280
1281
1282
1283
1284
1285
* <variable:string>
* <variable:number>
* <variable:object>
* <variable:list>
* <variable:boolean>

Every element has the reference attribute:
1286
1287
1288

[options='header']
|======================================================================================================================================
Raj Shah's avatar
Raj Shah committed
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
|Attribute    |Type      |Required |Meaning
|reference    |String    |yes      |The reference name to the <<variableDeclaration-group,<variableDeclaration>>>.
|======================================================================================================================================

.Example: If logeed user is a customer then inhibit action
----
<policy id='urn:policy:banking-demo:getTransactions'>
  <variableDeclaration:string name='RoleLoggedUser'>
    <pip:string method='urn:info:banking-demo:checkRole' default=''>
      <parameter:number name='loggedUser' value='1'/>
    </pip:string>
  </variableDeclaration:string>
  <mechanism event='urn:action:banking-demo:get-bankusers'>
    <if>
      <equals>
        <variable:string reference='RoleLoggedUser'/>
        <constant:string value='Customer'/>
      </equals>
      <then>
        <inhibit/>
      </then>
    </if>
  </mechanism>
</policy>
----
////
[[timer]]
== timer

With a <timer> it is possible to fire events in a specified interval, independent from an actual event occurrence.
 A <timer> must contain at least one <<timeEvent,<timeEvent>>> element.
 A <timer> can have the following attributes:
[options='header']
|======================================================================================================================================
|Attribute      |Type       |Required |Meaning
|cron           |cron       |yes      |Describes the time interval to fire an event.
|description    |String     |no       |Description of the timer.
1326
1327
|======================================================================================================================================

Raj Shah's avatar
Raj Shah committed
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
[[timeEvent]]
== timeEvent

A <timerEvent> declares the event which should be fired from PMP to PDP in a specified time interval.
Child elements can be elements from <<parameter-group,parameter-group>>.
The <timeEvent> has the following attribute:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Required |Meaning
|action       |String    |yes      |Defines the event id.
|======================================================================================================================================
////