= IND^2^UCE Policy Language Documentation - Version 3.2.46
Fraunhofer IESE
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 4
:sectlinks:
:stylesdir: ./css
:stylesheet: ind2uce.css
:linkcss:

[[introduction]]
= Introduction

This documentation is about the definition of *privacy policies* regulating security-relevant system events.

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

* Inhibition of system events
* Modification of system events
* Execution of compensating actions
* Time interval based executions of mechanisms (cron jobs)

Policies are based on Boolean logic and can make use of:

* Data contained in the monitored event
* External data sources (e.g. LDAP)
* The history of events

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.

.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"
[source,xml]
----
<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>
</policy>
----

[[language-elements]]
= Language Elements

[[policy]]
== policy

The *<policy>* tag is the root element of an IND²UCE security policy. It has the following attributes:

[options='header']
|======================================================================================================================================
|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.
|======================================================================================================================================

The *<policy>* tag must have at least one <<mechanism,<mechanism>>> child and can optionally contain <<variableDeclaration-group,variableDeclaration>> children.

.Example: The following policy describes the basic policy structure
[source,xml]
----
<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>
</policy>
----

[[mechanism]]
== mechanism

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.

The *<mechanism>* element has the following attributes:

[options='header']
|======================================================================================================================================
|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.
|======================================================================================================================================

A *<mechanism>* can have the following child elements:

* <<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.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* A specified <<execute,<execute>>> inside the <<mechanism,<mechanism>>> tag is triggered by the event, independently from the satisfaction of a condition.
===============================

.Example: The following policy inhibits access to accounts and loggs the action
[source,xml]
----
<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>
</policy>
----

[[if_elseif]]
== if, elseif

The *<if>* and the *<elseif>* elements declare the condition that is evaluated each time the mechanism fires.

A condition can have the following child elements:

* 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


.Policy Specification Rules
[CAUTION]
===============================
* 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.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* 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>.
===============================

.Example: Prohibits access to transactions after 3pm and loggs access to transactions between 2pm and 3pm
[source,xml]
----
<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

.Policy Specification Rules
[CAUTION]
===============================
* 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.
===============================

.Example: If role is banker *then* allow the event "get transactions" *else* inhibit
[source,xml]
----
<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>
      <inhibit/>
    </else>
  </mechanism>
</policy>
----

