Rule Application Patterns, Part I: Adding Members to a Collection Using Vocabulary and Explicit Rule Sets
Introducing Rule Application Patterns
This blog post is the first in a series which will highlight common rule authoring patterns of note. The InRule ROAD Team (Rule Oriented Application Design) has compiled a wide selection of useful rule authoring patterns which we intend to share through these blogs. Future rule application pattern blog posts will examine other useful patterns.
The Pattern: Adding Members to a Collection of Messages Using Vocabulary and Explicit Rule Sets
Our first rule authoring pattern is an expert-level pattern with a simple goal: to call a rule set which adds a member to a collection of messages with custom information using a Vocabulary template. While irAuthor has a number of built-in error messaging features (ex: fire notifications), you may desire more detail and configurability in the messages you pass back to the calling application.
Some initial use cases for this kind of pattern include:
- Adding richly detailed error messages to a collection
- Creating an audit trail of complex processes
- Identifying which rule fired to create a decision (adding a UDF to this pattern)
A quick pattern summary is below.
Step 1: Add a Collection
The first step in our design is to set up an entity and fields which can accommodate the messages. Suggested fields might include MessageID, MessageText, CallingRuleName, MessageRecipient, and MessageRecipientEmailAddress. Once the entity is created, you should then create a collection of that entity in another entity context.
Here’s a sample top entity and a sample error collection entity. We’ll refer to this entity model moving forward.
Step 2: Add the Messaging Rule Set which Adds a Collection Member
The next step is to add an explicit ruleset which requires parameters. Why this step? We could instead just create a Vocabulary template which adds collection members. The problem with that approach is that it the template will work only within a narrow range of rule set contexts.
An explicit rule set, however, can generally be called from a much wider variety of rule set contexts within your rule application, especially if that explicit ruleset resides within a top-level entity (or independent) context.
Our Explicit Rule Set with Parameters
Step 3: Create an Add Collection Member Rule in the Messaging Rule Set
The point of this overall pattern is to add a collection member to your collection of messages using the parameters that were passed into our explicit rule set. In order to do this, we will type those rule set parameters directly into an Add Collection Member statement within that rule set as we mentioned earlier.
The Add Collection Member Statement (in Our Messaging Rule Set)
Step 4: Add a Vocabulary Template which Calls this Rule Set
The final setup is to create the execute rule set Vocabulary template which calls that parameterized explicit ruleset. The datatypes of the placeholders in this template will need to match up with the parameters in the explicit rule set that we’re calling.
Step 5: Use the Vocabulary within a Business Language Rule
The final step in this process is the easiest part: set up rules to consume the new Vocabulary template with passed parameters. Those parameters can be typed in directly or can be set to the value of other fields in your schema.
The Final Product: Custom Messages
The final product is a custom set of messages that can be tailored to the needs of your business.
Also Worth Knowing
- Want the name of the rule that caused this message? You’ll want to include a UDF (user-defined function) if you wish to also include the name of the calling rule in your collection (with text: “return Context.Ruleset.Name”).
- Want to include state information in this message? Make one of the rule set input parameters (and collection members) an entity.
Feel free to drop me a line with questions. Happy rule authoring.