Creating Vocabularies

Vocabularies contain all the information that 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 that for designing rules and the reason for generating both window and frame vocabularies is to split the rules into several small and simple frame ruleflows instead of having all the rules in a single big window ruleflow.

So rules should and in most cases can be placed in the frame rules by default unless there are cases where the conditions and actions reference fields from multiple frames or ribbons (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.

At runtime whenever a field is changed or a record is selected etc. it triggers the ruleflow execution for the frame and also the ruleflow execution for the window (if there are ruleflows 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 to generate. 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 - Vocabulary files with the .ecore extension. Rulesheet files with the .ers extension. Ruletest files with the .ert extension and the main ruleflow file with the .erf extension. All the rule files are 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 JavaScript files. The JavaScript should not and cannot 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 with all the rule files. The root directory also contains directories for every generated ruleflows containing the .js files. The generated directory .js files are located in the root directory in part because this is their default location in the generate .js files dialog-box and would not require changing the value manually everytime.

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.

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 rulesheet file has a different suffix like _IsEnabled, IsVisible, _Pages etc. (see rulesheet design) and the ruletest start with the same name as their rulesheet including the suffix plus _Test (see ruletest design).

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).

Rulesheet Design

There are advantages and disadvantages to separating unrelated rules with unrelated conditions to a single rulesheet or combining them to a single rulesheet.

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

The general best practices from Progress is to use separate rulesheets 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.

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 rulesheets and rules which is also the same way the rule specification divides 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 rulesheets with a descriptive name suffix.

Unrelated conditions and actions in a single rulesheet 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 rulesheet covering all the combinations, and in either the frame or window rules but never both. Setting the same property in different rulesheets 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).

Continuing the guidelines above the fixed rulesheet should only be used for properties that have a fixed or constant value and should not be used for default values. The fixed rulesheet can also be used for setting custom properties by calling the custom JavaScript functions to fetch values.

In the message rulesheet, use the cellValue in the new message action and place the message in the cell for the action column.

Ruletest Design (Unit tests)

Ruletests are the first and best way to debug and track down problems even before logs. Every rulesheet should have at least one ruletest with the exception of the fixed rulesheet.

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

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 in 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 just 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 function 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).