The following instructions apply to zAgileConnect customers with pre-1.15 version of zAgileConnect who wish to add another Jira instance to their existing deployment.

To enable support for multiple Jira instances, a number of steps are needed to migrate Jira Issues data that corresponds to the existing Jira instance to accommodate connectivity with multiple Jiras.

The steps described below are specifically for zAgileConnect customers with pre-existing Salesforce and Jira integration that want to add additional Jira instances to the same Salesforce org. The steps involve migrating existing Salesforce-Jira relationships to prepare for a multi-Jira integration environment.

Please make sure that you are starting with zAgileConnect Release 1.13 or 1.14 prior to upgrading to Release 1.15.  If you are currently on an earlier release, you will first need to upgrade to zAgileConnect 1.14.x prior to upgrading to Release 1.15.

It is strongly recommended that these steps first be performed in a test environment consisting of a copy of the prod SF org and corresponding copy of prod Jira instance. This is especially critical if there are any customizations on zAgileConnect that may be impacted by the upgrades. Please refer to the following link for preparing a sandbox environment for testing/upgrading zAgileConnect.

Preparing a sandbox environment for zAgileConnect

Overview

Preparing for upgrade

  1. Identify impacted customizations (reports, apex triggers, flows, etc).
  2. Backup zAgileConnect custom objects.

  3. Capture zAgileConnect package configurations via screenshots.

Upgrading to zAgileConnect 1.15.0

  1. Install 1.15 Salesforce Package and corresponding Jira Add-on (for Jira Server and Jira Data Center)

  2. Validate Salesforce package configurations (using screenshots above)

Migrating Data for Multi-Jira support

  1. Contact zAgile to enable Multi-Jira Feature in your Salesforce Org (this feature is not available with the standard zAgileConnect subscription)

  2. Disable any Triggers/Flows on zAgileConnect objects

  3. Migrate zAgileConnect Data

  4. Update impacted customizations

  5. Re-enable any Triggers/Flows on zAgileConnect objects

Connecting a second Jira

  1. Make sure the existing Jira connection is marked as Default

  2. Add a new Jira Connection and configure it

  3. Add the zAgileConnect Lightning Web Components for the second Jira connection

Preparing for upgrade

1. Identify impacted customizations

The fields listed below in the zAgileConnect objects are impacted by this migration and will need to be replaced in any custom trigger, Flow or Report. Please find all static and dynamic references to these fields in your Salesforce Org. You can use the “Where is this used?“ button in Object Manager to find static references, for example to find references to IssueKey field on ZIssue Object:

Field Label

Field API Name

Object

IssueId

zsfjira__IssueId__c

ZIssue

IssueKey

zsfjira__IssueKey__c

IssueId

zsfjira__IssueId__c

ZIssue_SF

Jira Comment Id

zsfjira__JIRA_Comment_Id__c

ZJiraIssueCommentDetails

2. Backup zAgileConnect custom objects

Go to Salesforce Setup → Data Export → Export Now and export all the custom objects for zAgileConnect (zsfjira__*)

3. Capture zAgileConnect package configurations

The upgrade to 1.15 will also migrate zAgileConnect configurations automatically. However we recommend capturing all package configurations to validate them after the upgrade.

For this go to Salesforce package configuration and open Steps 3, 4, 5, 6, General Settings and Permission Settings and capture screenshots for each configuration.

Upgrading to zAgileConnect 1.15.0

1. Install zAgileConnect 1.15.0

Upgrade zAgileConnect components to 1.15.0 in your Salesforce Org. 

Note that for Jira Server or Datacenter you need to upgrade both the Salesforce package and the Jira Add-on. See Upgrading to zAgileConnect v1.15.

2. Validate Salesforce package configuration migration

Go to configuration Steps 3, 4, 5, 6, Salesforce Actions from Jira (previously called General Settings) and Permission Settings and confirm it is consistent with the configurations you captured before (note that some configurations were removed from the previous General Settings page)

Migrating Data for Multi-Jira support

1. Contact zAgile to enable Multi-Jira Feature in your Salesforce org 

Contact zAgile and provide your Salesforce Organization Id to enable Multi-Jira capability.  Please note that this feature is not available with a Standard subscription. 

2. Disable any custom Triggers/Flows on zAgileConnect objects

Identify and disable any customization you may have on the following Salesforce Objects:

  • ZIssue

  • ZJiraIssueCommentDetails

This includes Apex Triggers, Flows, Process Builder Flows, and any other customization that could be executed as part of DML updates on records from those Salesforce Objects.

3. Migrate zAgileConnect Data

Go to the zAgileConnect Salesforce package configuration and open the migration page:

This will start two Apex Jobs to migrate the ZIssue and ZJiraIssueCommentDetails objects.

Once the Jobs are completed you can activate Multi-Jira.

4. Update impacted customizations

Make the necessary changes on your customizations identified as impacted by this migration. The following table describes the recommended changes on your impacted reports, flows, apex, etc.

Object

Field API Name

Recommended Action

ZIssue

zsfjira__IssueId__c

  • Use the new 'JiraIssueId' custom field instead

zsfjira__IssueKey__c

  • Use the ‘Name' field instead. Note the ‘Name’ field label is also ‘IssueKey’ but API Name is 'Name’

ZIssue_SF

zsfjira__IssueId__c

  • Use the new 'JiraIssueId' custom field from ZIssue object instead

ZJiraIssueCommentDetails

zsfjira__JIRA_Comment_Id__c

  • Use the new 'JiraIssueId' custom field instead

5. Re-enable any trigger/flow on zAgileConnect objects

Re-enable any customization you may had disabled on the following Salesforce Objects:

  • ZIssue

  • ZJiraIssueCommentDetails

Connecting a second Jira

1. Make sure the existing Jira connection is marked as Default

Go to Salesforce Setup → Installed packages → zAgileConnect → Configure and make sure your Jira is marked as 'Default' in the Jira(s) section. You can also edit the connection and set a custom Alias.

2. Add a new Jira Connection and configure it

Add a new Jira connection and specify an Alias.

Then follow the same steps described here zAgileConnect Installation & Configuration to configure another Jira instance.  These steps will vary depending on whether you are connecting to Jira Cloud or Jira On-Prem (Server or Data Center).

3. Add the zAgileConnect Lightning Web Components for the second Jira connection

Each Jira will have its own Lightning Web Components for Related Jira Issues, Search, etc. Add the Lightning Web Components to the Case Lighting Page(or any other object integrated with Jira) and select the Jira Connection.