...
Creating 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.
...
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 (Workspace)
There are 4 main rule file types and file extensions -
...
In addition, the root directory contains directories for every generated window or frame rule flows containing the .js files. These directories are located in the root directory partly because this is the default location in the Corticon Generate Ruleflow dialog-box and it saves developers from changing the directory manually every time.
Guidelines
- Open the Corticon.js Studio in the root rules directory, in the /osiv-webui/Rules directory.
- 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.ers - 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.ert - Generate the .js files directory in the root rules directory which is also the default location in 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.
...
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 rule sheet to save on rulesheets rule sheets files and are also where the Check for Conflicts and Check for Completeness is less needed. In other words, it's a balancing act, just like writing code.
Guidelines
Taking into account that UI rules are
...
mostly made up of many simple
...
rules and how the rules are divided in the specification at OSIV, the rules should be divided in the following way -
- Fixed property settings (for example: The form field ICD is always read-only or disabled).
- Rules for enabling form fields.
- Form fields visibility rules.
- Pages (tabs) visibility rules and enabling or disabling pages.
- Message rules (errors, warnings and info messages).
With the exception that complicated rules with conditions containing more than 5 to 10 fields and many combinations are put in a separate rule sheets with their own descriptive name suffix.
Guidelines
- Place rules in the frame rule flow whenever you can and the window rule flow whenever you have to for the purpose of dividing the rules into many simple frame rule flows instead of one big and complicated window rule flow (see creating vocabularies).
- Divide the rules into the following rule sheets and rules (which is also the same way the rule specification at OSIV divided the rules) -
<window>rule sheet names (unless they have no rules. There's no need for empty rule sheets) -- <window or frame>_Fixed.ers - Fixed property settings.
- <window><window or frame>_IsEnabled.ers - Rules for enabling form fields (using the <field>__isEnabled property).<window>
- <window or frame>_IsVisible.ers - Form fields visiblity rules (using the <field>__isVisible property).<window>visibility rules.
- <window or frame>_Pages.ers - Pages (tabs) visiblity rules and enabling or disabling pages.
- <window><window or frame>_Messages.ers - Message rules (errors, warnings and info messages).
- With the following exception - if there are complicated Complicated rules with conditions containing more than 5 to 10 fields and many combinations then it is recommended to put these rules should be put in a separate rule sheets with a their own descriptive name suffix.
Unrelated conditions and actions in a single rule sheet should be separated with an empty row for clarity.For example: EntscheidDetailBasisFrame_.ers - 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 . 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 rulesrule sheets.
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 in combination with the default the column instead of an OR condition for setting properties to decrease the number of combinations and simplify rule sheets (because AND conditions use a single combination column and while OR conditions use multiple combination columns which helps simplify and shorten rule sheets).
- Continuing the guidelines above the 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.
For example: if the specification says this form field is always enabled. - The fixed rule sheet can also be used for setting custom properties by calling the custom JavaScript functions to fetch values (see incorporating code).
- In the message _Message rule sheet, use place the cellValue message text values in the new message cell action column and place the message in the cell for the action column.use the cellValue for the message parameter.
For example: Message.new[type='info', entity='EntscheidDetailWindow', message=cellValue]
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.
...
Ruletests need to be incorporated and run as part of the build and pipeline unittests.
Ruleflow Design
Copy all the rulesheets to the ruleflow.
...
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.
...
The window and frame names are unique so there is no risk of conflicts.
Related DynSelect Setting
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.
...