One aspect of irCatalog is the ability to support enterprise-scale management for authoring rule applications by offering functionality that enables granular check-in/check-out for elements of rule applications such as Schema, rule sets, data elements, and End Points. By leveraging irCatalog, the various rule elements are also available for sharing across multiple rule applications.

irCatalog operations are available at a rule application level by selecting the Catalog Tab:

Also, irCatalog operations may be available at an Item level, by right-clicking on a given item (i.e. Entity, rule, data, etc).

Please see the Overriding irCatalog Permissions topic from the irCatalog for Rule Management section for details on overriding irCatalog level permissions.

Catalog Icon Definitions

Small icons next to a rule element indicates its status.

•     - Currently checked-in
•    - Currently checked-out
•    - Newly added to a checked-out rule application
•   - Latest revision of the shared element
•     - Shared
•   - Shared item is bound to this rule application
•   - Shared item is bound to another rule application

Check-Out Operations

A check-out from irCatalog will prevent other users from modifying a rule application or rule element while it is being worked on by a user. The following elements within a rule application can be checked-out:

• Rule Flows
• Rule set Context, such as an Entity or independent rule set; checks out all rule sets in the context
• Rule set Folders; checks out all rule sets in the rule set Folder
• Rule sets
• User Defined Function Libraries
• Data Elements
• End Points Schemas (Includes the Schema elements from the "Schemas" Navigation Pane, Entities and Vocabulary)
• Entire rule application

To Perform Rule Application Level Check-outs

1. Select the Catalog tab.
2. Click the Check Out button. A form will be displayed giving you options on what you want to check out.
3. To undo checkout, Click the Undo Checkout button.

The following table lists the resulting elements that are checked-out with each option. Elements that can be added are also detailed for each option. The important thing to remember is that certain rule elements can be tied to an Entity structure like queries used in calculations or value lists used by Fields. When a Schema is checked-out, those tied elements are also checked-out.

1 You must also check out the rule application when checking out the Schema.

2 You can select the "All rule set and element items" without also selecting to check out the Rule application or schema. In addition, you can select to check out individual elements via the item's context menu in irAuthor. In this case, you cannot add any items to the rule application. You can only edit the elements that are checked-out.

To Perform Item Level Check-outs

1. From an open rule application, right-click on the item (rule set element, data element, etc.)
2. Select Check Out.
3. The Catalog icon for the item will change to the check mark icon.
4. To undo check out, right-click on the item and select Undo Checkout.

Check-out Considerations:

• A user has to perform a check-out on any rule application saved in irCatalog in order to make any changes to it.
• Item level check-out allows multiple users to work in the same rule application at the same time without overwriting each other's work.
• Rule application level check-out means that the rule application is checked-out exclusively. No other user can perform any check-outs on that rule application until it is checked back in.
• No single item can be checked-out by two different users at the same time.
• irAuthor supports undo changes / undo check out on checked-out items having pending changes, preserving other unsaved changes in the active rule application.
• Operations like insert, cut, copy and paste require the complete rule application to be checked-out.
• If the user tries a check-out on any other version but for the latest, the user will be prompted to get the latest rule application version from Catalog.

Check-In Operations

When a user is finished making modifications to a rule application or a particular item, they must perform a check-in operation to save the changes back to irCatalog. Subsequently, although an item is checked-in, it can only be modified by other users if it has been checked-in and is no longer checked-out to the original user.

To Perform a Rule Application Level or Item Level Check-in

1. Click Catalog to select the Catalog Tab.
2. Click the Check In button. A form will be displayed giving you options on what to check into irCatalog.
3. The following form will be displayed:

• Name: If the rule application has not been previously saved into irCatalog, the user can assign a name. Can only be entered if user selects Save As -> New
• Action:
  • Check In - Selecting Check In saves the changes as a revision in irCatalog. The option can be left unchecked if the rule application should be saved to irCatalog without being checked-in.
  • Leave checked out - Selecting Leave Checked Out retains the checked-out status of the rule application or rule element. If selected, the check mark icon will remain after the check-in. If not selected, the lock icon will displayed after the check-in.
  • Save to the user's workspace - The workspace is an additional irCatalog location set aside for each irCatalog user where that user can save a checked out rule application without having to check it back in.
    • This can be useful if the user has checked out a rule application and made some changes, but is not yet ready to check them in, and wants to close irAuthor and resume work at another time. The rule application can be saved to the user's personal workspace and the user can close out irAuthor. When reopening the rule application, it will be retrieved from the personal workspace, at which time the user can make additional changes, check it in, or undo the check-out.
    • The personal workspace is saved in the irCatalog database.
    • The rule application must stay checked out in order for the changes saved to the personal workspace to be retained. If an undo checkout is performed, the changes saved in the personal workspace will be lost.
    • The personal workspace is per irCatalog user, and can only be accessed when logged into irCatalog as the same user.
