Documentation can often be seen as a hassle. From finding time to write new documentation, updating existing or searching for previously generated documentation, its perception as a necessary evil is valid. However, within irAuthor there are several ways to simplify documentation. The result? Greater clarity and transparency into your rules and less time spent on the entire process. With just a little bit of convention and discipline, you can easily assemble a rich set of contextual information that will serve as a tour guide to your business logic.
Tool Window Options
Many of the options that I will cover in this post are in the Tool Window Options in irAuthor. The Tool Window is set to “Auto-hide” by default, but can be viewed by hovering your cursor over the desired option and the tool window can be “pinned” by clicking on the “thumbtack” icon shown below.
The three options I will discuss are Descriptions, Notes, and Attributes.
Descriptions
The first option for simplifying documentation would be using the “Description” options in your rules and rulesets. An example can be seen in the screenshot below:
This is a logical place to document rulesets and the narrative description that you enter there will appear in the “Messages” section in irVerify (as shown below) to provide added information for your testers.
Every object in the rule application can be annotated with a Description so use of this field can be helpful for both your rulesets and your individual component rules, as well as field and entity descriptions.
Notes
Another option for documentation within irAuthor is the Notes section, which can be accessed in the same way as Descriptions above. This section is especially useful when multiple rule authors or developers are tasked with writing or changing rules. Multiple notes can be stored on a single object and when a note is made the system captures the user name and a date time stamp of the entry.
Attributes
Attributes allow the user to store metadata in objects in InRule, using key and value combinations as seen below:
Attributes can also be easily leveraged within your rules using the Get Attribute syntax function. An example of User Defined Functions using Attributes can be found in our samples section at Github available here: https://github.com/InRule/Samples/tree/master/Authoring%20Samples
Exporting
While it is important to create and update documentation, you may need to export it, as well. Descriptions and Notes are automatically included in the rule application report, which can be generated from the by clicking the rule application report button shown below:
The rule application report lists every entity, field, calculation, rule, user defined function, action, and data element in the rule application, as well as the description and notes listed above. The report format is in HTML and is easily editable in MS Word.
Attributes are not included in the rule application report, but can be accessible via the irSDK like the other items above. For example, if you wanted to access the attribute values of a field, you could add the values into a collection in the irSDK like so:
// Get Attributes
ICollection attributes = fieldDef.Attributes.Values;
Conclusion
irAuthor offers many built-in options for the inclusion of documentation in your rule application. Using these options increases the transparency and clarity of your business rules. You fellow rule authors will thank you.
Happy Authoring!
