.NET Assembly Schema

One of the most common methods of integrating InRule into a host application is to bind the rule application to a .NET assembly schema (aka .NET object model). Object-based integration provides the following advantages:

• Automated schema generation and synchronization based on .NET Assembly reflection
• Runtime state management allowing for custom business object instances to be used as rule engine state
• Incorporating object instance methods as custom authoring functions

A .NET Assembly schema is used to specify an assembly external to InRule containing types that will be used to define entities and fields in the rule app, and whose instance methods may subsequently be used from within rule expressions or using the Execute Method action.

To add the schema, click on the Schemas icon in the Navigation Pane and then click the Add button - > .NET Assembly Schema

The following is a description of the .NET Assembly Schema Edit form:

Name

Name of the schema. Derived from Assembly name on first assembly load.

Assembly

Specifies the assembly. At runtime, this assembly is searched for in the binaries, GAC and "EndPointAssemblies" subdirectory (unless otherwise configured) of the host application's binaries directory. (The host application is either irAuthor / irVerify or a custom application using irSDK). The default EndPointAssemblies directory for irAuthor is "Program Files\InRule\irAuthor \EndPointAssemblies".

The "…" selection prompts for an Assembly to load from the above directory by default. It's best to copy your assemblies to this directory in order to use irVerify, which looks for them there.

"Apply To RuleApp" must be subsequently selected in order to complete the synchronization of the rule app with the selected "Entity" classes and properties / fields.

Reload

Reloads the assembly information from the directory location described above. Use this to resynchronize the rule app with updated assembly information.

"Apply To RuleApp" must be subsequently selected in order to complete the synchronization of the rule app with the selected "Entity" classes and properties / fields.

Classes

Each public class in the specified assembly is shown.

The "Alias" column defines the rule app entity name if an entity class. Note this "Alias" name may be changed by clicking on it.

The "Entity" column, is selected for non-abstract classes having one or more usable public instance properties and / or fields, specifies whether this class and its selected public properties and/or fields should be synchronized with a rule app Entity and its Fields.

If an "Entity" class is selected, the data entity type for any selected data entity or data entity collection properties implementing the "IList" interface will be automatically selected, provided the data entity type is found in the Classes list for this assembly. All usable instance methods are available (always selected).

Use Intrinsic

This option is relevant only when there are .NET TypeConverter(s) recognized in the user's assembly for a given field. By default inRule treats these as an "intrinsic" (value) type on import, but the user has the option to uncheck this checkbox and have them treated as object (Entity) types. This option is read-only when a type-converter is not in play.

Apply to RuleApp

Synchronizes the selected Classes and Properties / Fields with the rule app schema. All existing same-named rule app Entities and Fields are preserved. A validation warning will occur when saving if Apply has not been run since the schema has last been refreshed via file, http or Reload. "Last Applied" indicates when this was last performed.

Advanced Settings

When clicked, the Settings > Advanced...button displays a form allowing you to configure various options about the assembly schema import.

• Enabling Bind Enum fields/ properties to value lists will populate the value list with the enumeration content and associate it with the appropriate field. [checked by default]
• Enabling Create Constraints for Enum fields/ properies will deny values that are not in the newly created value list. If this is checked, the Bind Enum fields/ properties to value lists must also be checked as the constraint cannot be enforced without an associated value list. Leaving this unchecked will allow users to import a .NET assembly schema containing enumerations without automatically creating these constraints. [unchecked by default]

Note: All settings will be saved with the rule application.

Any fields, collections or calculations not present and selected in the Assembly Properties / Fields set will be removed from the rule app for the selected Entity on Apply, except for "Temporary Storage" Fields, Collections and Calculations which may exist in the rule app schema without being selected in the End Point.

.NET Assembly State Refresh Options

Purpose of .NET Assembly State Refresh Options

When a rule application is bound to a .NET Assembly in irAuthor, the author has the option to incorporate instance methods on the object and use them to extend the available authoring functions and actions. Depending on how the method (or property in some cases) is written, it may have “side-effects” with regards to whether or not it modifies other property value(s).

When a method does have side-effects, if the property value(s) it modifies during the call are used as inputs into rule conditions or actions, the InRule rule engine needs to be aware of the fact that the value is subject to change and pull it into the Rule Engine Working Memory immediately after the method call. If not, rules may be processed with “stale” data.

The .NET Assembly State Refresh Options exist to provide the author with course (at the class level) or granular (at the method and property level) ways to tell the engine when it’s necessary to refresh values from the object (i.e. state). It allows users to optimize performance when the rule application is bound to a .NET Assembly and an object is passed into the engine at runtime.

Understanding the settings

By default .NET Assembly State Refresh is turned on for all bound fields. This conservative approach is by design to ensure the rule engine’s dependency network is aware of the changes that may have occurred within the method. It is the author’s responsibility to turn off state refresh if the methods being used by the rule engine have no side effects.

In general, minimizing the fields that are refreshed after the call can reduce overall processing time, especially for large bound schemas or when instance methods are called often. There are two ways to set the State Refresh Options in irAuthor: 1) at the class level and 2) at the method level. The next sections explain the process of telling the rules engine to only update specific fields specified by the user.

Setting at the class level

At the class level, the user has the option to turn state refresh options on or off for every method in the class. By clicking on the Refresh Options button in the .NET assembly schema import pane, two menu options are available to either “Mark all methods ‘refresh all’” or “Unmark all methods ‘refresh all’”.

Settings at the method level

To get more granular control over how state refresh occurs, users should use the refresh settings at the method level. By clicking on method, the user can then click on the Refresh Options button to get to the "RuleWrite Information" dialog. This dialog allows the user to control whether or not the method call action in InRule needs to refresh the working memory state with the updated object memory state (see screenshot below).

The setting "Refresh all bound objects" (which is enabled by default) instructs the runtime engine refresh the entire object state to working memory after each method invocation. This setting may be unchecked when it is known that the method will not result in underlying state changes that need to be refreshed.

In situations where the refresh is warranted, but performance is still of utmost consideration, individual fields can be designated for refresh rather than the entire object. Within the "RuleWrite Information" dialog, with "Refresh all bound objects" unchecked, one can explicitly list the fields that are to be refreshed when the method is called. Checking the "Enable Recursion" checkbox for an entity field will recursively refresh all of the entity's children.

General Guidance and Considerations

• In situations where there are no property and method side effects, .NET Assembly State Refresh Options should be turned off.
• In situations where there is a large object graph, there are method side effects, and those side effects update a lot of underlying values on the object, then “Refresh all bound objects” should be checked.
• In situations where there is a small or large object graph, there are method side effects, and those side effects update a small number of underlying values, then “Refresh all bound objects” should be unchecked and individual values should be specified in the “Rule Write Information” dialog.
• These optimizations are also obtainable by decorating your classes and/or methods with "InRuleImport*" attributes. For an example of how these attributes can be implemented and applied, please see our sample "Assembly Import using Attributes".
• The Refresh Fields Action is also available in rule authoring and can be used to selectively refresh field values to working memory.