RFCs are a way for Atlassian to share what we’re working on with our valued developer community.
It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.
Please respect our community guidelines: keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
Summary of Project:
“App migration web hook in Connect Descriptor” will enable marketplace partners to register app migration webhook for their app data migration to all cloud sites on which their app is installed, by declaring an entry in Connect descriptor once.
- Publish: 11 May 2023
- Discuss: 25 May 2023
- Resolve: 08 Jun 2023
Problem
App migrations failing due to cloud apps not having an app migration webhook registered for the destination cloud site, is one of the major failure points for customers performing server to cloud app migrations using cloud migration assistants. Today , marketplace partners register their webhook (absolute URL) specific to a cloud site. This means they need to register their webhook for each cloud site on which their cloud app is installed. Customers running an app migration to a cloud site for which that cloud app missed to register webhook will often see a long running app migration with no progress updates until that app migration eventually expires and fails. This problem gives an unpleasant experience to customers and customers end up reaching out to Atlassian support or marketplace partner support or both and losing considerable amount of time in getting this issue fixed.
Who are we solving for?
For marketplace partners : “App migration web hook in Connect Descriptor” aims to provide a declarative way for marketplace partners to register their app migration webhook by adding an entry on their connect descriptor once and thus registering their app migration webhook for all cloud sites at once.
For customers : “App migration web hook in Connect Descriptor” aims to reduce the number of customer app migrations failing due to cloud apps not registering app migration webhook on their cloud sites.
Proposed Solution
“App migration webhook in Connect Descriptor” will allow the marketplace partners to add a new entry cloudAppMigration to the connect descriptor as shown below,
{
// Existing field for base URL
"baseUrl": "https://your.sample.app.com"
...
...
// Existing field for data residency purposes
// https://developer.atlassian.com/cloud/confluence/data-residency/#enable-data-residency
"regionBaseUrls": {
"US": "https://us.your.sample.app.com",
"EU": "https://eu.your.sample.app.com",
"AU": "https://au.your.sample.app.com",
"DE": "https://de.your.sample.app.com"
}
...
// New field for registering app migration webhooks
"cloudAppMigration": {
"migrationWebhookPath" : "<relative-url-to-migration-notification-endpoint>"
}
...
}
App migration platform will form the webhook URL to notify app migration events as follows,
- For apps NOT supporting data residency, webhook URL will be formed as
baseUrl+cloudAppMigration.migrationWebhookPath - For apps supporting data residency, webhook URL will be formed as corresponding
regionBaseUrl+cloudAppMigration.migrationWebhookPath
Precedence of webhooks :
App migration platform will use the following precedence to decide which type of webhook should be used to notify app migration events,
- If your cloud app has app migration webhook defined on the Connect descriptor, App migration platform will use the app migration webhook URL formed from the fields of Connect descriptor
- If your cloud app have registered app migration webhook using the REST API, App migration platform will use the webhook URL registered for the specific cloud site
- If you have registered a default app migration webhook for your app with App migration platform, App migration platform will use the default webhook URL
Note :
- Precedence defined above is to help marketplace partners to onboard to this new solution without worrying about off-boarding their existing app migration webhooks.
- Default app migration webhook is not publicly available or a self-serve feature. We have reached out to a few marketplace partners to onboard their default app migration webhook to App migration platform. So, #3 in the above precedence is not applicable for all the marketplace partners.
Possible extension to this project :
Support for cloudAppMigration.migrationWebhookPath as connect module for Connect On Forge apps is out of scope for this RFC, but App migration platform can add that support if Connect On Forge becomes widely adopted and marketplace partners require that feature.
Other options considered :
We have considered allowing marketplace partners to add absolute URL on the connect descriptor for app migration webhook, but this option won’t enable App migration platform to notify migration events to the cloud app on the region based URLs based on the product realm (related to data residency support).
Actions
While we would appreciate any reactions you have to this RFC (even if it’s simply giving it a supportive “Agree, no serious flaws”), we’re especially interested in learning more about:
- Do you have any blocking use case that will stop you from using the proposed solution to declare a relative path to App migration webhook endpoint on Connect descriptor ? If yes, could you please share such use cases ?
- Do you have any concerns in the App migration platform snapshotting the webhook URL to be used for an app migration at the start of that app migration ? (Note : This will help in avoiding App migration platform delivering the events related to single app migration using different webhook URLs, if the webhook changed during an active app migration)
- Do you plan to move your Connect app to Forge app using the
Option Bexplained on this page ? If yes, does adding the support tocloudAppMigration.migrationWebhookPathas a Connect module on your Forge manifest be helpful ? - If your app supports data residency or planning to support data residency, would you like to get your server to cloud app migration events on the region based URL based on the realm location of the cloud product ?
Thanks for your feedback!
. I’ve added a note under the precedence defined in the RFC. I’ll update the RFC again, once I get your thoughts on the follow up question.
Thanks!