List an app version from Java

The Marketplace API Java client lets you create app versions through the Addons API. You might want to do this as part of an automated release process. The manual equivalent would be to go to manage listings on Marketplace, select one of your existing apps, select Create version and fill in the version creation form.

For a stand-alone demo, see CreateAddonVersion.java in the Marketplace API Tutorials repository.

Prerequisites

You will need:

• A Java project that uses the marketplace-client-java library
• An existing app listing on Marketplace (can be public or private)
• A MarketplaceClient object that was configured with the credentials of your Atlassian account
• If the app is directly installable, the installable artifact (.jar, .obr, or workflow file) for the new app version

Step 1: Specify an installable artifact

If the app is directly installable, and the installable artifact is in a file on your local file system, you can use the uploadArtifact method in the Assets API to upload the file. It will return an ArtifactId, which is a reference to the file data on the Marketplace server:

1
2
File file = new File("/path/to/my-app-1.0.jar");
ArtifactId artifactId = client.assets().uploadArtifact(file);

Alternatively, if the artifact is not on your local file system but can be downloaded from a publicly accessible server (such as a Maven repository), you can simply construct an ArtifactId that tells Marketplace where to find it:

1
2
ArtifactId artifactId = ArtifactId.fromUri(URI.create("http://my-server.com/url/to/download/my-app-1.0.jar"));

Step 2: Build a version object

Calling ModelBuilders.addonVersion() gives you a builder object which you can use to specify the properties for your new version:

1
2
ModelBuilders.AddonVersionBuilder versionBuilder = ModelBuilders.addonVersion();

// These properties must always be specified for every new version:
versionBuilder.buildNumber(100)                // build numbers are unique values you choose to determine version ordering
    .paymentModel(PaymentModel.FREE)           // is this version of the app free, paid via vendor, or paid via Atlassian?
    .status(AddonVersionStatus.PUBLIC)         // you can make a version public or private
    .releaseDate(new LocalDate("2016-03-17"))  // this date will appear in the app's version history
    .releaseSummary(Option.some("this version fixes some bugs"));  // a brief description of the release

// If you have an ArtifactId (see step 1), attach it to the version like this:
versionBuilder.artifact(Option.some(artifactId))

// Or, if there is no ArtifactId because the app is not directly installable, you will normally
// provide an external download URI, like this:
versionBuilder.externalLinkUri(AddonVersionExternalLinkType.BINARY, URI.create("http://my-vendor.com/page-for-getting-the-addon"));
versionBuilder.name("1.0");  // Marketplace can detect the version string automatically for installable apps; but
                             // if there is no installable artifact, you'll need to specify the version string yourself.

// You do not need to specify compatibility details if they are the same as the previous version;
// but if they have changed, you can set them for the new version like this (the numeric values
// are application build numbers):
versionBuilder.compatibilities(ImmutableList.of(
    ModelBuilders.versionCompatibilityForServer(ApplicationKey.JIRA, 70107, 71003)
));

// Finally, call build() to produce an AddonVersion object that has all of the specified properties.
AddonVersion version = versionBuilder.build();

Step 3: Post the new version to Marketplace

Call createVersion in the Addons API (specifying the app key of your existing app) to send the new version to the server. If successful, it returns another AddonVersion object containing the state of the version as it now exists on the server:

1
2
AddonVersion createdVersion = client.addons().createVersion("my.app.key", version);

Approval for new versions

Note that Atlassian may need to approve the new version of your app if you are creating a public version. For example, approval is required if the app was previously using a different payment model or hosting option. See App approval guidelines for more information.