Editions for Connect apps

You can create standard and advanced editions of your app under a single Marketplace listing. This is handy if you're looking to expand the presence of your app in the cloud market.

Before you begin

Before creating editions of your app, we assume you've already gone through Phase 1 of a three-phase process, which is the planning phase.

Phase 2 involves the technical aspects of creating editions and is comprised of the following steps:

1. Differentiate features that go into the standard and advanced editions of your app.
2. Update app code with conditional logic for each of the features of the respective editions.
3. Test the editions of your app to ensure the features across the editions are working as expected.

1. Differentiate features for standard and advanced editions

We recommend that you list the features that would go into the standard and advanced editions of your app. This way, you have a list you can refer to while going through your app code in the next step.

Refer to the customer segmentation and strategy you will have already prepared after going through this guide in the Planning phase section.

2. Update app code with conditional logic

Now that you have a list of the features for your standard and advanced editions, you need to go through your app code to introduce conditional logic for each of these features.

There are several ways to do this, depending on your app's functions and how these are coded. As you go through your list of differentiated features, check how you may need to update one of the following in your app code:

• Requests with license status
• Lifecycle HTTP request payload
• Connect JavaScript API
• Connect conditions
• License API

It's important to note that editions are only available for cloud customers who are on the improved billing experience. This means, however, that customers who are on the original billing experience will not have access to editions until they are migrated to the improved billing experience.

You'll need to continue supporting such customers as you're currently doing today. Our APIs will only share capabilitySet information (more on that below) for customers on the improved billing experience. You must update your app code to handle both scenarios.

Requests with license status

Each incoming request from the Atlassian product site includes a query parameter named lic, which may look like this:

1
2
http://....?lic=active

Your app should check this value to determine the license status of the site associated with the current request. The lic parameters may have either of the following values:

• active: the license is valid for this instance and app
• none: no license is present

To introduce conditional logic for relevant requests in your app, you need to add the new parameter capSet and set the value to either capabilityStandard or capabilityAdvanced accordingly.

The conditional logic may look like this in the incoming request:

1
2
http://....?lic=active&capSet=capabilityAdvanced

Note, the capSet property is not available for customers who are on the original billing experience. This should be factored into your conditional logic as well.

Lifecycle HTTP request payload

Lifecycle callbacks contain a JSON data payload with important tenant information that you will need to store in your app in order to sign and verify future requests.

As part of the EAP, we're adding the capabilitySet property, which you can then set to either capabilityStandard or capabilityAdvanced to introduce conditional logic in your app.

The installation payload logic may look like this:

1
2
{
  "key": "installed-addon-key",
  "clientKey": "unique-client-identifier",
  "sharedSecret": "a-secret-key-not-to-be-lost",
  "serverVersion": "server-version",
  "pluginsVersion": "version-of-connect",
  "baseUrl": "https://example.atlassian.net",
  "displayUrl": "https://issues.example.com",
  "displayUrlServicedeskHelpCenter": "https://support.example.com",
  "productType": "jira",
  "description": "Atlassian Jira at https://example.atlassian.net",
  "serviceEntitlementNumber": "SEN-number",
  "entitlementId": "Entitlement-Id",
  "entitlementNumber": "Entitlement-Number",
  "capabilitySet": "capabilityAdvanced"
  "eventType": "installed",
  "installationId": "ari:cloud:ecosystem::installation/uuid-of-forge-installation-identifier"
}

See Lifecycle HTTP request payload for more details.

Connect JavaScript Context

Context is a JavaScript module that provides functions for the current product context. Depending on how your app is using Context methods, you will be able to read the new property capabilitySet under the license object, where you can then set the value to capablityStandard or capabilityAdvanced accordingly:

1
2
license:
  active: true
  capabilitySet: "capabilityAdvanced"
[[Prototype]]: Object

Connect conditions

A condition specifies requirements that must be met for a user interface element exposed by an app to be displayed to a user. Typical use cases include requiring a user to be logged in or to have specific permissions.

There are different classes of conditions. Most commonly used are the predefined conditions provided by each host product. When further customization is needed, conditions can be specified in terms of properties stored by the app in the host product.

