Overview

Changes in a requirement may create a need to review linked requirements (or other types of issues) that depend on it. R4J allows you to create a fine-grained “suspect logic” that alerts users about requirements that need review due to changes in linked requirements. The logic takes the form of project-specific rules that specify which fields are to be monitored for changes, which link types are to be examined, and the users that are to be notified when suspects are discovered.

Configuring suspect logic rules can be challenging, so a detailed example has been provided - see Example of How to Configure a Suspect Logic Rule.

1 Overview
2 Configuration of Suspect Logic Rules
- 2.1 Linked Issues as trigger for suspects
3 Example of How to Configure a Suspect Logic Rule
- 3.1 Configuring the Jira Link Type
- 3.2 Configuring the R4J Suspect Logic Rule

Configuration of Suspect Logic Rules

To configure rules for suspect logic, you need the "Suspect Configuration" user permission - see Managing User Permissions.

In the Jira main navigation bar, select Requirements > Suspect Configuration. Selecting the desired project causes the existing rules for that project (if any) to be displayed. The following actions are available:

Purpose	Action

Purpose

Action

Create rule

Select the option Add Suspect Configuration.

Give the rule a name.
Select the fields you want to be monitored for changes. Choose <All fields> if you want all fields to be monitored.

To avoid being overwhelmed by links incorrectly getting marked as suspect, think carefully about which fields are selected here. Only those fields that, if changed, might necessitate changes in related requirements should be included. The requirement description is an obvious candidate, since a change in a requirement’s description may necessitate coordinated changes in related requirements. But a change in, say, the assignee of a requirement probably has no impact on related requirements.

Select the link types that you want to be included in the scope of the rule. Choose All Types if you want all types of links to be included in the scope.
Select whether the scope includes only downstream relationships (what Jira calls “outward” links), upstream relationships (“inward” links), or both.
Optionally, select specific users or roles that receive a notification when a requirement is marked as suspect. The possible roles are assignee, reporter, and project lead.
Select Add to create the rule, which takes immediate effect.

Modify rule

Select the edit icon next to the rule, modify the rule configuration as desired and select Update.

Delete rule

Select the delete icon next to rule and select Delete.

Linked Issues as trigger for suspects

There may be a need for requirements to mark newly linked issues as suspects to check its impact on requirements. When linking an existing issue or creating a new link, regardless of the scope indicated, the link between both changed and linked issue will be marked as a suspect since it is identified equally as a change for both.

The revision may also show the issue keys in the “R4J Suspect“ revision interchangeably (in the example below, ABC-123 and ABC-456) since Jira does not provide the direction which the links are created.
Example of an “R4J Suspect“ revision: R4J Suspect: Suspect set in ABC-123 due to change in ABC-456

Example of How to Configure a Suspect Logic Rule

The following example describes a possible situation in requirements management, explains what we want to accomplish with a suspect logic rule, details how to configure the link type in Jira, and how to configure the suspect rule in R4J.

Suppose some of our requirements are descriptions of use cases. The use cases are described in such a way that they are independent of the details of our system. We also have requirements that specify how the use cases are to be realized in the system. We have two issue types to handle this situation: Use Case and Use Case Specification.

We want to link Use Cases and Use Case Specifications so that we can trace each use case to one or more specifications. Since the specifications depend on the use cases, we also want to be alerted if a use case description is changed, so that we have a chance to review the linked specifications to see if they also need to be changed. However, we do not want to be alerted if use case specifications are changed, since use cases do not depend on them.

Configuring the Jira Link Type

We start by formulating a statement of the desired relationship between use cases and use case specifications in natural language, which is then a reliable guide for the configuration of the link type in Jira. When Use Case A is linked to Use Case Specification B, we express the relationship in the following ways:

A is a use case for B.
B is a use case specification of A.

Using the words italicized in these statements we create a Jira link type as follows:

Name	Use Case Specification
Outward Description	use case for
Inward Description	use case specification of

It’s a good idea to use such specific link descriptions, so that users understand that links of this type are intended to relate use cases and use case specifications – and not other types of requirements. The practice is particularly helpful when using suspect logic rules, since it contributes to the avoidance of false positives that result from suspect logic rules relying on link types with ambiguous or imprecise descriptions.

A link between Use Case A and Use Case Specification B is created as follows:

If the link is created from issue A, then the item “use case for” is selected from the list of links and B is selected as the linked issue.
If the link is created from issue B, then the item “use case specification of” is selected from the list of links and A is selected as the linked issue.

Link types that have different outward and inward descriptions are asymmetrical and hence can be seen as having a unique direction. In this example, the link between A and B is directed from A to B. We can indicate that with an arrow, writing either A → B or B ← A, depending on our point of view.

Configuring the R4J Suspect Logic Rule

With use cases and use case specifications now linked as explained in the previous section, we configure the following suspect logic rule to ensure that we are notified of changes that might require attention:

Option	Value	Explanation

Option	Value	Explanation
Name	use case specification	This is simply a name by which you can recognize the purpose of the rule.
Fields	Description	Only changes in the Description field are of interest. If there are other fields where changes might require a review of the linked use case specifications, they can be added here.
Link Types	Use Case Specification	The rule only applies to links of this type.
Scope	Downstream Only	Given issues A and B, linked by a link of type Use Case Specification, and such that A → B, the values of this option are to be understood as follows: Downstream Only: Only changes in A are relevant. Changes in B are irrelevant. Upstream Only: Only changes in B are relevant. Changes in A are irrelevant. Both: Changes in both A and B are relevant. Since use cases are independent of use case specifications, the option Downstream Only is the right choice. (If we selected Upstream Only, we would be alerted to changes in linked use case specifications, which is not what we want. If we selected Both, we would be alerted to changes in both linked use cases and use case specifications, which is again not what we want.)
Notification		This option is set to the users, if any, that are to be alerted to events that lead to a link being marked as suspect - i.e. a change in the Description field of a use case with linked use case specifications. Note that R4J provides information about suspect links in other ways than notifications (e.g. the Suspect Report), so explicit notifications are not necessary - see Suspect Links.

Configuring Suspect Logic