Refresh Jira Align self-hosted data

Data refreshes update the data stored in a target deployment, such as a test, UAT, or development environment, with the data from a source (production) deployment.

This process is crucial for priming the test environment, allowing administrators to carry out UAT enhancements, discover new Jira Align functionalities, educate Jira Align users with an identical copy of the production setup, and beyond.

This article offers a step-by-step process on how to execute a data refresh in a self-hosted environment, which includes backing up the database on the source instance and then restoring it on the target instance.

• Before you begin
• Prepare for the refresh
• Perform the refresh
• After the refresh
• Validation

Before you begin

The entire target database will be overwritten. This includes:

• Organizational data: All organizational data (hierarchies, timeframes, work items, objects) in the target environment will be overwritten with the current production data set. We strongly recommend refreshing your target Jira environment at the same time as Jira Align to avoid data misalignment issues.
• Users: All users in the target environment will be deleted and replaced with the current production users. Any users unique to the source instance (that do not exist in production) will need to be recreated post-refresh.
• Connectors: The connector services in the Jira Align target instance should be kept inactive until the connector settings in Jira Align are correctly configured to connect to the appropriate Jira UAT instance. Failing to do so may result in connecting to the Jira production instance.
• SSO: The single sign-on (SSO) functionality may not function correctly immediately after restoring data from the Jira Align production instance. To modify the SSO configurations, you must enable manual sign-in once the data has been restored on the Jira Align target environment. This adjustment requires executing a SQL script.
• Version compatibility: The source instance and target instance can operate on the same Jira Align version, or the target instance may run on a later version.
  • Downgrading the Jira Align version isn’t supported. The source instance cannot be newer than the target.
  • Upon transferring the source data to the target instance, which runs on a later version than the source, the deployment script (refer to the installation guide) must be run on the target instance to align the database with the updated version settings.

Prepare for the refresh

In the source instance

1. SSO settings
   1. Confirm that SSO is enabled in Jira Align at Settings > Platform > Security.
   2. Ensure you have at least one Super Admin user enabled and with a Jira Align user password set. After the data restoration, the single sign-on (SSO) feature will be disabled in the target instances. A Jira Align super admin user will need to manually log in and modify the SSO settings for the target environment before they can re-enable this feature. If you need assistance enabling a user to sign in manually, contact Atlassian Support.

2. In the SQL server hosting the Jira Align source instance database
   Take a full backup of Jira Align source instance’s database from PROD SQL Server as a .bak file:

   1. Run a full SQL backup of the source instance’s database in the instance by right-clicking the source instance’s database, then selectingTasks > Back Up… In the screenshot below, the name of the source instance’s database is JAPROD.

      

   2. Set the Backup type option to Full and select the destination folder and filename.bak by selecting Add in the lower-right. In this example, the backup is stored on the Jira Align folder C:/YourCompanyName/Yourdatabasename.bak.
      

      

   3. Copy the source instance Jira Align database backup (.bak) file to the test instance’s SQL server.

In the target instance

1. SSO settings

   1. Copy the Sign In URL from Settings > Platform > Security.

   2. Copy the Sign Out URL from Settings > Platform > Security.

   3. Copy the SAML 2.0 metadata from Settings > Platform > Security > Select the pencil (edit) icon to the right of the SAML 2.0 Identity Providers setting.

2. License key
   1. Make sure you have the Jira Align target instance’s license key code handy. You’ll need to reapply it after the data refresh. If you don't possess the license, you can raise a support ticket to retrieve the license code for the Jira Align target instance.
3. Feature toggles
   1. All feature toggle settings configured in the target instance will be lost when the database is updated with the source database copy. If feature toggle usage is different between the two instances, you can copy the current feature toggles from the target database before overwriting it, and adjust it accordingly after the data is restored (covered in the post-refresh tasks).
   2. If you want to preserve the feature toggle settings on the target instance, execute the SQL query below on the target database and save the results.

      select FeatureToggleId, Enabled from tblfeaturetoggles
      order by Enabled desc, FeatureToggleId asc

4. Connector configurations (Jira/Azure DevOps)

   1. Jira integration configurations: Take a screenshot and copy all details such as the Jira URL, API URL, Jira admins configured, authentication type, consumer key, Oauth public key, API token, etc. (as per the authentication type—API, Oauth, PAAT, etc.)

   2. Azure DevOps integration configurations: Take screenshots and copy the details, such as the Azure DevOps URL, authentication, tokens, settings, etc.

