The ConDec Jira plug-in enables the user to capture and explore decision knowledge in Jira. Decision knowledge covers knowledge about decisions, the problems they address, solution proposals, their context, and justifications (rationale). The documented decision knowledge can be linked to Jira tickets such as features, tasks to implement a feature, or bug reports. The plug-in supports four documentation locations for decision knowledge: entire Jira tickets with distinct types, comments and the description of Jira tickets, commit messages, and code comments.
The plug-in works for Jira server and data center instances. The following prerequisites are necessary to compile the plug-in from source code:
- Java 11 JDK
- Atlassian SDK
The source code is compiled via terminal. Navigate into the cures-condec-jira folder and run the following command:
atlas-package
(Run atlas-package -DskipTests=true to skip unit tests to speed-up compilation.)
The .jar file is created.
Run the plug-in locally via:
atlas-run
The precompiled .jar-File for the latest release can be found here: https://github.com/cures-hub/cures-condec-jira/releases/latest
The ConDec Jira plug-in is available via the Atlassian Marketplace.
Alternatively, the plug-in can be installed via uploading the .jar file to your Jira application:
- As a system administrator, navigate to Jira's administration console and click the "Add-ons" tab.
- Select "Manage add-ons" on the side-bar.
- Click on "Upload add-on" and select the previously compiled .jar file.
- Click "Upload" for upload and installation.
- Activate the "Decision Documentation and Exploration" plug-in.
- Activate the plug-in for the specific project in the setting page.
ConDec adds several views and features to the issue tracking system Jira. The user interface structure diagram provides an overview of the views and features.
The ConDec Jira plug-in adds knowledge overviews in a separate page. The indented outline lists all documented knowledge elements. The user can choose the type of the top level knowledge element, e.g., to understand which decisions were made or which issues (decision problems) were addressed in the project. Decision knowledge elements can be selected and the related elements can be viewed and selected as well.
Knowledge overview page showing the indented outline (left) and a node-link tree diagram of a single decision (right)
The node-link tree diagram enables the user to explore decision knowledge related to the selected decision knowledge element.
The user can filter the decision knowledge and manage it using drag and drop and a context menu.
The ConDec Jira plug-in provides a Jira issue module that enables the user to explore decision knowledge related to a specific Jira ticket such as a requirement.
The project setting page enables the user to:
- Activate the plug-in for the specific project.
- Activate whether decision knowledge can be stored in entire Jira tickets. If activated, the plug-in automatically adds decision knowledge types to the issue type scheme of the project.
- Configure the rationale model.
- Configure the features listed below.
ConDec offers the following features:
- Decision knowledge documentation in various documentation locations
- Knowledge management
- Extraction and presentation of knowledge in git
- Interactive knowledge visualization based on a knowledge graph containing requirements, decision knowledge, code files, and other software artifacts
- Change impact analysis
- Definition of done checking to support high quality of the knowledge documentation
- Rationale backlog listing knowledge elements that violate the definition of done
- Automatic text classification to identify decision knowledge in natural language text
- Recommendation of solution options from external knowledge sources
- Link recommendation and duplicate recognition
- Nudges for decision knowledge documentation and exploitation
- Decision grouping
- Creation of release notes with explicit decision knowledge
- Metrics presentation in a knowledge dashboard
- Knowledge export
- Webhook to inform a receiver system about changed knowledge
The plug-in consists of a frontend and backend component. The backend is implemented in Java code organized into 15 packages. The following class diagram gives an overview of important classes (only ten packages are included).
Overview of important backend classes (UML class diagram)
The model classes represent the data model of decision knowledge and other software artifacts in Jira. The class KnowledgeGraph contains KnowledgeElements and Links. The class KnowledgeElement represents decision knowledge (e.g., decision problems, alternatives, decisions, pro and con arguments) and other software artifacts (e.g., requirements and code). Each knowledge element has attributes to describe its location (DocumentationLocation), its knowledge status (KnowledgeStatus), and its type (KnowledgeType), whereby the possibilities for the knowledge status depend on the type of the knowledge element. The documentationLocation attribute describes where an element is documented, for example, if it is documented as an entire Jira ticket, in the description or comments of a Jira ticket, or in code. Each knowledge element also has an attribute origin. By default, the documentationLocation and origin of an element are the same, but for knowledge elements that originated in commit messages, the documentationLocation is the text in a comment of a Jira ticket, but the origin is a commit message. This is due to the fact that ConDec parses the decision knowledge from commit messages and automatically posts them as comments on the related Jira tickets.
Model classes and associations (UML class diagram)
The classes in the rest package provide representational state transfer (REST) endpoints for communication between the frontend and backend. They provide methods that are called by the JavaScript code in the frontend to get the data from the backend for the respective feature (see next section).
The persistence classes manage the storage of decision knowledge in relation to other software artifacts. The KnowledgePersistenceManager is the central class responsible for knowledge storage. The JiraIssuePersistenceManager manages the storage of decision knowledge elements as Jira tickets. Jira issue links are used to link decision knowledge elements documented as entire tickets to each other and to Jira tickets of other types such as requirements. The JiraIssueTextPersistenceManager manages the storage of decision knowledge elements in the description and comments of Jira tickets. The GenericLinkManager manages linking of the decision knowledge elements in the description and comments and the AutomaticLinkCreator performs automatic linking.
Overview of classes for knowledge persistence
The git classes deal with the extraction and presentation of code changes and decision knowledge from git.
The view classes represent the views on the knowledge graph. The filtering classes provides ways to filter the knowledge graph. The config classes store the configuration options and settings. The classification classes deal with automatic text classification to extract decision knowledge from various knowledge sources.
The quality classes check whether the knowledge documentation fulfills the definition of done. The metric classes calculate metrics on the knowledge graph data structure. The metrics are presented in the knowledge dashboard.
The ConDec Jira plug-in provides a representational state transfer (REST) application programming interface (API), e.g., to retrieve, insert, update, and delete decision knowledge in Jira. These services can be accessed via the following link:
Jira base URL/rest/condec/latest/knowledge|config|view|dashboard|grouping|dodchecking|git|decision-guidance|linkrecommendation|nudging|classification|releasenotes|webhook/REST service
The frontend component of the ConDec Jira plug-in uses the REST services in the REST JavaScript client.
This repository contains unit tests that are automatically executed when calling atlas-package.
The repository cures-condec-jira-system-tests contains automated system tests that require a running Jira instance with the ConDec Jira plug-in installed.
The static code quality is tested with various source code analyzers, such as PMD and ESLint.
The backend (Java) code of the plug-in contains LOGGER.info() statements that can be used to monitor the plug-in usage,
e.g., to evaluate which views the users prefer.
You need to configure the log4j.properties so that LOGGER.info() statements are logged.
More infos on usage data analysis can be found here.