Attachments are a special class citizen in Atlassian Confluence but a lot of Confluence admins do not pay attention on them until bigger problem starts to surface.
This comprehensive guide comes from our experience with our interactions with many customers and share the best practices that is useful for other fellow Confluence administrators.
We will organise the points by 5 important considerations for Confluence Administration
Integrity
Security
Performance
Cost
Uptime
In each section, we will explain on the implications of attachments on each aspect and recommend solutions to address them.
1) Integrity
Missing Attachments
Have you encountered the scenario where you tried downloading an attachment and got the Attachment File Not Found error message?
A system is useless if you cannot retrieve the information stored in them. Without the trust, users will not have the confidence to store their work in the system.
There are many possibilities that attachments can go missing in Confluence
Deleted by antivirus on the backend
Error during the uploads or blocked by the Web Application Firewalls (WAF)
Files upload when Confluence does not have sufficient disk space
Human errors during backup/restore during migration of servers
Ransomware
To address the issue, we recommend to use the Missing Attachment Scanner periodically to scan your Confluence instance. It will run a full scan of your entire Confluence site during off-peak hours to see if any attachments are missing. You can also run this integrity check before migrating to Atlassian Cloud.
For those Confluence servers with anti-virus software installed, we also recommend to enable Missing File Feedback feature with Attachment Checker. It will double check if the file is accessible upon every attachment upload.
In a normal circumstance, the virus scanner will quarantine the infected file quietly. There is no feedback provided to the end users. Nobody will know the file is missing until someone tries to download it. The app helps to address this scenario by posting a comment on the Confluence page to inform the users, so that they can take timely corrective actions.
Overwritten Files
Another scenario is multiple users working on the attachment at the same time, and overwritting the newer version of attachments with an older version. Cenote Lockpoint is a Confluence app which solves the issue with a mechanism to check out attachments for exclusive editing.
Missing Metadata
In some rare scenarios, it is possible for attachments to have missing metadata (e.g. creation date and author). This is an issue when importing the data over to Confluence Cloud. Attachment Checker helps to check during the upload and also identify the list of affected files from the Missing Attachments Scanner report.
2) Security
Malicious Files
A common security weakness for web applications is CWE-434 (Unrestricted Upload of File with Dangerous Type).
A malicious file can compromise the security in 2 possible ways
The Confluence server processes the file which results in unwanted code execution within the server itself
Users download the file onto their computers causing a virus infection
For those Confluence sites with public users, the MIME type checks provide an additional level of security against malicious users who rename the file extension to bypass the file type checks.
Information Disclosure
Another security risk is unintentional information disclosure or wiki leaks. Sometimes an intern or external vendor may download all the attachments for purposes other than work.
While the easiest way is to secure the Confluence spaces with the correct permissions, it is also possible to manage these groups by
restricting them from downloading files from Confluence
keeping a log of the download activities within the space
3) Performance
Processing of large attachments
One of my favourite feature in Confluence is the ability to preview documents directly without having to download it and open with another application. However the document conversion process with very big files may cause performance issues in some cases.
When you insert a file into a page (for example a Word document, or Excel spreadsheet), Confluence will convert the contents to a format that can be viewed inline in the page, in the preview, or in some macros. This can be quite memory and CPU intensive, and has been known to cause out of memory errors when processing very complex files.
We had a customer who has encountered irresponsive Confluence on several occassions due to users uploading certain type of files. We developed the Large Attachment Tracker to facilitate the Confluence admins to do a quick check if this is a cause whenever users are reporting a slowdown.
Streaming of Media Content
If you are using Confluence as a corporate intranet or learning management system, Confluence may experience slowdown after a major corporate event when everyone is simultaneously checking out the event videos and photos from the server. Confluence is not a video streaming server, so it may not be able to handle very high workload when a lot of users are downloading large videos at the same time.
It is a best practice to split the photos and videos into several pages and turn off autoplay so that they do not hoard up a lot of resources within a single page load.
Anti-Virus Scanners
Another common reason for Confluence slowing down is due to the virus scanning. The CPU and disk I/O can increase due to inspection of files. Atlassian has put up a KB article on the best practices and workarounds when Confluence is suffering a performance issue.
A possible solution is to check each file once during the upload. This reduces the unnecessary checks during subsequent file access. It is possible by integrating with a compatible virus scanner and queuing all the uploaded attachments for a scan without overwhelming the server resources.
4) Cost
For large Confluence sites, it is a never ending uphill challenge. People are uploading attachments everyday but the disk space is finite. Without taking any action, the disk space will eventually be full.
Most people will say increasing the disk storage is a small problem since disk storage is very affordable nowadays.
Types of Hidden Costs
However, the hidden truth is the real costs is more than buying a bigger hard disk. There are a few types of costs.
Type of Cost
How it affects
Backup cost
The amount of disk space used is even higher since it is a common practice to keep multiple generations of backups
Bandwidth cost
This may not be applicable for everyone. We also have a customer whose users are working on ships and their Internet bandwidth is limited and expensive. Hence they want all their images to be scaled down instead of the high resolution quality which is a norm nowadays.
Operational cost
This is an invisible cost in terms of energy consumption and time that system engineers spent on – increasing the disk storage – managing the backups – doing upgrades and reindexing – executing virus scans – migrating to new hardware – generating reports on disk usage by Confluence spaces
Storage cost
There is a need to upgrade to a bigger hard disk. For those planning to migrate to Confluence Cloud, it is needed to upgrade from the Standard plan to the Premium plan once the disk usage hits a limit of 250Gb.
Usage cost
For larger files, it takes slightly more time to download and open. – Every user takes 5 more seconds for each download – A typical user downloads 5 such files a day – A company with 500 users can save 3.4 hours a day or 104 hours a month When the disk space is insufficient, they need to spend time to do housekeeping.
There are 2 schools of thought on how to address the challenge of ever growing attachments.
Removing useless content
The first approach is to remove those content that is no longer in use. There are 2 apps on Atlassian Marketplace which allow users to identify unused attachments and bulk deletion:
Lastly, when the total size of attachments grows, it takes a longer time to execute backups and upgrades. This implies a longer downtime for scheduled maintenance activities
Conclusion
Although this article may be more relevant for bigger or enterprise scale Confluence instances, it is useful to start addressing the issues early than to spend more effort doing the cleanup in the future.
external system sending thousands of REST API calls (to retrieve or update update)
incompatibility across plugins
Individually each app works ok, but they cause issues with each other
CPU intensive jobs
e.g. project level exports can be intensive if there are a lot of custom fields
a lot of custom fields
By updating the custom field context, it can help to improve the performance
The best way to improve the speed is to identify the root cause and treat the problem accordingly.
If it is a plugin related issue, you can try to disable the plugin to isolate the problem
If it is a data triggered issue, you can try to remove the data
You can use Site Statistics for Jira Cloud to track the historical growth of issues in your Cloud instance. It can be helpful to see if the slowness is caused by huge increase of issues.
What does Atlassian Intelligence says?
I posed the question “Possible reasons causing Jira Cloud to be slow” and got the answer below
High network latency: Slow internet connection or high network congestion can result in slower response times for Jira Cloud.
Large number of issues: If your Jira project contains a large number of issues, it may impact the performance of Jira Cloud.
Heavy usage: Concurrently performing resource-intensive operations such as searching, reporting, or updating a large number of issues can slow down Jira Cloud.
Misconfigured plugins: In some cases, misconfigured or poorly optimized plugins can cause performance issues in Jira Cloud.
Insufficient hardware resources: Inadequate server resources such as CPU, memory, or disk space can affect the performance of Jira Cloud. ❌
Outdated software version: Running an outdated version of the Jira application may lead to performance degradation and compatibility issues with other components.❌
To troubleshoot and improve the performance of your Jira Cloud instance, you can follow these steps:
Check your network connectivity and ensure that you have a stable internet connection.
Optimize your issue database by archiving or deleting unnecessary data to reduce database size and improve overall system performance.
Review installed plugins and disable any that are not essential or causing slowdowns. Ensure that all installed plugins are up-to-date with compatible versions for your current JIRA setup.
Monitor system resources (CPU, memory) on the server running JIRA to identify any bottlenecks and consider scaling up hardware if required.
Regularly update your JIRA application to benefit from bug fixes and performance improvements provided by Atlassian through new releases.
❌ The hardware for Jira Cloud is managed by Atlassian. It is always upgraded to the latest version automatically.
One of Jira’s strengths is that it allows 3rd party integration via REST API calls. By providing the username, password and Base URL, it is possible to 3rd party apps to query or update Jira automatically.
In this article, we will share why using API Tokens is a better and safer option than using Password Authentication.
The Power of Passwords
Besides entering passwords on the Jira login screen, it is also possible to provide the passwords on 3rd party applications or scripts to execute REST API calls.
Some of the use cases are like
Create issues from Slack
Send alerts to Microsoft Teams
Update Jira issues with Commits information from GitHub
Integrate with your in-house systems
If the password fails in the wrong hands, it is possible that
Wikileaks of your confidential data
Your Jira system can slow down drastically due to excessive API calls which affects the usage of other users
Benefits of using API Tokens over Passwords
By using API Token, it improves the security of your Jira instance
Safer – The API Token has a certain level of password complexity which defends against dictionary attacks
Isolation – It distributes the risk by having a different API token for each 3rd party integration. It is possible to revoke/reset the token for that application without any impact to other applications.
Differentiation – With a different mechanism, it is possible to apply more stringent checks on the usage of API Tokens (e.g. restriction by IP address range)
Control – It restricts ordinary users from using their credentials to do REST API calls
Availability – For sites running on Single Sign On. Users will not know their passwords other than their Windows passwords
Validity – It is possible to set the expiry date of the token
It allows basic authentication with API Tokens. Currently, it is not possible to use the Jira Data Center’s Personal Access Token together with the username on 3rd party websites.
Warning: If you disable Basic Authentication with passwords in the System Wide settings, you also can’t authenticate on non REST endpoints with API Tokens directly. You can still do that by reusing a session you got from authenticating with an API Token.
Able to limit usage to particular IP ranges
It is possible to limit the usage of the API token to the IP address of the internal system. You can ensure the REST API calls are coming from your trusted network.
Block requests with malicious characters in path
This is a bonus feature which helps to defend against some attack vectors.
Limit usage of API Tokens
It is a security best practice to grant rights only to users who needs it and has proper training. There are incidents arising from users who entered their Jira passwords on 3rd party sites or executed a buggy script.
Tip: We recommend to create a group “jira-api-users” to manage those service account users who can use API Tokens.
Set a validity of the API Token
If the token is for testing or for temporary usage, the Jira admin can just set a shorter validity that will expire automatically. Otherwise it relies on the Jira Admins to remember to revoke the access manually.
Service Accounts typically do not have a password validity. If the service account is from an Active Directory, there could be disruption if there is a 90 day reset password policy.
By using the Active Directory passwords, it is possible that account is locked out of all applications after multiple wrong password attempts.
Control over audit logging
It offers admins a fine level of control over the information to be logged.
Automation for Jira is one of the most popular apps on Jira. The app allows users to automate and extend Jira with no coding required. Being very user-friendly, there are a lot of admins who can dive straight into using the tool without reading the user guide. As part of our Best Practices series, we have summarised the key things you need to know in this blog post.
For those who are new to Automation for Jira, you can check out this YouTube video below for an introduction.
Things you need to know
1) Asynchronous processing
To speed up on the response time, the Automation for Jira plugin will add all updated issues into a queue. Although there are 8 background threads to process the requests, it still does not ensure the issue are processed immediately. Therefore, users will need to refresh the issue to view the changes applied by the automation rule.
It is possible to select synchronous execution of the rule but that will have some impact in the performance.
2) Rule Matching/Execution
Whenever an issue is updated, the issue is matched against all the configured automation rules (global + project) . As a result, when there are a lot of automation rules, it takes time to
to check against each individual automation rule
to execute against each matching automation rule
Hence it is important to reduce the number of global automation rules by setting them as single project rules whenever possible. You should try to optimise the rules with more specific requirements.
If you are seeing a lot of No Actions Performed in the rule’s audit log, then there might be chance for optimising the rule
3) Traceability
The powerful app allows multiple rules to update an issue due to a single triggered event. As a result, it may not be direct to identify the problematic rule. Moreover, if multiple rules are chained together without proper planning, it could lead to “spaghetti code” scenarios which is not easy to troubleshoot.
If the update is via workflow post functions, it would be easier to identify the bug.
4) Performance & Runtime
To cater to the flexibility and power of the Automation for Jira plugin, there are some tradeoffs. One of them is the processing time for automation rules is slower than post functions. For example, a simple assignment rule can take up to 3s to complete.
We have encountered some rules that can take up over 10 seconds to be processed. So you should check the audit logs on the performance of the rules.
5) Service Limits
Not a lot of users are aware of the Service Limits which can affect the execution of the automation rules. Some of the common service limits are listed in the table below:
When any of the limits is breached, the rules will be throttled until the limits are not exceeded. This could result in some unexpected behaviours as the issues are not processed during this period.
The likelihood of throttling is increased when a huge number of issues are created via REST API or Test Automation plugins.
6) Housekeeping
The app maintains an audit log of the rule executions. Over time, the audit logs can build up which impacts your Jira database performance and clogging up your disk space.
We have encountered some sites which the retention period is set to the default value of forever.
It will be good to revise the retention period and set the schedule expiry during off-peak periods. For more info, check out this KB article.
7) Integration with other apps
Not a lot of people are aware that there are other apps which are compatible with Automation for Jira app. If you have these apps, you can use them with automation rules too.
Try to scope the rules within the project if possible. Use global rules only when necessary.
Make sure your Jira project administrators know what they are doing. You can consider restricting the rights to trained project administrators (e.g. jira-power-admins group)
Conduct periodic audits. You can view performance Insights to see if there is any issues
Conclusion
Automation for Jira is a very useful feature. However, there is a likelihood to see everything as a nail when you have a hammer in your hand. This can result in performance issues in time to come.
We will need to understand what is the requirements and the underlying approach used by various apps. For certain scenarios, we feel it is better to use post functions with apps like
We have identified Jira Dashboards can be a potential bottleneck while helping our customer to tune the performance of their Jira. This article explains why Jira takes longer time and give some tips on how to speed things up.
Why my Jira Dashboard takes a long time to load?
These are some factors that contributes to the slowness of Jira:
Huge number of gadgets within a single dashboard
Gadgets with complex reporting
Filters with a huge number of issues
Huge number of gadgets
Whenever a Jira Dashboard page is loaded, the browser will send a number of requests to the server for all the CSS and Javascript required. (For more details, check out JRASERVER-62126). When there are more gadgets, it will fire more requests.
It will be faster if you focused doing 1 task at a time versus doing 100 tasks concurrently. By the same principle, your dashboard will load faster if Jira has less requests to work on at the same time.
We have a couple of support tickets which the end users added a lot of Gauge Gadgets in their dashboard. As a result, some gadgets on the dashboards cannot load.
This is because the browser will silently throw the error message Failed to load resource: net::ERR_INSUFFICIENT_RESOURCES if it detects that are way too many requests within a short interval.
To support the users, we introduced Multiple Filters Counter Gadget that can display multiple counter within a single gadget.
Complex Reporting Gadgets
Not all Jira gadgets are the same. There are some gadgets which involves complex processing. For example, our Tissue for Jira app performs the handy task of traversing all the linked issues and extracting the various field values to present a tabular overview.
If you are using such complex reporting gadget, it will be advisable to have lesser gadgets within that dashboard.
Filters with many matching issues
It is likely that some dashboards load very fast when they were created initially. However, as the number of issues in the project increases over time, the performance of the dashboard become slower without the original author noticing.
The simplest way is to pump more computing resources like more CPU and memory. Jira Data Center also scales the performance by distributing the workload across more nodes.
Split into multiple dashboards
As mentioned previously in Best Practices in Jira Dashboard Reporting, it is recommended to keep a dashboard to its objectives to allow people to identify the action required.
But it is troublesome to have many dashboards
Beside adding the links to various dashboards as project shortcuts in your Jira project, you can also add links to related dashboards using our free Link Menu Gadget to facilitate navigation. You can also add links to the your Confluence spaces and other related project resources too.
If that is still not enough and you want to access your dashboards easily from everywhere in Jira. You can organise your Dashboards in cascading Dashboard Folders which can be accessible in the Jira top menu.
What is the performance of your Jira Dashboard?
You may want to do the 23 seconds test on your frequently used dashboards. If it is taking longer than that, you might want to tidy up your dashboards.
Jira Dashboards is a very powerful feature if used correctly. In this article, we will share with you the common pitfalls as well as some best practices based on our experiences as an Atlassian Solution Partner.
Why people use Jira Dashboards
Dashboards can be from a macro perspective like % of project completion to micro level on the list of tasks with their statuses.
Some common use cases for Dashboards are:
monitor the progress of the tasks
track the KPIs and the health of the project
highlighting important stuffs (e.g. SLA breach, bottlenecks, shortages) for action taking
show progress to motivate the team
More organisations are preferring dashboards over reports because of the following reasons:
live information – able to see the current status which is more accurate
time saving – there is no need for someone to spend time to compile the weekly/monthly progress reports manually
interactive – as compared to a chart image in a PPT/PDF
allows drilling in – you can zoom into the details of the issue for more information
self reinforcing – it encourages people to update their Jira issues regularly
Common pitfalls and recommendations
Security / Information Disclosure
From our Jira consulting experiences, there are a number of instances where the dashboards and filters are accessible by users without logging in.
Although Jira’s permission scheme will prevent public users from viewing the issues, it is still possible to disclose sensitive information which may not be meant for public eye.
You should check whether there is information disclosure by logging out of Jira and visiting the URLs
Unless the dashboards/filters are for public access, users should not select Public for the Add Shares option.
Tip: There is a “Sharing with anyone on the web” in Jira configuration which you can disable to remove the Public option if your Jira instance is not for public access.
Performance and utility
Another common pitfall is people tends to create 1 dashboard for each project and cramp everything inside. We have seen a dashboard with over 20 gadgets added. As a result, it clutters the dashboard and is slow because it has to load a lot of information. This can also slows down the Jira instance for other users.
From a design point of view, this is bad because it introduces a lot of noise in the dashboard. As a result, people cannot zoom into the important things that they need to take action from the dashboard.
A well designed dashboard should fulfil the following:
Targeted for the role/purpose – A management report should not include the micro information like the list of tasks. Likewise a developer will be more concerned about the list of tasks he needs to work on. You can create different dashboards for different roles.
Incite emotion or action – it should bring attention to the readers to take any necessary action. With correct use of colours and placement, users can determine the severity easily.
Responsive – it should be fast to display the information without the reader having to scroll through many screens to read the entire page.
Discoverability
A dashboard is useful only when there are people using it. Another common pitfall we observed is that every user tends to build their own dashboards. While this is flexible, there are some disadvantages like:
duplicated effort to create and maintain the dashboards
decreased utility since only 1 person is using it
some users are unaware on the types of gadgets available that they can use for reporting
some users lack the proper training on how to write complex JQL queries and design good useful dashboards
no standards on the performance metrics to monitor within the organisation
To tackle this, we advocate to design a set of dashboards as a template for every Jira project. When a new project is created,
the set of dashboards and filters are also created based on the template
The filters and dashboards are shared with the project so that people who have access to the project can access them
Then the dashboards/filters are added to the Jira’s project shortcuts where all project members can access easily
They can also be added to the Dashboard Folders and Menu Gadgets so that users can easily navigate to the reports
Maintainability
Another common problem that Jira admins face is obsolete dashboards/filters. By default, only the original creators can edit their dashboards/filters.
From Jira 7.12 onwards, it is possible to grant permissions for other team members to edit filters/dashboards. Hence a useful tip after creating a filter/dashboard will be granting permissions to the associated project roles
to grant view permission to all project members
to grant edit permission to the project administrators
Naming Convention
We also recommend to define a naming convention for filters and dashboards. E.g <Jira project key> – <purpose>.
This is especially helpful for users when they are searching for a filter when configuring the gadgets. For very large instances, you can find multiple filters with the same name while selecting a filter for a gadget.
This is an ebook on a collection of Jira best practices that Atlassian has gathered from Jira experts around the world.
The title “Be a Jira Hero – A guide for Admins, by Admins” is well deserving. Therefore we recommend all Jira administrators and wannabes to read the 25 pages ebook.
Jira Best Practices ebook
The ebook is well-organised into different sections with short but clear snippets of wisdoms:
How to keep Jira clean and simple for your users
How to use issues effectively
Best practices on managing Custom Fields and Screens
Things to consider when building workflows
Tips on managing backlog in Jira
How to get people to work on the issues
Best practices on designing the Jira dashboards for even more effective reporting
Shortcuts & Hacks to work faster with Jira
How to make use of automation to make life easier
One Common Mistake
For example, the book has highlighted in Tip #20 to incorporate Resolution into the workflows. We observed that a number of Jira admins who did not have formal training tends do not understand the concept of resolution. Consequently, they overlook this important step while creating new workflows. While the Jira appears to be working, the implications are some built-in reports may be inaccurate and an important piece of information is missing.
Our Additional Jira Tip
Dashboards are very useful if they are used correctly. Team members can have visibility on the progress and be reminded on the outstanding tasks. Furthermore, Management can have clear visibility without spending a lot of time preparing routine reports. As a result, users will understand the value of updating their tasks in Jira.
Multiple Filters Statistics Bar Chart Gadget
Horseshoe Gadget Jira
Conclusion
To sum up, if you are a Jira administrator, you should download the ebook and review whether you have been applying the Jira best practices.
This is a “lengthy” guide on the best practices on choosing and managing a Jira app. Coming from our years of experience as an Atlassian Solution Partner, it covers
How to evaluate a Jira app
How to better manage the apps installed in your Jira instance
Things that Jira administrators need to watch out
Jira Apps from Atlassian Marketplace
By installing additional Jira apps, you can add new features to your Jira. For example, some of our popular Jira apps
Being an Atlassian Solution Partner, there are a number of criteria that we consider before recommending a Jira app to a customer. They are:
Fit to Purpose
The app should be able to address the requirements fully. It should be easy to use. The additional feature should not cause confusion to the existing users. We will also assess their design is robust and does not conflict other plugins or use cases.
Atlassian Marketplace Listing
It is very important to check out the app listing on Atlassian Marketplace. It contains a lot of useful informations like
Rating and Reviews
Number of Active Installations
Vendor Accreditation
Compatibility with the latest version of Jira
Support
Rating and Reviews
While the rating and reviews do not mean much for a newly listed app, they do give insight of poor services or badly designed apps. Typically, users will flag out any issues that require attention. So, if there are no negative reviews, it is safe. And if there are a number of good reviews, then it is very safe.
Number of Active Installations
If an app is popular with a significant number of active installations, that is a good sign that the app is useful and functioning without major issues.
Vendor Accreditation
Atlassian has a Top Vendor program who has met the following requirements
App traction – Their paid apps must attain at least 500 active installations
Timely support – Has a Service Level Agreement (SLAs) and committed to provide at support for their users
Support Website – Customers can raise support request easily via a website or email when necessary
Vendor reliability – Atlassian conduct checks periodically to ensure they offer great customer experiences
For those exceptionally good ones, they are further recognised as Gold/Platinum Top Vendor.
Versions compatibility
If the app is only compatible with an older version of Jira, that is a big warning. You do not want to be left dangling helplessly for your next Jira upgrade.
Support
Some apps are explicitly marked as unsupported. Unless you can accept the risks, it is better to avoid them.
Data Center Approved
Data Center approved apps are those that have passed Atlassian’s stringent criteria for use in Jira Data Center environments. As it takes considerable effort to become a Data Center Approved App. vendors will usually do that for their established apps. Therefore this is a plus point.
Thorough Documentation
Although some users will usually dive in without reading the user guide, it helps when the documentation contains
A quick overview of the functionalities
Comprehensive writeup and how to use
FAQs to facilitate on-boarding and best practices
Up-to-date release notes
An easy to navigate structure
Unless the app is really simple or open source, it is a risk to install an app with a one pager documentation.
Pricing
Last but not least, the pricing of the app is also an important consideration. The app should have a reasonable pricing so that you will be assured of support for long term. It is also possible that you will upgrade to higher user tier or Data Center as Jira becomes an enterprise application. Hence the pricing for higher tiers should not exceed your budget.
For free apps, they should be from a credible publisher with significant number of installations. Otherwise, the publisher may withdraw support in near future.
Before Installing an App
Downloading the compatible version
There is a common mistake for Jira administrators who are unable to download the app via the Atlassian Universal Plugin Manager. The default download link on the Marketplace listing is for the latest version of Jira.
If you are not using the latest version of Jira, the correct steps to install/upgrade the app will be
Click on the Versions tab
Select See all … versions
Hover on the topmost version which matches your Jira version
Click on the Download link
Upload the file via Atlassian Universal Plugin Manager in Jira
Testing
It is a best practice to install the Jira app on a Test environment first. It is not advisable to install an app directly onto the Production environment. This is because some apps may make changes to the database. Some changes are not be reversible when you uninstall the app later.
Maintaining a Change Log for the Apps
We usually advise our customers to create a Confluence page to track on the app installations, upgrades and uninstallation. This best practice helps to keep all the related information organised neatly on a single page.
The change log table can include the following information
Date of Change
Changed By
Name of App
Action Performed (e.g. install/upgrade/uninstall)
From Version
To Version
Jira Issue Key
Additional Notes
This will be useful especially when there are multiple Jira administrators who can perform changes. Although the audit log has a record of the changes, the default data retention period is only 90 days. It is also not that easier to read.
By using a Change Log, the administrator can link the change with a Jira issue and add notes. The Jira request helps to identify the user who raised the request to install the app together with the background context.
When there is an incident, the App Change Log will be useful to identify issues caused by app changes.
Things to watch out
It is not the end of the story after installing the app. There are a few useful tips for Jira administrators to watch out.
Hardware Sizing
With more apps installed, it is likely that the memory footprint might increase over time. It will a best practice to check on the JVM memory utilisation from the System Information page after people start using the features. Likewise, CPU usage monitoring is also a best practice.
Expiring Licenses
There are a handful of apps which will stop working without an active license. So be sure to renew your licenses before they expire to gain access to support and newer releases.
Being informed
You can click on the Watch app link on the Marketplace listing. By doing so, Atlassian Marketplace will send you an email whenever there is a new version released.
Upgrading the Apps
As a best practice, it is important to upgrade regularly to get newer features, performance improvements and bug fixes. For security vulnerabilities, you should upgrade as soon as possible once you received a security advisory.
Scheduling Upgrades
Although there is no need to schedule a maintenance downtime for installing/upgrading Jira apps, it is a best practice to do that during off-peak periods. During an app installation, there is a short interval where the Atlassian Universal Plugin Manager removes the old version and installs the newer version. You do not want any critical operations in between that period.
Also some apps may execute jobs during the upgrade to do some data crunching to support a new feature. Therefore, please read the release/upgrade notes for the app before you click on the upgrade button in Jira.