5. Site URL
   1. Copy the target instance's site URL from Settings > Platform > Security > Server Name.
6. Database server: target instance
   1. Copy the name of the Jira Align target database.
   2. Copy the SQL login account username and password for a user who has dbowner permission on the Jira Align target database.
   3. Make a full backup of Jira Align target database for safety.

Perform the refresh

All refresh tasks are performed in the target instance.

In the target instance

1. Stop Jira Align services
   1. Log in to the Jira Align target instance server and stop the IIS, connector services, and the Backoffice service.
2. Restore the database
   1. Restore the production (source) database backup (in this example, Yourdatabasename.bak) on the target database by right-clicking Yourcompanydatabasetest and selecting Tasks > Restore > Database.
      
   2. Select the Device option and select the ellipses (…) button.
      
   3. Select Add, then select the source database backup file (in this example, Yourdatabasename.bak), and confirm by selecting OK.
      
   4. Select the Options tab and ensure that the Overwrite the existing database(WITH REPLACE) option is checked. You may now select OK to perform the refresh.
      

After the refresh

All post-refresh tasks are performed in the target instance.

In the target instance

1. Turn on manual sign-in
   If the source Jira Align instance is configured with SSO, proceed. Otherwise, you can skip this step.
   1. Turn on manual sign-in the Jira Align target instance through the database. If this is not implemented, the target instance will redirect to the source instance’s SSO, resulting in authentication failure.
   2. Use this query on the Jira Align target database to disable SSO:

      UPDATE tblSetup SET AutoTrimValue = 0 WHERE SetupID = 81

       

2. Restore feature toggles
   The newly restored database now has the same feature toggle settings as the source instance. If there were custom feature toggle settings on the test instance, those will need to be adjusted.
   1. Run this query to get the feature toggle settings from the newly refreshed database and compare them with the exported output of feature toggles you collected for the target instance before the refresh:

      select FeatureToggleId, Enabled from tblfeaturetoggles
      order by Enabled desc, FeatureToggleId asc

   2. To turn feature toggles on or off, run this query:

      Update tblFeatureToggles
      set Enabled = 1 --Use 1 to enable or 0 to disable
      where FeatureToggleId = 11 --Replace 11 with the proper feature toggle ID to be updated

3. Start services

   1. Start the IIS.

   2. Start the Backoffice Service on the target instance’s server.
      Note: DO NOT start Connector services on the target instance yet.

4. Server name and site URL
   1. With settings values captured before the refresh, reconfigure the Server Name from Administration > Settings > Platform > Security. Enter the target instance’s URL in the format https://<URL> and save your changes.
5. Reconfigure SSO (if applicable)
   1. Enter the SAML metadata noted in pre-refresh tasks under Settings > Platform > Security > SAML 2.0 Provider > Edit.
   2. Turn off manual sign-in under Settings > Platform > Security > Disable Manual Sign-in. Select Yes and save your changes.
6. Connector configurations (Jira/Azure DevOps)
   1. Reconfigure all connectors with the details captured on the target instance’s server in the pre-refresh tasks.
   2. Start all connector services on the target instance’s server.
7. License key
   1. Apply the license key at Settings > Support > Version.

Validation

1. Ensure SSO is working on the Jira Align target instance (if applicable).
2. Ensure there is no banner message/warning regarding the license in the target instance’s UI.
3. If weblinks are not appropriate on Jira UAT instance due to the Jira data refresh, follow these knowledge base articles to update the Jira Align weblinks on Jira:
   • Issue links in Jira test environment point to production Jira Align after a data refresh
   • How to update or change outgoing links from Jira. issues and dashboards
4. Open any existing work item integrated with Jira. Make sure the View in Jira button opens the work item in the Jira UAT instance.
5. Open any existing work item from Jira UAT integrated with the Jira Align target instance. Make sure the Jira Align web link directs you to the Jira Align target instance.
6. Update the description of any existing Jira-integrated work item in the Jira Align target instance. Make sure the changes sync with Jira if bidirectional sync is enabled.
7. Update the description of any existing issue in the Jira UAT integrated with the Jira Align target instance. Make sure the changes with the target instance if bidirectional sync is enabled.
8. Create a new work item in the Jira Align target instance and associate it with a Jira-Integrated project. Make sure a new corresponding issue is created automatically in Jira if bidirectional sync is enabled.
9. Create a new issue in Jira UAT in a Jira Align-integrated project. Make sure a new work item is created automatically in the Jira Align target instance if bidirectional sync is enabled.