Overview

This document describes best practices for promoting Jira configuration from the development to production environment. You can use Botron's Configuration Manager add-on to effectively test your desired changes prior to rolling them out in the production environment. 

Definitions

For this document, we'll assume the following definitions:

• Development – A free-for-all one or many environments where users can play with cutting-edge or risky changes.

• Staging – A pre-production environment, where the systems administration team can establish exact procedures prior to rollout. The staging should be a clone or close replica of the production environment. 

• Production – Your live instance, expecting minimal downtime and well-tested changes.
• Configuration snapshots are created using the Configuration Manager for Jira add-on and represent the state of your Jira configuration objects and their relations to each other at a given point in time. There are two types of configuration snapshots:
  • Project snapshot – Contains the configuration of a number of selected projects (with their schemes, workflows, fields, etc.)
  • System snapshot – Contains the entire configuration of a single Jira instance (projects, workflows, schemes, screens, etc.)

Architecture Strategy Recommendations

If Jira is a critical system, we recommend a 3-tier architecture strategy consisting of development, staging, and production environments.

If Jira is not a critical system, you can use a 2-tier strategy with development and production.

Planning

Prepare environments (hardware)

Staging should be as close as possible to the hardware used for the production server. Although the development can be any type of hardware, the general guideline is that it is as close as possible to production too.

Keep the staging in sync

The staging environment is used as final rehearsal prior to introducing changes in production. To ensure that the rehearsal is accurate and to eliminate potential surprises during the actual deployment, the staging should be an identical replica of the production environment.

Depending on the type of hardware used for production, there are several options for keeping the staging in sync:

• Physical hardware – Keeping staging in sync can be accomplished by either cloning the storage used for the database and filesystem, or simply following the Jira Backup/Restore procedure.
• Virtual machine  – Creating a snapshot of the production, and creating a new virtual machine from this snapshot.
• Configuration Manager  – A unique feature allows the staging server configuration to be restored with the production.

Configuration Manager for Jira

Botron's Configuration Manager for Jira add-on needs to be installed on each Jira server. 

Tracking

It is recommended that every change to Jira setup and configuration is tracked via change request ticket. The change request ticket should follow the chosen promotional path and include the initial user request, as well as additional information as it progresses through the lifecycle – configuration snapshot, change and impact analysis, duration, etc.

Disruptive changes

A recommended IT practice is that all non-emergent fixes should be introduced in a defined cadence, e.g. each Friday afternoon from 1 to 3 PM. The changes introduced can be segmented into two groups – disruptive and non-disruptive. The former can be introduced only in defined maintenance windows when the user access is limited.

Communication strategy

A communication strategy is designed to inform Jira users about the changes that will be introduced – this information includes the exact date of the changes roll-out, as well as a comprehensive summary.  A link to the change request ticket might also be included.
The communication strategy can be conducted via email, notification banners, or other standard means of internal communications. A recommended practice is to inform the users at least 5 times:

• 1 week prior to the changes being introduced
• At the beginning of the business day
• 1 hour before
• Notification right before
• After the changes are introduced, a message indicating success/failure.

System health

The system health of all 3 servers should be assessed, and any Integrity Check errors should be resolved.

Stages of three-tier architecture strategy 

In this section, we'll walk you through the process of rolling out changes for Jira production environment with a 3-tier architecture strategy. The illustrated processes require the installation of the Configuration Manager for Jira add-on, which enables you to create and deploy configuration snapshots between the different environments. The add-on should be installed on each environment. For more information regarding licensing – visit the FAQ section.

First stage (development)

Overview of the first stage:

• Environment: Development environment
• Goals: Develop new project configuration; allow user acceptance testing; create configuration snapshot that can be promoted to the staging environment.
• Users: Business users or administrators. Open to anyone with expertise in Jira configuration.
• Tools required: Configuration Manager for Jira

The first stage of this process is conducted in the development environment. It typically involves the following users: business users or administrators, anyone with an expertise in Jira configuration.

The steps of this stage are as follows:

1. Develop new project configuration – a project configuration can contain several configuration elements, e.g. workflows, custom fields, screens, etc.
2. Once the new configuration is in place, a user acceptance testing is performed to ensure proper configuration.
3. Create configuration snapshot that can be promoted to the staging environment.
   
   
   
   
4. Download the configuration snapshot (if your Jira configurations are being tracked via tickets, the snapshot should be attached to the appropriate tickets.)

Second stage (staging)

A high-level overview of the second stage:

• Environment: Staging environment
• Goals: Validate proposed configuration changes; assess changes and impact; prepare communication plan; estimate the required downtime, and clarify production rollout procedure.
• Users: Jira System administrators
• Tools required: Configuration Manager for Jira

The second stage of this process is conducted in the staging environment and involves Jira system administrators who perform a comprehensive validation to ensure that the introduced changes won't impact other projects. There is a difference between change and impact. For example, a change in the name of a workflow status (from Done to Accepted) might interfere with the company policy or break JQL filters used for reporting. A typical example of an impact is when a change to the notification scheme is introduced – that change will likely impact other projects in production.

The steps of this stage are as follows:

1. Deploy configuration snapshot and validate proposed configuration changes.
   
   
   
   
2. It is crucially important to validate the proposed new configuration for changes and impact. If the result is negative – go back to Development.
3. Communicate any changes to your users prior to officially introducing them.
4. Estimate the required downtime and clarify production roll-out procedure by measuring the required deployment time and updating your ticket.

Third stage (production)

A high-level overview of the third stage:

• Environment: Production environment
• Goal: Roll-out configuration changes to production
• Users: Jira System administrators
• Tools required: Configuration Manager for Jira

