Installing cloud apps

If you built a Hello World app, ran Jira Cloud in development mode, and installed your app manually into the product, then the next phase of your app development is to test your app being installed via the Atlassian Marketplace.

This is important if you wish to test your app in a licensed state, or start along the path to listing your app. This is necessary whether you want to eventually make your app available privately or publicly, free or paid.

Before starting

There are a few prerequisites before you create your Marketplace listing:

• Create or get access to a cloud-hosted product instance
  You can create an environment for testing simply by signing up for a free development cloud product.
• Your app and your atlassian-connect.json descriptor file are served over HTTPS
  Your app (and your atlassian-connect.json descriptor) must be served over HTTPS to be installed into a cloud instance. Your app must have a baseUrl that starts with https://; a baseUrl of the form http://my-server.example.com:443/ will not be accepted. Additionally, your HTTPS certificate cannot be self-signed.
• You have an Atlassian user account associated with the Marketplace
  You need a Marketplace user account associated with a partner profile to create a listing. You can create a new partner profile when you create your listing, or have your account added to an existing profile by somebody already associated with it. To get an account associated with the Marketplace, sign up here.

Creating the Marketplace listing

With your Marketplace account set up and app descriptor on hand, create the Atlassian Connect listing as follows:

1. Log in to https://marketplace.atlassian.com/ with your vendor account.
2. Click Publish a new app from the profile menu in the upper right.
3. Choose a vendor. If you don't have a vendor profile yet, click Register your organization and contact details to configure a new vendor profile for your app.
4. For apps you'd like to list on the Marketplace, choose Public. For internal-only apps, choose Private as the app visibility option. If you intend to use the app for internal-use only, it can remain private for the lifetime of the listing.
5. Provide the URL to your app descriptor.
6. Follow the instructions to configure the remaining fields and options on the form. Many of the fields are optional and only apply to public listings. If you're listing privately, you can leave these for later. There are a few fields that require a little more explanation for an Atlassian Connect app listing:
   • Payment model: Choose only Free or Paid via Atlassian. Atlassian Connect apps can't be listed as paid via vendor.
   • Availability: This field specifies the Atlassian application deployment model (Cloud or Server). Connect apps are only available for cloud-hosted applications, so this field is pre-populated accordingly for you.
   • Version visibility: While the listing has a visibility setting, so do individual versions of your app. This lets you beta test version updates privately before publishing them. While different versions of an app can have different visibility settings, note that if you make the listing itself private, all versions of the apps also become private, even if they were previously published as public versions.
   • Beta release: Indicates that your app version is in the testing stage only. Choose this option if you intend to list the app publicly, but it isn't ready yet.
   • Compatible application: For an Atlassian Connect app, after you choose the product you are targeting and the minimum version, the Compatible to version is uneditable (that is, it defaults to Any). Because Atlassian Connect apps use stable, forward-compatible web APIs and cloud versions are frequently updated, the notion of a latest-compatible version is absent for Atlassian Connect apps. It is applicable, however, to downloadable Java apps.
7. Click Submit.

Now, you can generate test license tokens for your app and install it in cloud instances, either through MyAtlassian for live instances, or through the descriptor link of the listing view for locally-running instances. The next section provides more detail on how to do this.

Access tokens

If you created a private listing in the Marketplace, you can create and use access tokens. Access tokens are like licenses that you can generate and manage without going through the usual licensing process. Tokens let you install and test apps under development in live cloud instances. You can also use these licenses to install and use private apps if you only intend your app for internal use.

If your app is paid, after you install your app and apply a token, you can test your app against various license states like valid, expired, and unlicensed.

Access token restrictions

While access tokens are like licenses, a few restrictions apply.

• 50-token limit: Each app can only have 50 active tokens at a time.
• Token removal: You can delete or remove tokens at any time. If you have 50 active tokens, you can remove one to be able to create another. Apps in cloud instances with deleted tokens are treated as unlicensed.
• No reusability:
  A token is bound to a particular app and cloud instance. After a token is applied to an Atlassian product site, it is permanently associated with that instance, and can't be used with another.

Creating tokens

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. If you're generating a token to share with an external tester, you need to create the token in the Marketplace.

Generating an access token from a Marketplace listing

After you create a private listing for an app, you can generate an access token from your listing:

1. Log in to https://marketplace.atlassian.com/ with your partner account.
2. Click Manage vendor account from the profile menu in the upper right.
3. On the Apps page, click the name of your private app.
4. Click on the Private listings tab.
5. Click 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.

Installing apps with access tokens

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 into the cloud instance where you want to install your app.
3. Go to Manage apps in the administration console.
4. Click 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 retrieved and installed, and your token is applied. You should see an "Installed and ready to go!" dialog.

Now you can test your app, modify its license states (if it's paid), or manage the token. To test, set the license state to the one you want. From the License status menu, choose the state you'd like to test - active trial, subscription, inactive subscription, etc.

The usual options for managing the subscription for your app will be disabled in the user interface, since the token is the mechanism that serves this function for now.

Applying a token from the administration console

You can also generate a token directly from a listing directly in the product like Jira or Confluence. You can do this from the Manage apps page in the administration console:

1. Follow the instructions above to Enable private listings from the Settings dialog.
2. Install the app using your HTTPS-hosted atlassian-connect.json descriptor URL. Click Upload app and paste the URL into the corresponding field.
3. After installing the app, expand the details view for the app.
4. Click the plus (+) symbol next to Access token.
5. Log in using an account associated with your Marketplace partner profile.
6. Follow the in-app directions to generate and apply the token.

If you need to delete a token from an app, click the edit icon next to the token in the app view, and clear the content and save. This deletes your token in the instance, although it still exists on the Marketplace listing. You can disable an app in the administration console after you have removed its token.