Rules Configurations

March 15, 2014 , by

A rule in Pistachio consists of one or more conditions and one or more results.
The rule framework executes each time a field associated with a rule is modified via the interface and on initial loading of the form if any rules are setup for the data model.

Setting Conditions

Each rule can contain multiple Conditions. For the rule's Results to execute, each Condition must be true. There are two categories of Condition Types, those that evaluate values and those that check user group assignments.

Condition Types

  • Value Equals The value being evaluated must match the one specified in Condition Value textbox.
  • Value Not Equals The value being evaluated must not equal the one specified in the Condition Value textbox.
  • Value Inside Range The value being evaluated must be equal to either the Start Value textbox or End Value textbox, or be between those two values. This condition type operates only with numeric and date values.
  • Value Greater Than or Equal To The value being evaluated must be greater than or equal to the value specified in the Condition Value value. This condition type operates only with numeric values or date values.
  • Value Less Than or Equal To The value being evaluated must be less than or equal to the value specified in the Condition Value textbox. This condition type operates only with numeric values or date values.
  • Value In List The value being evaluated must be contained within the value list specified in the Condition Value textbox; each value in that list must be separated by a semicolon.
  • Value Not In List The value being evaluated must not be contained within the value list specified in the Condition Value textbox; each value in that list must be separated by a semicolon.
  • Value Has Changed The value being evaluated has changed from the value previously stored in the database (or changed from a blank value, if the rules are being run on an "add" interface).
  • Value Has Not Changed The value being evaluated has not changed from the value previously stored in the database (or has not changed from a blank value, if the rules are being run on an "add" interface).
  • User In Group This condition evaluates whether the current user belongs to the specified Pistachio user group.
  • User Not In Group This condition evaluates whether the current user does not belong to the specified Pistachio user group.

Condition's Value Expression

The value being evaluated to match against the configured conditions can either come from

  • Test Structure Element - Provides a drop-down of fields in the active data model to evaluate the value from.Whenever this field is modified, the rules framework will execute.
  • Test Form Element - Here, you can specify the document's form element whose value you want to use. The format for specifying the form element is : fieldname. This feature is useful if a rule belonging to a child data model needs to check against a value contained in a parent data model's record.
  • Test Session Variable - will evaluate value from the provided session variable name. eg sessionVariableName
  • Test Formula - will evaluate value based on the provided formula. The format for specifying formula is: (##price## * ##quantity## * ##form:taxrate##) + 3.5
    • Use parentheses to denote order of operation
    • Placeholders can be used to denote field names from the data model, such as ##price## in the above example. A placeholder that begins with form: will plug in a value from the submitted form directly. A placeholder that begins with session: will plug in a value from the stated session variable directly.
      • ##record:record_id## is available to plug in the current key field value of the record.
      • ##activeuser:userid## is available to plug in the currently logged in Pistachio user id.
      • As of version 1.2.8
        • ##activeuser:user_ad_guid## plugs in the currently logged in Pistachio user Active Directory GUID.
        • ##activeuser:user_email## plugs in currently logged in Pistachio user name.
        • ##activeuser:user_name## plugs in currently logged in user's user name.
        • ##activeuser:user_full_name## plugs in currently logged in user's full name.
    • Supported mathematical operators : + - * / ^
    • A formula that begins with Select will be evaluated as a SQL statement and executed against the data model's data source.
  • Condition Value - The value to compare the result from the test condition ( from one of the above test conditions). Placeholders are accepted as of version 1.2.9
    • ##record:record_id## is available to plug in the current key field value of the record.
    • ##activeuser:userid## is available to plug in the currently logged in Pistachio user id.
    • ##activeuser:user_ad_guid## plugs in the currently logged in Pistachio user Active Directory GUID.
    • ##activeuser:user_email## plugs in currently logged in Pistachio user name.
    • ##activeuser:user_name## plugs in currently logged in user's user name.
    • ##activeuser:user_full_name## plugs in currently logged in user's full name.
    • ##<FieldName>## - Replace with the desired field name present in the data model.

The first filled out value expression in the above presented order will be selected by the rules framework.

Condition Results

If all of the conditions are true, then several results can be triggered. Many Result Types involve adjusting displayed structure elements. There are also Result Types that can trigger custom Java Scripts. Below are the available Result Types you can use.

  • Hidden The field specified for the Result Element will be hidden.
  • Visible The field specified for the Result Element will be visible.
  • Required The field specified for the Result Element will be required. This applies to field of type Data or Relationship.
  • Not Required The field specified for the Result Element will not be required.. This applies to fields of type Data or Relationship
  • Filter Select Element The lookup list of the field specified in the Result Element dropdown box will be filtered. The Lookup Table Filter Field Name textbox is used to specify the database field in the field's lookup table that will be set to a filtering value. The filtering values can come from a specified field, an explicit value, or a form element.
  • Unfilter Select Element The lookup list of the field specified in the Result Element dropdown box will be unfiltered. This Result Type is utilized to cancel out lookup list filtering that might have been carried out by another rule.
  • New Value The field specified in the Result Element dropdown box will be set to a new value. This Result Type applies to structure elements of type Data. It will either use a specified value or a specified formula that will compute a value. Placeholders available for new value:
    • now = DateTime.UTCNOW
    • user_name = User name of the logged in user
    • user_id = Internal Pistachio User Id of the logged in user
    • As of version 1.2.8
      • user_ad_guid = The ActiveDirectory GUID of the logged in user.
      • user_email = The email of the logged in user
      • user_full_name = The full name of the logged in user
  • Popup Message The text in the Result Value will be displayed as a JavaScript alert message. It is recommended that any rule utilizing this Result type also contain another result that insures the same popup message is not re-displayed.
  • Execute JavaScript The JavaScript specified in the JavaScript textarea will be executed.