This guide will help you to configure Automatic Pull from Salesforce by enabling the Automatic Pull feature, as well as configuring the required Salesforce triggers. If you haven't done so, configure the available objects and fields before proceeding with the following steps. The Salesforce Package must be installed and configured as well.
Note that Automatic Pull will only work if:
- Connection is configured to Allow Automatic Pull
- Association is configured to Allow Automatic Pull
- Salesforce Triggers for the respective objects are installed
- Connection allows modification
- Salesforce object for which you configure the Automatic Pull trigger is configured to be available
A word on naming: Automatic Pull in Jira is called Automatic Push in Salesforce. The naming is chosen based on the point of view of the user of the respective system.
Enabling Connection to allow Automatic Pull
- If you are using Jira Cloud, click the Jira icon in the top left ( > Salesforce > Connections. , , , or )
If you are using Jira Server, click > Add-ons, and then in the sidebar go to Salesforce > Connections.
- At the Salesforce Connections screen, go to the Connection you want to configure > Options Menu
- At the Connection Configuration screen, locate the Connection Settings and enable the switch for Allow Automatic Pull. At this point make also sure the switch for Allow Modification is enabled:
Create Automatic Pull Enabled Association
Automatic Pull from Salesforce has to be enabled/disabled per Association. You can do this either when creating an association or later by Configuring an association. Additionally, the preset configuration for the Automatic Pull switch can be configured on the Connection Configuration page.
Create and Deploy Apex triggers
The Connector relies on Apex triggers to be informed of changes on Salesforce objects. These triggers have to be created and deployed manually in Salesforce. For Salesforce Enterprise and Unlimited edition, the standard deployment of Apex triggers are required (see Salesforce documentation).
The following code samples shows how to write triggers for Cases. To create triggers for other objects, replace the object name in the code accordingly.
Push to Jira after Object updated
Apex test class for the triggers
Once triggers are created, they need a certain level of test coverage to be allowed to deploy to the Production environment. The package contains a test helper which tests the whole scenario. You simply need to add a unit test for each trigger and call the test helper method as follows:
Your Jira and Salesforce system should now be ready to push changes on configured Salesforce objects automatically to the associated Jira issues.
Just as the trigger itself, you need a test for each object trigger. All you have to do is replace
Case in the above code with the actual object name.
After creating your test class, click Run Test. This ensures the test gets associated with your newly created trigger and provides code coverage.
You will need to re-run the Apex class if you ever deactivate and reactivate the trigger.
The above-mentioned method works only if you call the API directly from within a trigger. If you need to call the API indirectly, for instance from a helper method, see the advanced usage section below.
Also note that our API should not be called from within a Future. When called from a Future, the API simply logs it as a warning. Check your Apex Logs to see if that is the case if the automatic synchronization is not working.
The Apex API and test helper methods work as well with any custom object. You just need to find out the object name (e.g. "
MyObject__c") and use it in the trigger code as documented above. If you are testing a Custom Object, provide the fully qualified name (include your namespace in the Salesforce Object Name, e.g.
'yournamespace__MyObject__c'). You can get the fully qualified name from the API Name which contains your namespace and the Salesforce Object Name.
To obtain the API Name, navigate to your custom object definition detail configuration screen and look for API name. For more information, view the Salesforce documentation on namespace prefixes.
Our Apex API supports a selective pushing, so that you can exclude unwanted Salesforce objects from the push. For this purpose you can use the following API method:
Pass all the objects for which you want a push to Jira to happen as
newObjects. Note that all the objects in this list must be of the same runtime type. So we recommend to use a concrete type, e.g.
List<Account> for the variable you pass as this parameter. The
oldObjects parameter is not used at the moment so you can pass
Trigger.old or an empty list for it.
For instance if you want to push updates only for Cases whose summaries start with "Post" you can use the following trigger code:
If you would like automatic pull of attachments, a separate trigger is required:
To get test coverage for the Attachment trigger, use the provided test helper below:
If you would like automatic pull of Salesforce Files, another trigger is required:
Known issue: Uploading multiple files in Salesforce at the same time may result in duplicate attachments in Jira.
To get test coverage for the ContentDocumentLink trigger, use the provided test helper below:
To make this work, Synchronize Attachments must be enabled in the Connection settings.