• Save as: If the rule application has not been previously saved into irCatalog, the user can declare the rule application as either New or a new revision to an existing rule application thereby performing a check-in for that rule application.
• Label: Enabling Labels allows the user to assign a new or existing label to the revision for deployment or management purposes. Requires that the revision be checked-in.
• Comments: The user can insert text that is saved along with the revision in irCatalog.

Check-In Considerations:

• A check-in operation will check in any other checked-out elements of the rule application.
• The user is required to check in any of the checked-out elements in order to save the changes made to the elements.
• A check-in operation disables all of the editing controls of that element until it is next checked out.
• Every check-in creates a new revision of the element. The revision number is displayed in the element name path in irAuthor.

Maintain Catalog

The Maintain command from the Catalog Tab in irAuthor enables management of v revisions in irCatalog. A user's ability to maintain irCatalog is dependent upon having the appropriate permissions to perform the maintenance functions.

To Open the Maintain Catalog Interface

1. In irAuthor, Select the Catalog Tab.
2. Click the Maintain button. The following form will be displayed.

All rule applications for the specified irCatalog environment will be displayed in the table. The following fields will be displayed:

Name

The rule application Name.

Label

Any labels assigned to the latest revision of the rule application.

Revision

The revision number for the latest revision of the rule application.

Checked-out by

If the rule application is currently checked-out, this will display the user who has the rule application checked-out.

Date modified

The last date and time the rule application was modified.

Description

The description of the rule application. This can be edited on the Settings page of the rule application within irAuthor.

The following actions are available from this view:

Undo Check-Out

Removes the checked-out status for the rule application revision. Changes made by users who performed the check-out are lost. You may only undo the check-out of items checked-out to you.

Activate

Removes inactive status from a rule application that was previously deactivated.

Delete

Presents a list of options for deleting or deactivating the rule application.

View History

Opens the revision history for a selected rule application.

Assign Label

Allows the user to assign a label to a rule application.

View Labels

Opens all revisions and their assigned label history for the selected rule application.

Include Inactive

Selecting this check box will include rule applications marked as inactive in the list of displayed rule applications.

Refresh

This causes the list of rule applications to refresh.

To Open a Specific Rule Application Revision

1. Select a rule application from the displayed list.
2. Click the View History button. The following form will be displayed:
   
   
   
3. Select a revision and click Open.

Label management functions are also available from this window.

To Assign a Label

1. Select a rule application from the displayed list.
2. Click the Assign Label button.
3. Enter a new label or select an existing one from the drop-down.
4. Click OK. The selected revision will show a new label and any revision that had the label previously assigned to will have the label removed.

To View Assigned Labels

1. Select a rule application from the displayed list.
2. Click on the View Labels button.
3. The Label Information form will be displayed.

The Label Information form shows any labels assigned to various revisions of your rule application. Here you may rename or remove labels.

To rename a label, select it and click Rename Label on the toolbar. Renaming a label will affect the label for all rule applications to which it is assigned.

To remove a label, select it and click Remove Label. This will remove the label from the rule application. In addition, if the label is not assigned to any other rule applications, it will be deleted.

Log Out of Catalog

The Log Out button from the Catalog Tab in irAuthor disconnects you from the currently connected irCatalog environment.

It does not disable all other irCatalog operations, but will simply require you to log in if any of those operations are selected.

The Log Out button will be disabled if you are not currently connected to an irCatalog environment.

If centralized authentication is enabled, this does not log you out of your centralized authentication session. It will only disconnect you from the currently connected catalog.

How to Avoid Timeouts When Opening or Saving Rule Applications to the Catalog

The following section describes how different parameters can affect irCatalog operations, which errors related to the timeouts and excessive resource consumption can occur, and how they can be avoided.

Catalog settings

The irCatalog service has configuration settings which allow to specify different timeouts for various irCatalog operations. There are two primary set of settings which can be configured according to the requirements:

• Client-side settings
• Server-side settings

Client-side settings

The irAuthor client-side settings are:

• Connection timeout. You may set this when you choose and log in to irCatalog, in the advanced options.

