Richly Document Rule Assets in Corticon 5.7

It's now easier than ever to richly document rule models in Corticon. Learn how to take advantage of this feature in this tutorial.

When business analysts build rule models from existing processes or documentation, they often have to resolve ambiguities and conflicts in current business practice. They have to make decisions about how rules should be implemented.

Accordingly, they need a way to record their design choices, reference supporting resources and log updates. Progress Corticon 5.7 makes it easier than ever to richly document rule models with a new commenting feature in Corticon Studio that supports change logs, todo lists, review lists and notes at a very granular level.

Adding Comments

Studio supports two categories of comments: asset-level comments associated with Rulesheets, Ruleflows, Testsheets and Vocabulary files and item-level comments associated with elements inside the assets, such as Vocabulary entities or attributes. 

Asset-Level Comments

To add comments to an asset, such as a Vocabulary, Rulesheet, Ruleflow or Testsheet, open it in the Studio editor and click the yellow speech bubble icon in the toolbar. Note that in Ruleflows, there is no icon in the toolbar for adding comments. In this case, select Ruleflow > Comment… from the menu.

Figure 1: Click the yellow Comment icon to document an asset file.

You can use asset-level comments to explain the purpose of the asset, reference relevant business documents, or describe how the asset should be used in the overall project. These comments can also hold todo lists or requests for review to help manage the design process.

Item-Level Comments

You can also attach comments to individual items inside an asset. To do so, select the item, right click and choose Comment….

Figure 2: Select an element and right click on it to add a comment.

You can comment the following elements in each asset:

 

Vocabulary	Entities, attributes, associations
Rulesheet	Columns, rows, individual cells, ranges of columns, rows or cells
Ruleflow	Rulesheets, Service Call-outs, Subflows, Embedded Ruleflows, Branches
Testsheet	Entities, attributes, associations in the Input Panel

Item-level comments can record a particular design decision, keep track of unresolved questions, attach a todo action, log changes or reference a relevant business document.

The Commenting Dialog Box

The dialog box for entering comments appears when you select the Comment... option or icon. 

Figure 3: The dialog box for entering a comment and selecting a category.

Type the comment in the box and use the drop-down menu above to select a category: Note, TODO, ChangeLog or NeedsReview. Studio automatically logs the comment along with the category, the asset or item it’s associated with, the author, the date and the time.

The Comments View

For each asset, you can see the existing documentation under the Comments tab, usually located below the main editor. Note that you can add multiple comments to any asset and most of the individual items to track the design process over time.

Figure 4: The log of existing comments under the Comments tab.

In the Comments view, you can sort the notes by clicking on any header. You can also use the search box near the top to find specific entries by date, user, category, item or keyword. So for any asset, you can easily list required todo actions, issues that need review or a historical record of changes.

If you click on an item-level comment, the associated item will be highlighted in the editor. For example, if you have a comment on Column 1 in a Rulesheet and you select that comment, Column 1 will be highlighted in orange so you can easily see the related item.

Conversely, if you want to see all comments associated with an item, you can select the item in the editor, then click the View Filter button on the Comments view toolbar. The list will then display only the notes related to that item.

Figure 5: The View Filter button in the Comments view will filter for any comments associated with a selected item in the editor.

The new documentation feature in Corticon Studio will make it much easier for analysts to record and share their design decisions and trace the evolution of the rule model over time. Analysts who take advantage of this powerful tool will minimize errors, confusion and re-work over the lifetime of the application.

This is just one of many new features in Corticon 5.7, so be sure to check out the full list of what’s new. Or if you’d rather jump right in, feel free to download a trial or schedule a demo today.