Writing Rules

This topic explains the methods, mathematical operators and logical operators that can be used to create object, control, and question rules. The system allows simple and complex rules to be created. Simple rules execute only one action, while complex rules can execute several using a single condition. The methods supported by the system to write rules and the logical operators that can be used are detailed below.

EqualsTo

This method can only be used with List of Options questions and is used to test the response provided by the interviewee to a question with a single answer. A rule using this method is considered true when the response option selected by the interviewee is associated with the value defined in the rule for the question. The EqualsTo method accepts a single value as a parameter.

When response options are created for List of Options questions, each option is associated with a value. For example, consider question number 5 in a certain survey as "How often do you create a backup of your work?"

In this case, the following response options can be created for the question:

For this example, the condition Answer[5].EqualsTo("2") will be considered true if the interviewee selects the option "Monthly", associated with the value "2".

Contains

Similarly to the EqualsTo method, the Contains method is applied to List of Options questions; however, it is used to test the response provided to a question that accepts more than one answer. A rule that uses this method is considered true when the interviewee selects at least one of the response options associated with values specified in the condition. For example, the condition…

Answer[6].Contains("0","1","2","3")

… will be true if in question number 6 the interviewee selects at least one of the response options whose values are 0, 1, 2, and 3. Other options can also be selected, but all of the ones specified by the rule must be selected for the expression to be true.

In the first two columns of the table below, the rule Answer[1].Contains("A","B","C") will return "True" and the corresponding action in the associated control will be executed since all of the required options (A, B, and C) were selected by the interviewee. Note that in the second column, the interviewee selected other options and the rule was still considered true, since all the required options were selected. In the third column, the rule returned "False" and the corresponding action in the associated control was not executed since option C was not selected by the interviewee.

There, then, is a relationship between rules and questions, which is established by the question numbers. Note that for each question there is a unique number. When there is a condition such as…

If (conditions)

Answer[5].EqualsTo("0")

…the number 5 indicates that this rule refers to question number 5 that was included in the survey for which the rule is being created. The number 0 in EqualsTo("0") refers to the value of one of the response options created for the question. A single choice question may have the following response options:

If the interviewee selects the answer "Yes" for question number 5 in the survey, the value associated with this response will be 0. In this case, the condition Answer[5].EqualsTo("0") will be true, and the action specified in the rule will be executed. Similarly, if the interviewee selects the option "No", the value associated with this option is 3. In this case, the condition will be evaluated as false and no action will be taken.

When creating rule conditions for questions that accept only a single answer, only the EqualsTo method can be used, since in these types of questions there is only one possible response that can be selected by the interviewee. However, in multiple-choice questions, both the Contains and the EqualsTo method can be used, and in many cases it may be useful to combine the results of various methods through the use of Boolean operators (AND, OR, NOT) to form more complex expressions.

MoreCompliantThan

The MoreCompliantThan method is used to test the response provided by the interviewee for a Compliance question. Keep in mind that the response options for Compliance questions come from the response set associated with the survey in the project. Each option of the response set has an associated Compliance Index (%) and Compliance Level (Compliant, Partially Compliant, Not Compliant, Not Applicable). This way, each response selected for Compliance questions has an associated Compliance Index value ranging from 0 to 100%. The MoreCompliantThan method is used to compare the Compliance Index associated with the response given by the interviewee with a value defined as a parameter for the method (between 0 and 100). If the value associated with the response is greater than or equal to this value defined as a parameter for the method, the condition will be met. For example, the condition…

If (condition)

Answer[1].MoreCompliantThan("60")

…will be true if the response option selected for question 1 in the interview was associated with a Compliance Index greater than or equal to 60. Otherwise, the condition will be considered false. Every time the condition is true, the actions specified in the rule will be executed in the question. Note that in the condition…

If (condition)

Answer[1].MoreCompliantThan("0")

…the value "0", entered between parentheses, means that any answer provided by the interviewee will execute the actions defined in the rule, because all response options must be associated with a Compliance Index greater than or equal to zero.

ALWAYS

The ALWAYS method must be used in capital letters and should be written by itself in the If (conditions) field. It can be used so that the condition for any type of question always returns true, regardless of the answer provided by the interviewee. For example, you can create a rule using the ALWAYS method so that the evidence attached to a question will always be attached to a control, regardless of the answer provided by the interviewee.

The ALWAYS method is also useful in question rules. You can decide a certain question will always be visible by writing ALWAYS in the If (conditions) field and setting the Property field to "Visible" and the Value field to "True". You can then write an exception rule using EqualsTo, so that the question is always visible except if the response to question number 2 (Answer[2]) is "Yes", whose value is 1 (EqualsTo("1")). In this case, the rule using ALWAYS should be executed first in order not to conflict with the second.

Rules with Mathematical Operators

Mathematical operators can be added to the actions of object rules that have Number questions. These operators behave like mathematical operations that act directly on numerical values. Operators require that at least two numerical answers be used in the action-portion of a rule. The mathematical operators supported by the system are:

•    +: Mathematical operator that adds numerical values.

•    -: Mathematical operator that subtracts numerical values.

•    /: Mathematical operator that divides numerical values.

•    *: Mathematical operator that multiplies numerical values.

•    ^: Mathematical operator of exponentiation between numerical values.

•    max: Mathematical operator that selects the highest value from the listed answers. The example below shows a rule where the condition is always true and the action updates the Criticality field of an asset with the answer that has the highest numerical value.

WHEN (ALWAYS) DO

