Rule Vocabularies

Vocabularies contain all the information which can be used in conditions and updated in actions. For example: The form field and the datasource field values we use in conditions, and the form field and page (tabs) enabled and visible properties we can set in actions.

Vocabularies can be generated either for an entire window and everything in it (all the datasources, forms, pages and ribbons) including nested frames, or just a frame with everything in it but not including nested frames so frame vocabularies are much smaller and simpler than window vocabularies which can be very big.

The guidelines for designing rules and the reason for generating both window and frame vocabularies is to split the rules into several small and simple frame rule flows instead of having all the rules in a single big window rule flow.

So rules should and in most cases can be placed in the frame rules unless there are cases where the conditions and actions reference fields from multiple frames or ribbons (ribbons are usually in the widow) etc. which are less common (or if there are no frames only windows).

In other words, use frames whenever you can and windows when you have to so make sure both the frame and windows vocabularies were generated.

Note: At runtime whenever a field is changed or a record is selected etc. it triggers the rule flow execution for the frame and also the rule flow execution for the window (if there are rule flows for the window and frame) incase the are rules in the window that are also effected.

There is currently no need or use case to change the default values when generating a vocabulary.

The Generate Vocabulary window creates a vocabulary file with the same name as the window or frame and the .ecore extension. Currently the file is saved out to the pasoe temp directory (c:\temp at OSIV). After the vocabulary file is generated, copy the file to your workspace (see file and directory structure).

Note that currently generating vocabularies for big windows can take 5 or more minutes. Generating vocabularies for frames is much faster.

In addition, the layout designer sets the RulesBehaviour and RulesMetadata properties for the window and the frame. These properties contain metadata and advanced options. There's currently no need or use cases to change these properties except when removing a ruleflow by deleting or setting an empty JSON object "{}".

Files and Directory Structure

There are 4 main rule file types and file extensions -

• Rule Vocabulary files with the .ecore extension.
• Rule Sheet files with the .ers extension.
• Rule Test files with the .ert extension
• Rule Flow files with the .erf extension.

If you open any of the rule files in a text editor like Notepad++ you can see they are all XML files.

In addition, there are also the generated JavaScript files (minified .js files) used at runtime. The rule files are the only and absolute source of truth for the generated .js files. The .js files should not be modified manually.

The rules root directory is located in the osiv-webui/Rules directory (in the frontend project repository).

The root directory contains a Ruleflows directory for all the rule files. The Ruleflows directory is organized into directories according to categories similar to the ClientLogic and OSIV3G source directories. For example: Entscheid, Sendung, Stamm etc. directories.

The root directory also contains directories for every generated window or frame rule flows (with the .js files). The generated directories (with the .js files) are located in the root directory partly because this is the default location in the Corticon Generate Ruleflow dialog-box and saves the need to change the value manually every time.

Guidelines

• Open the Corticon.js Studio in the root rules directory, in <environment>/osiv-webui/Rules.
  
  
• All the rule files for a window or frame should be placed in a single directory with the same name (inside the correct Ruleflows category directory).
  
  
• All the rule files should start with the same name as the window or frame (there is only one vocabulary and one workflow files so they should have the same name as the window or frame).
  
  
• Every rule sheet file should have a different suffix like _IsEnabled, _IsVisible, _Pages etc. (see rule sheet design).
  For example: EntscheidDetailWindow_IsEnabled
  
  
• Rule test files should start with the same name as their rule sheet including the suffix plus _Test or _Test<number> for multiple rule tests (see rule test design).
  For example: EntscheidDetailWindow_isEnabled_Test.
  
  
• Generate the .js files directory in the root rules directory which is default location of the Corticon Generate Ruleflow dialog-box.

Git

Currently the .js files are included in the git repository and need to be committed instead of being generated in the build. There is a risk of the rules and .js files not matching in this approach. For example: if the rules were updated and someone forgot to generate the .js files.

Incase the .js files will need to be generated in the build the script files in the akioma corticon-java project can be used to generated the .js files (see the in Corticon integration guide).

Rule Sheet Design

There are advantages and disadvantages to separating unrelated rules with unrelated conditions to separate rule sheets or combining them to a single rule sheet.

On the one hand keeping unrelated rules in separate rule sheets allows for the best use of the Check for Conflicts and Check for Completeness features in Corticon but on the other hand having many rule sheets files with just one line rules is also unwanted.

