Using JIRA as a Document Library


One of the most effective ways I am using JIRA is…as a document library!

Most readers will now be thinking – “eh? why don’t you use Confluence to manage your documents?”.  Well the answer is that my companies employees are not IT-friendly, and are therefore definitely not ready for a wiki.  And when making a new intranet site, I didn’t want to confuse people by having two systems.  So I decided to pick the most convenient system for our needs, which was JIRA, and try to somehow hack it to also act as a document library.  It was tough but I managed it.

This Document Library is easily the most popular feature on our JIRA, and it is definitely the ‘killer app’ that got everyone using the system.  All our employees need access to these documents, so by moving them all to JIRA we could force them all to use it and thus encourage them to use the various collaboration projects we have.

How it works

Here is a screenshot of our ‘Document Library’ dashboard page:


Here is a close up of one of the tables on the dashboard above:


As you can  see each table contains a many hyperlinks, a bit like Craigslist.   You can do this with the ‘Text Portlet’ (it must be turned on in Administration->Plugins) from JIRA 3.12+, pre 3.12 you can use the Improved HTML plugin.  Then you can use HTML to create the tables and hyperlinks. (By the way this feature is amazing and I use it for many other things, especially for showing iframes of custom-made PHP pages to support the intranet.  It may have security issues if you allow users to use it.).

When you click on one of the hyperlinks, for example “Manuals / English / A-G”, the following issue navigator page is shown:

doc-agThe cool thing here is there is a ‘Hyperlink’ to each document displayed right here, so you dont have to open each issue to download the attachment.  You can achieve this in one of two ways:

  1. Set up a customfield of ‘URL’ type, and just insert a direct hyperlink to the file (hosted on your JIRA or on an external website).
  2. Set up a customfield of ‘single line text’ type, and in the Field Configuration options set the Renderer to WIKI.  You can then use WIKI code to put a hyperlink to a file attached to the JIRA issue.  The WIKI code is like this: [^filename.pdf]. Genius or what?  An added bonus is that you can keep updating the file (filename.pdf) and so long as you do not change the filename you never have to update the WIKI customfield, because it will automatically link to the latest version of filename.pdf.

As you can see we also use Status field to indicate if the document is active or not.  We also keep an archive of old versions of the document inside the issue.  And of course the document can be discussed inside the issue, or linked to from other JIRA projects.

Notice also that we show ‘new/updated documents’ filter on the dashboard.  This is nice to show people that we are actively updating things, and for them to stumble upon documents they may be interested in.  Of course they could make search filters for updated documents in their language, and subscribe to the filter in order to get email notifications, however they are not IT-savvy enough to do it.  But the feature is there waiting for them once they get more used to JIRA.


So that is basically it.  Sorry it is not a step by step guide, but I think this should be enough to guide you to do a similar thing.  Of course, it takes  a long time to setup all the search filters that will be linked to by your HTML tables, but once done it is done forever.  Maybe someone knows a good way to quickly setup 100’s of similar filters, but I used a temp staff to do it.   If you setup the columns you want, then you can use ‘save as’ to carry those columns across to the next search filter.


One thought on “Using JIRA as a Document Library

  1. Cool idea. Fortunately, my users are a little more tech-savvy, but I wanted to mention the solution I have in the works at the moment. Basically, our “bits” of documentation (i.e., business rules and test cases) are stored as JIRA issues, but then I pull those issues into Confluence pages that are organized by system entities. So, for example, I might have an “Employee” page in Confluence and use the JIRA Issues gadget on the page to pull in the list of Business Rules around employees in our system. This approach gives my users to search and browse the wiki almost like a user guide, but I get to manage the “bits” of knowledge for each version of software and link them together, as appropriate.

Comments are closed.