[[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.
|======================================================================================================================================

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

[[modify]]
=== modify

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

Child elements can be all elements of the <<parameter-group,parameter-group>>. The mandatory and optional parameters depend on the selected modifier method.

.Example: Replace the bank code number before showing it
[source,xml]
----
<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>
</policy>
----

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

[[execute]]
== execute

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.

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Required |Meaning
|action        |String   |yes    | The action to be executed.
|======================================================================================================================================

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.

.Example: Replace the account information before showing it and log the event
[source,xml]
----
<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'/>
        </modify>
        <execute action='urn:action:banking-demo:logNotification'>
          <parameter:string name='message' value='Log Message'/>
        </execute>
      </then>
    </if>
  </mechanism>
</policy>
----

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

.Policy Specification Rules
[CAUTION]
===============================
* <plus>, <minus>, <multiply> and <divide> must have at least two child elements.
===============================

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.

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

.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.
[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|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.
|======================================================================================================================================

Child elements can be all elements with boolean return value (e.g. <constant:true>, <event:boolean>) or elements of the <<boolean-functions>,boolean-functions>>.

.Policy Specification Rules
[CAUTION]
===============================
* The *<and>, <or>, <xor>* and *<implies>* elements must have at least one child element.
* The *<not>* element must have exactly one child element.
===============================

.Example: Inhibit transaction if user has id 1 *and* the transaction amount value is greater than 10.000
----
<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.
|======================================================================================================================================

Child elements can be all elements with boolean return value (e.g. <constant:true>, <event:boolean>) or elements of the <<boolean-functions>,boolean-functions>>.

.Policy Specification Rules
[CAUTION]
===============================
* The <valueChanged> and <valueUnchanged> element must have exactly one child.
===============================

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

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|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.
|======================================================================================================================================

A *<regex>* can have the child elements with string return value and elements from the <<string-functions, string-functions>>.

.Policy Specification Rules
[CAUTION]
===============================
* The <regex> element must have at least one child.
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* 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.
===============================

.Example: If the transaction prupose matches to "Gehalt", "Lohn", "salary" or "pay" than replace the amount
----
<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>
</policy>
----

=== contains

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

A <contains> element has the following attribute:

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

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.


.Policy Specification Rules
[CAUTION]
===============================
* 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,...).
===============================

.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>
</policy>
----

=== eventHasParameter

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:

options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|mode         |enum      |ALL           |no       |The mode declares how many child element must match. Possible modes are ALL, EXACTLY_ONE, AT_LEAST_ONE, NONE.
|======================================================================================================================================

Because <eventHasParameter> only evaluates strings it can only have child elements which return string values.

.Policy Specification Rules
[CAUTION]
===============================
* The *<eventHasParameter>* element must have at least one child element
===============================

.Policy Evaluation Rules
[IMPORTANT]
===============================
* 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.
===============================

.Example: Log event if user id is empty (event has no parameter $.id)
----
<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>
</policy>
----
////
=== continuousOccurrence

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

The following element processes strings:

* <concat>

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

.Policy Specification Rules
[CAUTION]
===============================
* The *<concat>* element must have at least one child element
===============================

.Example: This policy prevents showing data if complete employee name is not on the list of priviledged employees
----
<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>
</policy>
----
////
[[time-elements]]
== time-elements

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.

The following elements are used to express times (specific times):

* 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

Special cases are:

* start
* end

=== specific times

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
[CAUTION]
===============================
* The time-elements doesn't have child elements nor attributes (except for the <start> and <end>).
===============================

.Example: Inhibit action if event get-money was already fired more than 15 times in this minute
----
<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>
</policy>
----

=== 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:

[options='header']
|======================================================================================================================================
|Attribute    |Type       |Required |Meaning
|time         |cron       |yes      |Declares the point in time for start or end.
|======================================================================================================================================

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

.Policy Specification Rules
[CAUTION]
===============================
* The <start> and <end> elements can have at maximum one <eventOccurrence> child element.
===============================

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

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

== continuousOccurrence

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:

options='header']
|======================================================================================================================================
|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.
|======================================================================================================================================

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.

.Policy Specification Rules
[CAUTION]
===============================
* 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.
===============================

.Example: If the user was not notified at least one time every day since thisWeek the event has to be inhibited
----
<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>
      <inhibit/>
    </else>
  </mechanism>
</policy>
----

[[eventOccurrence]]
== eventOccurrence

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:

[options='header']
|======================================================================================================================================
|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.
|======================================================================================================================================

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
----
<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>
</policy>
----
////
[[parameter-group]]
== parameter-group

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:

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

The elements have the following attributes:

[options='header']
|======================================================================================================================================
|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.
|======================================================================================================================================


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


[[pip-group]]
== pip-group

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:

[options='header']
|======================================================================================================================================
|Attribute    |Type      |Default Value |Required |Meaning
|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".
|======================================================================================================================================

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

[[event-group]]
== event-group

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

The following event elements are available:

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

The elements have the following attributes:

[options='header']
|======================================================================================================================================
|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.
|======================================================================================================================================

.Example: If customerId is 1 then replace transactions with XXX
----
<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>
</policy>
----

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

The following constant elements are available:

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

[options='header']
|======================================================================================================================================
|Attribute    |Type                                                 |Required |Meaning
|value        |depends on constant type (string, number, boolean)   |yes      |The value of the constant.
|======================================================================================================================================

.Example: If Role is Banker, then inhibit action
----
<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>
</policy>
----

[[variableDeclaration-group]]
== variableDeclaration-group

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:

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

[options='header']
|======================================================================================================================================
|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>
</policy>
----

[[variable-group]]
== variable-group

The variable elements are used as references to the variableDeclaration elements.
 They return their specific value:

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

Every element has the reference attribute:

[options='header']
|======================================================================================================================================
|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.
|======================================================================================================================================

[[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.
|======================================================================================================================================
////