App Descriptor Updates when Gradually Increasing Capabilities

Jira Development Jira Cloud
#1

Hi everybody,

we’re working on an Add-on for Jira Cloud that we want expand gradually over time. We want to start with just a statically hosted web app and add a backend component down the line.

We’ve a few questions regarding changes to the App Descriptor where we can’t figure out the answer from the docs:

  1. Is there a way to quickly experiment with updates as they would happen via the Marketplace?
  2. Are there templates or best practices for deployment of a Connect app?
    We’re wondering how we should handle Add-on instances being stuck on older versions because the admin doesn’t approve an update.
  3. Can we change the baseUrl with a new apiVersion without requiring reinstallation?
    Should we prefix all urls relative to the base in the descriptor with a version code instead?
  4. Can lifecycle hooks and authentication be added later?
    Will existing installations call e.g. the installed hook with a sharedSecret after an update that adds the hook and changes the authentication type from none to jwt?
#2

Is there a way to quickly experiment with updates as they would happen via the Marketplace?

Not sure. I think the best thing would be through a private listing with a different url and then use access token to install things.

Are there templates or best practices for deployment of a Connect app?

Take a look through the AtlasCamp archives: https://www.atlassian.com/atlascamp/2017/archives/featured/keynote . But in general think of it as as an integration application (it’s not a plugin - you own it all and Atlassian is a third party (Sorry Atlassian for making you a third party)).

We’re wondering how we should handle Add-on instances being stuck on older versions because the admin doesn’t approve an update.

Add a version into your urls and make sure you’re backwards compatible. You will get installations that don’t upgrade their descriptors.

Can we change the baseUrl with a new apiVersion without requiring reinstallation?

Not quite sure on this one, but use a Product specific dns entry and you’re safe. :slight_smile:

Should we prefix all urls relative to the base in the descriptor with a version code instead?

Yes or make your payloads be backwards compatible.

Can lifecycle hooks and authentication be added later?
Will existing installations call e.g. the installed hook with a sharedSecret after an update that adds the hook and changes the authentication type from none to jwt?
I think so. But it will require the administrator to upgrade the app.

I’m hoping that @rmassaioli or @rwhitbeck comes through and corrects me if I’m wrong (I’ll buy them a beer at Atlassian Summit if they do).

2 Likes
#3

The Base URL is in the descriptor. All descriptor modifications require reinstallation in order to take effect.

#4

Everybody is a third party in the cloud. :slight_smile:

+++ Agreed.

Also decide what your deprecation period is going to be, what period of time will you be backwards compatible for? It should be on the order of months or years.

Yes, as you have identified though, it will require an upgrade.

As always @daniel, great answers! Keep it coming!