Schemas

Schemas define any external sources that you have imported entities from and that will be bound to the rule application. The three types of sources you can bind a schema to are:

• .NET Object Model
• XML
• and Database

.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 allows 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 then .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 is 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.

• Alias- This column defines the rule app entity name of an entity class. The "Alias" name may be changed by clicking on it.
• Entity- The Entity column, is selected for non-abstract classes having one or more usable public instance properties and/or fields and 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/properties 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]

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 that 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 the 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
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, you have 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

Use the refresh settings at the method level to get more granular control over how state refresh occurs.

Click on Method and then 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 to 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.

XML Schema

An XML Schema is used to synchronize the rule application schema with an externally defined XML Schema Definition (XSD). To add the schema, click on the Schemas icon in the Navigation Pane and then click the Add > XML Schema

The following is a description of the XML Schema Definition form:

Name

The logical name of the XML Schema Definition.

Opening a file from the File or HTTP dialog will import the XSD and display the entities it defines. Apply to RuleApp must be selected to actually apply and save the imported information. Read the article, Working with Entities for more information.

Load-from Path

Displays the last-loaded XSD path for this schema, if any.

This file does not have to be present after it is imported and applied in order to execute the rule application runtime.

Shortcuts 

• Use File to browse for an XSD from the file system
• HTTP to enter a URL path to an XSD.
• And the Reload button will force a resynchronization from the current XSD file. If there has been no change in the XSD file since the last load and apply, a confirmation message will appear.

Global Elements and Types

Lists the complex elements contained in the XSD file, and which ones are selected to be included in the rule app schema.

When a complex element is marked with a checkmark, any complex elements referred to by elements of the just-selected complex element are also automatically checked.

The rule app schema entity, complex field or complex collection name may be aliased by entering a custom value in the Entity / Complex column.

Local Elements

List the child elements for the currently selected complex elements, and which ones are selected to be included in the rule app schema.

When a local element which is a complex type is checked, the complex type is also automatically checked.

The rule app schema field or Collection name may be aliased by entering a custom value in the field column.

Rule app schema fields may be manually changed from field to Calculation.

Auto Select

Automatically selects other dependent global elements.

Deselect All

This deselects all global elements from the XSD.

Apply to RuleApp

Synchronizes the selected complex elements with the rule app. 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.

Any fields, collections, or calculations not present and selected in the XSD schema child elements 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.

View XSD

Loads the XML schema definition in a browser for viewing.

Advanced Settings

Import

• When enabled, Create Entities for anonymous xs:complexTypes will create an entity for nested complex types. When disabled, nested complex types will be nested as complex fields within the entity schema [enabled by default].
• Remove Orphaned Entities After Schema Reload indicates any entities left in an orphaned state after the user reloads the XSD will be removed. [unchecked by default]
• Enabling Bind xs:enumeration restriction fields 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 xs:enumeration restriction fields will deny values that are not in the newly created value list. If this is checked, the Bind xs:enumeration restriction fields 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 an XSD containing enumerations without automatically creating these constraints. [unchecked by default]
• Enabling Embed XSD in rule application will save the XSD along with the rule application. When an XSD is embedded in a rule application, the original XSD can be moved or it's filepath can be altered without affecting the ability to test or save the rule application. Any future changes to the XSD will still have to be manually reapplied to the rule application. [checked by default]
• Enabling Auto-include dependent cs:complexTypes [checked by default] will include related complex types even if they were not selected for inclusion in the Global elements and types grid.

Runtime

• Enabling Validate XML when loaded will perform validations on the XSD standard compliance including but not limited to XML namespace validity, custom Boolean formatting, and local date formatting. XSD validation will always occur on the loaded XML unless an endpoint override is specified at runtime. The endpoint override may specify the use of the embedded XSD or a URL/Filesystem path XSD. [checked by default]
• Enabling Allow Duplicate Instances will allow XML graphs containing duplicate entity instances to be loaded in either irVerify or in the irSDK object for calling the rule engine, RuleSessionState. For example, if a collection member is duplicated as another member in the same collection, loading this scenario into irVerify will cause errors unless this option is checked. When the option is selected, duplicate instances of the entities are permitted. [unchecked by default]

Validation Errors Tab

Any validation errors related to the XSD import are shown here.

Notes Tab

Allows free-form capture of text to describe the XSD

Database Schema

A Database Schema is used to synchronize the rule application schema with an external database.

To add the schema, click on the Schemas icon in the Navigation Pane and then click Add > Database Schema

The following is a description of the Database Schema Definition form:

Name

The logical name of the Database Schema Definition.

Connection String

Specifies the parameters the rule engine should use when connecting to this database such as the type of database server, the computer name or IP address, the database name, the user id, etc. This must be an "OLEDB" format connection string at authoring time (but may specified to be any type of connection string at runtime).

The button launches the connection string wizard to assist with the construction of a valid connection string.

Reload

Reloads the database schema information based on the connection string. Use this to resynchronize the rule app with updated database 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.

Apply to RuleApp

Synchronizes the selected tables and elements with the rule app. All existing same-named rule app Entities and Fields are preserved.

Last Applied indicates when this was last performed.

Any fields, collections, or calculations not present in the imported columns 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.

Show XSD

Displays the configuration of the schema in XSD format in a browser.

Deselect All

This deselects all checked tables in the schema configuration pane.

Options

Ignore Readonly Settings

When this option is checked, the readonly attribute of a column being imported will not be propagated to the corresponding schema field. For example, an identity column is typically a readonly column. If this option is checked and then the database schema is applied to the rule application, the corresponding field created in the schema will not be readonly. Therefore, during rule application execution values can be assigned to the schema field which corresponds to the identity column.

By default, this option is not checked and read-only settings are enforced.

Create Child Fields

If this option is checked, fields or collections are created to reflect one-to-one or one-to-many relationships, respectively. For example, for the following one-to-many relationship between Orders and Order Details.

Two entities will be created: Order_Details and Orders. The entity Orders will contain a collection called Order_Details whose members are of entity type Order_Details. If this option is not checked, the collection Order_Details will not be created.

This option is checked by default.