Use JIRA and Confluence to create a knowledge management system

Introduction

This article details out how you can use JIRA and Confluence to implement an advanced knowledge management system, where JIRA is used for knowledge acquisition, categorization and improvement, Confluence for knowledge discovery and communication.  This system has been implemented for a large global cooperation, looking to unify many different knowledge repositories into one.

People before technology

One of the first observations we made is that technology is the least of the concerns.

Getting many people, located in many different parts of the world, agree on the content of articles is seen as the most important requirement, and probably the most difficult.  Although there is one version of the truth, knowledge proposed in one end of the world is not always fully applicable for the other end.  It's like everyone speaks the same language, but every word means something else.

Confluence as a knowledge management system

Given that our customer was already successfully using confluence for various applications, the decision was made to expand its functionality for setting up the knowledge management system.

Confluence provides advanced capabilities to layout, search and communicate knowledge in the enterprise.  Its security system allows to apply fine grained restrictions for each article.

Not a walk in the park

Apart from the typical knowledge management requirements, we were asked to implement a number of specific features 

• The system must support an approval process where multiple people need to be consulted before an article can be published.  Every decision must be documented in an audit trail for later reference.
• Depending on the approval, knowledge articles can be consulted by one group but not another group
• It must be possible to rework an article and have it approved before overwriting the existing article
• The system must promote interaction with the users, such that the feedback of the users can help to improve the overall quality of the articles.
• Articles have a life span, and should be automatically expire after a predefined expiration time.

Enter JIRA in the mix

JIRA is exactly what you need, if you have to deal with advanced approval workflows involving many people.  Each approval can be tracked separately.  Notifications can be used to keep the stakeholders in the loop.  All modifications, state changes, comments are kept in a history log.

All information can neatly be structured, classified and reported on.

How to bridge JIRA and Confluence

Combining these two applications into one integrated system was achieved by introducing a synchronizer, which provides a one-way intelligent synchronization between JIRA and Confluence, based on a set of conditions (such as under what conditions an article should be published)

JIRA Setup

On JIRA we defined two issue types

• An article which tracks all relevant information (such as description, related information, ...)
• An approval sub-task for each department allowing to track departmental approvals for each article

Using approval records as sub-task issue types is very beneficial to ensure that multiple departments can proceed  with the approval process  in parallel.  Multiple approval types allow for modelling specific business requirements.  Approval records can be assigned to individuals within the company that can comment on the article ...

The article workflow

The article workflow manages the overall article life cycle and indicates if an article can be published, should be archived when the expiry date has been reached, or if an article needs to be taken offline cause it contains wrong information.

The transition of an article from one state to another has an effect on the status of the underlying approval records.  For instance when an article is submitted, all the approval records are automatically progressed to status 'review', notifying people that they need to review and approve an article.

The synchronizer in action

Depending on a number of business rules, JIRA will queue synchronization commands - such as 'publish', 'archive', 'flag', which are picked up by the synchronizer.   When processing for instance a 'publish' command, all information (including attachments) are transferred to confluence using a predefined layout.

The synchronizer is also taking care of setting the right restrictions on the article, such that only the right audiences can see specific articles.  

The knowledge space

Users looking for specific information access the knowledge management space.
The home page contains

• An instant search facility to immediately find the article you're looking for,
• A number of dashboard gadgets to highlight the most popular article in a particular category, the highest rated article, a list of favorite articles,
• a request form to establish a new knowledge article if the required information is not found.

Every knowledge article contains

• The content of the article itself (obviously)
• A way to provide comments on the article and rate its relevance
• A list of related articles (based on the taxonomy)

Technology used

• JIRA  
• Confluence
• The rate macro confluence plugin from Adaptavist to collect feedback from the users.
• Article management is implemented using the script runner plugin
• Synchronizer is a custom JIRA plugin.

More information

iDalko is the Belgian expert dedicated to the complete Atlassian product suite and third party plug-ins. We provide 'SLA-backed' professional services and solutions, including custom development of plug-ins and training sessions. Together with your team, we propose and implement a road map for your development environment.

Please contact us on how we can develop a similar solution for your environment.