Migration Guide: Forge Based USU Service Management Connector for Jira
This guide outlines the steps to successfully update your USU Service Management Connector to the new version built on Forge.
1. Backup Your Current Configuration
Before proceeding, back up your existing interface settings manually (after the update all of your previous setting will be lost):
Interfaces: note down their current configurations
Event Mappings: note down the settings if any changes were made
Webhooks: note down the JQL, issue-related events (within a webhook) and related interface
Unfortunately, there’s no automated way to back up this data. Ensure you save this information manually.
2. Update the App
Navigate to Manage Your Apps in Jira.
Locate USU Service Management Connector for Jira.
Click the Update button to install the new Forge-based version.
3. Post-Update Steps
After updating:
recreate your interfaces - use your backed up data
test the connection - If the test connection does not work, ensure:
you have used the correct interface credentials
your firewall is configured as outlined in Section 4 of this document
recreate their corresponding webhooks
The new version uses Jira System Webhooks, which require a different setup:
Create a Webhook
Go to Jira System Webhook Settings.
Click Create a Webhook.
Configure the Webhook
Events: Select the relevant events provided by our app:
Issue Created
Issue Updated
Comment Created
Comment Updated
Attachment Created
Attachment Deleted
Secrets: Leave the secret field empty; the app's permissions handle authorization.
Set the Webhook URL
Obtain the Webhook URL from the app settings:
Navigate to the app interface in settings.
Click the three-dot menu next to the desired interface.
Select Copy Interface Webhook URL.
Paste the URL into the webhook configuration in Jira System Webhook Settings.
4. Update Firewalls
Allow outbound connections to the current IP address ranges used by Forge apps.
Reference: Atlassian IP Address Ranges.
These IP ranges are shared by all Forge apps, so allowing connections from this range permits connections from any Forge app.
Rollback Option: Returning to the Connect Solution
If for any reason you need to revert the app back to the Connect solution, this rollback can only be performed by Atlassian. Here’s what you need to know:
Support Request Required:
Reach out to our support team to initiate the rollback process.
Provide the tenant details and the reason for the rollback request.
Atlassian Involvement:
Our team will contact Atlassian on your behalf to facilitate the rollback.
Site-Wide Procedure:
The rollback is performed on a site-wide basis and cannot be done independently by customers.
Documentation:
Ensure any necessary interface or webhook data is backed up prior to initiating the rollback, as settings may need to be reconfigured after the change.
Additional Notes
The update process may take a few minutes. If it seems to be taking too long, refresh your site. The update should still be applied correctly.
For any issues during the migration, contact support.
By following these steps, you can ensure a smooth transition to the Forge-based USU Service Management Connector for Jira.