Effector 6.3 developer manual

XML reference 6.3

Effector Studio 6.3 summary

Effector Studio 6.3 manual

Effector 6.2 developer manual

XML reference 6.0

Effector Studio 3.2 summary

Effector Studio 3.2 manual

Rules

Rules (RuleValueType) can actually be viewed as miniature algorithms created to evaluate changing expressions. Often, we need values calculated in a particular way from the data of one or more existing objects, which calculations are defined by setting such rules.

It is common that certain data has to be displayed or hidden depending on the actual user group, or it has to be verified during work processes if certain data is properly entered or if the modification of a particular piece or set of data is allowed.

These tasks can be carried out by defining rules. Most frequently rules will return a true or false value once they are evaluated but there is a possibility to calculate and return other data types as well depending on application. Later we will discuss the configuration of rules in detail.

Rules

General procedure of processing rules:

  • 1: Getting the result of given rule(s) from the evaluator of the rule.
  • 2, 3: Obtaining rule definition
  • 4, 5: Using the data available, evaluating the rule based on its definition
  • 6: Providing results to the processing unit requesting evaluation.

Their location in the system

Rules span the operation of the entire system; thus, they don't have a dedicated configuration file, they have to be defined at the location of the use. Their location can be best illustrated by a connection diagram.

Rules in the system

In addition to their connections, rules can be grouped according to the method of their use. Groups are distinguished by node names related to specific uses. These can be the following:

  • Visible: Visibility rule. By its evaluation, it can be decided whether a given sub-unit will be visible or hidden. Its return value is strictly of boolean type. In case of a True value the given unit will be visible.
  • Readonly: Read-only rule. It determines whether the given data is modifiable or read-only. Its return value is strictly of boolean type. In case of True the data is read-only.
  • Required: Required field rule. With this we can configure whether a given data must be set or it is an optional field. Its return value is strictly True or False. In case of True the given field is mandatory.
  • WorkflowRequired: Required field rule attached to a workflow. It operates the same way as the Required rule with the exception that it is evaluated before the given workflow step is set to ready (that is before the value of the Done field is set to True). It is important to note that in such a case the editor screen must also contain a Task field (which may even be invisible)!
  • DefaultValue: : Default value rule. Its return value corresponds with the type of the given data. It gets evaluated when workflows and business objects are being constructed. These are used to set the default value of the ControlPanel Control field in case of grid-based displays (and graphs).
  • SessionValue: A rule used for the evaluation of the home icon (own value) found on input fields. This rule provides the default data of the given session. Its return value, similarly to the DefaultValue rule, matches the type of the given data.
  • ComputedValue: A rule used for the evaluation of a computed field. Its return value matches the type of the given data. It gets evaluated when the value of the control that triggers the computation changes. (If field B has a ComputedValue rule which refers to the value of field A and field A changes, the ComputedValue rule defined on field B gets evaluated.)
  • ComputedValueList: Applicable in case of drop-down lists only, this rule basically replaces the evaluated text with the 1=1 text in the SQL statement within the file (ComboDefinition) describing the value set of the drop-down list.
  • PlaceHolder: Placeholder text used to fill in empty fields can be specified with it.
  • ValidateRule: A rule used for validating the data of an input field. This rule has importance only in case of Form type views. If the rule’s return value type is of boolean and its value is invalid (false), a message specified in the message attribute appears. If the rule’s return value is ’string`, Effector displays the message that was returned by the rule. In such a case an empty text means that the value is valid.
  • Condition: A rule that can be used in case of workflows when moving from one state to a different one, and with which the individual steps can be bound to conditions. In addition, it can be used on the EditForm as well, but in such a case a Question node binds it together with the Message rule. In this case the Condition defines when the given massage be displayed.
  • Tooltip: It allows for displaying a message in the system. It gets activated when the mouse cursor hovers over it.
  • Warning: : It allows for displaying a message in the system. It gets activated when the mouse cursor hovers over it. Its icon is different from that of the Tooltip.

Example: Evaluation method of the default value (DefaultValue):

<DefaultValue type="Constant" return="int" default="0">Rule or value definition </DefaultValue>

Defining rules

The type attribute defines the type of the rule to be evaluated, the value of which can be any of the following:

-    `Constant`: definition of a constant rule with a specific value or by using references.
-    `Simple`: A rule containing a simple condition. It is evaluated by the JavaScript engine.
-    `SQL`: A rule evaluated on the database server.

The common attributes are:

  • The return attribute contains the type of the result returned after the evaluation of the rule. The system attempts to convert the result into this type. Its value may be:
    • int: simple integer (whole number)
    • boolean: logical value (True/False)
    • string: tex.
    • datetime: Date and time
    • float: floating-point number
  • The value set in the default attribute is returned by the system as a result if an error occurs during the evaluation of the given rule. If it is not filled in, the return value will be the default value of the specified type.

  • The isDecision attribute is used exclusively by the WorkflowRequired type of rules. Here it can be entered whether the given field of the process step defines a decision point. It is used by Effector Studio to continue the process depending on the value of this field.

  • The message attribute is used exclusively by the ValidateRule type of rules. Here, a message can be entered to be displayed if the computed value is invalid (false) or the rule returns a result that cannot be converted to a boolean value.

       <ValidateRule type=”SQL” return=”Boolean” default=”True” message=`This contact name for this company already exists!”>
       <![CDATA[    
           SELECT CASE WHEN
               (SELECT COUNT(*) FROM People WITH (NOLOCK) WHERE Name =`[##Field.Name##]` AND CompanyID = `[##Field.CompanyID##]` AND Deleted = 0 AND PeopleID != `[##Field.PeopleID##]`) > 0
                   THEN `False`
                   ELSE `True`
                   END
       ]]>
       </ValidateRule>
    

