RoboClerkTags

Working With RoboClerk Tags

To indicate where in the templates information should be inserted by RoboClerk, RoboClerk tags are used. There are two types of tags, inline and block. Inline RoboClerk tags are indicated with @@ and can be used to insert data inline while block tags are indicated with @@@ and are typically used to insert larger blocks of information.

Inline Tags

Examples of the use of inline tags in a asciidoc document:

## Demonstration
This is a demo of inline tags.
This next tag @@Config:SoftwareName()@@ will be replaced by the name of the software pulled from the project configuration file.  
This one by the version: @@Config:SoftwareVersion()@@
To trace a system requirement to the text, use a trace tag: @@Trace:SystemRequirement(id=12345)@@

After running RoboClerk with "RoboClerk" as the SoftwareName and "0.1" as the SoftwareVersion the following output is produced:

## Demonstration
This is a demo of inline tags.
This next tag RoboClerk will be replaced by the name of the software. 
This one by the version: 0.1  
To trace a system requirement to the text, use a trace tag:

An inline tag consists of a number of elements @@<SOURCE>:<ENTITY ID>(<PARAMETERS>)@@.

<SOURCE> indicates to RoboClerk where the data for this tag should be retrieved.
<ENTITY ID> is the identifier that RoboClerk uses to determine what data should replace the tag in the output document.
<PARAMETER> is a comma separated list of parameters which can be empty. An example is @@SLMS:SoftwareRequirement(ItemId=1234)@@. This will match the software requirement with identifier 1234. Note that the parameter names are case insensitive.

Block Tags

Example of the use of a block tag in a asciidoc document:

# Software Requirement

@@@SLMS:SoftwareRequirement(itemID=10)
This is where the software requirement will be placed. 
@@@

After running RoboClerk the following output is produced:

# Software Requirement

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

| Software Requirement Revision: | 3/26/2022 2:57:14 PM

| Software Requirement Category: | Data Management

| Parent ID: | N/A

| Title: | a feature without a parent!!!

| Description: a| I have no parents, I am an orphan
|====

The block tag has the same elements as the inline tag:

@@@<SOURCE>:<ENTITY ID>(<PARAMETERS>)
<OPTIONAL TEXT>
@@@

Note that any text that you enter within the block will be removed in the final result. It can be helpful to describe what the block represents so that a person trying to understand the template can understand what the intent is.

Supported Sources

The following sources are currently supported by RoboClerk. Note that for some sources, using an inline tag can produce strange results because the contents of the tag are incorporated in the output text in-line. Inserting, for example, a complex table like a requirement using an inline tag will probably not result in valid asciidoc if there is text around the tag.

Config - RoboClerk looks in the project configuration file for the tag and pulls the text that will replace the tag from there. Here the <ENTITY ID> is the name of the configuration entry.
Trace - RoboClerk interprets that inline tag as a trace link. The <ENTITY ID> for trace tags is the identifier of the type of entity that is being traced from (e.g. SWR for a software requirement). To indicate what precise item is traced, provide the ID as a parameter.
Ref - This is a document reference. Here the <ENTITY ID> is the identifier of the document. Documents are defined in the project configuration file. If, instead of the complete reference document title, one wants to refer to the abbreviation only, set parameter SHORT to true.
SLMS - This is any information that is expected to be supplied by the Software Lifecycle Management System, the source of truth. <ENTITY ID> here refers to the identifier of the truth entity we are pulling from the SLMS. The truth entities are configured in the project configuration file. These truth entities can be referred to by their identifier or their abbreviation. Examples could be SWR for software requirements or SoftwareSystemTest for all software system tests. Parameters are the properties of the item object (see documentation, linked in the list below). The current list of entities that the SLMS supports are:
- SystemRequirement
- SoftwareRequirement
- DocumentationRequirement
- SoftwareSystemTest
- UnitTest
- Risk
- Anomaly
- SOUP
- DocContent
- TraceMatrix - this is a special tag that requires more explanation. See further down below.
Comment - This is a tag that allows you to provide comments in template documents. This is handy to help people fill out the information in the templates that is not generated by RoboClerk. Everything in a comment tag will be removed form the final document.
Post - This is a tag that indicates that a certain action or content needs to be generated in post processing. asciidoc, while very powerful for such a simple markup language, does have a number of limitations that need to be resolved in post processing. RoboClerk inserts a string in the output that can be picked up by post processing software. E.g. @@Post:TOC()@@ inserts a placeholder for a Table of Contents into the document. The supported post processing actions are:
- TOC - Indicates the location where post processing scripts should insert a Table of Contents.
- REMOVEPARAGRAPH - Indicates a paragraph that should be removed in post processing.
- PAGEBREAK - Indicates a location where a pagebreak should be inserted.

TraceMatrix

One feature of RoboClerk is that it also tracks exactly what things go into what documents and what items are connected. One way to visualize this is to generate a trace matrix. You can trace any item to any other item or document. The way to set up the traceability is through the project configuration file. In RoboClerk trace starts with a particular item type (e.g. SystemRequirement) and from there traces the requirement to documents and other connected items. Here is an example trace configuration:

[TraceConfig.SystemRequirement]
		SystemRequirementsSpecification.forward = ["ALL"]
		SystemRequirementsSpecification.backward = ["ALL"]
		SystemRequirementsSpecification.forwardLink = "DOC"
		SystemRequirementsSpecification.backwardLink = "DOC"

		SoftwareRequirement.forward = ["ALL"]
		SoftwareRequirement.backward = ["ALL"]
		SoftwareRequirement.forwardLink = "Child"
		SoftwareRequirement.backwardLink = "Parent"

		RiskAssessmentRecord.forward = ["Risk Control Measure"]
		RiskAssessmentRecord.backward = ["OPTIONAL"]
		RiskAssessmentRecord.forwardLink = "DOC"
		RiskAssessmentRecord.backwardLink = "DOC"

		Risk.forward = ["Risk Control Measure"]
		Risk.backward = ["OPTIONAL"]
		Risk.forwardLink = "Related"
		Risk.backwardLink = "RiskControl"

This trace configuration starts with all the systemrequirements in the system and traces them to the SystemRequirementSpecification which is a document that is also defined in the project configuration file. The forward and backward trace allows you to indicate what kind of trace link should be present. In this case, SystemRequirementsSpecification.forward is ALL. That means that every category of SystemRequirement must trace to the System Requirement Specification. SystemRequirementsSpecification.backward is ALL which means that every System Requirement that shows up in the System Requirement Specification must trace back to a System Requirement. The link type here is "DOC" which means it is to and from a document. The next trace item that the SystemRequirement traces to is the SoftwareRequirement. These items are extracted from the SLMS. As you can see every SystemRequirement must have at least one or more Software Requirements linked to it. The Software Requirement is a Child of the System Requirement which is the Parent of the Software Requirement. Typically, the type of link can be indicated in the SLMS. In some cases RoboClerk may change the type of a link from the one used in the SLMS. This is done in the SLMS plugin. Next there is more trace to the RiskAssessmentRecord document. Notice, that only those System Requirements of category "Risk Control Measure" need to trace to the risk items in the RiskAssessmentRecord. Risks in this document can trace back to SystemRequirements but they don't have to (OPTIONAL). Finally, there is trace to the risk items extracted from the SLMS.

To produce the trace matrix associated with the System Requirements use the following tag:

@@@SLMS:TraceMatrix(source=SystemRequirement)

@@@

Provide feedback

Saved searches