Vivid Trace 2021.1 Solution Guide
This document outlines general practices and topical solutions for implementing traceability with Vivid Trace. We define traceability as:
traceability noun The quality of being able to trace the progression of the materials and units of work that ultimately produce an output or deliverable. In Jira, traceability enables us to relate i.e. requirements with design decisions, implementations, and test case results by following paths formed by relationships between issues (the units of work).
These solutions are proposed starting points that you can use and adapt to your situation, be it software development lifecycle (SDLC), application lifecycle management (ALM), ITSM/ITIL, or customer support and help desk scenarios. While the figures in this document depict abbreviated data sets, your data sets are probably large. A strength of incorporating traceability into your systems and workflows is in empowering you to process larger volumes of information with vastly greater speed.
You can get ideas on how to beneficially apply traceability just by browsing the list of topics in this document.
- Traceability Implementation Checklist
- View an Issue Dependency Graph
- Graph Exact JQL Query Results
- Trace Requirements to Implementations and Tests
- Monitor Cross-Team Response to Customer Support Request
- Conduct Change Impact Analysis
- Embedding Traces in Confluence Pages
- FDA Medical Device Software Traceability Analysis
- Find Unblocked Issues
- Identify Blocking Issues
- ISO 15504 SPICE Compliance
- Monitor Support Request Chain of Events
- Scan for Prematurely Resolved Parent Issues
- Scan for Completed Tests of Unfinished Implementations
- Scan for Escapee Issues
- Scan for Excessive Aggregation of Issues
- Scan for Non-Blocking Issues with Blocker Priority
- See All Issues in Jira
- Watch Issues in a Graph
Prerequisites: Familiarity with Issue Relation Graphs. Familiarity with the Trace Studio. Some knowledge of JQL, Atlassian's Jira Query Language for searching for issues. Awareness of Vivid Trace's JQL functions.
Range of Traceable Project Artifacts: The Vivid Trace proposition is traceability between project artifacts, currently defined as issues inside a single Jira instance. Source code commits, test case information, Confluence objects, issues in multiple Jira instances, and other project artifacts are slated to come into direct range in ensuing releases.
Traceability Implementation Checklist
Use this checklist as a guide to implementing traceability. If you would like assistance, contact Vivid Support.
- Traceability Information Models Define your traceability goals. Agree on what information is necessary and how it should be structured in traceability reports to be useful to team members, other stakeholders, and/or regulatory authorities. Agree on how to model traceable project artifacts in terms of issue types, issue fields, and which projects they will live in. You might be using Jira add-on tools that provide task-specific idioms, such as for requirements management and test management, which already provide issues, issue fields, and relations that can be incorporated into the tracing and reporting strategy. Agree which relation types to use between project artifacts and on the interpretation of each. When thinking about how items should be related, consider the idioms that your Jira system offers and that your teams are using.
- Decisions Determine which portions of information will be: Managed in Jira, synchronized with or mirrored into Jira from other systems, and housed outside of Jira. Decide how to display issue and relation information in trace results. Decide how project artifacts will reference each other within, straddling, and outside Vivid Trace's traceable range. Decide how to preserve the referential integrity between artifacts in order to produce accurate traceability analyses.
- Team Pre-Flight Stakeholders and participants buy in to the traceability goals and the measures required to implement them. Set up Vivid Trace in your Jira system (See the Deployment Readiness Checklist). Prepare the projects that are involved: Project configuration, issues, and issue fields. Prepare the issue link types and other relations that will represent relations between project artifacts. Project administrators know how to adjust Vivid Trace project configurations. Team members know to properly manage issue data and relations. People who will conduct traces are capable with the Trace Studio and its prerequisites. Create initial drafts of your trace configurations in the Trace Studio, and share them with the appropriate people.
- Recommended Practices Maintain issue relations at the time of artifact creation and work. If you are not dependent on Jira's time tracking feature, Vivid suggests that you might consider avoiding Jira's Sub-task system in favor of a more flexible modelling idiom. Create a generalized issue link type to model work breakdown and superior/sub-ordinate relationships. For example, to model a parent and sub-task relationship, create a new issue link type named "Sub-task" with outward description "sub-task" and inward description "is sub-task of". Thus, with this abstraction, you'll be liberated to model multi-level decomposition of requirements, user stories, implementations, and nearly anything else with the utmost flexibility. Prefer tracing criteria that is too wide rather than too-narrow to avoid costly omissions. Give names to trace configurations that help you correctly and quickly identify them in the Trace Studio. Validate the trace criteria of a given trace configuration before using it to create reports. Inspect the resulting trace data for errors and omissions before relying on the results. If the trace data does not properly cover the traceable items then the tracing criteria may need adjustment, and missing and erroneous trace data must be remediated. Ensure that any modifications made to the trace configurations and the Traceability Information Model are agreed upon, saved, and communicated. Generate trace reports meant for sharing from freshly-loaded, unmodified trace configurations. This practice promotes reproducibility of the reports and improves the likelihood that decisions are based on accurate reports. Judge a compiled report whether it objectively demonstrates traceability among the desired items as agreed.
View an Issue Dependency Graph
You can use this method to immediately view the issue dependency graph for an issue, several issues, or the results of a JQL query. In the Trace Studio, just input one or more issue keys (separated with spaces and/or commas) or a JQL query into the Seed issues and press the Enter key to run the trace. You can edit the seed issues as often as you like, pressing Enter after each edit to re-run the trace.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Seed issues | Issue keys or JQL query |
|---|
Issue dependency graph illuminating all of an issue's dependencies. This dependency map was instantly and automatically generated on live data by tracing the issue key MD-51 in the Trace Studio.
Explanation: The Trace Studio accepts issue keys or the results of JQL query and uses them as seed issues to run a trace. When you first started a new trace, the Trace Studio was set to its default configuration with parameters set to cast the widest possible net. This resulting trace configuration (the default configuration plus your seed issues criteria) produces a full dependency graph.
Going Further: The resulting trace is a good starting point for examination, and for experimental investigation and refinement of the trace results by way of adjusting the various trace settings. To visit issue detail pages for particular issues, instead of clicking on issues to navigate to them, open issues in new tabs so that the web browser doesn't navigate away from the trace causing you to lose the trace configuration. Add issue fields to the Issue Field Layout to understand more about the dependencies. Experiment with the Distance, Artifact Types, Issue Link Types, and other settings to improve signal-to-noise in the graph. Explore the other entries in this document to see what else is possible.
Graph Exact JQL Query Results
To graph the exact results of a JQL query without expanding the trace beyond the query results, simply use the JQL query as the seed issues in the Trace Studio and trace at a distance of zero.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Distance | 0 |
|---|---|
| Seed issues | JQL query |
Explanation: With the results of JQL query being used as the seed issues, setting the distance to zero instructs the tracing process to not expand the trace beyond the seed issues. Vivid Trace, thus prevented from tracing beyond, advances to graphing the issues resulting from the JQL query according to the trace configuration. In this case, we started with a new trace meaning that the trace configuration is initialized to display relations of all types as per the default configuration.
Trace Requirements to Implementations and Tests
You can confirm which requirements for a given release are implemented and tested, and which ones are still incomplete (known as Requirements Fulfilment and Requirements Satisfaction). This traceability gives you transparency into process execution and results, and reduces the time spent on vigilance tasks.
Assumptions: Requirements, implementations, and tests are mapped as Story, Task, and Test issue types, respectively. The three types are related using issue links leading outward from the requirements.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Distance | 0 |
|---|---|
| Seed issues | issue IN relations('jql = issueType = Story ANDScope', 'direction = outward', 'artifactType IN (Task, Test)') |
Set Scope to the characteristics of the requirements of your interest, such as to a specific project version: project = ABC AND fixVersion = 1.2.3. You'll need Browse permission on all of the associated projects and issues. The larger the scale of your results, the more likely you'll encounter the Graph Traversal Time Limit and the Issue Count Soft Maximum add-on settings, which will truncate your traces (Fine-grain control of this limit is scheduled for a future release.) Your Jira administrator is able to increase these add-on settings to accommodate your needs.
Requirements traced to their implementations and tests. This figure is a small clipping from a much larger trace report. According to the figure, requirement ASX-1 is waiting on the implementation of ASX-10 and the completion of a batch of testing in the QA project, whereas requirement ASX-7 has been fully implemented and tested.
Explanation: Starting from the seed issues JQL query, the jql parameter passed to the relations() JQL function identifies the requirements that you are interested in. Taken with the other parameters, relations() traces just the mentioned artifact types downstream from the requirements. Setting the distance to zero in the Trace Studio causes just the seed issues (the JQL relations() query results) to be graphed; all actual tracing work from requirements to implementations and tests was done by the inner JQL query in the seed issues.
Going Further: Instead of just depending on the datum of whether an issue is resolved or not, it might be wiser to add, at minimum, the Status and Resolution fields to the issue field layout to determine which work breakdowns are properly complete and which have been disrupted. You might even be able to save time over your development period by refining a duplicate of this trace that reports only on such incomplete sets.
Monitor Cross-Team Response to Customer Support Request
Participants at various points along an event chain can monitor and communicate progress, direction, and outcome while events unfold or after the fact. This capability is particularly useful for customer support, ITIL, and help desk environments, where being able to rapidly convey ground-truth status to customers results in a better Customer Journey experience. As traces are generated in real time, you can promptly inform customers of the current actual status: progress, when a fix is scheduled for release, if there are any hold-ups.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Distance | Unlimited |
|---|---|
| Directions | Outward, Subtasks |
| Seed issues | Issue key of the customer support request |
Alternatively, on the issue details page of the customer support request, view its contextual trace. Ensure that your personal graphing options won't hide any downstream issues, as provided in the suggested settings for the Trace Studio, immediately above.
Trace of a customer support request. In this example, it looks like Customer Success filed a bug report from a customer. Product acknowledged the bug and fixed it, and is co-operating with dev-ops to release the fix. Maybe we can check the details on that last issue to find out when it will be officially announced, which we can do by merely clicking or tapping it right inside the graph.
Conduct Change Impact Analysis
Conducting change impact analysis up-front increases your success rates in implementing changes. Change impact analysis is highly beneficial in that it identifies the potential scope and consequences of an initiating change, enabling you to produce a realistic data-based estimate of what is involved to accomplish the change. When it comes to a decision on whether to green-light a change proposal, with analysis results in hand, scheduling, budget, and risk will be known quantities prior to the decision, rather than a surprise afterwards.
Benefits of Change Impact Analysis
Conducting change impact analysis with Vivid Trace offers a wide array of benefits:
- Automatic discovery: Manually determining what and who is affected by a change is time consuming and error-prone. Vivid Trace automates the bulk of the exploratory effort instantly and accurately.
- Avoid surprise domino effects: Flush out unanticipated snags that might be lurking behind even simple change requests.
- Change management: Understanding the impact of a change enables teams to better evaluate and respond to change requests while gaining control over the scope of change.
- Compliance: Change management is frequently employed in safety-critical and mission-critical environments in industries such as healthcare, aerospace, and automotive, and by high performing teams adhering to CMMI and ISO 15504 SPICE general practices, to ensure that the changed deliverables can still satisfy compliance requirements. Change management also helps to assure compliance with contracts to increase customer satisfaction while defending against criticism and reducing legal exposure.
- Conflicts and risks: Prevent scheduling conflicts and curtail risk when it is less expensive to do so i.e. during earlier phases of the project.
- Customer satisfaction: Enhance your ability to manage customer expectations, deliver on approved change requests, and maintain customer satisfaction and loyalty.
- Determine scope: Analyse relations between requirements and specifications, code, and other assets to produce an objective assessment of the scope of change.
- Implementation: Identify associated code and other design elements that need to be created, modified, and removed, including files, models, and documents.
- Project and budget oversight: Develop an objective understanding of the implications of changes and produce reliable estimates, allowing you to make informed business decisions about which proposals to approve as well as to contain threats to your budget and schedule.
- Requirements and specifications: As a core aspect of requirements management, change impact analysis helps you identify the requirements, specifications, customer feedback, and marketing inputs that might need revisiting.
- Scale return on investment (ROI): Change impact analysis pays dividends in proportion to the size of the change and the project: As larger projects escape memorization by team members, up-front impact analysis pays off in developing reliable estimates and reducing risk.
- Testing and quality assurance (QA): Identify the specific set of impacted requirements, features, and story acceptance criteria that need to be retested.
As an example, a manufacturer of a portable medical device used for cardiographic diagnosis and monitoring can learn through impact analysis that the addition of a tethered pulse oximeter would cause changes to (partial list): the materials and safety specification, the electronic I/O sub-system, the case molds, the software responsible for reading, recording, and displaying sensor data, and the electronic health information privacy compliance documentation concerning the product's technical safeguards. Furthermore, the impact analysis can reveal domino effects: Modifications to the electronics and software would give rise to the need to re-audit both the hardware and the software for regulatory compliance. Some of the impacted items might be immediately obvious or a matter of course for the project team, and other items might be afterthoughts or forgotten entirely. Importantly, all items crucial to the successful production and testing of the product and to receiving regulatory permission to market the finished product are identified through impact analysis. Once the scope of the impact of change is identified, you can make objective calculations of resource, cost, and risk estimates, enabling you to make better-informed decisions.
Prerequisites
In the context of Vivid Trace, change impact analysis is an investigation into a body of project artifact information already stored in your system. A portion of the data required for this analysis might not be within Vivid Trace's traceable range and won't be included in these trace results.
Conducting Impact Analysis
The following procedure outlines the general steps in conducting impact analysis.
- Identify the items subject to the change. How are those items represented within Jira?
- Determine how other items are related to these items, such that they could be impacted. How are those relations and items represented within Jira?
- Starting with a new trace in the Trace Studio, determine and set the tracing criteria.
- Run the trace and use the results to identify the items subject to change.
- Process the found items to develop an objective understanding of resource, schedule, cost, and more.
Recommended Practice: When thinking about how impacted items could be related within Jira, consider the idioms that your Jira system offers and that your teams are using. Are impacted items likely to share the same project components, labels, keywords, top-level requirement, or individual source code changesets? Also consider how impacted items are not conclusively related in order to avoid pitfalls; for example, impacted items can span projects (projects can be structured along functional or team lines while their aggregate output all goes into the same deliverable) and they can also span versions (newer features in coming versions can impact the behavior of older, existing features introduced in prior versions). You can develop knowledge of how impacted issues actually relate by comparing and contrasting issues directly in Jira that are known to be impacted as well as those that are known to not be impacted. Thinking on this topic can also be leveraged to develop and improve your data management practices in Jira so that your system becomes more conducive to impact analysis.
Recommended Practice: Prefer tracing criteria that is too wide rather than too-narrow to avoid omissions. The point of this impact analysis is to have the system aid you in producing a reliable estimate of a proposed change. If the tracing criteria is too narrow such that some of the impacted issues are not identified, the omitted factors might not be incorporated into the resulting estimate and ultimately degrade the quality of the impact analysis.
Embedding Traces in Confluence Pages
Embedding traces in Atlassian Confluence pages can be tremendously useful for project updates, requirements management, test plans, and more. Refer to Confluence Integration for complete information.
FDA Medical Device Software Traceability Analysis
This information references Guidance for the Content of Premarket Submissions for Software Contained in Medical Devices, dated 2005 May 11.
This section is relevant to medical device manufacturers who intend to market a medical device that is subject to approval by the U.S. Food and Drug Administration (FDA). The FDA Medical Devices Guidance Document recommends that manufacturers include in their premarket submission package a Traceability Analysis document that objectively demonstrates "traceability among requirements, specifications, identified hazards and mitigations, and Verification and Validation testing." The FDA Guidance further recommends submitting a Traceability Analysis document for devices at all Levels of Concern (Minor, Moderate, and Major), according to "Table 3. Documentation Based on Level of Concern." For convenience, the "Traceability Analysis" section of the Guidance is repeated here:
A Traceability Analysis links together your product design requirements, design specifications, and testing requirements. It also provides a means of tying together identified hazards with the implementation and testing of the mitigations. We recommend that you submit for review explicit traceability among these activities and associated documentation because they are essential to effective product development and to our understanding of product design, development and testing, and hazard mitigations. The Traceability Analysis commonly consists of a matrix with line items for requirements, specifications and tests, and pointers to hazard mitigations. It is possible to document traceability simply through a shared organizational structure with a common numbering scheme; however, we recommend that you include some mechanism, such as a matrix for guiding the reviewer through the information you submit.
The objective of this section is to outline the general process of producing this Traceability Analysis document or some portion of it within the scope of the project artifacts reachable by Vivid Trace.
Preparation
Determine which traceable items and item information will be included in the Traceability Analysis document, and then consider:
- How to represent units of requirements and specifications as Jira issues.
- How relations will be represented between units in Jira.
- How to represent verification and validation test results in Jira, and how to display their result values in Vivid Trace traces.
- Whichs portions of information will be managed in Jira, mirrored into Jira from other systems, and kept outside of Jira.
- How to guarantee that the integrity of this information in Jira is maintained over the course of development in order to produce an accurate traceability analysis.
The decisions made during this preparation form the traceability model that is used to produce an FDA medical device traceability analysis report.
Producing a Traceability Analysis
- Within the Trace Studio, start a new trace.
- Configure the trace according to the prepared traceability model. Once configured, save this trace configuration for future recall.
- Run the trace, and inspect the output for errors and omissions.
- Use the export feature in the Trace Studio to capture the report in a common file format.
- Compile the exported file into the Traceability Analysis document for inclusion in the premarket submission package.
Recommended Practice: Validate the trace criteria and trace results before relying on the results. Prior to compiling the trace output into the Traceability Analysis document, run the trace and inspect the resulting trace data for errors and omissions. If the trace data does not properly cover the traceable items then the tracing criteria may need adjustment, and missing and erroneous trace data must be remediated. If you are operating on a saved trace configuration, consider saving the modifications made to it. Look over the compiled traceability analysis and judge whether it objectively demonstrates traceability among the aforementioned items.
Find Unblocked Issues
Query for issues that are unblocked, tasks that are available to be worked on next. These are issues whose immediate upstream blockers are all resolved.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Distance | 2 |
|---|---|
| Issue field layout | Issue Type Key Priority Summary |
| Issue link types | Blocks |
| Seed issues | issue IN relations('direction = inward', 'issueLinkType = blocks') AND resolution IS EMPTY ANDScope |
Unblocked issues. In this figure, issue JET-14 is the only blocker and has been resolved, unblocking JET-15 which is now ready to be started.
Explanation: The seed issues are produced using the relations() JQL function to select inwardly blocked issues of any kind, keeping only those that are unresolved and satisfy Scope. Then, those seed issues are traced along their Blocks relationships to find their blocker issues. Because it's possible that an issue can be waiting on several blockers, only a portion of which are resolved, setting the distance to at least two (2) and keeping all directions enabled ensures that any unresolved peer blockers will also appear in the graph, helping to prevent misunderstanding.
Going Further: If you have too many results, narrow Scope with more conditions. If you seek to delegate work to a particular person, add the assignee to Scope such as .. AND assignee =User Account. Get more information to aid prioritization by adding Due Date, Status, and Resolution to the issue field layout.
Identify Blocking Issues
Identify blocked issues (issues causing the blockages, known as "blockers"), and knock-on effects. Reading the results will help you understand the broader impact of the blockages and assess their impact and the value of resolving them, information that is useful for prioritizing work, directing resources, and communicating with others.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Directions | Outward, Sub-tasks |
|---|---|
| Seed issues | issue IN links('issueLinkType = Blocks') ANDScope |
Set Scope to the properties that define your field of interest, such as by project and version: project = ABC AND fixVersion = 1.2.3
A blocked issue, its blocking issue, and the downstream blockage.
Explanation: This trace is conducted in two stages. First, blocked issues and their blockers are identified using the links() JQL function according to your Scope criteria; these resulting issues are used as the the seed issues. Next, all downstream blockage is traced by Vivid Trace to complete the picture of blockages and their knock-on effects.
ISO 15504 SPICE Compliance
This information references Automotive SPICE Process Assessment / Reference Model, Version 3.0, dated 2015-07-16.
Implementing ISO 15504 SPICE compliance with Vivid Trace and Jira entails that relevant and correctly-formed issue and relationship information is in Jira prior to producing trace reports. Ideally, work products mandated by SPICE or by your particular model are managed as objects in Jira that are traceable by Vivid Trace, and relevant issue and relationship information is properly maintained throughout the project lifecycle. Pragmatically, it might be your case that not all SPICE work products are being managed in Jira directly (or perhaps mirrored into Jira from other systems) or are reachable by Vivid Trace, including requirement and architecture items, software implementation units and static verification, and change requests. In such cases, the tracing information produced here will need to be combined with information derived from other sources in order to form a complete and satisfactory traceability document for inclusion in the regulatory submission package.
Use the reports produced by Vivid Trace as a basis to satisfy the corresponding specifications for SPICE Annex D.4, "Traceability and Consistency":
- SYS.5 BP5 System qualification test results
- SYS.4 BP7 System integration test results
- SWE.6 BP5 Software qualification test results
- SWE.5 BP7 Software integration test results
- SWE.4 BP5 Unit test results
- SUP.10 BP8 Static verification results
Preparation
Trace configurations need to be created for each of the desired reports. You can achieve this by creating a trace in the Trace Studio for each of the reports. The traces must ensure that:
- The seed issues and other trace settings net all of the work products required by the report.
- Each work product is clearly identified in SPICE terms, perhaps by capturing the identity on a per-issue basis in a custom field which in turn is included in the trace's issue field layout.
- The status of each work product is indicated, by including the Issue Status and/or other fields in the trace's issue field layout.
- The resulting issue and relation information is coherent.
Recommended Practice: Give each trace configuration a name that indicates the corresponding project and SPICE report. When periodically running the set of traces over the course of the project, this naming scheme will help you to correctly and quickly identify them.
Using the Traces to Produce Reports
Run the trace configurations to produce traceability reports. With the trace reports in hand, you can use the export feature in the Trace Studio to capture the reports in common file formats for inclusion in other documents. You can also obtain an enumerated list of a particular report's issue results by using the "List issues" feature, producing the same issues but in the form of JQL query results in Jira's Issue Navigator, from where you can work sequentially and further process and output results at will.
Recommended Practice: Validate the trace criteria and trace results before relying on the results. Prior to each use of the reports, run the traces and inspect the resulting trace data, confirming the degree to which the SPICE criteria are satisfied and by extension the admissibility of the report. If the trace data does not properly cover the work products then the tracing criteria may need adjustment, and missing and erroneous trace data must be remediated. Ensure that any modifications made to the trace configurations are saved.
Recommended Practice: Generate final trace reports from freshly-loaded, unmodified trace configurations. This practice promotes reproducibility of the trace reports and improves the likelihood that decisions are based on accurate reports.
Monitor Support Request Chain of Events
Monitor the chain of events stemming from a customer support or help desk request. This enables support personnel and their managers, as well as other participants along the chain of events, to:
- Report progress of a particular support request to the customer.
- Confirm whether a fix is available yet to a customer in response to their bug report.
- Plan and estimate work and change requests.
- Monitor progress on each and every outstanding request chain.
- Coordinate operations and optimize communications between teams, departments, suppliers, and partners.
- Continuously improve processes as new issues come to light through incident reports.
- Satisfy your stakeholders by giving them direct visibility into the chain of events and by seeking their verification when work is complete.
Assumptions: The support project key is SUPPORT. Support case issues are closed only after the customer affirms resolution. Issues created as a consequence of the request are related directly or indirectly to the request, meaning that issue links are created and maintained correctly.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Directions | Outward, Sub-tasks |
|---|---|
| Issue field layout | Issue Type Key Assignee Summary Status Resolution |
| Seed issues | issue IN relations('jql = project = SUPPORT AND resolution IS EMPTY') |
Visualization of support requests that are still in motion. Evocative of Lorenz' Butterfly Effect, a simple request can spark a flurry of activity, but in our case, cause and effect can be traced both forwards and backwards.
Going Further: Monitor areas of responsibility and time pressures concerning each chain by adding the Due Date, Reporter, Resolved, and priority fields to the issue field layout. Once you have a trace set up, save it so that you can conveniently recall it whenever you wish to monitor progress and changes. If you are interested in a specific case, identify an issue that lies somewhere along the chain and open it in a new browser tab. Alternatively, get a trace of the case by visiting its issue detail page in Jira or tracing its issue key in the Trace Studio.
Scan for Prematurely Resolved Parent Issues
In a parent and sub-task relationship, the sub-tasks can be viewed as dividing the workload represented by the parent issue. In this sense, the parent represents the totality of the work and can only be considered completed or resolved when all of its work breakdown sub-tasks are resolved.
This health check visualizes parent and sub-task arrangements of issues that might be violating this resolution ordering, where a parent is resolved before all of its sub-tasks have been, and gives you a quick jumping off point to inspect questionable cases.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Directions | Sub-tasks |
|---|---|
| Issue field layout | Issue Type Key Status Resolution |
| Seed issues | issue IN relations('jql = issueType = Sub-task AND resolution IS EMPTY', 'direction = parents') AND resolution IS NOT EMPTY ANDScope |
Set Scope to the characteristics of the parent issues of interest, such as to a specific project version: project = ABC AND fixVersion = 1.2.3
A parent issue that is resolved ahead of some of its sub-tasks. In this figure, despite the issue statuses appearing to be proceeding normally, JET-1 has been resolved ahead of its incomplete sub-tasks JET-4 and JET-5 and therefore merits investigation.
Explanation: The pattern we are sifting for is resolved parents with unresolved sub-tasks. The jql parameter of the relations() JQL function finds unresolved sub-tasks, which in turn become the seed issues relations() uses to find the parents of. Only resolved parents matching Scope are kept; these become the seed issues for the Trace Studio. In turn, the Trace Studio traces from these resolved parents in the direction of sub-tasks, visualizing each parent/sub-task arrangement exhibiting a resolved parent with unresolved sub-tasks.
Going further: This pattern can be applied to any type of work breakdown structure where a superior unit can be resolved only after all of its subordinate units have been. Primarily, the jql and direction parameters of the relations() JQL function and the directions trace setting need to be adapted to map to the issue types and relations in use.
Scan for Completed Tests of Unfinished Implementations
In general, testing of a feature should be concluded after the feature has been fully-implemented, not before. Run this health check to find implementations and their tests that might be in violation of this principle.
Assumptions: Implementations and tests are represented by the Task and Test issue types, respectively. They are related using an issue link type named Tests.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Distance | 0 |
|---|---|
| Issue field layout | Issue Type Key Status Resolution |
| Seed issues | issue IN relations('jql = issueType = Test AND resolution IS NOT EMPTY', 'direction = inward', 'issueLinkType = Tests') AND issueType IN (Task, Test) ANDScope |
Set Scope to criteria that identifies your test cycle, release version, or even the whole project.
Explanation: The relations() JQL function traces from resolved test issues (provided by the jql parameter as seed issues) following inward Tests issue links types. Task and Test issues that match Scope are graphed, and nothing further (controlled by the Distance of zero setting in the Trace Studio).
Scan for Escapee Issues
Scan for issues that should be related with issues in your current working set but are not. Project artifacts not linked into your working set might be escaping your purview.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Seed issues | ScopeAND issue NOT IN relations() |
|---|
Set Scope to the characteristics of the issues of interest, such as to a specific set of projects: project IN (ABC, DEF)
Explanation: The first half of the AND conjunction ensure that only issues in Scope are considered. The relations() JQL function can operate in either of two modes; this mode, identified by its lack of seed issues criteria, will select issues based on whether they have relations to other issues or not. While relations() in this mode is able to select issues based on specific properties of their extant relations, this particular usage of relations() has no parameters and therefore simply selects a given issue as long as it doesn't have any relations whatsoever.
Going Further: Open issues in new browser tabs to modify them and establish relationships with other issues, bringing them into the working set. Add fields to the issue field layout to better understand each of the issues you are sieving through. Improve the quality of results by excluding false positives, for example by adjusting Scope or by parameterizing relations() to discriminate certain types of relations: relations('issueLinkType = Audit').
Scan for Excessive Aggregation of Issues
Epics and stories can be expected to aggregate a maximum number of work units as determined by you, but there might be some that aggregate an order of magnitude more. This health check makes such project management symptoms, or "smells", visually obvious, and gives you the opportunity to investigate and refactor these issue aggregators. At this time, Vivid Trace issues cannot be selected on the basis of having a certain number of issue relations so it is necessary to visually inspect the graphs to identify such outliers.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Directions | Outward, Sub-tasks |
|---|---|
| Seed issues | issueType = Epic ANDScope |
Set Scope to select issues of interest, such as by project.
An Epic issue aggregating an unhealthy quantity of issues. Do you have any egregious cases like this?
Scan for Non-Blocking Issues with Blocker Priority
This health check scans for issues with blocker priority but do not have Blocks issue links out to other issues. When looking over the results, ask: What is it blocking and why? Is the team aware of this blocker? By relating blockers to your working set of issues, everyone can be aware of the existence and status of blocking issues and properly sequence work around them.
Assumptions: An issue priority named Blocker is in use. Blocking relationships between issues are managed, using the Blocks issue link relationship.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Distance | 1 |
|---|---|
| Issue field layout | Issue Type Key Assignee Summary Priority |
| Seed issues | priority = Blocker AND issue NOT IN relations('issueLinkType = Blocks', 'direction = outward') ANDScope |
Set Scope to the properties that define your field of interest, such as by project and version: project = ABC AND fixVersion = 1.2.3
Explanation: The issueLinkType parameter of the relations() JQL function selects issues with Blocker priority, and the direction parameter sets selection to that of outward issue links. Setting distance to one (1) provides some visual context for those issues that have other relations.
See All Issues in Jira
This trace, perhaps driven by curiosity, digs up all of the issues in your Jira system and graphs them, but with some limitations: Issues to which you do not have browse permission will be omitted, the tracing process will continue only until the Graph Traversal Time Limit is reached, and the results will be capped at the Issue Count Soft Maximum.
Start with a new trace in the Trace Studio and apply the following changes to its configuration:
| Seed issues | project IS NOT EMPTY |
|---|
Explanation: The use of a JQL query is necessary because the Trace Studio will not perform a trace with an empty seed issues criteria. And so we need a JQL query that selects all issues. This particular query exploits the fact that every issue in Jira must have an associated project, meaning that the project field always has a value and is therefore never empty.
Watch Issues in a Graph
By watching issues in a graph you will be instantly alerted to progress, changes in status, and problems as they occur. With such timely information, you can shrink communication and feedback lag with your report line, customers, partners, and other stakeholders, generally improving communication and satisfaction for everyone involved. Use the following process to watch some or all of the issues in a graph.
- Perform a bulk operation on the issues in a graph by selecting Bulk change issues from the Tools menu from the Tools menu in the Trace Studio or from the context trace menu.
- In the bulk operation, choose the issues to start watching.
- Continuing the bulk operation, select the "Watch Issues" operation to watch the selected issues.
- Successfully complete the bulk operation.
watchedIssues() JQL function.