...

• 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 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 or frame>_IsEnabled.ers - Rules for enabling form fields.
  • <window or frame>_IsVisible.ers - Form fields visibility rules.
  • <window or frame>_Pages.ers - Pages (tabs) visiblity rules and enabling or disabling pages.
  • <window or frame>_Messages.ers - Message rules (errors, warnings and info messages).
    
    
• Complicated rules with conditions containing more than 5 to 10 fields and more than 5 to 10 combinations should be put in a separate rule sheets with their own descriptive name suffix.
  For example: EntscheidDetailBasisFrame_IsUnUpdatable.ers
  
  
• Use the vocabulary fields not expressions in the condition and action panes unless you have to.
  For example: In the condition pane, do not use EntscheidDSO.Visum_Dat = null. Use EntscheidDSO.Visum_dat and null in the cell value.
  For example: In the action pane, do not use EntscheidDSO.isAvailable = true. Use EntscheidDSO.isAvailable and T in the cell value.
  
  
• Beware of NULL's. Datasource field values are null when the record is not available so you may also want to add isAvailable and T cell value to your condition.
  For example: add EntscheidDSO.isAvailable and T cell value, to EntscheidDSO.Visum_dat and null cell value.
  
  
• 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. 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 combinations and simplify rule 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.
  
  
• Use an AND condition in combination with the default 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 while OR conditions use multiple combination columns). 
  
  
• 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 messages rule sheet, place the message text values in the cell action column and use the cellValue for the message parameter.
  For example: Message.new[type='info', entity='EntscheidDetailWindow', message=cellValue]
  
  
• Every rule action should have a rule statement with a simple description (the descriptions will not be shown to the user) used internally for debugging and understanding what rules were triggered (see rule tests design). No need to add a rule statement for the default column (column 0).
  
  
• Avoid dependencies - Avoid using calculated values from rule sheets. Only use values coming from the vocabulary.
  With the exception of Custom properties set with JavaScript functions (see incorporating code).

...

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 frame or window controller callRules() method to execute the screen rules.

Custom Events

The framework provides several entry points in the Corticon execution process:

• EventBeforeRuleExecution: will be run before the rules are executed
• EventAfterRuleExecution: will be run after the rules are executed
• EventAfterRuleApply: will be run after the rules execution payload is processed
• EventAfterRuleDisplay: will be run after the messages are displayed

The events can be specified from the Corticon 'RulesBehavior' attribute, using properties with the same name as the event.
The event format itself is identical with the other framework events, with 'self' referencing the rules' main window.
The payload is made accessible through the window's akEvent property. (akEvent.rulesExecution.payload)

Custom Properties

As of SWAT 21.14, the vocabularies will be generated with a new custom screen properties entity. (_CustomData.CustomScreenProperties)
By default the entity will be empty, it won't contain any properties.
To add screen properties, the 'RulesBehavior' attribute now accepts a new property 'CustomPropertyObjects', which will contain a comma-separated list of MATCHES patterns for repository data fields.
(ex. "field1,field2,fields*", which will match objects 'field1', 'field2' and all objects starting with 'fields')
All matching data field objects will be processed and a corresponding property will be added to the custom screen properties entity.
The role of this new entity is to provide an easy and accessible way to add custom properties to a vocabulary without risk of losing them on regeneration. (as it happens now for manually added ones)

The custom properties can be assigned from the Corticon custom events and to facilitate this, the following helper functions have been made available:

/**
 * Gets an entity from a given payload
 * @public
 * @static
 * @memberOf Corticon
 * @param {Object} payload The payload
 * @param {string} entityName The entity name
 * @returns {Object} The entity object from the payload or undefined if not found
 */
Corticon.getCustomScreenPropertiesFromPayload(payload);

/**
 * Gets the 'CustomScreenProperties' entity from a given payload
 * @public
 * @static
 * @memberOf Corticon
 * @param {Object} payload The payload
 * @returns {Object} The entity object from the payload or undefined if not found
 */
Corticon.getEntityFromPayload(payload, entityName);

Resources

• Progress tutorials (see link below) -
  https://www.progress.com/corticon/corticon-learning-center
  
  

• Corticon.js Integration Guide for DevOps (see link below) -
  For example: generate .js files and run unit tests from the command line)
  corticon_js_integration_draft.pdf
  
  

...