Useage

To define rules, nodes appropriate for specific rule types can be used. Though these can have various values, their structure is uniformly treated throughout the system. This rule definition will be uniformly referred to as of RuleValueType both in the document and the manual.

A rule can be evaluated in three ways (type attribute values)

  • Constant: It simply replaces the references in the rule. Such a rule can be evaluated both on client and server side. Example:
    • <Visible type="Constant" return="boolean">false</Visible>
    • <DefaultValue type="Constant" return="boolean">[##Session.UserID##]</DefaultValue>
  • Simple: After replacing the references in the rule, the system runs it on a JavaScript engine. The system then converts the value returned by the engine to the specified (return) type. Comparing two or more values is also possible ('[##Field.Mezo##]' != 200). It is a common configuration error that the value replacement rules are configured as simple, which is incorrect. For instance, the following is inaccurate: <Visible type="Simple" return="boolean">'[##Field.Mezo##]'</Visible>. In this case the following should be used <Visible type="Constant" return="boolean">[##Field.Mezo##]</Visible>. The <Visible type="Simple" return="boolean">false</Visible> rule is also incorrect. Instead, the <Visible type="Constant" return="boolean">false</Visible> expression should be used. Such a rule can be evaluated on the client as well as the server side. Example:
    • <Required type="Simple" return="boolean" default="false">'[##Field.Description##]' == '' || '[##Field.Description##]' == '0'</Required>
    • <ValidateRule type="Simple" return="boolean" default="false" message="A figure from 1 to 10 is an accurate value!"><![CDATA['[##Field.Grade##]' > 0 && '[##Field.Grade##]' < 11 ]]></ValidateRule>
  • SQL: The rule definitions of SQL type offer the widest range of options. Essentially any logic available in SQL and via references supported by the system can be implemented. SQL statement can be used freely even with the help of stored procedures or functions. The queries configured here will be evaluated on the SQL server storing the database. Example:
    • <DefaultValue type="SQL" return="datetime">SELECT GETDATE()</DefaultValue>
    • <ValidateRule type="SQL" return="boolean" default="" message="The responsible being cannot be a group!">SELECT CASE when IsGroup=1 and '[##Field.Done##]'='True' THEN 'false' ELSE 'true' END FROM People WHERE PeopleID ='[##Field.Responsible##]'</ValidateRule>

References to be used

References should be defined in this format: [##<group>.<field>##]. Field names that can be used for groups will be discussed in detail in the following section:

  • Field: the value of a business object field can be referenced here.

    Example: [##Field.PeopleID##] this shows the PeopleID field of the actual business object.

  • Session: details of the signed-in user can be accessed within the group, such as:
    • UserID (Integer): Unique identifier of the user.
    • UserName (String): User name of the user.
    • CompanyID (Integer): Unique identifier of the company rendered to the user.
    • CompanyName (String): Name of the company rendered to the user.
    • HostName (String): DNS name of the computer used to sign in.
    • ComputerName (String): Name of the computer used to sign in.
    • Language (String): Active locale identifier.
    • LongSessionID (Integer): LongSession identifier of the user.
    • IsDeveloper (Boolean): Does the user hold a developer license?
    • IsGuest (Boolean): Is the user signed in to a guest account.
  • Special: Other non-user specific constants. Possible field values are:
    • Today (DateTime): Timestamp (with date and time of day) in the format of the actual locale.
    • Date (DateTime): Actual date (without time of day) in the format of the actual locale.
    • Time (DateTime): Actual time of day (without date) in the format of the actual locale.
    • IsObjectEditListEnabled (String): If the IsObjectEditListEnabled function is turned on in the DBConnection XML, this field contains the list of names – separated by commas - of the users who are editing the object at the given moment.
    • ClickedButton (String): It is the identifier of the clicked button in case of rules whose evaluation is carried out after clicking on a button.
  • Filter: the value of a given returning filter. Example: [##Filter.Project_ID##]
  • Triggered: it is used with workflow steps only. In such a case the Field always contains the value of the BO where the workflow is initiated from, while the Triggered contains the BO fields of the workflow to be created.

  • Last update: 2 weeks 5 days ago
  • Effector