ItemTemplates

Item Templates

Each item processed by RoboClerk (e.g. System Requirement, Software Requirement, Software of Unknown Provenance (SOUP), etc.) is rendered in the produced asciidoc documentation according to its Item Template. The item templates are in the RoboClerk_input directory, under ItemTemplates. What the item templates allow you to do is change the way items are inserted into the documentation. An example could be that in your organization, you do not want to show the category of requirements because you do not assign one. By changing the item template, you can achieve this without recompiling RoboClerk. Note that not every single item has a template, in some cases, you will need to recompile RoboClerk. Let's take a look at an item template and how it can be adapted. The following example is for requirement items:

[csx:
// this first scripting block can be used to set up any prerequisites
// pre-calculate fields for later use etc.
using RoboClerk;

TraceEntity te = SourceTraceEntity;
RequirementItem item = (RequirementItem)Item;
string pl = GetLinkedField(item, ItemLinkType.Parent);
AddTrace(item.ItemID);
]
|====
| [csx:te.Name] ID: | [csx:GetItemLinkString(item)]

| [csx:te.Name] Revision: | [csx:item.ItemRevision]

| [csx:te.Name] Category: | [csx:item.ItemCategory]

| Parent ID: | [csx:pl]

| Title: | [csx:item.ItemTitle]

| Description: a| [csx:item.RequirementDescription]
|====

RoboClerk reads these template files and executes those sections of the file that are in [csx:<CODE TO BE EXECUTED>]. The first such section is executed as-is. RoboClerk assumes that all other sections return a value which is inserted into the template. The first section can be used to set up variables or to define functions that are used in the later blocks. In the example above, several objects are retrieved and these objects are later used to insert information into the item template. Below is an example of what the end result is once RoboClerk executes the template with a particular requirement item:

|====
| Requirement ID: | http://localhost:3001/issues/2[2]

| Requirement Revision: | 4/3/2022 7:01:03 PM

| Requirement Category: | Risk Control Measure

| Parent ID: | N/A

| Title: | Mitigate the risk

| Description: a| The software shall mitigate the risk to reduce its impact.
|====

Making Changes

To change the way items are inserted into the documentation, simply edit the template. For example, if instead of the category, we would want to show who the requirement was assigned to and instead of the revision we would like to show the status of the requirement, the updated item template file would look like this:

[csx:
// this first scripting block can be used to set up any prerequisites
// pre-calculate fields for later use etc.
using RoboClerk;

TraceEntity te = SourceTraceEntity;
RequirementItem item = (RequirementItem)Item;
string pl = GetLinkedField(item, ItemLinkType.Parent);
AddTrace(item.ItemID);
]
|====
| [csx:te.Name] ID: | [csx:GetItemLinkString(item)]

| [csx:te.Name] Status: | [csx:item.ItemStatus]

| [csx:te.Name] Assignee: | [csx:item.RequirementAssignee]

| Parent ID: | [csx:pl]

| Title: | [csx:item.ItemTitle]

| Description: a| [csx:item.RequirementDescription]
|====

To understand what information is available, you can use the source or you can use the auto generated documentation. Each item template has access to a ScriptingBridge object that makes certain information available. The documentation for this object can be found here. In the above example, the SourceTraceEntity, Item, GetLinkedField and AddTrace are member Properties and Methods of the ScriptingBridge class. To understand what Properties are available in what type of item, see the various item types here. Once changes are made, run RoboClerk again and the updated item templates will be used to generate the documentation.