These conditions operate on properties of the user at the browser, the entity being viewed (e.g. an issue or a blog post) or its container (e.g. a project or a space), or the entire system.

Apps can also use conditions as building blocks of boolean expressions containing the logical operations conjunction (AND), disjunction (OR), or negation.

See the following documentation, depending on the product you're creating app editions for:

• Confluence Cloud
• Jira Cloud platform
• Jira Software Cloud
• Jira Service Management

To introduce conditional logic in your app, you need to add the new condition capability_set and set the value to capabilityStandard or capabilityAdvanced accordingly. This condition lets the app show or hide a certain module, depending on the customer’s license edition.

The conditional logic may look like this:

1
2
{
"modules": {
    "jiraProjectPages": [
        {
            "conditions": [
                {
                    "condition": "capability_set",
                    "params": {
                        "value": "capabilityAdvanced"
                    }
                }
            ]
        }
    ]
}

License API

Atlassian Connect provides a set of REST APIs specifically designed for use by cloud apps. Requests to these resources are made against the Jira or Confluence Cloud instance, not the Marketplace API.

Note that Jira and Confluence have separate URIs for these resources.

See License API for cloud apps in the Marketplace documentation for more details.

As part of the EAP, you will be able to read new property capabilitySet under the license object with a value of either capabilityStandard or capabilityAdvanced accordingly.

You can access the license edition detail from license.capabilitySet as part of the License API payload.

3. Test the editions of your app

Connect apps use access tokens to evaluate and test the license states of apps via private app listings on the Atlassian Marketplace.

Access tokens are like licenses that you can generate and manage without going through the usual licensing process. They let you install and test apps under development in live cloud instances.

Testing the editions of your app involves the following steps:

1. Generate an access token
2. Install the app with the access token

Generate an access token

You can create a token from your app's private listing on the Marketplace. If you've already installed the app, you can create tokens directly from the Manage listings page.

To generate an access token from your app's private listing:

1. Log in to https://marketplace.atlassian.com/ with your partner account.
2. Click Manage partner account from the profile menu in the upper right.
3. On the Apps page, select the name of your private app.
4. Select the Private listings tab.
5. Select Create a token. The Private listings tab appears only for private, cloud-hosted apps. If you don't see the button here, make sure your listing is private and cloud-hosted.

New tokens appear in the subsequent list. From here, you can either apply them manually to an app if it's already installed, or use the link for the token to install the app and install the app at one time. Delete tokens using the Remove button.

The Marketplace token links are installation URLs that include the token. You can share this link with external customers or partners for testing.

Install the app with the access token

After generating the token, you can use the token URL to install the app and apply the token in the same process:

1. Copy your token link from your Private listings page in Marketplace.
2. Log in to the admin.atlassian.com and select the correct organization.
3. Select ••• next to the product you want to install the app to, and select Manage apps.
4. On the Manage apps page, select Settings at the bottom of the page.
5. Check the box to Enable private listings.
6. Back in the Manage apps page, click Upload app.
7. Paste the URL of your descriptor from the Marketplace, and click Upload.

Your descriptor is now retrieved and installed, and your token is now applied. Now you can test your app editions accordingly.

By default, your app is set to the standard edition. To switch between editions for testing, go to Private Listings, select Manage Apps, select your app, and select the edition you want to test.

You can then verify whether or not the particular edition you're testing is behaving as intended.

Video walkthrough

Check out this video outlining the journey you'll take when building editions for your Connect apps.

Limitations

For existing installations of an app, app editions are nonexistent until a customer switches from one edition type to another. For example, when an app customer decides to upgrade from standard to advanced edition, it’s only at this time that the edition itself will be set and will become available to the app. Because of this, the value for capabilitySet will not be returned for customers where the edition is still nonexistent.

To handle this, when introducing conditional logic in your app code, we recommend to apply logic on either:

• the presence of capabilitySetAdvanced for features that should only be visible for customers `on advanced editions, or
• the presence of capabilitySetStandard or the absence of app editions, which is effectively for customers on standard editions.