Product Documentation

General Syntax

Rules consist of an action and an optional condition. If a Condition is omitted, the action will always occur; otherwise the action will be taken if all the conditions are true.

Rules will have one of the following syntaxes:

• <Rule Action>
• if (<Rule Condition >) <Rule Action> ; <Rule Action>
• if (<Rule Condition > && <Rule Condition> ...) {
     <Rule Action> ; <Rule Action>
     <Rule Action> ; <Rule Action>
     <Rule Action> ; <Rule Action>
     <Rule Action> ; <Rule Action>
  }

There is also a special syntax for negative conditions:

if !(<Rule Condition >)

Rules also support the following conditional operators. These conditional operators will work with all numeric and date display field types. They also work as operators using a string compare operator when used with text and list display types.

Note: The condition(s) may extend over multiple lines, and are controlled by the parentheses.

Note: You may not set the value of the fields AREA and PROJECT with a load, refresh or clone directive.

Within the rules, all referenced fields must exist in the data dictionary, and must appear on the layout to which the rule applies. You cannot define variables or new fields "on-the-fly".

Assignment

By definition, all fields have a type, specified by its display type in the data dictionary. As with all other computer languages, assignments must be made between fields with the result being of the correct type. For example, you can assign a text field to another text field, but cannot assign a text field to a number field. However, you might assign the a value in a list field to a text field, as the individual values within the list field are of type text.

For the most part, automatic conversions are made between different data types. For example, if you assign a list type field to a text field, the display title of the list value is automatically provided and used. Similarly, if you assign a text field to a list value, then a reverse lookup is performed on the text value to populate the list field. Of course, if you make an assignment of this last type, then the value in the text field must correspond to an existing value of a list title else an error will be generated.

An important feature of rules within ExtraView is that you can only perform a single operation with a single rule. For example, to add two fields together (FLD_1 and FLD_2) and place the result in a third field (FLD_TOTAL) you must take two steps:

FLD_TOTAL = FLD_1;
FLD_TOTAL += FLD_2;

You cannot and must not use the form:

FLD_TOTAL = FLD_1 + FLD_2;

When applied to a repeating row field, the above syntax updates the field value on all repeating row fields. The following syntax demonstrates how you make an assignment to a repeating row field on a single row. Note that the repeating rows are numbered from zero, not from one.

Numeric Calculations

Assignment Operators:

Null numeric field values have special treatment. When a numeric field has a null value, and is being used in a calculation, it is assumed the value is zero. This avoids errors and null results occuring. However, tests on numeric type fields with value qualifiers such as numeric_field.{is null} and numeric_field.{not null} return true or false depending on whether there is a null value.

Text Operation Assignments

Date Calculations

Date calculations where you want to compute the difference between two dates, giving a numeric result are an exception to the above syntax. This is because you desire a numeric result and you cannot assign a date to a number without causing an error. The correct syntax to calculate the difference between two dates (DAT_1 and DAT_2) and place the result in the field DIFF is:

DIFF = (DAT1 - DAT2);

Date differences in rules may specify qualifiers to get results computed in units other than days. The qualifiers are {seconds}, {minutes}, {hours}, and {days}. Each of these results in an integral value after the date difference is computed. The fractional part of the computation is truncated, not rounded. This implies that the meaning is "the integral number of between the two dates".

Example:

You can specify a specific business calendar to use with date calculations. This is done with the calendar directive. For example, if you use the WEEKDAY calendar provided with ExtraView, and you have a calculation such as:

where SYSDATE is a Thursday, the result will be Tuesday, i.e. it is 3 workdays, plus the 2 weekend days.

If you add 0 to a date using a business calendar, the result will skip to the first work day beyond that date if that date is not a work day.

Null date and day field values have special treatment. When a date or day field has a null value, and is being used in a calculation, it is assumed the null date is January 1st, 1900. This avoids errors and null results occuring. However, tests on date and day type fields with value qualifiers such as date_field.{is null} and date_field.{not null} return true or false depending on whether there is a null value.

Date fields and Day Fields

Using a Day type field within a Business Rule is consistent when it is compared or combined in expressions with other Day type fields. When compared with Date fields, the Date is converted to a Day value using the user's time zone (to which the Date value is, by definition, relative) and the comparison is done with a Day field to Day field comparison or calculation.

Manipulating Multi-Valued List Fields

You may assign a single value to a multi-valued list field in exactly the same way you would assign a value to a standard list field. For each assignment of a value to a multi-valued field, you are effectively adding an additional selected value to the list. You can also use the following syntax to assign multiple values to a multi-valued list field at one time:

"IF" statements

IF statements allow the conditional processing of statements. For example, consider the following rule:

if (PROJECT = 'Customer Tickets')
  { ASSIGNED_TO = 'BSMITH' }

This will work equally well as a load rule, an onchange rule or a preupdate rule. It will not work as a postupdate rule, as no update will be made once the rule has been read and executed. Next, consider this rule:

if (PROJECT.{changed to:'Customer Tickets'})
  { ASSIGNED_TO = 'BSMITH' }

This will only work as an onchange or a preupdate rule, as it is during these times that changes can be detected.

Manipulating Accordion Folds with Rules

Accordion folds are described on the page Adding Accordion Folds to Layouts. You may use rules to set the initial state of an accordion fold to be open or closed, according to the rules described on that page.

Simple Examples

1. The following is a preload rule that sets the Status field to a value of Open and the Privacy field to a custom value. These will always execute, as there is no condition:

   <== load ==>
   STATUS=Open;
   PRIVACY=Engineering;

2. Here is an example of an ‘if’ statement with a single action line. The following assigns the issue to the Current User if the Originator is an internal user:

   if (USER.{is internal}) ASSIGNED_TO=USER;

3. A single action rule could also be written on more than one line and either the condition or the action can contain multiple parts, but the action will only consist of a single line.

   if (USER.{is internal} && ASSIGNED_TO.{is null} && STATUS = 'New' )
   ASSIGNED_TO=USER; STATUS=Open;

4. Here is an example of an ‘if’ statement with multiple action lines. An ‘if’ statement may have multiple lines of actions if these are enclosed in braces. The following rule sets a field named SUB_STATUS to a value of Needs Review, assigns the issue to a user named BSMITH, and sets the due date to the current day, but only if this is a New Customer Support issue entered by an external user:

   if (AREA=’Customer Support’ && STATUS=’Submitted’
   && ORIGINATOR.{is external}) {
   SUB_STATUS='Needs Review'; OWNER=ASSIGNED_TO;
   DUE_BY_DATE = SYSDAY;
   }