/
Migration Guide: Forge Based USU Service Management Connector for Jira

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

  1. Navigate to Manage Your Apps in Jira.

  2. Locate USU Service Management Connector for Jira.

  3. Click the Update button to install the new Forge-based version.

Update option
Accept app update

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:

  1. Create a Webhook

    • Go to Jira System Webhook Settings.

    • Click Create a Webhook.

  2. 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.

  3. 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.

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:

  1. 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.

  2. Atlassian Involvement:

    • Our team will contact Atlassian on your behalf to facilitate the rollback.

  3. Site-Wide Procedure:

    • The rollback is performed on a site-wide basis and cannot be done independently by customers.

  4. 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.

Related content