The third and final stage of this process includes rolling out your configuration changes to production. After ensuring that the results of the change and impact analysis of the previous stage don't show any conflicts or undesired impact, move forward with the deployment to the production environment.

The steps of this stage are as follows:

1. Execute the communication plan required.
2. Create a configuration snapshot for backup.
3. Limit user access – changes to production servers are done during maintenance windows when the user access is limited (this is not a strong requirement but rather a recommended best practice.)
4. Deploy configuration snapshot.
5. Review audit logs for any warnings.
   
   
   
   

6. Declare SUCCESS/FAILURE – based on the deployment result. If it is successful and the access to the users was limited, communicate and open the system for all users.

7. In case of FAILURE – restore the snapshot on the production server, and start again. If the staging server is identical to the production, failures at this point aren't possible.

Moving add-on data

Migrating the add-on data is one of the most common data portability issues we've encountered. In this section, we will explore various options for effectively moving the add-on data.

The data created and stored by each add-on can be categorized based on its usage and storage mechanism.

• User-created data. For example – the hierarchical structures created by the Structure add-on include data created and consumed by users. It is not related anyhow to the project, system, or even add-on configuration. This type of data is not handled by Configuration Manager for Jira and the add-on should provide the export/import functionality.
• Configuration data. The add-on configuration could contribute to workflow post functions/conditions/validators, custom fields, dashboard gadgets, and other Jira objects, or could be private for the add-on and stored in the database (e.g. using Active Objects.) Configuration Manager supports several add-ons out of the box, other add-ons can be easily made compatible if the add-on vendor implements SPI provided by Configuration Manager.

Limitations & workarounds

There are certain system limitations that need to be considered during a configuration roll-out, including:

• Add-ons data – Certain add-on custom field configuration, add-on workflow property configuration, and any other add-on data outside of Jira configuration objects might not be included.
• Jira Service Desk  – Jira Service Desk-specific configuration is not supported. It will be added in future releases of Configuration Manager.
• Differences in configuration objects in 6.x to 7.x – This should be considered when the snapshot is created on a different major version of Jira than the target. 7.x has removed some permission types (e.g. the USE global permission is replaced by Application roles) and has introduced various other configuration objects, specifically permissions for permission schemes (e.g. manage sprints), security level type (application role), visibility permission (logged in users.)

Suggested workarounds regarding limitations and other known issues include:

• Scripts – API level scripts can be developed to migrate any data that is not handled by Configuration Manager for Jira. Great choice for scripts development is using the ScriptRunner add-on.
  
• Manual – If the amount of configuration is not extensive it can be manually added to the target Jira.
  
• Professional Services – Botron's team of solution architects can develop a custom solution that migrates any type of data.
  

Common issues

We have identified several common issues during deployments, which could negatively impact the data portability process. Some of the most common issues include:

• Integrity Check errors which prevent the snapshot creation/deployment. To preserve the integrity of the target/production server, Configuration Manager Integrity check is executed every time a snapshot is created or deployed. All critical errors reported should be resolved in order to continue. Detailed information can be obtained here.
• Differences in Jira versions – differences in the source-target Jira versions, specifically major versions.
• Application permissions/licenses – for 7.x, e.g. deploying a software project when the user performing the deployment doesn't have permissions to create software projects; or the Jira Software application isn't installed/licensed.
• Inconsistencies in user directories – if test/stage/production environments don't have the same user directory, user creation may be required if a new project is deployed and the project's lead doesn't exist in the target's user directories.
• Proxy/firewalls – this may be problematic for large instances when creating a snapshot or before the Analysis phase when deploying, otherwise there shouldn’t be any issues with the deployment itself. This is worked around by increasing any timeout limits on the proxy servers and disabling the firewall blocking rules.

Frequently Asked Questions

1. Is my entire configuration going to be rolled out to production automatically using Configuration Manager for Jira?
   Yes. The entire configuration, captured in the configuration snapshot, will be rolled out. The supported configuration objects types which are included in the snapshots are listed here.
   
   
2. Can I roll out project configuration changes from a newer server instance to an older server instance?
   It is strongly recommended that your production and staging server are on the same version. Configuration Manager allows deployment between different versions and warns the user about that. Snapshots created on newer versions may not work on old ones, as they might include new configuration objects which do not exist in the older versions – for example in Jira 7.x there are new permissions which do not exist in 6.4.x.
   
   
3. How long does it take to deploy the configuration snapshot?
   Project configuration snapshots take in most cases from a few seconds to 1 minute. Large system snapshots which include hundreds of projects, thousands of filters, and hundreds of Agile boards could take more than 1 hour to deploy. An accurate estimate of the deployment time should be obtained during the staging.
   
   
4. What if an error occurs during deployment? Does that break the target/production instance?
   All changes deployed by Configuration Manager are executed in a single transaction. If an error occurs, the whole transaction is rolled back so the only time the server configuration is modified is when all the changes are deployed successfully.
   
   
5. Can I automate the snapshot creation and deployment?
   Yes. Configuration Manager provides a public REST API for this purpose.
   
   
6. I can't create configuration snapshot due to Integrity check errors. Why is there such a limitation? How can I resolve this problem?
   The Integrity check errors could indicate a serious problem. Other not critical errors are marked as warnings and they don't block the creation or deployment of snapshots. By not allowing a deployment of configuration with critical errors, Configuration Manager protects the production system from being modified with something that is not working.
   
   
7. Can Configuration Manager handle custom-built add-ons?
   Yes. Configuration Manager can be extended to handle any custom add-ons. Contact Botron's services team for more information.

Need help?

If you cannot resolve the problem yourself, you can contact us for assistance via the following communication channels:

• • Send email to support@botronsoft.com
  • For training or services specific information, contact services@botronsoft.com