The connection timeout specifies the maximum allowed time per service call per irCatalog operation, such as opening or saving a rule application using the irCatalog service. When the timeout exceeds specified number, an error is thrown by the service.

The total operation time consists of the following components:

• Send time - is the time required to prepare the request for an action, to transfer the request to the service, and to receive an acknowledgment that the request is being delivered over a communication channel;
• Operation time - is the time required to complete the operation by the service and to prepare the response;
• Receive time - is the time required to deliver the response from the service to the client, and to confirm that it was delivered over a communication channel.

The following is an example of the programmatic setting for the connection timeout specified in the InRuleConnection constructor:

RuleCatalogConnection connection =
      new RuleCatalogConnection(new Uri("http://localhost/
InRuleCatalogService"), TimeSpan.FromSeconds(30));

Server-side settings

The irCatalog server-side settings are:

• MaxItemsInObjectGraph
• LockAcquisitionTimeoutInSeconds
• CommandBatchSize
• CommandTimeout

The MaxItemsInObjectGraph parameter sets the maximum number of items which may be serialized or deserialized in an object graph. Some rule applications may have a large number of elements, which can exceed the default number allowed to be sent to the irCatalog service. When this condition occurs, the irCatalog service throws an exception with the message "The number of items exceeds the maximum value.". This exception can occur when a Catalog operation such as a check-in or open is performed in the irAuthor application. In both cases, the MaxItemsInObjectGraph parameter can be modified from the default to avoid this error and to accommodate larger rule applications:

<inrule.repository.service>
      <maxitemsinobjectgraph>6000000</maxitemsinobjectgraph>
</inrule.repository.service>

The LockAcquisitionTimeoutInSeconds parameter specifies the maximum period of time to wait for a lock acquisition to complete. The service locking mechanism ensures that there is only one operation is modifying data related to a rule application. If a lock cannot be acquired when request is made, an error with the following message is thrown by the service: LockAcquisitionTimeoutInSeconds error. For some large rule applications the time required to complete an operation may increase and a lock is retained for a longer period. To avoid this, the LockAcquisitionTimeoutInSeconds parameter can be increased so that the client will wait longer for a lock to be acquired:

<inrule.repository.service>
       <lockAcquisitionTimeoutInSeconds>100</lockAcquisitionTimeoutInSeconds>
 </inrule.repository.service>

The CommandBatchSize parameter specifies the maximum number of sql statements per batch, when it is submitted to the database server. If rule application elements, such as data elements, endpoint schemas contain large amounts of the data, the batch size can be decreased to submit the data to the sql server in smaller blocks. If there are many small data elements in a rule application, the batch size can be increased to improve the performance. The following is an example of the setting configuration with this parameter specified:

<inrule.repository.service>
      <commandBatchSize>40</commandBatchSize>
 </inrule.repository.service>

The CommandTimeout parameter specifies the maximum allowed time per sql command, when it is submitted and completed by the database server. It is the time it takes to submit a chunk of the data and to retrieve a result from the database server. Large rule applications with large amounts of data may take longer to be processed by the server and can timeout. To change the setting and specify different value for this parameter the following can be added to the service configuration file:

<inrule.repository.service>
      <commandTimeout>30</commandTimeout>
 </inrule.repository.service>

In the following table specified the default values for each setting:

Examples

The following is an example of the available settings, which can be specified:

<inrule.repository.service>
       <maxitemsinobjectgraph>6000000</maxitemsinobjectgraph>
       <lockAcquisitionTimeoutInSeconds>100</lockAcquisitionTimeoutInSeconds>
       <commandBatchSize>40</commandBatchSize>
       <commandTimeout>30</commandTimeout>
 </inrule.repository.service>

Transport quotas

The irCatalog service provides a policy mechanism based on the infrastructure for deciding when a connection is consuming excessive resources. The available quotas prevent performance bottlenecks and improve the security of the service.

The transport MaxReceivedMessageSize property specifies the size of the messages that can be received on the wire. The message size is intended to prevent exposure to security risks and excessive memory utilization. The following is an example of the transport setting MaxReceivedMessageSize:

<system.serviceModel>
      <bindings>
          <wsHttpBinding>
                <binding
                     name="WSHttpBinding"
                     maxReceivedMessageSize="50000000">
                </binding>
          </wsHttpBinding>
      </bindings>
 </system.serviceModel>

The transport MaxStringContentLength property limits the length of strings that are created and returned by various components of the irCatalog service. This setting specifies the maximum string representation of the individual defs of a rule application and the entire rule application during open operation. The following is an example of the transport setting MaxStringContentLength:

<system.serviceModel>
       <bindings>
            <wsHttpBinding>
                 <binding
                         name="WSHttpBinding">
                    <readerQuotas
                          maxStringContentLength="50000000"/>
                 </binding>
             </wsHttpBinding>
        </bindings>
 </system.serviceModel>

Sharing Elements

irAuthor and irCatalog together provide sharing of elements in a rule application to facilitate reuse in other rule applications. Sharing elements designates that an element of identical structure and content can be used in completely separate rule applications.

With regard to promoting rule applications, shared items are local to the source catalog. Shared items are currently not propagated to the target Catalog when promoted in a multiple Catalog architecture.

Business Scenarios

The following describes some of the business scenarios where shared items are useful.

Many organizations have a need to share rules, data elements and data models across multiple applications. This need most often occurs for the following three types of organizations:

1. Large Organizations – Departments want systems that meet their specific needs. Alternatively, IT departments would like departmental systems to share a common framework so that maintenance and integration are easier.
2. Systems Integrators – Clients want as much pre-built functionality for their industry as possible. Except that they want to be able to change or override functionality in some places to maintain their unique competitive advantage.
3. Software Providers – Much like with systems integrators customers want software that is a close fit out-of-the-box. However, they also want the flexibility to configure the software for their own specific business needs.

Traditionally these often conflicting needs have been handled with custom programming. InRule provides functionality in irAuthor and irCatalog that allows companies to create flexible applications by combining new rules and elements with existing rules elements from other applications.

To better understand how InRule’s sharing functionality might be useful for you, we’ll explore how a company that provides a retail software solution could use it. Following is a diagram that gives a high-level overview of how the rules are organized in the catalog for this example:

With a model like this, new customers can choose to use rules that are applicable to them as building blocks for their new application. In areas where they want their application to work differently, they can create new sets of rules. For example, Electronics Source is going to leverage most of the software vendor’s out-of-the-box rules for Electronics and Movies & Music products. However, they specialize in home theater systems so they will use their own promotion rules for those systems.

As changes are made to the master rules and elements, the customers will have the option to pull those changes into their applications. For example, the software vendor might add new rules for detecting return fraud to their Return Policy Rules rule set. Since Stacy’s Boutique is a small business, return fraud is a major issue for them but they do not have the resources to create their own optimized return policy. They will be sure to get the latest return policy rules whenever they are made available by the software vendor.

Sharing

Sharing a rule element allows the element to be consumed in other rule applications. Once shared, the element is no longer considered "local" to the current rule application. In order to share an element, it must first be checked into irCatalog. By default, shared elements can be checked out by any consuming rule application. To control modifications of shared elements, a rule application can be set as the owner of the element by binding to it. Once an element is bound to a rule application, other consuming rule applications can no longer check out the element for modification.

Items that can be shared include the following:

• Rule Flows
• Rule Sets
• User Defined Function Libraries
• Data Elements
• End Points
• Schemas (Includes the Schema elements from the "Schemas" Navigation Pane, Entities and Vocabulary)

Share a Schema

1. Select the Catalog Tab
2. Click the Share Schema button
3. All Schema Elements (e.g. Schemas, Entities and Fields, Vocabulary) for the shared schema will now display the share icon

Share a Rule Element

1. Right-click on the rule element in the Navigation Tree
2. Choose Share
3. Shared items will now display the sharing icon

Inserting Shared Elements

After an element has been shared by a rule application, it is available to be inserted into other rule applications. When inserting a shared element, the search screen will automatically filter the view of shared items relative to the folder you are inserting into. For example, you will only see shared rule sets when inserting a shared rule set element.

Insert / Consume a Shared Schema

1. The consuming rule application must be saved in the Catalog and must be in a checked-out state
2. Select the Catalog Tab
3. Click Insert Shared Schema. A form will be displayed allowing you to find shared elements based on a search criteria.
4. Add relevant criteria or wild cards and click the Search button to view all shared Schema elements. The Name column indicates what type of shared elements are being displayed.
5. Select a Schema and click the Add button. Existing Schema items in the receiving rule application will be overwritten and a windows will appear allowing you to confirm this.
6. Click Yes and the receiving rule application Schema will be overwritten with the shared Schema definition. Entities and Fields and Vocabulary will also display the sharing icon.

Insert / Consume a Shared Rule Element

e.g. Rule Set

1. The consuming rule application must be saved in irCatalog and must be in a checked-out state.
2. Click on the Rules pane in the Navigation Bar
3. Click the Add rule set drop down, then select Add Shared rule set. A form will be displayed that will allow you to select the Rule Set context.
4. Select the appropriate Entity context for the rule set being inserted. The selected Entity context should match the Entity structure of the Rule Set being inserted. rule application compile errors will be displayed if Entities used in the shared Rule Set do not exactly match the receiving rule application Entity Rule Set context.
5. The Search dialog will be displayed.
6. Add relevant criteria or wild cards and click the Search button to view all shared rule set elements. The Name column indicates the rule set name of the shared elements that are being displayed.
7. Click Add and the shared rule set will be inserted and checked into irCatalog for the receiving rule application. The rule set will also display the sharing icon.

 For large irCatalogs databases, it is advised to apply a filter to the search via the "Name" column. Applying a search without any search criteria against a large irCatalog database could take a significant amount of time to produce results.

Unsharing

Unsharing brings a local copy of the element into the rule application and stops consumption of the shared element. Therefore, you will no longer be prompted for new revisions of the shared element.

Unsharing is NOT an option for the owner rule application (the application where the element is bound ). An unshare can only be performed in rule applications that are consuming the element (where it is not bound).

Unshare a Schema

1. Select the Catalog Tab.
2. Click the Unshare Schema
3. To complete the Unshare command, a check-in must occur. If there are other pending check- ins, you will have the option to check those in or cancel.
4. Once complete, the Schema elements will no longer display the share icon.

Unshare a Rule Element

1. Right-click on the rule element in the Navigation Tree.
2. Choose Unshare
3. To complete the Unshare command, a check-in must occur. If there are other pending check- ins, you will have the option to check those in or cancel.
4. Once complete, the unshared rule element will no longer display the share icon.

Binding

A rule application that shares or inserts shared elements from other rule applications can become the owner of those shared elements by binding to them.

When an element is shared and inserted among several rule applications and no single rule application has yet performed a Bind command, the shared element can be checked out and updated by any of the rule applications using the element.

Performing a Bind command for a shared element means that only the bound rule application can perform a check-out on that shared element. Other rule applications that inserted the shared element may not make changes to that shared element. Changes to the shared element made by the master rule application prompt other rule applications using the element to Get Latest Changes for that element.

Bind to a Shared Schema

1. The Schema must be shared and NOT bound to another rule application
2. Select the Catalog Tab
3. Click the Bind Schema button

In a bound state, the Schema cannot be unshared

Bind to a Shared Rule Element

1. The element must be shared and NOT bound to another rule application
2. Select the rule element in the Navigation Tree
3. Right-click on the item and select Bind to Rule Application

In a bound state, the element cannot be unshared

Unbinding

A rule application that shares or inserts shared elements from other rule applications can become the owner of those shared elements by binding to them. Similarly, an unbind command allows a rule application to give up ownership of a shared element. When an element is shared and inserted among several rule applications and no single rule application is bound to it, the shared element can be checked-out and updated by any of the rule applications using the element.

When an element is bound, only the bound master rule application can perform a check-out on that shared element. Until the master performs an "Unbind" no other rule application can assume ownership by binding to that rule element.

Unbind a Bound Shared Schema

1. The Schema must be shared and bound to the current rule application
2. Select the Catalog Tab
3. Click the Unbind Schema button

Once unbound, the Schema can be unshared

Unbind a Bound Shared Rule Element

1. The element must be shared and bound to the current rule application
2. Select the rule element in the Navigation Tree
3. Right click on the item and select Unbind from rule application

Once unbound, the element can be unshared

Get Latest Changes

If changes are made to any shared element, consuming rule applications may require updates to those shared elements. When a rule application that uses shared elements is opened from irCatalog, a screen will display with all of the revision updates, requiring an action to be selected for each.

• Item - Name of the shared element that requires a revision update
• Type - Type of shared element
• Action -"Get Latest" or "Ignore". Default is "Get Latest". To select "Ignore", click into the cell and select the drop down menu.
• Set All To Latest - Sets all actions to Get Latest

Manually Get the Latest Version of a Shared Element

1. Select the Catalog Tab.
2. Click Get Latest Changes button
3. If shared elements are out-of-date, the Revision Updates pop-up will be displayed, providing the "Get Latest" or "Ignore" option to be selected for each element.
4. If shared elements are up-to-date, the Revision Updates pop-up will NOT be displayed.

After getting the latest revision for a shared element, the "Latest Shared Revision" icon will display next to that element. You must click save or perform a check-in operation to ensure that the updated revisions take effect.