Preparing a sandbox environment for zAgileConnect

Please note that to setup an environment for testing zAgileConnect, you must have provisioned both -- a Salesforce sandbox AND a corresponding test Jira instance. 

zAgileConnect maintains configurations and relationships (between Salesforce objects and Jira Issues) in both Salesforce and Jira.  It is therefore imperative that the two applications are in sync, with regards to the integration, when preparing a test environment.  Unless both the Salesforce sandbox and test Jira environment are refreshed at the same time, it is likely that they are out of sync, i.e. Case-Issue relationships in the Salesforce sandbox do not match those reflected in Jira, or vice versa.  For example, there may be newer Issues represented in Salesforce (if the Salesforce sandbox is recent) than those that exist in the test Jira instance.

The steps below describe the process to synchronize them for the purpose of creating a reliable testing environment for the integration.  They also assume that the zAgileConnect Salesforce package and Jira add-on have previously been installed in the test environments.  

zAgileConnect Package and Jira Add-on Versions

The Salesforce AppExchange and the Atlassian Marketplace have the latest versions of zAgileConnect components (Salesforce package and Jira Add-on).  If you wish to replicate your production environment for the purpose of testing the integration, please get the appropriate versions of the package and add-ons from zAgile. 

These are also available in the documentation

Release Notes – Salesforce Package installation links

Installing Jira Add-on (Jira Data Center) – download and install corresponding versions of the Jira add-on

Installing Jira Add-on (Jira Server) – download and install corresponding versions of the Jira add-on

Installing Jira Add-on (Jira Cloud) – install Jira add-on 

Please make sure to refer to the documentation version (marked on the top right) that corresponds to the release that you are testing.

Establish Connectivity between Salesforce sandbox and Test Jira

If you have recently refreshed the Salesforce sandbox, it will likely have inherited the Jira connection configuration from the production Salesforce org.  This connection configuration represents the production Jira.  Furthermore, FullCopy Salesforce sandboxes that inherit zAgileConnect from the production org also replicate Jira credentials and related configuration parameters associated with the zAgileConnect configuration. This allows a Full Copy sandbox to connect to a production Jira instance, concurrent with the production Salesforce org. Since zAgileConnect only supports connectivity between a single Salesforce org and a single Jira instance, having a Salesforce sandbox and a Salesforce production org connected to the same Jira instance can have unpredictable effect, result in data integrity issues, and should be avoided.

To avoid this scenario, we recommend reconfiguring zAgileConnect in the Sandbox to point to test Jira instance, first removing any configurations that reflect production Jira instance, specifically Remote Sites, oauth certificate, and Connected App (Jira Server and Data Center).

The next step to creating a test environment for the integration is to re-establish connectivity between Salesforce and Jira.  This involves repeating the same steps as when setting up the integration in production.  All connection parameters have to be recreated for the test environment.  

zAgileConnect Installation & Configuration (Salesforce & Jira Server)

zAgileConnect Installation & Configuration (Salesforce & Jira Data Center)

zAgileConnect Installation & Configuration (Salesforce & Jira Cloud)

After authentication steps are completed, the remaining zAgileConnect package configuration (Steps 3 thru 6) that is inherited from the production Salesforce org can either be ‘Saved’ as-is or modified and Saved to allow these configurations to also be shared with the test Jira instance.

The direction of synchronization will depend on which of the two is deemed to be the 'source of truth'.  Both options, i.e. to synchronize Salesforce from Jira or Jira from Salesforce, are described below.  You will choose one of these based on the known state of each sandbox with regards to its data.

Synchronize Salesforce Sandbox from Jira Sandbox

This document provides guidance to synchronize Salesforce sandbox from a recently refreshed Jira test environment.

The steps are:

1. Delete zAgileConnect objects in Salesforce sandbox

2. Import Salesforce-Jira relationships from Jira sandbox into Salesforce sandbox

The synchronization process addresses a number of possible scenarios, as described below:

(*) Since Jira was refreshed with production, it may contain Salesforce entities that do not exist in the Salesforce sandbox based on the timing of the refresh.

We recommend disabling custom Triggers and any other customization related to zAgileConnect before beginning the synchronization.

Steps for Synchronizing Salesforce sandbox from Jira

1. Delete zAgileConnect objects in Salesforce sandbox

Execute the following APEX code via an anonymous block using developer console or workbench to remove existing Salesforce-Jira relationships in the Salesforce sandbox.

delete[SELECT Id FROM zsfjira__ZIssue__c];

The DML operation above may fail if there are too many (>10,000) records to be deleted. In such scenario, you can change the SOQL to append a “LIMIT” clause to it to reduce the number of records returned by the query and execute it multiple times.

2. Import Salesforce-Jira relationships from Jira sandbox into Salesforce sandbox

In Salesforce, go to zAgileConnect settings and open the link “Import data from Jira”

Follow the steps to confirm the import operation:

Synchronize Jira Sandbox from Salesforce sandbox

The steps consist of:

1. Remove Case-Issue relationships in Jira
2. Import Case-Issue relationships in Jira from Salesforce

3. Perform Salesforce Data Synchronization in Salesforce to clean up Salesforce-Jira relationships in Salesforce

4. Re-synchronize Salesforce sandbox with Jira by importing data from Jira into Salesforce

The synchronization process addresses a number of possible scenarios, as described below:

(*) Since Salesforce was recently refreshed with production, it may contain Jira issues that do not exist in the JIRA sandbox.

We highly recommend disabling custom Triggers and any other customization related to zAgileConnect before beginning the synchronization.

Steps for Synchronizing Jira sandbox from Salesforce

1. Remove Case-Issue relationships in Jira

In Jira, go to Jira Setup->Apps->zAgileConnect→Remove Data

2. Import Case-Issue relationships in Jira from Salesforce

In Jira, go to Setup->Apps→zAgileConnect→Data Import/Refresh

3. Clean up Salesforce-Jira relationships in Salesforce

This step removes existing Salesforce-Jira relationships from the Salesforce sandbox in preparation for rebuilding these relationships from those newly created in Jira via the import above.

Execute the following APEX code as an anonymous block via Developer Console or Workbench.

delete[SELECT Id FROM zsfjira__ZIssue__c];

The DML operation above may fail if there are too many (>10,000) records to be deleted. In such scenario, you can change the SOQL to append a “LIMIT” clause to it to reduce the number of records returned by the query and execute it multiple times.

4. Re-synchronize Salesforce sandbox with Jira by importing data from Jira into Salesforce

This import step will rebuild Salesforce-Jira Issue relationships in Salesforce from Jira

In Salesforce, go to zAgileConnect settings and open the link “Import data form JIRA”

Follow the steps to confirm the import operation: