Search this space

Live demo

Want to see a live demo and learn what this Connector can do? Join our jam sessions!

Page tree

If you are looking for documentation for the new Salesforce & JIRA Cloud Connector, click here.

Skip to end of metadata
Go to start of metadata


If you are using a version of the Connector prior to version 5, you will need to migrate your configurations and data onto the new data structure.

There are a number of items that will need to be migrated and some which are no longer required, please see the following sections for the comprehensive list.

Before Migrating...

Both new and old versions of the Connector are required during the migration process. The migration has to be done in JIRA 4.3.4 - 4.4.5 since these versions are compatible with both the Legacy (Old) and NextGen Connector (New).

For example:

Upgrading from JIRA v4.1 to JIRA 5.0:

  1. Upgrade JIRA to v4.4.5.
  2. Make sure both Legacy Connector and NextGen Connector are installed in JIRA v4.4.5.
  3. Run the connector migration in JIRA v4.4.5.
  4. Upgrade JIRA to v5.+/6.+.

Use the following URL for RPC URL and Display URL:


You can get the domain after successfully logging in to your Salesforce instance and then checking your browser's address field:

And the application link should setup as below:


When upgrading to version 5 of the connector, you can simply remove the configuration for the listeners used in version 4.x and earlier of the add-on as the listener is now managed automatically by the add-on without requiring additional configurations.

The listeners used in earlier add-ons that can be removed are:

  • net.customware.add-ons.crm.salesforce.jira.listener.SFCaseUpdateListener
  • net.customware.add-ons.crm.salesforce.jira.listener.CommentUpdateListener


These has been completely restructured in version 5 to be easier to input and manage, therefore no automated migration of this is possible. It is strongly recommended to re-evaluate your existing mappings and then reconfigure them using the new mapping system. We are using a combination of Mappings and Mapping Schemes to make the mapping process as simple and flexible as possible.

Please see the relevant sections of the Administrator Guide below for more details on how to achieve this:

Custom Fields

Please see Connector Custom Fields for more details on the complete list of fields.

We are currently building a migration tool as part of the add-on which migrates links from any of the custom fields provided in the previous versions of the add-on to the custom fields provided by the new add-on. There are only 2 fields which are not added to the migration tool for the initial phase:

  • Reason
  • Origin

The rest of the fields are supported with the migration tool.


The process of migrating the custom fields is quite straightforward, however as this is a bulk operation and quite intensive on the server, it is strongly recommended to migrate the data 1 field at a time.

To migrate a single custom field, you will need to first determine if it is used to synchronize data or not. Synchronized fields update data in another system; otherwise they are simply referencing data from the other system ("read-only"). Based on this determination, you can migrate the field in one of the two ways below.

Please make sure that the new add-on is installed, your Salesforce instance is configured in the Connection settings correctly and your mappings and mapping schemes are already set up before starting.

  1. Go to the "Migrate Data" admin interface by going to Administration -> add-ons -> Migrate Data
  2. On the left hand side, find the legacy field you want to migrate into the new field
  3. Select the appropriate custom field used for the new add-on (by default this is named "<MY_CONNECTION_NAME> <OBJECT_NAME> Reference", e.g., " Case Reference")
  4. If successful, you will get a success message, otherwise, a list of errors will be displayed.
Page Contents

Migrating Non-synchronized Fields

Please make sure that the new add-on is installed and that your Salesforce instance is configured in the Connection settings correctly before starting.

  1. Download the latest version of the migration tool (salesforce-migration-tool-1.0-beta1.jar).
  2. Add a new Custom Field of the following type:
    1. If you want multiple Salesforce objects to a single JIRA issue, create a new Multi Remote Object Link custom field.
    2. If you a single Salesforce object to a single JIRA issue, create a new Remote Object Link custom field.
  3. Go to the Custom Field administration screen and click Configure for the custom field you just created.
  4. In the configuration screen, click Edit Configurations, this will bring you to a new screen where you can configure the display template as well as which remote system/remote object type.
  5. On this screen, select the appropriate remote system and object type (e.g., Remote System:, Remote Object Type: Case) then click Save.
  6. Go to the "Migrate Data" admin interface by going to Administration > Plugins > Migrate Data.
  7. On the left hand side, find the legacy field you want to migrate into the new field, then for this, select the newly created field from step 2, then click Migrate.
  8. If successful, you will get a success message, otherwise, a list of errors will be displayed.

For more information on configuring which Salesforce attributes to display in your new object custom field, view Modifying the Custom Field Template. Configurations

The only changes required are the URLs configured for each of the Salesforce buttons/links/Visualforce pages. You will need to replace the ones used for versions 4 and under with the following new ones for each Salesforce configuration.

For more detailed information, refer to the documentation on Configuration.

Issue Creation Button

Update the URL attribute from:




Note: please make sure you put in the appropriate attributes for CONNECTION_ID and YOUR_JIRA_URL.

Issue Synchronization Button

Update the URL attribute from:




Related JIRA Issues VisualForce Page

Find the following section within the VisualForce page code:


And replace it with:



Even though the synchronization of attributes do not occur, you may still configure the add-on to display the attributes that you are interested in so that the JIRA user can see fields from the Salesforce object without needing to log into

This allows you to have multiple Salesforce objects linked to a single JIRA issue and vice versa.

  • No labels