The general best practices from Progress Software is to use separate rule sheets for complex conditions with many combinations and combine simpler rules into a single rulesheet to save on rulesheets files and are also where the Check for Conflicts and Check for Completeness is less needed. In other words, it's a balancing act.

Guidelines

• Taking into account that UI rules are usually made up of many simple rules it is decided to group the rules for a window or frame into the following rule sheets and rules (which is also the same way the rule specification at OSIV divided the rules) -
  
  
  • <window>_Fixed.ers - Fixed property settings.
  • <window>_IsEnabled.ers - Rules for enabling form fields (using the <field>__isEnabled property).
  • <window>_IsVisible.ers - Form fields visiblity rules (using the <field>__isVisible property).
  • <window>_Pages.ers - Pages (tabs) visiblity rules and enabling or disabling pages.
  • <window>_Messages.ers - Message rules (errors, warnings and info messages).
    
    
• With the following exception - if there are complicated rules with conditions containing more than 5 to 10 fields and many combinations then it is recommended to put these rules in a separate rule sheets with a descriptive name suffix.
  
  
• Unrelated conditions and actions in a single rule sheet should be separated with an empty row for clarity.
  
  
• A specific property, like, a form field is enabled property (or any other property) must be set in one place and one place only. The property must be set in one rule sheet covering all the combinations, and in either the frame or window rules but never both. Setting the same property in different rule sheets increases the risk of conflicts.
  
  
• Use the default action column whenever possible to decrease the number of condition combinations and simplify the rules. For example: if you set the default for the is enabled property to false then you only need to specify the condition combination when it is true (which in many cases is a single combination).
  
  
• Use an AND condition and the default the column instead of an OR condition for setting properties (because AND conditions use a single combination column and OR conditions use multiple combination columns which helps simplify and shorten rule sheets). 
  
  
• Continuing the guidelines above the fixed rule sheet should only be used for properties that have a fixed or constant value and should not be used for default values. The fixed rule sheet can also be used for setting custom properties by calling the custom JavaScript functions to fetch values.
  
  
• In the message rule sheet, use the cellValue in the new message action and place the message in the cell for the action column.

Rule Test Design (Unit Tests)

Rule tests are the first and best way to debug and track down problems. Every rule sheet should have at least one ruletest with the exception of the fixed rulesheet. In addition, rule statements should be filled with a description for every combination to help debug what rules were triggered when running ruletests or at runtime.

You cannot have multiple separate tests in a single rulesheet and they must be separated to several ruletest files with the _Test<number>.ert suffix. Alternatively, use a single ruletest that can combines or triggers multiple rule conditions and actions.

When copying entities to the ruletest input column, remove unused fields that have no conditions to keep the ruletests simple and readable keeping in mind that some forms and datasources can have tens or even hundreds of fields.

Ruletests need to be incorporated and run as part of the build and pipeline unittests.

Ruleflow Design

Copy all the rulesheets to the ruleflow.

Even though the rulesheets have no dependencies except for special cases, the rulesheets should be connected in the following order - 1. fixed rulesheet, 2. is enabled rulesheet, 3. is visible rulesheet, 4. pages rulesheet, 5. messages rulesheet, 6 and above. if there are additional rulesheets (see rulesheet design guidelines).

With the exception if there are special cases with a different dependency or a more complicated ruleflow.

Packaging Rules for Deployment (Generating JavaScript Files)

There is currently no need or use case to change the defaults when generating the .js files except for setting the Platform to browser.

Corticon creates a directory in the rules root directory with the same name as the ruleflow (which is also the name of the window or frame) containing all the required files.

The Corticon runtime looks for the generated file in the same directory so there is no need to copy or manually move files.

The window and frame names are unique so there is no risk of conflicts.

Related UI Design

Guidelines

• If there are any related fields that should be updated when a dynSelect value is changed in a form or calculated fields in business entities then they should be added to the dynSelect mapping so the correct values are available for Corticon. This guideline is true when using Corticon as it is when writing TypeScript.

Incorporating Code (Advanced Cases)

Using code should only be used as a last resort and if there is no other choice. Whenever possible backend data should be taken from the business entity. If the data does not exist in the business entity, consider adding the fields or even creating another business entity with the required fields.

To run simple synchronous code like fetching data from the UI, Corticon.js supports JavaScript functions calls in rulesheets. You can create custom properties and set their values with JavaScript functions in the fixed rulesheet.

To run asynchronous code like backend calls, create a regular TypeScript event handler file that sets custom properties in the screen akEvent payload property and then calls the screen callRules() method to execute the screen rules (and the window rules).