{

Asset.Criticality = Answer[1] max Answer[2] max Answer[3];

}

In the above rule, if the value of the first answer is 4, the value of the second is 3, and the value of the third is 5, then the expression identifies 5 as the highest numerical value and therefore, once executed, the rule will update the criticality of the asset to 5.

•    min: Mathematical operator that selects the lowest numerical value from the listed answers. The example below shows a rule where the condition is always true and the action updates the Relevance field of an asset with the answer that has the lowest numerical value.

WHEN (ALWAYS) DO

{

Asset.Relevance = Answer[1] min Answer[2];

}

In the above rule, if the value of the first answer is 1 and the value of the second answer is 3, then the expression identifies 1 as the lowest numerical value and therefore, once executed, the rule will update the relevance of the asset to 1.

Note: Answers used with mathematical operators must respect the numerical limits of each field. In other words, as the Criticality field accepts values ​​from 0 to 100, the rule will be valid only if the answers have values ​​within these limits. For example, in the Asset.Criticality = Answer [1] max Answer [2] expression, an answer with a criticality of 105 would make the rule invalid.

Rules with Logical Operators

Logical operators can be added to a rule, allowing more than one method to be used in the same condition and making it more complex. The logical operators supported by the system are as follows:

•    AND: Logical operator representing conjunction. When used within a rule with a compound condition, the condition will be true only when all of the propositions associated with the operator are also true. For example:

If (conditions)

Answer[1].EqualsTo("2") AND Answer[2].EqualsTo("3")

Then (actions)

Status of control 1234 = Implemented

The above rule states that if the option with the value of 2 is the only one selected in question number 1 AND if the option with the value of 3 is the only one selected in question number 2, then the status of control 1234 will be changed to "Implemented". Note that in this example the rule uses different questions to execute an action in a single control. A single rule may use various questions but will only act on a single control in a risk survey.

•    OR: Logical operator representing inclusive disjunction. When used within a rule with a compound condition, the condition will be true only when at least one of the propositions associated with the operator are true. For example:

If (conditions)

Answer [1].EqualsTo("0") OR Answer[2].EqualsTo("2") OR Answer[3].Contains("1","3")

Then (actions)

Status of control 1234 = Not Implemented

The above rule states that if the option with the value of 0 is the only one selected in question number 1, OR if the option with the value of 2 is the only one selected in question number 2, OR if options with the value of 1 and 3 are selected for question number 3, then the status of control 1234 will automatically be changed to "Not Implemented". Note that this compound condition combines the EqualsTo and Contains methods and evaluates the responses provided for three different questions.

•    NOT: Logical operator representing negation. This value inverts the value of true for the expression to which it is applied. For example, if the expression Answer[1].EqualsTo("0") is true, then the expression NOT Answer[1].EqualsTo("0") will be false.

As the expression Answer[1].EqualsTo("0") will only be true if the interviewee selects the response whose value is 0 for question number 1, its negation (NOT Answer[1].EqualsTo("0")) will be true if the interviewee selects any other response option whose value is not 0.

The operations using these operators are left-associative; that is, if there are more than two operators, the first to be evaluated will be the farthest left. The use of parentheses alters the precedence, as occurs in mathematical operations. In the expression…

Answer[1].EqualsTo("0") AND Answer[2].EqualsTo("2") OR Answer[3].Contains("1","3")

…the order the operators will be evaluated in is left to right (first AND, then OR).

Below are some additional examples for creating rules with compound conditions.

Example 1: Given a question that supports multiple responses whose number is 1 and whose response options are:

High – Value 0

Medium – Value 1

Low – Value 2

Very Low – Value 3

Suppose the interviewee must select the responses "High" and "Medium", whose values are 0 and 1, respectively, but cannot choose the option "Low", whose value is 2, in order for the condition to be considered true. In this case, the condition (If) of the rule may be expressed as follows:

If (conditions)

Answer[1].EqualsTo("0") AND Answer[1].EqualsTo("1") AND NOT Answer[1].EqualsTo("2")

Then (actions)

Status of control 1234 = Implemented

This expression will only be true if the interviewee selects the response options "High" and "Medium" in the question, whose values are 0 and 1, and at the same time does not select the option "Low" when answering the question. When the expression is true, the action for the rule will be to change the status of control 1234 to "Implemented".

Example 2: Given a question that supports multiple responses whose number is 5 and whose response options are:

A)   Always – Value 0

B)    Only when requested – Value 1

C)    Only when requested and approved by my manager – Value 2

D)   Never – Value 3

Suppose that the interviewee must select the options B and C, whose values are 1 and 2, respectively, but cannot select any other option for the condition to be considered true. In this case, the condition (If) of the rule may use the EqualsTo method twice in a compound expression. The condition would be expressed as:

If (conditions)

Answer[5].EqualsTo("1") AND Answer[5].EqualsTo("2")

Then (actions)

Status of control 1234 = Implemented

Note that in this case, the Contains method cannot be used, since if we used the expression Answer[5].Contains("1","2"), the condition for the rule would be true if the interviewee selected only the two options, but it would also be true if all the options were selected, and this was not what the condition was intended for.

Alternatively, the Contains and EqualsTo methods could be combined as follows:

If (conditions)

Answer[5].Contains("1","2") AND NOT Answer[5].EqualsTo("0") AND NOT Answer[5].EqualsTo("3")

Then (actions)

Status of control 1234 = Implemented

This expression will only be true if the user selected options "Only when requested" and "Only when requested and approved by my manager" but did not select either "Always" or "Never".