Rules are very powerful in terms of providing extensions to the IGI’s functionality. However, there is limited documentation available, both for the Sample Rules shipped with the product, as well as around the Custom Rules that could be developed and used in deployments. Rules can be fairly complex at times.

To help address this issue, we have developed rules-specific documentation and collected a set of sample rules hosted on github (IGI Rules), that you can use in your own IGI deployment. This blog describes the github and the content hosted there.

Our assumption is that the rules will be imported into the Rules interface in IGI. However, there is also an Eclipse plugin for rules development and parts of the github provide samples to use in the plugin.

IGI Rules in GITHUB

This section looks at the structure of the igi_rules github and the sample rules there, especially:

• Structure of igi_rules space on GITHUB.
• Sample Rules.
• Naming convention of the rules.
• Search for specific rules.

Structure of igi_rules space on GITHUB

The content on GITHUB is organized as follows:

• Sample Rules – A collection of rules stored in text documents (.md or markdown files).
• JavaRules – A collection of rules in .java format allowing them to be used in the Eclipse rules plugin. These rules are linked within the rules (under Sample Rules) in .md format, just so that any user who wants to leverage the Java rules directly have an option.
• Rules Guide – This document (IGI Rules Guide v03.pdf) should be the first thing you should read to start working with Rules.
• Rule Engine Toolkit Usage Guide – This document (Rule Engine Toolkit Usage Guide) should help you get access to the Eclipse Rules Plugin.

The following figure shows this structure in a local copy of the igi_rules github:


Note: The sample rules and the corresponding Java Rules are provided as-is and are not supported by IBM.

Sample Rules

This section looks at the sample rules provided in the github, their organization in the folder structure, the naming conventions applied, how to search for sample rules, and the layout of the sample rule files (.md files).

Organization of Rules Within Different Folders

The rules are organized under different folders, under Sample Rules, each of them signifying a different area of rules

• Enterprise Connector Mapping Rules – Enterprise Connector mapping rules.
• Event-Driven Rules – Rules on the IN, OUT & Target queues messages, scattered across the following folders:
  • IN Queue – Rules on the IN event queue messages.
  • OUT Queue – Rules on the OUT event queue messages.
  • Target Queue – Rules on the Target (TGT) event queue messages.
• Other Rules – Rules around Account Management, Password Management & Workflow, scattered across the following folders:
  • Advanced – Rules pertaining to account management, certification campaigns etc.
  • Generic – Basic rules, agnostic of any given module.
  • Hierarchy – Rules pertaining to hierarchy management.
  • Workflow – Rules pertaining to workflow, such as the pre- and post-actions.

Notes:

1. If there are multi-step rules, the same folder would contain them, with a proper call out on the Step 1, Step 2 et. al.
2. More folders will be added as we collect rules. For example, when we collect INTERNAL queue sample rules, we will add an INTERNAL Queue folder.

NAMING CONVENTION

The sample rule files follow a naming convention: short description.md. For example:

• Set Random Password on Ideas Account for a New User.md – A rule to run on the IN queue to set a random password on an Ideas account for a new userAccount.
• New Permission Assignment Drives Continuous Campaign.md – A rule to capture a change in the permission assignment of a user and put the corresponding user in the continuous campaign dataset.
• Pass Arguments Between Rules in a Flow.md – A rule that purely demonstrates how we could pass arguments from one rule to the other, of course in the same flow.

RULE SEARCH

Given the above naming convention, you can find a specific Rule, using the default keyword search of github. The following figures show examples of the same:

In the github, you can select the Sample Rules folder (click on it), then click the Find file button (highlighted below):

You can then type a search argument and github will show all the filenames containing your search text (Say for e.g. “password”):

For all the matching files you get:

• The file path – This indicates the type of rule.
• The file name – This describes what the rule does.

The example above shows an Enterprise Connector Mapping rule that will set a random password for a re-enabled account.

LAYOUT OF A GIVEN .md FILE

The sample rules are stored in .md files (markdown text files) and are structured with the following sections:

• Description – Description of the rule to provide clarification of what the rule does (in case the title of the file is not descriptive enough).
• Package Imports – Any additional package imports needed.
• Rule Code – The sample rule code itself.
• Java Code – This is an optional section of the document. If you happen to find this section in the document, you would find a link to the corresponding Java Code that could be imported directly in the Rule Engine Toolkit and used from there.

Notes:

1. The Package Import statements show up in 2 separate sections. The first set of import statements in a given .md file are the ones that are available by default for the rules shipped in the product. The second set of import statements in that same .md file are theg ones that need to be explicitly specified in the Rule Imports.
2. At times, there would just be one section of imports. If that’s the case, likely that no further imports beyond the defaults would be needed.

The following figure shows an example of one of the sample rule files:

Overall Summary

The Rules Guide talks about how to define and use rules in general. With the samples provided in this github you would:

1. Check the Package Imports for the type of rule you are using.
2. Copy and paste the Rule Code into the Rules interface in IGI.
3. Tweak the rule further, as needed by the requisite business logic.

Conclusion

We expect to continue to grow the github as more examples come along. We are also looking to add scenarios that may involve multiple rules (and other configuration in IGI).

For questions or more information you can email Ramakrishna J Gorthi or David Edwards.